• EditingGuidelines

EditingGuidelines

TableOfContents

Overview

The APL Wiki contains many kinds of information. You are free to edit almost all of this, but your changes must be appropriate to the material.

For ephemera such as forums, 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. If your contribution is a zip or other binary file, see the policy on attachments.

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 APL code between backticks or {{{ }}}

Beginners

If you are new to wikis, see the Beginner's Guide to editing wiki pages.

• 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 underbar. This is because the wiki rewrites blanks to underbars in page names, so an underbar 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: [:Topic/SubPage:User's Info] which will be displayed as "User's Info".

• To reduce the risk of name conflicts, page names should, in general, use sub-pages, a MoinMoin construct which offers something like a folder structure.

• 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. Wikis are not Content-Management-Systems.

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.
• 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

InterWiki Linking

Among different ways pages can be linked, common external resources, such as WikiPedia, MathWorld:MathWorld or OEIS: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: [wiki:WikiPedia/Euler Leonhard Euler] will become [wiki:WikiPedia/Euler 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: [ISBN]ISBN (Amazon): [wiki:ISBN/ISBN ISBN (Amazon)]

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 but on top of CategoryReference, 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 [:EditingGuidelines/OwnedPages:OwnedPages.].

Navigation Integrity

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.

Categories

Adding a string "CategorySomething" on a perticular page is in first place nothing but a simple keyword. But there is some magic in place: if you call the page "CategorySomething", this page will create then a list of all pages containing that keyword. And because it is created dynamically when called, it is definitly up-to-date.

Inventing a new category page is simple: choose the appropriate template - the name is obvious. That's it!

You can add several categories to a particular page. For example, you can add one or more of "CategoryDyalog", "CategoryDyalogDotNet", "CategoryGeneralUtilities".

When you think about a new category, check the list of already defined categories carefully!

.NET pathes

Address .NET methods/classes/enumerations/interfaces always fully. This makes it not only easier to understand the code, it makes it also much easier to find related articles. For example, if you use the ⎕USING mechanism, you can call the method "ShowHelp" from System.Windows.Forms.Help by adressing it as "ShowHelp". Surely there are plenty of other methods with exactly the same name! So it is more appropriate to search for System.Windows.Forms.Help.ShowHelp if your are looking for an example how to use this .NET method.