EditingGuidelines

Permission

Before you can edit the wiki, you must create an account and obtain permission to edit the wiki. To do so, please email <wiki AT SPAMFREE jsoftware DOT com> with your exact wiki login name.

After signing up and obtaining permission, login to be able to edit the wiki.

If, after logging in, you still see Immutable Page and not Edit at the top left, then you need to refresh the page (similarly for other "immutable pages)".

Overview

The J Wiki contains many kinds of information: reference manuals, forums, puzzles, code contributions, news of the day. You are free to edit almost all of this, but your changes must be appropriate to the material.

For ephemera such as forums and puzzles, your voice is just one of many and you are free to express yourself as you wish.

For code contributions, your coding style is your own, but you should take some care to put your contribution where it fits best, and you should document the interface to your code at least as well as others have documented theirs.

For reference documentation, you must take care to integrate your contribution into the document. You have succeeded if no one can tell that another hand was in the work. The reference documentation on the Wiki is the official version, and will be extracted for inclusion in the downloads when J is released, so you can help all J users with accurate editing or hurt them all with sloppy editing.

Keep these rules in mind when editing reference documentation:

• Make sure your changes are accurate. If you think something needs explaining but you're not 100% sure what the explanation should be, just insert the word ExplainMe and someone will come along to make the change properly.

• Avoid "thread mode", where you simply add your thoughts to a page without taking the trouble to make the page a unified whole. Thread mode is OK in Forums but not in documentation.

• Be sure to enclose J code between backticks or {{{ }}}. `x=.2` or {{{x=.2}}} will be displayed as x=.2.

Beginners

If you are new to wikis, see the Editing Wiki beginner's guide to editing wiki pages.

Special Characters

The wiki supports markup, useful for math formulae: .

For APL characters, see Typesetting/APL Characters.

For the box-drawing characters used in J, see Typesetting/Box Drawing Characters.

Page Names

• Create new pages at the appropriate place in the directory hierarchy.

• Page names can use CamelCase, i.e. each word capitalized and no blanks. Page names can also contain blanks as in My Page.

• Page names should not contain an underscore. This is because the wiki rewrites blanks to underscore in page names, so an underscore is not properly recognized as such. Instead, use blanks, e.g. [[My Page|mypage]] instead of [[My_Page|mypage]].

• To refer to a page, insert a reference like this example: [[JAL/User Guide|User's Info]] which will be displayed as User's Info.

• To reduce the risk of name conflicts, page names should, in general, use directories (MoinMoin calls these sub-pages).

• Do not create additional levels of directory hierarchy unnecessarily. It is harder to refactor and move pages when the directory tree is deep. When creating a directory, make it a top level directory if you expect others will add pages to it.
• To move pages, just rename them. You need to be logged in, then go to the page and select Rename from the drop down menu. You also need to modify the parent pages to point to the new location - the wiki will not automatically update the links.

Examples

• A relatively few pages, typically created by the site administrators, will have no directory path, for example: FrontPage. Also, all user pages have no directory path, and users can then add pages using their name as the top level directory, for example: PeterSimple/Projects.

• Most pages will be in two levels, dirname/pagename, as in: Studio/Rank.
• Sometimes three levels may be appropriate, typically for your own projects, for example: Packages/Mars/Source.
• Suppose you want to add a new directory Templates to the Code directory, and expect that it will contain several pages. In this case, create Templates as a top-level directory, i.e. instead of: Code/Templates/Desert create: Templates/Desert

Attachments

If your contribution is a zip or other binary file, see the policy on attachments.

Image Illustrations

It is good to enhance text with graphical illustrations. Wiki makes it easy to add images by uploading them as attachments and linking in the text. With a few simple considerations you can make your screenshots and pictures look good on the page. See more at Images guidelines.

InterWiki Linking

Among different ways pages can be linked, common external resources, such as WikiPedia, MathWorld or OEIS (Sloane), can be conveniently referenced in a uniform way with the help of InterWiki syntax. There are two common variations:

• target name used as is: WikiPedia:Euler will produce Euler

• or substituted with an alias: [[WikiPedia:Euler|Leonhard Euler] will become Leonhard Euler

InterWiki syntax is compact, site names are easy to remember, and page content is isolated from future changes of the link address.

Other useful links:

Embedding External Content

The EmbedObject macro is used for embedding media from other web sites, such as video from YouTube, PDF, etc into Wiki pages. Only certain types of media are allowed by the Wiki configuration due to security considerations.

See Embedding examples.

Categories

See HelpOnCategories for grouping pages into categories or marking pages with specific attributes (CategoryFixMe or CategoryWorkInProgress).

Footnotes

Footnotes are added with the FootNote macro, which is also used without parameters to place the target list. In summary,

to create a footnote in text, use

... paragraph text <<FootNote(Footnote test ...)>> paragraph continued ...

to place the target list in correct section order, use an explicit Footnotes section before Authorship and Categories sections

== Footnotes ==
<<FootNote>>

<<BR>>
Contributed by ...
----
CategoryWorkInProgress

Authorship

We recommend that you add an authorship statement to any page where you have made a substantial contribution to the contents. Exactly what is a "substantial contribution" is left to your discretion.

Use your wiki name (create one if necessary), so that a link is created to your wiki home page.

We recommend that this be done at the foot of the page, as in the following examples:

----
Contributed by IkeNewton.

Contributed by IkeNewton, with further contributions by
LeoEuler, CarlGauss, PaulErdos, ...

Contributed by IkeNewton, found to be ill-written and then
completely reworked by PomPosity.

Owned Pages

You can take ownership of a page, so that only you have the ability to change it. See Owned Pages.

Navigation Integrity (Delete Cache!)

The simplicity of Wiki format to include links can easily be abused if care is not taken about accidentally introducing an non-link using WikiName syntax or leaving a page without references. The SiteNavigation page contains links to special lists of problem pages, such as WantedPages and OrphanedPages.

When finished editing, check your links and verify the problem lists. In some cases to remove a problem it is required to Delete Cache from menu on the referring page as well as the problem list page for a change to take effect. This is often the case when the linked page is created after the referer is last changed. Redirections need to be added into Exceptions to be explicitly orphaned.

Another way to check if page is linked correctly is to click on the page title from itself. This will show all linkto pages.

• Note: Don't use underscore [[Like_This]] in links, use space [[Like This]] instead. Otherwise the link is not recognized by problem lists.

Reusing Page Name

If you want to delete an obsolete page and then rename a different page to its name, you cannot do it directly in MoinMoin. Instead, rename the obsolete to Trash/Page Name, then rename the different page to its name. All the Trash/ child pages will be periodically purged by administrators.