|
|
| (6 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| ==Overview==
| | <p class="warn"><b>Note:</b> This page preserves the history of the page now known as [[Updating M204wiki]], which apparently was created by a copy and paste instead of a move of this "M204wiki style guide," which would have saved its history. |
| While the most important part of a wiki is the content, following a few simple rules in formatting wiki documentation pages can make it easier for people to use the wiki because the consistent look and feel of each page. In addition, following these rules can make it easier to write the pages, as standard use of wiki and HTML tags makes it possible to convey information in the format of the text rather than having to state it explicitly.
| |
| | |
| Use of HTML tags and attributes that focus on the semantics of text also has some advantages:
| |
| <ul> | |
| <li>It's easier to remember semantic tags and attributes than remembering the physical display characteristics of a certain kinds of text.
| |
| <li>It's easier for Sirius to tweak or customize the look and feel of text based on its semantics if the semantics of the text is explicit in the markup.
| |
| </ul>
| |
| In fact, as a general rule of thumb, if you're coding any explicit physical text attributes in your wiki markup, it's probably a sign that you're doing something wrong or that Sirius needs to expand its list of semantic classes.
| |
| | |
| For example, if you enter <code><nowiki>''Model204''</nowiki></code> or <code><i>Model 204</i></code>, you're doing something wrong. You <strong>should</strong> enter <code><var class="product">Model 204</var></code>. Even if you're trying to emphasize something, like the "should" in the last sentence, you should use <code><strong>should</strong></code> not <code><nowiki>'''should'''</nowiki></code> or <code><b>should</b></code> though, admittedly, <code><strong></code> doesn't tell one a heck of a lot about the semantics of the enclosed word or words.
| |
| | |
| ==Headings==
| |
| The outermost headers on any page should be level two headers so should have two equals sign on either side:
| |
| <p class="code"><nowiki>==This is a heading2==</nowiki>
| |
| </p>
| |
| For a subsection of the heading2:
| |
| <p class="code">===Here is a heading3===</p>
| |
| These headings are included in the page's table of contents at the top of the page
| |
| (if there are enough sections — usually three — to generate one).
| |
| | |
| All of the page and section names are case sensitive. Capitalize the first word and any proper nouns, but leave the rest of the words in lowercase.
| |
| | |
| Don't create links or put HTML tags in headings.
| |
| | |
| ==Links==
| |
| For cross-references (links) to an article/page, your markup can simply be the exact article title enclosed in pairs of left and right brackets. To link to the article entitled "My target page":
| |
| <p class="code">[[My target page]]</p>
| |
| | |
| If you want the text of the link that the viewer sees to be different from the page title, append to the page name a vertical bar (<tt>|</tt>) followed by the text you want displayed:
| |
| <p class="code">[[My target page|My special link text]]</p>
| |
| | |
| In the wiki page view, the above markup displays as:
| |
| <p class="code">[[My target page|My special link text]]</p>
| |
| | |
| The link text above will display in red to remind that this page has yet to be created. For more information anout creating a page, see [http://www.mediawiki.org/wiki/Help:Starting_a_new_page Help:Starting a new page].
| |
| | |
| For links to a section on a page, where the section is an h2- through h6-level heading, thus automatically indexed by the wiki code,
| |
| follow the page title as above by <code>#<i>sectionName</i></code>, where <var class="term">sectionName</var> is the exact heading title. Then append to the section name a vertical bar followed by the text you want displayed, enclosed in double-quotation marks:
| |
| | |
| <p class="code">[[My target page#My section|"My section"]]</p>
| |
| | |
| In the wiki page view, the above markup displays as:
| |
| <p class="code">[[My target page#My section|"My section"]]</p>
| |
| | |
| Using the quotation marks is arbitrary, but it is the style used in this wiki.
| |
| | |
| For more information about formatting variations of the above types of links as well as other kinds of links, including external links, those to a target outside of the wiki, see [http://www.mediawiki.org/wiki/Help:Links Help:Links]
| |
| | |
| ==Syntax diagrams==
| |
| One of the most common documentation structures is a syntax diagram. Syntax diagrams show the format of a command, statement, or method invocation. While some of the syntax diagrams are generated from the Model 204 code (all methods, for example), much of the work of indicating syntax must be done manually. And there is no macro language for specifying the key elements of a syntax diagrams.
| |
| | |
| The first rule of syntax diagrams is that they must be contained inside a <code><p></code> element with a class of <code>syntax</code>:
| |
| <p class="code"><p class="syntax">
| |
| ... syntax diagram goes here
| |
| </p>
| |
| </p>
| |
| There are other rules that must be observed:
| |
| <ul>
| |
| <li>All keywords that must be typed literally as in the syntax diagram must start with an uppercase character.
| |
| | |
| <li>All syntax terms that are <strong>not</strong> literals should start with lowercase letters.
| |
| | |
| <li>[http://en.wikipedia.org/wiki/Camel_case Camel case] should be used for artifical compound word such as, for example, <code>veryImportantParameter</code>. Of course, keywords can also use this kind of captilization but, because keywords must begin with upper case characters, the casing is, strictly speaking, referred to as [http://en.wikipedia.org/wiki/Pascal_case Pascal case].
| |
| <li>Optional words or phrases must be inside of square brackets. These can be nested if, for example, an optional keyword appears inside an optional clause. Note that for <var>Callable</var> methods, the target (including the equal sign) should be inside square brackets. Note also that, strictly speaking, the syntax diagram for functions is not really correct as a function can be used in a context where its result is not assigned to a variable, but the standard syntax diagram shows an assignment to a variable. It's not obvious how we can make the syntax diagram more accurate without losing information or making it needlessly complex.
| |
| | |
| <li>Similary, methods can apply to variables or the results of expressions. This dichotomy <strong>can</strong> be expressed by not using the percent sign in the syntax term for the method object (nor for parameters). This "rule" is currently not followed everywhere — some places use the percent sign at the start of syntax terms that might be variables or results of expressions and some don't. For now, the recommendation is that the percent sign be used only where a percent variable is required. Perhaps, some day, this will turn into a rule.
| |
| | |
| <li>Use the standard <var class="product">Model 204</var> continuation character, hyphen (<code>-</code>), to continue each line whose syntax is continued on the next line. While more than 90% of the time, syntax diagrams will refer to a single-line statement or a command, it's still good discipline to stick with this rule so that multi-line syntax is obvious.
| |
| </ul>
| |
| | |
| Because syntax diagrams should be inside a <var><p></var> element, rather than, say, a <var><pre></var> element, wiki markup is allowed inside the block. This means, that you can include a link to a section that provides more detail about a word or phrase. For example, if there is a syntax term in a syntax diagram called <code>eve</code>, and a section called <code>All about eve</code>, a syntax diagram might be coded as follows:
| |
| <p class="code"><p class="syntax">object:[[Foo|foo]](<nowiki>[[All about eve|eve]]</nowiki>)
| |
| </p>
| |
| </p>
| |
| <p>
| |
| In current practice, however, a link within syntax is uncommon and the technique is more often used within code examples.
| |
| </p>
| |
| Note that in the above example, the syntax diagram starts on the same line as the <code><p class="syntax"></code> tag. This is because starting the syntax diagram on the following line results in an extra, unnecessary blank line at the top of the box that contains the syntax diagram in the output wiki page. There is no known work-around for this.
| |
| | |
| It is generally a good idea to try to get the terms in a syntax diagram to line up "nicely" if the diagram extends beyond one line. Obviously, "nicely" is a term that leaves a lot of room for interpretation but, since <code><p class="syntax"></code> blocks are always displayed in a monospace font, it shouldn't be a daunting task to make words in multiple lines line up for readability. There are also no guidelines for the width of syntax diagram lines, but making lines too long can result in them running off the end of the page or becoming difficult to scan because of the number of characters on a single line.
| |
| | |
| ==Examples==
| |
| Code examples are much like syntax diagrams but they use the <code>code</code> class, like this:
| |
| <p class="code"><p class="code">for %x from 1 to %myStringList:Count
| |
| if %myStringList(%x):subString(1,3) eq ':h2' then
| |
| printText this is a header: {%myStringlist(%x)}
| |
| end if
| |
| end for
| |
| ...
| |
| </p>
| |
| </p>
| |
| Notes:
| |
| <ul>
| |
| <li>M204wiki practice is to put the first line in the example on the same line as the <code><p class="code"></code> tag, and, by default, to start immediately after (no blanks) the closing angle bracket of that tag
| |
| | |
| <li>If certain characters (like asterisk, period, hyphen) occupy the <i>first</i> position of an example line, they will be interpreted as wiki markup, so you can do one of the following to prevent this:
| |
| | |
| <ul>
| |
| <li>Put a blank in position one and the character in position two.
| |
| | |
| <li>Specify their equivalent [http://ascii.cl/htmlcodes.htm HTML decimal or entity code] (for example, for an asterisk, use <code>&#42;</code>)
| |
| | |
| <li>Enclose the character in the <code><nowiki></code> tag (for example, for an asterisk, use <code><nowiki>*</nowiki></code>)
| |
| </ul>
| |
| </ul>
| |
| | |
| ==Tables==
| |
| M204wiki documentation uses tables extensively, and it uses [http://www.w3.org/TR/REC-html40/struct/tables.html XHTML tags] to create the tables. By default, the M204wiki <code><table></code> tag and attributes are styled to include background shading and solid borderlines, and most notably to italicize (as well as bold) the content of <code><th></code> cells.
| |
| | |
| For example, the following table is produced by the code shown below the table:
| |
| | |
| <table>
| |
| <tr><th>%outString</th>
| |
| <td>A variable to receive the string result of the <var>Unspace</var> method.</td></tr>
| |
| | |
| <tr><th>string</th>
| |
| <td>The input method object string</td></tr>
| |
| | |
| <tr><th><var>Spaces</var></th>
| |
| <td><var>Spaces</var> is an optional, [[Notation conventions for methods#Named parameters|name required]], parameter that is a string that specifies the set of characters considered to be whitespace.
| |
| <p>
| |
| If you specify multiple <var>Spaces</var> characters, the first character of the string is the replacement space character.</p>
| |
| </td></tr>
| |
| </table>
| |
| | |
| <p class="code"><table>
| |
| <tr><th>%outString</th>
| |
| <td>A variable to receive the string result of the <var>Unspace</var> method.</td></tr>
| |
| | |
| <tr><th>string</th>
| |
| <td>The input method object string</td></tr>
| |
| | |
| <tr><th><var>Spaces</var></th>
| |
| <td><var>Spaces</var> is an optional parameter that is a string that specifies the set of characters considered <br/>to be whitespace.
| |
| <p>
| |
| If you specify multiple <var>Spaces</var> characters, the first character of the string is the replacement space <br/>character.</p>
| |
| </td></tr>
| |
| </table>
| |
| </p>
| |
| | |
| <div id="notes"></div>
| |
| Notes about the table example:
| |
| <ul>
| |
| <li>As is typical, the <code><table></code> tag is used without any qualifying '''class'''. If you want to create a table that does not have solid borders, for example, you would code the tag as <code><table class="noBorder"></code> to use the [[MediaWiki:Common.css|M204wiki stylesheet overrides]] <code>noBorder</code> class which specifies a transparent border.
| |
| | |
| <li>Each HTML tag is explicitly started and has an '''explicit end tag'''.
| |
| | |
| <li>In this example, the table has no column headings and no preceding caption. This is frequently the case with M204wiki tables.
| |
| <ul>
| |
| <li>To create a '''heading row''', tag the row (<tr>) with the "head" class, and tag each cell in the row with <code><th></code>. The "head" class prevents text in such headings from wrapping (probably what you want), and it makes the heading text non-italic. For example:
| |
| <p class="code"><tr class="head"><th>A wordy column-heading title</th><th>Another wordy column-heading title<th></tr> </p>
| |
| | |
| <li>To create a '''table caption''', specify a <code><caption></code> tag after the <code><table></code> tag and before any heading tags. For example:
| |
| <p class="code"><table>
| |
| <caption>My favorite table></caption>
| |
| <tr><th>%outString</th>
| |
| ...
| |
| </table> </p>
| |
| <p>
| |
| The caption will display in bold text above, and centered with respect to, the table. The default amount of space between the caption and the table varies with browser type. </p>
| |
| </ul>
| |
| | |
| <li>To divide a cell's content into '''blank-separated paragraphs''', you explicitly use a starting and ending paragraph tag (<code><p></code>), as in row 3.
| |
| | |
| <li>The <b>cells in the non-heading, first column</b> in the table <b>are</b> tagged with <code><th></code>, which makes the cell content bold and italic. The following are alternatives to this default for the non-heading, first-column content:
| |
| | |
| <table>
| |
| <tr class="head"><th>Desired effect </th><th>Technique</th></tr>
| |
| | |
| <tr><td nowrap>Some non-italic (but still auto-bold) items</td>
| |
| <td>Enclose the non-italic content within <code><var></code> tags (see <code>Spaces</code> in row 3, column 1). </td></tr>
| |
| | |
| <tr><td>All not auto-italic and not auto-bold<br>(that is, like this table)</td>
| |
| <td>Use the <code><td></code> tag instead of the <code><th></code> tag, which will remove the automatic italic and bold.</td></tr>
| |
| | |
| <tr><td>All not auto-italic (but still auto-bold)</td>
| |
| <td>Use the <code><table class="thJustBold"></code> tag, and keep the first-column <code><th></code> tags.
| |
| <p class="note"><b>Note:</b> Tag <i>heading</i> rows with <tr class="head">.</p></td></tr>
| |
| </table>
| |
| </ul>
| |
| | |
| ==Notes and warnings==
| |
| ===Notes===
| |
| Note paragraphs call attention to particular information you want to emphasize. Often such a note is a sentence or two, but sometimes it may include an example or additional paragraph(s). For example:
| |
| | |
| <p class="code"><b>Note:</b> Only a declared <var>Recordset</var> object variable may be the target of such a <var>Find</var> statement: that is, a <var>Recordset</var> member
| |
| invocation is not allowed to be the target. </p>
| |
| | |
| The markup for this indented note uses the <code><p class="note"></code> tag and an explicitly bolded <code>Note:</code>:
| |
| <p class="code"><p class="note"><b>Note:</b> Only a declared <var>Recordset</var> object variable
| |
| may be the target of such a <var>Find</var> statement: that is, a <var>Recordset</var>
| |
| member invocation is not allowed to be the target. </p></p>
| |
| | |
| If a note extends beyond a single paragraph or includes an example or list, however, you must use a <code><blockquote class="note"></code> tag (that is, <b>not</b> <code><p class="note"></code>) to enclose the entire note. Here is an example:
| |
| <p class="code"><b>Note:</b> As shown earlier, the <var>Recordset</var> object declaration specifies
| |
| the file or group context to which the <var>Find</var> statements apply.
| |
| The <var>In File</var> and <var>In Group</var> clauses in the statements above '''must'''
| |
| agree with their corresponding object declarations.
| |
| For an example where an <var>In Group</var> clause is more meaningful,
| |
| see [[Recordset class#Selecting group members|"Selecting group members"]].
| |
|
| |
| If there is no <var>In File</var> or <var>In Group</var> clause, there must be a default file context.
| |
| </p>
| |
| | |
| Here is the markup:
| |
| <p class="code"><blockquote class="note"><b>Note:</b>
| |
| As shown earlier, the <var>Recordset</var> object declaration specifies
| |
| the file or group context to which the <var>Find</var> statements apply.
| |
| The <var>In File</var> and <var>In Group</var> clauses in the statements above <b>must</b>
| |
| agree with their corresponding object declarations.
| |
| For an example where an <var>In Group</var> clause is more meaningful,
| |
| see [[Recordset class#Selecting group members|"Selecting group members"]].
| |
| <p>
| |
| If there is no <var>In File</var> or <var>In Group</var> clause, there must be a default file context.</p>
| |
| </blockquote> </p>
| |
| | |
| For messages that deserve greater emphasis than a Note but do not concern a risk of losing data or data integrity, use a Note but also use italics or boldface for part or all of the message text.
| |
| | |
| ===Warnings===
| |
| If you need to provide a note that has greater urgency, say to warn users about an operation's potential serious consequences to their system or data, use a paragraph with a <code>warn</code> class, and use the prefix <code><b>Attention:</b></code>. Here is example markup:
| |
| <p class="code"><p class="warn"><b>Attention:</b> To ensure file integrity, it is strongly recommended that you
| |
| never reset the FISTAT (file status) parameter when it is set to the file-physically-inconsistent
| |
| flag until just before you reorganize the file. However, you must reset FISTAT before you
| |
| reorganize a physically inconsistent file.
| |
| </p></p>
| |
| | |
| The above warning displays with top and bottom horizontal bars:
| |
| <p class="warn"><b>Attention:</b> To ensure file integrity, it is strongly recommended that you never reset the FISTAT (file status) parameter when it is set to the file-physically-inconsistent flag until just before you reorganize the file. However, you must reset FISTAT before you reorganize a physically inconsistent file. </p>
| |
| | |
| As with Note messages:
| |
| <ul>
| |
| <li>Warnings longer than a single paragraph require <code><blockquote="warn"></code> rather than <code><p="warn"></code>.
| |
| | |
| <li>To provide greater emphasis to Attention messages that deserve it, use italics or boldface for part or all of the message text.
| |
| </ul>
| |
| | |
| ==Categories and Lists==
| |
| Sirius has avoided the use of third-party add-on modules to MediaWiki in order to make it easy for sites to take local copies of M204wiki material without having to validate and install extra software.
| |
| | |
| Unfortunately, that leaves out a few useful features, like Dynamic Page Lists (DPL) which make up for some of the shortcomings of the default MediaWiki "Category" technology. Our compromise has been to use both MediaWiki categories ''and'' to create hand-built 'list' pages, buttressed by by some User Language consistency checks.
| |
| | |
| The standard MediaWiki category page is less informative, but updates itself (nearly) automatically. The hand-built list is at risk of being out of date, but it is also more useful as a quick cheat sheet for a set of related methods or functions.
| |
| | |
| For some category/list sets, such as the big table on [[List of $functions|"List of $functions"]] and the tables on the "$Function set" on the top of that page, we have some User Language (here, FUNSCHECK.WIKI) which we <b>should</b> run regularly to ensure all is well.
| |
| | |
| Other cases may not yet have had the User Language built but should be straightforward, for example, the [[List of JANUS WEB subcommands]] and
| |
| the [[:Category:JANUS WEB subcommands|JANUS WEB subcommands category page]].
| |
| | |
| Some will be harder, such as the
| |
| hand-built [[List_of_Fast/Unload_$functions|"List of Fast/Unload $functions"]], because there is no category for it specifically. It is all of the $function entries in the [[Fast/Unload User Language Interface]], and once we convert that page to a hand-built list (with its *CHECK.WIKI!) then the Fast/Unload $function list should be checkable.
| |
| | |
| ===PDFs of the contents of Category pages===
| |
| Most Category pages have a link to create a PDF file that contains all the categories on the page. That PDF will also include any Subcategory entries on the page '''if''' the MediaWiki link that placed the subcategory items onto the Category:Commands page is appropriately edited on the "home Category page" of those subcategories. This is also true for the sidebar link "PDF of this page."
| |
| | |
| For example, the "Operator commands" subcategory on the "Category:Commands" page is ordinarily the result of a <code><nowiki>[[Category:Commands]]</nowiki></code> tag on the "Operator commands" page source. If that markup is changed to <code><nowiki>[[Category:Commands| Operator commands]]</nowiki></code> (note space before "Operator"), the "Operator commands" subcategory on the "Category:Commands" page will display as before and in the same position except without a bold "O" heading for items that begin with the letter "O". If the other subcategories on the "Category:Commands" page are similarly edited, PDFs of the "Category:Commands" page will include the subcategories.
| |
| | |
| ==Pages that contain auto-generated content==
| |
| Some content on some pages is auto-generated by SOUL operating on information in the <var class="product">Model 204</var> load module. Many of the "List of ..." pages are examples of this, like:
| |
| <p class="code">[http://m204wiki.rocketsoftware.com/index.php/List_of_Arraylist_methods List of Arraylist methods] </p>
| |
| | |
| When you are in edit mode on such an auto-generated page, you see a warning at the top of the page:
| |
| <p class="code"><!-- This page was automatically generated and will be automatically
| |
| replaced, so any manual edits will be lost. You've been warned. --> </p>
| |
| You should heed this warning, and, instead of updating the page, copy the URL of of the wiki section most closely containing the wiki content that you want to update, and paste the URL into an email to the most relevant people describing the update you had in mind. Further discussion will likely ensue.
| |
| | |
| ==Graphics and PDFs==
| |
| Model 204 documentation on M204wiki contains few graphics (images). For information about using graphics on an M204wiki page, see [http://www.mediawiki.org/wiki/Help:Images Help:Images]. For an M204wiki example, see [[Datetime string formats#Using CENTSPAN|Using CENTSPAN]].
| |
| | |
| To locate a .pdf file that has been uploaded to M204wiki, you can search for File:<i>filename</i>, where <i>filename</i> is the full name of the PDF file. Or you can specify the URL <code>http://m204wiki.rocketsoftware.com/index.php/File:filename</code>. Both methods will bring you to the "home page" of the file, from which you can invoke the PDF.
| |
| | |
| From the PDF's home page, you can also hover your mouse over the link to the PDF, which will reveal the URL of the file. You can then use that URL to code links to directly invoke the PDF without having first to go to its home page.
| |
| | |
| ==Section numbering==
| |
| By default, the sections in the table of contents at the top of most pages is automatically numbered. The section headings themselves in the actual page content are ''not'' numbered by default, but you can override this default by changing your user preferences:
| |
| <ol>
| |
| <li>At the top of any page, select the <code>my preferences</code> link.
| |
| <li>On the Preferences page, select the <code>Appearance</code> tab, then in the <code>Advanced options</code> section, select the <code>Auto-number headings</code> checkbox.
| |
| </ol>
| |
| | |
| ==See also==
| |
| <ul>
| |
| <li>For examples of pages that have "good" formatting, see the individual method pages linked to from [[Lists of classes and methods]].
| |
| | |
| <li>For a more comprehensive editing guide, see MediaWiki's [http://www.mediawiki.org/wiki/Help:Contents Help page].
| |
| </ul>
| |