|
|
| (61 intermediate revisions by 5 users 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.
| |
| ==Headers==
| |
| 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 header==</nowiki>
| |
| </p>
| |
| ==Syntax diagrams==
| |
| One of the most common documentation structures is syntax diagrams. Syntax diagrams show the format of a command, statement, or method invocation. While in an ideal world there would be a nice macro language for specifying the key elements of a syntax diagrams, we don't live in an ideal world so most of work of indicating syntax must be done manually.
| |
| | |
| 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 upper case character.
| |
| <li>All syntax terms that are <strong>not</strong> literals should start with lower case 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>The standard <var class="product">Model 204</var> continuation character dash (<code>-</code>) should be used to continue each line where the 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 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. The most useful wiki markup in a syntax diagram is a link, usually 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>
| |
| 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. This sucks, but there's no known work-around.
| |
| | |
| This point's suckiness is increased by the fact that it's generally a good idea to try to get the terms in a syntax diagram to line up "nicely" if 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 and, even if that doesn't happen, producing diagrams that are difficult to scan because of the number of characters on a single line.
| |
| ==Examples==
| |
| Code examples are much like syntax diagrams but use the <tt>code</tt>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>
| |
| The standard is to indent code a few spaces to make it stand out from other material.
| |