- Contents
- 1. Introduction
- 2. Document Sections
- 3. Paragraphs
- 4. Lists
- 5. Dividers
- 6. Inline Formatting
- 7. Links
- 8. Sample Code Blocks
- 9. Comments
1. Introduction
The UIZE JavaScript Framework implements a system for building HTML from documentation that is written in a Wikitext like format called Simple Doc.
This document describes the SimpleDoc documentation system and its various formatting rules.
1.1. In a Nutshell
SimpleDoc is a human readable, non-XML, indentation based document format for writing structured documents.
SAMPLE
Section One This is the first paragraph of section one. MY EXAMPLE ........................................................ This is some stuff that should appear in an example box. This is some stuff that should appear in an example box. This is some stuff that should appear in an example box. ........................................................ Below is a bullet list... - bullet list item - another bullet list item - yet another bullet list item Below is an ordered bullet list... 1) ordered list item 1) another ordered list item 1) yet another ordered list item This line contains some *bolded text*. This line contains some _italics_. This line contains some __bolded italics__. This line contains some =inline code=. This line contains some ==bolded inline code==. This line contains a link to `Section Two`. This line contains a link to [[Section Two]]. This line contains a custom titled link to [[Section Two][go to Section Two]]. This line contains a link to the [[http://en.wikipedia.org][Wikipedia]] Web site. This line contains a bolded link to [[http://en.wikipedia.org][*Wikipedia*]]. This line contains an untitled link to the URL [[http://en.wikipedia.org]]. Section Two Nothing to see here. Move along. Move along. ### Commented Section This whole section and all its subsections is commented out.
The above sample SimpleDoc document demonstrates a smattering - but not all - of the formatting rules available in the SimpleDoc format. This document (yes, the one you're reading) explaining SimpleDoc is, itself, written in SimpleDoc.
1.2. Key features...
SimpleDoc has numerous compelling features...
| Human Readable -- because SimpleDoc does not employ XML, it is easier to read in its raw format | |
| Neat and Clean -- avoiding XML means that SimpleDoc text remains neat and clean and can be woven into JavaScript modules for their documentation without making your JavaScript code look cluttered and unwieldy. | |
| Auto Section Linking -- when generating HTML documents from SimpleDoc documents, appropriately formatted section names occurring inside paragraphs are automatically linked to the corresponding sections of the document. | |
| Wiki-like Formatting - bolding, italicizing, linking, and more... and in a way that will appear familiar to anyone with experience editing Wikitext formatted documents. | |
| JavaScript Support -- the UIZE JavaScript Framework provides various modules to support parsing of SimpleDoc documents and rendering them into HTML documents, with the aid of JavaScript Templates and JavaScript build scripts. |
1.3. Indentation Based Structure
Structure in a SimpleDoc document is indicated by indentation, much like the Python programming language.
Put simply, all lines that are indented deeper than a preceding line, and that are indented to the same level, are a document section, where the preceding line is that section's heading.
EXAMPLE
Section One Section One's 1st paragraph. Section One's 2nd paragraph. Section Two Section Two's 1st paragraph. Section Two's 2nd paragraph. Section Two's 3rd paragraph.
Much like Python, SimpleDoc doesn't care about how much indentation is used to start a line - only that other peer lines belonging to the same level in the document's structure are indented the same way. And you can even mix tabs and spaces for indentation in the same document - if you really want to live dangerously.
1.4. Which Editor?
Editing SimpleDoc documents does not require any special editor - any old text editor will do.
That said, however, there are two key features that make editing SimpleDoc documents even more enjoyable...
1.4.1. Folding
Folding (sometimes known by other names) is a feature that allows a structured text document to be collapsed at any level of its hierarchy.
Because structure in SimpleDoc documents is indentation based, folding that can be driven off of indentation is extremely useful when making sense of a large document. The jEdit text editor, which is a Java based (and, therefore, cross-platform) text editor has excellent and highly configurable support for folding, with versatile features for expanding and collapsing parts of a document in different ways. Other folding editors will also suffice.
1.4.2. Soft Wrapping to Indentation Level
While not essential, soft wrapping to the indentation level of the line being wrapped is very helpful in making SimpleDoc documents prettier to look at.
Many text editors support soft-wrapping so that you don't have to have ridiculous horizontal scrolling thrown on top of vertical scrolling. However, many of those text editors will also continue the wrapped line at the extreme left. This is particularly unfortunate, as it breaks the visual flow of the document's structure. Lines wrapped in this way appear to "poke out" of the indentation level they belong to. Once again, jEdit comes to the rescue with just the right behavior in this case.
2. Document Sections
Document structure is achieved with indentation.
All lines that are indented deeper than a preceding line, and that are indented to the same level, are a document section, where the preceding line is that section's heading. The contents of any section can contain any number of further subsections, so arbitrarily complex document structures can be achieved.
SOURCE
This is a Section
This is a Subsection
This is some text in the subsection. This is some text in the subsection. This is some text in the subsection. This is some text in the subsection. This is some text in the subsection. This is some text in the subsection. This is some text in the subsection. This is some text in the subsection. This is some text in the subsection. This is some text in the subsection. This is some text in the subsection. This is some text in the subsection.
This is Another Subsection
This is Just Crazy
Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here.
Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here.
This is Just Even Crazier
Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here.
HOW IT LOOKS
2.1. This is a Section
2.1.1. This is a Subsection
This is some text in the subsection. This is some text in the subsection. This is some text in the subsection. This is some text in the subsection. This is some text in the subsection. This is some text in the subsection. This is some text in the subsection. This is some text in the subsection. This is some text in the subsection. This is some text in the subsection. This is some text in the subsection. This is some text in the subsection.
2.1.2. This is Another Subsection
2.1.2.1. This is Just Crazy
Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here.
Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here.
2.1.2.2. This is Just Even Crazier
Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here. Stuff inside here.
3. Paragraphs
A paragraph is a line of text that is not a section heading, a list item, or a note heading.
A paragraph is terminated by a linebreak. Therefore, paragraphs are separated by linebreaks. Paragraphs do not need to be separated by blank lines, although having a blank line between paragraphs may make the source of a SimpleDoc document easier to read. One or more blank lines separating paragraphs are considered insignificant whitespace and are not reflected in the HTML document that is generated from a SimpleDoc document.
SOURCE
This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 2. This is paragraph 2. This is paragraph 2. This is paragraph 2. This is paragraph 2. This is paragraph 2. This is paragraph 2. This is paragraph 2. This is paragraph 2. This is paragraph 2. This is paragraph 2. This is paragraph 2. This is paragraph 2.
HOW IT LOOKS
This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1. This is paragraph 1.
This is paragraph 2. This is paragraph 2. This is paragraph 2. This is paragraph 2. This is paragraph 2. This is paragraph 2. This is paragraph 2. This is paragraph 2. This is paragraph 2. This is paragraph 2. This is paragraph 2. This is paragraph 2. This is paragraph 2.
4. Lists
The SimpleDoc format provides various means for formatting standard Bullet Lists, Custom Unordered Lists, and Ordered Lists labeled using either numerals or letters.
4.1. Bullet Lists
A bullet list is a series of peer lines that are all started with the same bullet list character, followed by a space.
Bullet list items can be started quite intuitively with any of the characters "-" (hyphen), "*" (asterisk), "~" (tilde), ":" (colon), and "." (period).
4.1.1. Example 1
In the most typical case for a bullet list, one can start each of a contiguous series of lines with a hyphen, separated from the rest of the line by at least one space.
SOURCE
- bullet list item 1 - bullet list item 2 - bullet list item 3
HOW IT LOOKS
| bullet list item 1 | |
| bullet list item 2 | |
| bullet list item 3 |
4.1.2. Example 2
An asterisk is also a valid bullet list item prefix.
SOURCE
* bullet list item 1 * bullet list item 2 * bullet list item 3
HOW IT LOOKS
| bullet list item 1 | |
| bullet list item 2 | |
| bullet list item 3 |
4.1.3. More Examples
Other bullet list item prefixes can also be used.
SOURCE
Using tildes... ~ bullet list item 1 ~ bullet list item 2 Using colons... : bullet list item 1 : bullet list item 2 Using periods... . bullet list item 1 . bullet list item 2
HOW IT LOOKS
Using tildes...
| bullet list item 1 | |
| bullet list item 2 |
Using colons...
| bullet list item 1 | |
| bullet list item 2 |
Using periods...
| bullet list item 1 | |
| bullet list item 2 |
4.2. Ordered Lists
An ordered list is a series of peer lines that are all started with the same ordered list item prefix, followed by a space.
4.2.1. List Item Prefix Syntax
Ordered list items can be started quite intuitively with a prefix that is defined as:
| any number of repetitions of one of the characters "<" (less than sign), "(" (open parenthesis), "{" (open curly brace), or "[" (open square bracket)... | |
| followed, optionally, by any number of spaces... | |
| followed by any one of the numbering style indicators "@" (at sign), "#" (hash / pound), "+" (plus sign), lowercase letters "a" through "z", uppercase letters "A" through "Z", or one or more digits... | |
| followed, optionally, by any number of spaces... | |
| followd by any number of repetitions of one of the characters ">" (greater than sign), ")" (close parenthesis), "}" (close curly brace), or "]" (close square bracket). | |
| followed by one or more spaces. |
According to the above rules, the following would all be valid ordered list items...
1) valid ordered list item
[+] valid ordered list item
a) valid ordered list item
<A> valid ordered list item
<<< # >>> valid ordered list item
{@} valid ordered list item
@ >>> valid ordered list item
4.2.2. Numbering Style Indicators
The numbering style indicators available in SimpleDoc support lists numbered by numbers, lowercase letters, and uppercase letters.
4.2.2.1. Number Labeled Lists
Number labeled lists can be achieved by using either a single "#" (hash / pound) character, a single "+" (plus sign) character, or one or more digits.
SOURCE
Using the digit "1"... 1. list item 1 1. list item 2 1. list item 3 Using the "#" (hash / pound) character... [#] list item 1 [#] list item 2 [#] list item 3 Using the "+" (plus sign) character... +) list item 1 +) list item 2 +) list item 3
HOW IT LOOKS
Using the digit "1"...
| 1. | list item 1 |
| 2. | list item 2 |
| 3. | list item 3 |
Using the "#" (hash / pound) character...
| [1] | list item 1 |
| [2] | list item 2 |
| [3] | list item 3 |
Using the "+" (plus sign) character...
| 1) | list item 1 |
| 2) | list item 2 |
| 3) | list item 3 |
4.2.2.2. Letter Labeled Lists
Letter labeled lists can be achieved by using a single lowercase letter (eg. "a"), a single uppercase letter (eg. "A"), or the "@" (at sign) character.
| lowercase letters - using a single lowercase letter ("a" through "z") will result in labeling using lowercase letters | |
| uppercase letters - using a single uppercase letter ("A" through "Z") will result in labeling using uppercase letters | |
| the at sign - using a single "@" (at sign) character will result in labeling using lowercase letters |
SOURCE
Using a lowercase "a"... (a) list item 1 (a) list item 2 (a) list item 3 Using an uppercase "A"... [A] list item 1 [A] list item 2 [A] list item 3 Using the "@" (at sign) character... @. list item 1 @. list item 2 @. list item 3
HOW IT LOOKS
Using a lowercase "a"...
| (a) | list item 1 |
| (b) | list item 2 |
| (c) | list item 3 |
Using an uppercase "A"...
| [A] | list item 1 |
| [B] | list item 2 |
| [C] | list item 3 |
Using the "@" (at sign) character...
| a. | list item 1 |
| b. | list item 2 |
| c. | list item 3 |
4.2.3. Numbering Style Indicator Replacement
When rendering out an ordered list, the numbering style indicator is replaced with the appropriate numbering for the current line. Consider the following example...
SOURCE
Labeled with numbers... 1. list item 1 1. list item 2 1. list item 3 Labeled with letters... << a >> list item 1 << a >> list item 2 << a >> list item 3
HOW IT LOOKS
Labeled with numbers...
| 1. | list item 1 |
| 2. | list item 2 |
| 3. | list item 3 |
Labeled with letters...
| << a >> | list item 1 |
| << b >> | list item 2 |
| << c >> | list item 3 |
4.2.4. Blank Lines Don't Terminate Lists
It should be noted that lists are not broken by blank lines, only by a line that doesn't follow the syntax for a list item, or by the end of a section.
This is convenient if a list would look more readable in a SimpleDoc document if its items were separated by blank lines. Consider the following example...
SOURCE
1. a long list item that wants to be spaced out from its peers in the SimpleDoc source 1. a long list item that wants to be spaced out from its peers in the SimpleDoc source 1. a long list item that wants to be spaced out from its peers in the SimpleDoc source
HOW IT LOOKS
| 1. | a long list item that wants to be spaced out from its peers in the SimpleDoc source |
| 2. | a long list item that wants to be spaced out from its peers in the SimpleDoc source |
| 3. | a long list item that wants to be spaced out from its peers in the SimpleDoc source |
This behavior has the implication that you can't have two lists one after the other, without some non-list item formatted line to break the two lists apart. Consider the following example...
WRONG! WRONG! WRONG!
1. list item 1 of list 1 2. list item 2 of list 1 3. list item 3 of list 1 1. list item 1 of list 2 2. list item 2 of list 2 3. list item 3 of list 2
HOW IT LOOKS
| 1. | list item 1 of list 1 |
| 2. | list item 2 of list 1 |
| 3. | list item 3 of list 1 |
| 4. | list item 1 of list 2 |
| 5. | list item 2 of list 2 |
| 6. | list item 3 of list 2 |
As you can see, all the items were seen as belonging to the same list, and the list item prefixes were numbered accordingly.
4.2.5. More Examples
4.2.5.1. Example 1
SOURCE
1) ordered list item 1 1) ordered list item 2 1) ordered list item 3
HOW IT LOOKS
| 1) | ordered list item 1 |
| 2) | ordered list item 2 |
| 3) | ordered list item 3 |
4.2.5.2. Example 2
SOURCE
[1] ordered list item 1 [1] ordered list item 2 [1] ordered list item 3
HOW IT LOOKS
| [1] | ordered list item 1 |
| [2] | ordered list item 2 |
| [3] | ordered list item 3 |
4.2.5.3. Example 3
SOURCE
(+) ordered list item 1 (+) ordered list item 2 (+) ordered list item 3
HOW IT LOOKS
| (1) | ordered list item 1 |
| (2) | ordered list item 2 |
| (3) | ordered list item 3 |
4.2.5.4. Example 4
SOURCE
[a] ordered list item 1 [a] ordered list item 2 [a] ordered list item 3
HOW IT LOOKS
| [a] | ordered list item 1 |
| [b] | ordered list item 2 |
| [c] | ordered list item 3 |
5. Dividers
SimpleDoc provides support for two types of horizontal divider lines: a Thin Horizontal Divider, and a Thick Horizontal Divider.
5.1. Thin Horizontal Divider
A thin horizontal divider is denoted by a line containing at least three hyphen characters (dashes), and only hyphen characters.
SOURCE
---------------------------------------------------------------------------
HOW IT LOOKS
It doesn't matter how many hyphens there are in the line, as long as there are at least three. The following lines all denote a thin horizontal divider.
EXAMPLE
-------------------- ---------------------------------------- ------------------------------------------------------------ --------------------------------------------------------------------------------
5.2. Thick Horizontal Divider
A thick horizontal divider is denoted by a line containing at least three equals sign characters, and only equals sign characters.
SOURCE
===========================================================================
HOW IT LOOKS
It doesn't matter how many equals sign characters there are in the line, as long as there are at least three. The following lines all denote a thick horizontal divider.
EXAMPLE
==================== ======================================== ============================================================ ================================================================================
6. Inline Formatting
Inline formatting in a SimpleDoc document is done using Wiki-like formatting rules that will appear familiar to anyone with experience editing Wikitext formatted documents.
6.1. Bolding
Bolding of a segment of text within a paragraph is accomplished by placing an asterisk on either side of the segment that should be bolded.
SOURCE
This is some *bolded text*.
HOW IT LOOKS
This is some bolded text.
6.2. Italicizing
Italicizing of a segment of text within a paragraph is accomplished by placing an underscore on either side of the segment that should be italicized.
SOURCE
This is some _italicized text_.
HOW IT LOOKS
This is some italicized text.
6.3. Bolded Italics
Both bolding and italicizing a segment of text within a paragraph is accomplished by placing two underscores on either side of the segment that should be bolded and italicized.
SOURCE
This is some __bolded and italicized text__.
HOW IT LOOKS
This is some bolded and italicized text.
6.4. Inline Code
Inline code within a paragraph is denoted by placing an equals sign on either side of the segment that should be formatted as inline code.
SOURCE
The statement =myWidth.set ({width:100})= is formatted as inline code.
HOW IT LOOKS
The statement myWidth.set ({width:100}) is formatted as inline code.
6.5. Note Headings
A special kind of note heading is denoted by a paragraph where all the alphabetical characters are uppercased.
Such a note heading may also contain non-alphabetical characters, as long as all the alphabetical characters are uppercase, and as long as the paragraph isn't formatted with a preceding "- " or any other prefix that would flag it as a list item.
Note headings are good for things like NOTES sections, IMPORTANT sections, WARNING sections, EXAMPLE or SAMPLE CODE headings, or for just about any way that you want to call out the contents below it. The nice thing about note headings is that they don't feature in the structure of the document, so they won't show up in the contents tree - you can use them at any level of a document's structure. So, they're more like callouts really.
SOURCE
NOTES - this is note 1 - this is note 2 - NOT A NOTE HEADING IMPORTANT!!! +] don't forget to feed the cat +] don't forget to feed the fish +] don't feed the fish to the cat +] NOT A NOTE HEADING
HOW IT LOOKS
NOTES
| this is note 1 | |
| this is note 2 | |
| NOT A NOTE HEADING |
IMPORTANT!!!
| 1] | don't forget to feed the cat |
| 2] | don't forget to feed the fish |
| 3] | don't feed the fish to the cat |
| 4] | NOT A NOTE HEADING |
6.6. Non-formatted Areas
While paragraphs in a SimpleDoc document can contain Inline Formatting, there are a number of places where formatting is imposed and inline formatting is not possible.
6.6.1. Section Headings
Segments of a section heading cannot be bolded, italicized, formatted as inline code, or contain any other inline formatting.
The entire heading for a section is styled in a single way, as determined by the CSS style sheet that decorates a SimpleDoc document that has been converted to HTML. One cannot use inline formatting within section headings.
WRONG! WRONG! WRONG!
Section Heading With *Bolded Text* The heading for a section CANNOT be formatted with inline formatting rules. Section Heading With _Italicized Text_ The heading for a section CANNOT be formatted with inline formatting rules. Section Heading With =Inline Code= The heading for a section CANNOT be formatted with inline formatting rules.
6.6.2. Example Blocks
Text inside Sample Code Blocks cannot be formatted.
Sample code blocks are, by definition, blocks of text that are displayed exactly as is - all formatting characters are treated literally. Consider the following example...
SOURCE
................................................................................. WHAT YOU CAN'T DO INSIDE SAMPLE CODE BLOCKS - You can't have bullet lists inside sample code blocks. - You can't *bold words* inside sample code blocks. - You can't _italicize words_ inside sample code blocks. - You can't have =inline code= inside sample code blocks. - You can't [[http://www.someplace.com][link to URLs]] inside sample code blocks. ### - You can't comment things out in sample code blocks. - You can't do any other kind of formatting inside sample code blocks. .................................................................................
HOW IT LOOKS
WHAT YOU CAN'T DO INSIDE SAMPLE CODE BLOCKS - You can't have bullet lists inside sample code blocks. - You can't *bold words* inside sample code blocks. - You can't _italicize words_ inside sample code blocks. - You can't have =inline code= inside sample code blocks. - You can't [[http://www.someplace.com][link to URLs]] inside sample code blocks. ### - You can't comment things out in sample code blocks. - You can't do any other kind of formatting inside sample code blocks.
7. Links
Text inside formatted areas of a SimpleDoc document can be linked to either other sections of the document or to arbitrary URLs, using either the backticks syntax or the square brackets syntax.
7.1. Backticks
The backticks syntax allows one to link to other sections in a SimpleDoc document, in a way that is relatively unobtrusive and pleasing to the eyes.
SYNTAX
`Section Name`
Consider the following example...
SOURCE
For further information, consult the section `Links to Sections`.
HOW IT LOOKS
For further information, consult the section Links to Sections.
7.2. Square Brackets
The square brackets syntax allows one to link to sections in a SimpleDoc document or any arbitrary URL, allowing one to specify a section name or URL and a title for the link.
SOURCE
To learn everything under the sun, visit [[http://en.wikipedia.org][Wikipedia]].
HOW IT LOOKS
To learn everything under the sun, visit Wikipedia.
To minimize conflicts with other uses of square brackets, double square brackets are used for denoting titled and untitled linked URLs and document sections.
7.3. Links to URLs
Arbitrary URLs can be linked with the use of the square brackets syntax.
SYNTAX
[[Section Name][Link Text]] [[URL][Link Text]] [[Section Name]] [[URL]]
IMPORTANT
The text inside the first and second pair of inner square brackets should not contain leading or trailing spaces.
7.3.1. Titled Linked URLs
Text can be linked to relative or absolute URLs by using the square brackets syntax and specifying the link inside the first pair of nested square brackets, and the link title in the second pair.
7.3.1.1. Absolute URL Example
SOURCE
Visit the [[http://en.wikipedia.org][Wikipedia Online Encyclopedia]].
HOW IT LOOKS
Visit the Wikipedia Online Encyclopedia.
7.3.1.2. Relative URL Example
SOURCE
For more info, see the explainer [[javascript-templates.html][JavaScript Templates]].
HOW IT LOOKS
For more info, see the explainer JavaScript Templates.
7.3.2. Untitled Linked URLs
Arbitrary relative or absolute URLs can be linked so that the URL is displayed as the link text, by using the square brackets syntax and simply not using the second pair of nested square brackets to specify the link's title.
Consider the following example...
SOURCE
A wealth of information is available at Wikipedia ([[http://en.wikipedia.org]]).
HOW IT LOOKS
A wealth of information is available at Wikipedia (http://en.wikipedia.org).
7.4. Links to Sections
Text in a SimpleDoc document can be linked to a section of that same document by using the backticks syntax or the square brackets syntax.
7.4.1. Section Links Using Backticks
Text that is enclosed by backticks will be linked to a section in the same document, if there is a section whose heading exactly matches the text inside the backticks.
SOURCE
For more info, consult the `Sample Code Blocks` section.
HOW IT LOOKS
For more info, consult the Sample Code Blocks section.
7.4.2. Section Links Using Square Brackets
Text that is linked using the double square brackets syntax will be linked to a section in the same document, if there is a section whose heading exactly matches the URL part of the link (ie. the first pair of nested square brackets).
7.4.2.1. Titled Section Links
When linking to a section using the square brackets syntax, the text that is linked to the section can be different to the section's heading by specifying a title for the link using the second pair of nested square brackets.
SOURCE
[[Sample Code Blocks][learn about sample code block formatting]]
HOW IT LOOKS
7.4.2.2. Untitled Section Links
A link to a section where the linked text is identical to the section's heading can be achieved by using the square brackets syntax and simply not specifying the second pair of nested square brackets.
This syntax produces the same result as and is merely an alternative to Section Links Using Backticks.
SOURCE
Learn more about formatting for [[Sample Code Blocks]].
HOW IT LOOKS
Learn more about formatting for Sample Code Blocks.
NOTES
| in the square brackets syntax for linked text, URLs take precedence over section headings. In order to distinguish between URLs and section headings, the parser does pattern matching. This means that it is not possible to use this syntax to link to a section with a heading like "http://www.uize.com", since the parser's pattern matching will identify this as being an absolute URL. |
7.4.3. Automatically Linked Inline Code
Text that is formatted as inline code is automatically linked to a section in the same document, if there is a section whose heading exactly matches the text inside the equals signs.
This feature is particularly useful for code documentation, where method or property names should be linked to the sections that describe them, and where it is also desirable for such method or property names to be formatted as inline code in paragraphs. The following example doesn't link a method or property name, since this document doesn't describe code and doesn't have any such sections, but imagine that "Sample Code Blocks" was a method name instead...
SOURCE
Learn more about formatting for =Sample Code Blocks=
HOW IT LOOKS
Learn more about formatting for Sample Code Blocks
7.4.4. Considerations
There are a number of considerations that should be kept in mind when doing section linking in SimpleDoc documents.
| section linking is case sensitive - in order for section linking to work, the linked text must exactly match a section heading - including its case | |
| avoid leading and trailing spaces - when specifying the section that your text should link to, avoid having any leading or trailing spaces in the section heading | |
| ambiguities can arise - it is possible within a SimpleDoc document to have multiple sections at different levels of the document's structure that have identical headings. While this is not recommended, it is possible. Therefore, there can be ambiguity when resolving section links, and your text may not link to the section you intended. The only way around this is to use unique headings for all sections. |
7.4.5. Dead Section Links
For any section link that is not matched to a section in the document, the link's title is not linked or decorated (backticks and double square brackets are removed).
7.4.5.1. Example 1
SOURCE
For more info, see the section `Non-existent Section`.
HOW IT LOOKS
For more info, see the section Non-existent Section.
7.4.5.2. Example 2
SOURCE
For more info, see the section [[Non-existent Section]].
HOW IT LOOKS
For more info, see the section Non-existent Section.
7.4.5.3. Example 3
SOURCE
For more info, [[Non-existent Section][see the Non-existent Section]].
HOW IT LOOKS
For more info, see the Non-existent Section.
8. Sample Code Blocks
Blocks of text that should be displayed as is (ie. not be formatted) can be denoted by enclosing them between two lines of periods, tildes, commas, colons, or backticks.
SOURCE
......................................
function myDummyFunction () {
// do something fantastic & amazing
// do something fantastic & amazing
// do something fantastic & amazing
}
......................................
HOW IT LOOKS
function myDummyFunction () {
// do something fantastic & amazing
// do something fantastic & amazing
// do something fantastic & amazing
}
As mentioned earlier, one can use periods, tildes, commas, colons, or backticks for the lines that enclose the block of pre-formatted text. The following sample code block formatting will all produce the same result...
USING TILDES
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
function myDummyFunction () {
// do something fantastic & amazing
// do something fantastic & amazing
// do something fantastic & amazing
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
USING COMMAS
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
function myDummyFunction () {
// do something fantastic & amazing
// do something fantastic & amazing
// do something fantastic & amazing
}
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
USING COLONS
::::::::::::::::::::::::::::::::::::::
function myDummyFunction () {
// do something fantastic & amazing
// do something fantastic & amazing
// do something fantastic & amazing
}
::::::::::::::::::::::::::::::::::::::
USING BACKTICKS
``````````````````````````````````````
function myDummyFunction () {
// do something fantastic & amazing
// do something fantastic & amazing
// do something fantastic & amazing
}
``````````````````````````````````````
Which character you use is mostly just a matter of personal preference, however, this support for multiple characters for denoting sample code blocks is useful when the contents of a sample code block contains a line that looks like a sample code block opener/closer, using the character you would normally use for enclosing sample code blocks. In such cases, you can just switch to one of the several other characters supported.
9. Comments
Portions of SimpleDoc documents can be commented out in two key ways: Section Commenting, and Region Commenting.
9.1. Section Commenting
An entire section - along with all its contents and child sections - can be commented out simply by prefixing the section heading with ### (three hash / pound characters).
EXAMPLE
Section One
This is some text for Section One.
### Section Two
This is a Subsection
This is some text in the subsection.
This is Another Subsection
This is Just Crazy
Stuff inside here.
Stuff inside here.
This is Just Even Crazier
Stuff inside here.
In the above example, "Section Two" is entirely commented out and this SimpleDoc document will only contain "Section One" when it has been parsed and when it is converted to an HTML document.
9.2. Region Commenting
An entire region of a SimpleDoc document can be commented out by using the opener and closer syntax for commenting.
EXAMPLE
Section One This is a paragraph about Ajax. #[ This is a paragraph about XML. This is a paragraph about JavaScript. This is a paragraph about XHTML. #] This is a paragraph about Rich Internet Applications.
In the above example, the three paragraphs about XML, JavaScript, and XHTML are commented out by being enclosed inside a comment region - only the paragraphs about Ajax and Rich Internet Applications remain.
Region commenting is useful for commenting out regions of a SimpleDoc document without regard for the structure contained inside that region, with possible implications for the resulting document structure. Consider the following example...
EXAMPLE
Ajax
This is some text explaining Ajax.
Rich Internet Applications
RIA in a Nutshell
This is some text explaining RIA.
#[
RIA Technologies
JavaScript
A paragraph about JavaScript.
Another paragraph about JavaScript.
#]
Examples of RIA Applications
A paragraph listing examples of RIA applications.
In the above example, most - but not all - of the section "RIA Technologies" has been commented out. However, the section "Examples of RIA Applications" has not been commented out, and because of its indentation level it will become a subsection of the section "RIA in a Nutshell", where previously it was a subsection of "RIA Technologies". By contrast, a section comment on the "RIA Technologies" section would comment out all its contents, including the "Examples of RIA Applications" section.
9.2.1. Region Commenting Syntax
The syntax for region commenting is quite flexible, but must conform to the following rules...
| the comment open marker line must start with a "#" character, followed by one or more of one of the valid opener characters - "(", "[", "{", "<" | |
| the comment close marker line must start with a "#" character, followed by one or more of one of the valid closer characters - ")", "]", "}", ">" | |
| the comment closer character used must be matched to the comment opener character (ie. "(" matches ")", "[" matches "]", "{" matches "}", and "<" matches ">") | |
| the number of opener characters used must match the number of closer characters used (ie. the comment opener "#<<<" matches the comment closed "#>>>", but does not match the comment closer "#>>") |
Below are some examples of valid comment regions...
#[
This paragraph is in a comment region.
#]
#[[
This paragraph is in a comment region.
#]]
#<
This paragraph is in a comment region.
#>
#{
This paragraph is in a comment region.
#}
#{
This paragraph is in a comment region.
#)
9.2.2. Flexible Opener and Closer Markers
Flexibility in the opener and closer markers makes it possible to nest different comment regions.
When using region commenting, a region comment is terminated by the first matching closer. In order to support nesting of comment regions, it is necessary to use different opener and closer markers for the different regions.
EXAMPLE
Ajax
This is some text explaining Ajax.
Rich Internet Applications
#<<
RIA in a Nutshell
This is some text explaining RIA.
#<
RIA Technologies
JavaScript
A paragraph about JavaScript.
Another paragraph about JavaScript.
#>
Examples of RIA Applications
A paragraph listing examples of RIA applications.
#>>
In the above example, the entire contents of section "Rich Internet Applications" - but not the line "Rich Internet Applications" - is commented out. There are two comment regions. The inner comment region uses "#<" and "#>" as opener and closer, while the outer comment region uses "#<<" and "#>>".
WRONG! WRONG! WRONG!
Ajax
This is some text explaining Ajax.
Rich Internet Applications
#<
RIA in a Nutshell
This is some text explaining RIA.
#<
RIA Technologies
JavaScript
A paragraph about JavaScript.
Another paragraph about JavaScript.
#>
Examples of RIA Applications
A paragraph listing examples of RIA applications.
#>
In the above example, Not all of the content of the section "Rich Internet Applications" would be commented out, because the first "#<" opener will be matched to the first "#>" closer, leaving some crud until the second "#>" closer.
9.3. Nested Comments
Comments using both the Section Commenting and the Region Commenting syntax can be nested together in various ways.
9.3.1. Nesting Section Comments
For any section that is commented out, any subsections can also be commented out, and the contents of the section may also contain region comments.
EXAMPLE
### Section One
### Subsection One
This is a paragraph for Subsection One.
#[
Subsection Two
This is a paragraph for Subsection Two.
#]
9.3.2. Nesting Region Comments
For any region that is commented out, any portion of that region can also be commented out using Region Commenting (provided that the subregion uses different opener and closer markers), and any sections contained inside the region can be commented out using Section Commenting.
EXAMPLE
#[[
Section One
### Subsection One
This is a paragraph for Subsection One.
#[
Subsection Two
This is a paragraph for Subsection Two.
#]
#]]