APL Wiki|
Size: 6175
Comment:
|
← Revision 24 as of 2017-02-16 19:46:15 ⇥
Size: 7194
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 3: | Line 3: |
| [[TableOfContents]] | <<TableOfContents>> |
| Line 21: | Line 21: |
| == Beginners == | == New Authors == |
| Line 23: | Line 23: |
| If you are new to wikis, see the Beginner's Guide to editing wiki pages. | If you are new to wikis, see the [[BeginnersStartHere|Beginner's Guide]] to editing wiki pages. |
| Line 25: | Line 25: |
| * Create new pages at the appropriate place in the directory hierarchy. | * Create new pages at the appropriate place (article, guide,...). |
| Line 29: | Line 29: |
| * 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: `[:MyNewPage:User's Info]` which will be displayed as "User's Info". |
| Line 31: | Line 31: |
| * 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 might use '''sub-pages''', a !MoinMoin construct which looks like a folder structure. |
| Line 33: | Line 33: |
| * 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. | === More about Sub-Pages === |
| Line 35: | Line 35: |
| * 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. | {{{StringsManipulations/Split}}} would be a nice name which takes advantage of the sub-page-concept, for example. It does not only reduce the danger of name clashes but also offers the user the opportunity to get a list of all pages related to the "folder" !StringsManipulations by punching in !StringsManip. |
| Line 37: | Line 37: |
| * 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. | === A Warning === |
| Line 39: | Line 39: |
| == Examples == | * Do not create additional levels of sub-pages unless you have a very good reason for that. It is harder to refactor and move pages then. |
| Line 41: | Line 41: |
| * 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. | * 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 all pages referring to that page - the wiki will not automatically update the links. Wikis are '''not''' Content-Management-Systems. |
| Line 43: | Line 43: |
| * Most pages will be in two levels, dirname/pagename. | == Hide complexity == |
| Line 45: | Line 45: |
| * 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 |
In case that a particular topic is complex, you might have to provide quite a large amount of information. On the Web, chances are that a user will stop reading any information at all if she gets flooded with too many pieces of information. A common technique to deal with this problem is to provide only essential information but to allow the user to "show" more information usually represented by a short description. That can be done in two very different ways: * Splitting it into different pages, adding links to sub-pages * Represent the details by a short description and make it visible by a click on it without the additional drawback of a page reload. The former technique has it's merits, of course, but it comes with drawbacks as well: If the sub-pieces are relatively small but their total number is high, it might increase the number of pages dramatically. Not helpful at all when searching pages. In those cases a hide/show mechamism local to that page is certainly an alternative. The APL wiki supports this via !JavaScript. For details see the SeeSaw page. == Categories == <<SeeSaw(section=categories, toshow="<<show>>", tohide="<<hide>>", bg="#FEE1A5")>> {{{#!wiki seesaw/categories/categories-bg/hide Categories allow a page to be connected with one or more Categeries. That makes it easier for visitors to find related information. Typical examples for Categories are * Windows/Unix * Dyalog/APL2 To make effective use of Categories it is important to understand the "Category" concept. See WhyUsingCategories for important details. }}} ##== Special characters == ##The wiki supports \LaTeX markup, useful for math formulae: $ \sqrt{a^2 + b^2} $. |
| Line 51: | Line 76: |
| Among different ways pages can be linked, common external resources, such as `[WikiPedia]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: | Among different ways pages can be linked, common external resources, such as WikiPedia: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: |
| Line 53: | Line 78: |
| * target name used as is: !WikiPedia:Euler will produce `[WikiPedia]Euler` | * target name used as is: !WikiPedia:Euler will produce WikiPedia:Euler |
| Line 55: | Line 80: |
| * or substituted with an alias: `[wiki:WikiPedia:Euler Leonhard Euler]` will become `[WikiPedia]Leonhard Euler` | * or substituted with an alias: `[wiki:WikiPedia/Euler Leonhard Euler]` will become [[WikiPedia:Euler|Leonhard Euler]] |
| Line 59: | Line 84: |
| Other useful links: `[ISBN]ISBN (Amazon).` | Other useful links: `[ISBN]ISBN (Amazon):` [[ISBN:ISBN|ISBN (Amazon)]] |
| Line 79: | Line 104: |
| ## == Owned Pages == ## ## You can take ownership of a page, so that only you have the ability to change it. See Owned Pages. |
== Owned Pages == You can take ownership of a page, so that only you have the ability to change it. See [[EditingGuidelines/OwnedPages|OwnedPages.]]. |
| Line 85: | Line 110: |
| 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. | 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. |
| Line 91: | Line 116: |
| * | In this wiki, MoinMoin's "Category" feature is used heavily. See WhyUsingCategories for important details! |
| Line 93: | Line 118: |
| Note: Don't use underscore {X} [:Like_This] in links, use space (./) [:Like This] instead. Otherwise the link is not recognized by problem lists. | * Note: Don't use underscore {X} `[:Like_This]` in links, use space (./) `[:Like This]` instead. Otherwise the link is not recognized by problem lists. |
| Line 95: | Line 120: |
| Reusing Page Name | == Reusing Page Name == |
| Line 97: | Line 122: |
| 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. last edited 2007-01-14 by KaiJaeger |
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. |
EditingGuidelines
Contents
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 {{{ }}}
New Authors
If you are new to wikis, see the Beginner's Guide to editing wiki pages.
- Create new pages at the appropriate place (article, guide,...).
Page names can use CamelCase, i.e. each word capitalized and no blanks. Page names can also contain blanks as in "My Page".
To refer to a page, insert a reference like this example: [:MyNewPage:User's Info] which will be displayed as "User's Info".
To reduce the risk of name conflicts, page names might use sub-pages, a MoinMoin construct which looks like a folder structure.
More about Sub-Pages
StringsManipulations/Split would be a nice name which takes advantage of the sub-page-concept, for example. It does not only reduce the danger of name clashes but also offers the user the opportunity to get a list of all pages related to the "folder" StringsManipulations by punching in StringsManip.
A Warning
- Do not create additional levels of sub-pages unless you have a very good reason for that. It is harder to refactor and move pages then.
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 all pages referring to that page - the wiki will not automatically update the links. Wikis are not Content-Management-Systems.
Hide complexity
In case that a particular topic is complex, you might have to provide quite a large amount of information. On the Web, chances are that a user will stop reading any information at all if she gets flooded with too many pieces of information.
A common technique to deal with this problem is to provide only essential information but to allow the user to "show" more information usually represented by a short description. That can be done in two very different ways:
- Splitting it into different pages, adding links to sub-pages
- Represent the details by a short description and make it visible by a click on it without the additional drawback of a page reload.
The former technique has it's merits, of course, but it comes with drawbacks as well: If the sub-pieces are relatively small but their total number is high, it might increase the number of pages dramatically. Not helpful at all when searching pages.
In those cases a hide/show mechamism local to that page is certainly an alternative. The APL wiki supports this via JavaScript. For details see the SeeSaw page.
Categories
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 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): 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 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.
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.
In this wiki, MoinMoin's "Category" feature is used heavily. See WhyUsingCategories for important details!
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.