UIZE JavaScript Framework

GUIDES Javascript Documentation System

1. Introduction

The UIZE JavaScript Framework implements a system for building HTML from documentation that is written in a Wikitext like format called SimpleDoc.

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 (see Links to Sections).
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.

2.1. HOW IT LOOKS

2.1.1. This is a Section

2.1.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.1.2. This is Another Subsection

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

2.2. Section Title Aliases

SimpleDoc provides an easy way to specify section title aliases for sections, where the aliases are not displayed but allow sections to be easily linked to by their aliases from other parts of the document.

2.2.1. Section Titles Can Have Multiple Aliases

Any number of section title aliases can be specified for a section, simply by placing the aliases on the same line as the section title, with all the aliases separated using the delimiter pattern of one or more consecutive "~" (tilde) characters surrounded by optional whitespace padding.

EXAMPLE

Example Section ~~ Alias 1 ~~ Alias 2 ~~ Alias N
  This is some text in the section.

Some Other Section
  Now link to the `example section` by its aliases: `alias 1`, `alias 2`, and `alias N`.

In the above example, the section "Example Section" has three section title aliases specified for it: "Alias 1", "Alias 2", and "Alias N". While only the "Example Section" portion will be displayed in the HTML document that is generated from the SimpleDoc document, the aliases can be used when linking to the section from other parts of the document, as can be seen in the first paragraph of the section "Some Other Section".

2.2.1.1. HOW IT LOOKS

2.2.1.1.1. Example Section

This is some text in the section.

2.2.1.1.2. Some Other Section

Now link to the example section by its aliases: alias 1, alias 2, and alias N.

2.2.2. Aliases Not Displayed

When section title aliases are specified for a section title, they are never displayed in the HTML document that is generated from a SimpleDoc document.

Only the first portion of the title - up until the first alias delimiter - is displayed.

2.2.3. Considerations When Linking Using Aliases

When using section title aliases to link to sections, all the same rules apply that would normally apply for displayed section titles.

This means that the same rules for case and whitespace apply and you should keep these in mind when linking using aliases. For more details, see the section Linking Considerations.

2.2.4. Use Cases For Section Title Aliases

Section title aliases can be useful in a number of real world situations, including disambiguating links to sections with the same title, linking using opposite of singular or plural form, and linking using abbreviations or alternate forms.

2.2.4.1. Linking Using Opposite of Singular or Plural Form

While you can generally just link to a section by using its title in a sentence with the backticks syntax for linking, sometimes a section's title is not in the desirable singular or plural form.

If a section's title is singular and you need to use a plural form in a sentence, or if a section's title is plural and you need to use a singular form in a sentence, then you can use the section title aliases feature to specify the alternate form as a section title alias.

EXAMPLE

Child Widgets ~~ Child Widget
  Documentation explaining what child widgets are all about.

Some Other Section
  For every `child widget` that one adds to a parent widget, ...

In the above example, "Child Widgets" is the desired display title for a section, but a sentence wishes to link to the section using a singular form that is grammatically correct in the context. While you could always use the square brackets syntax in this case, by specifying the section title as the section link and specifying the singular form as the linked text, this can become cumbersome if there are many sentences that would like to link to the section using the singular form. Instead, we specify the singular form as the section title alias for the section. Then we can use the more convenient backticks syntax with the singular form alias.

2.2.4.1.1. HOW IT LOOKS
2.2.4.1.1.1. Child Widgets

Documentation explaining what child widgets are all about.

2.2.4.1.1.2. Some Other Section

For every child widget that one adds to a parent widget, ...

2.2.4.2. Linking Using Abbreviations or Alternate Forms

Similar to the case of linking using opposite of singular or plural form, it is sometimes desirable to link to a section with linked text that differs from the section's title.

Of course, you can always just use the square brackets syntax in such cases and specify the alternate form as the linked text, but the section title aliases feature makes it very easy to specify the alternate form as an alias for a section and then link to the section using the more convenient backticks syntax for linking.

EXAMPLE

What is Ajax? ~~ Ajax
  Ajax is a technology that has become a staple for Web 2.0 applications, ...

Developing Ajax Applications
  In order to incorporate `Ajax` into one's Web applications, ...
2.2.4.2.1. HOW IT LOOKS
2.2.4.2.1.1. What is Ajax?

Ajax is a technology that has become a staple for Web 2.0 applications, ...

2.2.4.2.1.2. Developing Ajax Applications

In order to incorporate Ajax into one's Web applications, ...

2.2.4.3. Disambiguating Links to Sections With the Same Title

When situations arise where multiple sections of a SimpleDoc document are to have the same display title, unique section title aliases can be specified for the different sections so that it is still possible to unambiguously link to the sections from other parts of the document.

EXAMPLE

Instance Properties
  children ~~ children Instance Property
    Documentation for the children instance property.

    NOTES
    - see the companion `children state property`

State Properties
  children ~~ children State Property
    Documentation for the children state property.

    NOTES
    - see the companion `children instance property`

In the above example, there are two sections with the display title "children" - one is for the instance property and the other is for the state property. Because the "children Instance Property" and "children State Property" aliases are specified, it is possible for the sections to cross-link to each other, simply by enclosing the aliases in backticks.

2.2.4.3.1. HOW IT LOOKS
2.2.4.3.1.1. Instance Properties
2.2.4.3.1.1.1. children

Documentation for the children instance property.

NOTES

see the companion children state property
2.2.4.3.1.2. State Properties
2.2.4.3.1.2.1. children

Documentation for the children state property.

NOTES

see the companion children instance property
2.2.4.3.2. Section Title Aliases and Square Brackets Links

Using the square brackets syntax for links, it is possible to link ambiguous display titles using unambiguous section title aliases.

EXAMPLE

Instance Properties
  children ~~ children Instance Property
    Documentation for the children instance property.

    NOTES
    - see the companion [[children state property][children]] state property

State Properties
  children ~~ children State Property
    Documentation for the children state property.

    NOTES
    - see the companion [[children instance property][children]] instance property

In the above example, two sections have the same display title. In each section, we're cross-linking to the other section, but only linking the ambiguous display title in each case. We accomplish this by using the square brackets syntax for links and specifying the unambiguous section title aliases as the link part and the ambiguous section titles as the linked text part.

2.2.4.3.2.1. HOW IT LOOKS
2.2.4.3.2.1.1. Instance Properties
2.2.4.3.2.1.1.1. children

Documentation for the children instance property.

NOTES

see the companion children state property
2.2.4.3.2.1.2. State Properties
2.2.4.3.2.1.2.1. children

Documentation for the children state property.

NOTES

see the companion children instance property

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

INCORRECT

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.

INCORRECT

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. Sample Code Blocks Are Non-formatted Areas

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 guide [[javascript-templates.html][JavaScript Templates]].

HOW IT LOOKS

For more info, see the guide 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

learn about sample code block formatting

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. Linking Using Section Title Aliases

Linking to sections using section title aliases is handled in the exact same manner as for the regular section titles that don't have aliases.

So, if a section title alias is defined for a section, then you can link to the section using the alias in any one of the supported linking styles, such as the backticks syntax or the square brackets syntax. Consider the following example...

EXAMPLE

The Section ~~ The Section Title Alias
  This is a section that has a section title alias.

Some Other Section
  Here are some links to `the section`, using the section title alias of the section...

  - Backticks (case preserved) - `The Section Title Alias`
  - Backticks (case differs) - `the section title alias`
  - Square Brackets (case preserved) - [[The Section Title Alias]]
  - Square Brackets (case differs) - [[THE SECTION TITLE ALIAS]]
  - Square Brackets (with alternate linked text) - [[The Section Title Alias][LINK TEXT]]
  - Inline Code (case preserved) - =The Section Title Alias=
  - Inline Code (case differs) - =the section title alias=

7.4.4.1. HOW IT LOOKS

7.4.4.1.1. The Section

This is a section that has a section title alias.

7.4.4.1.2. Some Other Section

Here are some links to the section, using the section title alias of the section...

Backticks (case preserved) - The Section Title Alias
Backticks (case differs) - the section title alias
Square Brackets (case preserved) - The Section Title Alias
Square Brackets (case differs) - THE SECTION TITLE ALIAS
Square Brackets (with alternate linked text) - LINK TEXT
Inline Code (case preserved) - The Section Title Alias
Inline Code (case differs) - the section title alias

7.4.5. Linking Considerations

There are a number of considerations that should be kept in mind when doing section linking in SimpleDoc documents.

7.4.5.1. Linking to the Nearest of Same Named Sections

When multiple sections share the same name, auto linked text links to the one of those same named sections that is nearest to the link.

Just as it is natural to have files with the same name at different places in a large folder structure, so it is natural to sometimes have sections of the same name at different places in a large structured document. When the case arises where multiple sections share the same name, the auto section linking behavior links section links to the section nearest the linked text.

Consider the following example...

SOURCE

MyClass.foo
  Parameters
    This section describes the parameters for the =MyClass.foo= method.

  In-depth
    For a refresher, refer back to the `Parameters` section.

MyClass.bar
  Parameters
    This section describes the parameters for the =MyClass.bar= method.

  In-depth
    For a refresher, refer back to the `Parameters` section.

In the above example, you'll notice that there are two sections named "Parameters". In the references for each of the methods, there are links back to these sections. Now, it's perfectly reasonable for each method reference to have a "Parameters" section, and links to those sections inside the references for those methods would be expected to go to the correct "Parameters" section - not some arbitrarily chosen section named "Parameters" in some other faraway place in the document.

You can see how this works below, where you'll notice that the links to the "Parameters" sections automatically do what you'd expect of them...

7.4.5.1.1. HOW IT LOOKS
7.4.5.1.1.1. MyClass.foo
7.4.5.1.1.1.1. Parameters

This section describes the parameters for the MyClass.foo method.

7.4.5.1.1.1.2. In-depth

For a refresher, refer back to the Parameters section.

7.4.5.1.1.2. MyClass.bar
7.4.5.1.1.2.1. Parameters

This section describes the parameters for the MyClass.bar method.

7.4.5.1.1.2.2. In-depth

For a refresher, refer back to the Parameters section.

7.4.5.1.2. Ambiguities Can Still Arise

Even with the smart behavior of linking to the nearest of same named sections when multiple sections share the same name, ambiguities can still arise that are not resolved correctly.

In the rare occasions where the automagic handling of same named sections in section linking does not produce the intended linking, the only guaranteed way around this is to use unique headings for these problem cases - there is currently no way to explicitly disambiguate individual links.

7.4.5.2. Whitespace Considerations

When specifying the section that your text should link to, avoid having any leading or trailing spaces in the section title.

Additionally, whitespace separating words in the section title you specify should match the whitespace separating words in the actual heading of the section you're trying to link to.

7.4.5.3. Section Linking is Case-insensitive

Links to sections in SimpleDoc documents are case insensitive, which allows linked section names to be used more naturally in sentences.

When specifying the name of a section that is to be linked to in an area that supports inline formatting, the name does not need to exactly match the case used in the section's heading. This is particularly useful when using a linked section name as part of a larger sentence, where retaining the section name's real capitalization would produce a sentence that looks awkward.

Consider the following example...

SOURCE

The First Section
  Here is some profound (or not) stuff inside the first section.

The Second Section
  Here are some links to the first section, using different case...

  - This is a link to `the first section` (using all lowercase).
  - This is a link to `The First Section` (using the section's real case).
  - This is a link to `THE FIRST SECTION` (using all uppercase).

You can see how this works below, where you'll notice that all the links to the first section work as desired, even though they all have different case, and two of the section links don't match the real case of the first section's heading.

7.4.5.3.1. HOW IT LOOKS
7.4.5.3.1.1. The First Section

Here is some profound (or not) stuff inside the first section.

7.4.5.3.1.2. The Second Section

Here are some links to the first section, using different case...

This is a link to the first section (using all lowercase).
This is a link to The First Section (using the section's real case).
This is a link to THE FIRST SECTION (using all uppercase).
7.4.5.3.2. Exact Case Matches Take Priority

When a document contains multiple sections that are named the same but are only different in their case, exact case matches take priority with any links to those sections - even taking priority over the behavior of linking to the nearest of same named sections.

Matching the section title specified in a section link to an actual section in the document is done using a two phase approach, with a first attempt at matching the specified section title to a section's actual heading done in a case sensitive way, and with a fallback to performing a case-insensitive match. The benefit to the two phase matching approach, rather than always just doing a case-insensitive match, is that the system can still support situations where case may be important - where different sections that you may wish to link to have headings that are the same except for their case.

Consider the following example...

SOURCE

Constants
  INITIALIZED
    This is the reference for the constant.

    NOTES
    - compare to the =initialized= instance property

Instance Properties
  initialized
    This is the reference for the instance property.

    NOTES
    - compare to the =INITIALIZED= constant

You can see how this works below, where you'll notice that the cross-referencing links between the reference for the constant and the instance property work as desired - even though section linking is case-insensitive. And, clearly the behavior of linking to the nearest of same named sections is taking a back seat, or the links in the NOTES sections would just link straight to the sections containing them.

7.4.5.3.2.1. HOW IT LOOKS
7.4.5.3.2.1.1. Constants
7.4.5.3.2.1.1.1. INITIALIZED

This is the reference for the constant.

NOTES

compare to the initialized instance property
7.4.5.3.2.1.2. Instance Properties
7.4.5.3.2.1.2.1. initialized

This is the reference for the instance property.

NOTES

compare to the INITIALIZED constant

And, of course, in the event that there are multiple sections whose names are exact case matches for a particular section link, then the actual section that is linked to will be determined by the behavior of linking to the nearest of same named sections. The same rule applies if there are no exact case matches but multiple case-insensitive matches.

7.4.6. Dead Section Links

For any section link that is not matched to a section in the document, the link's text is not linked or decorated (backticks and double square brackets are removed).

7.4.6.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.6.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.6.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. Object Blocks

Object blocks are specially formatted blocks whose contents are given special handling, examples of which include the HTML object block, the samplecode object block (including the more concise form of sample code blocks), and the table object block.

8.1. Format of Object Blocks

The format of an object block consists of three key parts: the object block enclosing lines, the object block type declaration, and the object block data.

As an introduction to the formatting of object blocks, consider the following example of an HTML object block...

EXAMPLE

..............................................................
<< HTML >>

code::
  <div style="font-weight:bold; color:#f00; font-size:20px;">
    This is some Arbitrary HTML
  </div>
..............................................................

In the above example you will see the three key parts of the format for object blocks: the two enclosing lines of periods (see object block enclosing lines), the "<< HTML >>" line that declares the type of the object block (see object block type declaration), and the declaration of a value for the code property (see object block data) that is supported by the HTML object block and that specifies the actual HTML code to be inserted into the HTML document that is generated from the SimpleDoc document.

8.2. How Object Blocks Are Processed

When an object block is encountered when generating an HTML document from a SimpleDoc document, the following steps are performed...

1.  The type of the object block is parsed out from the object block type declaration.
2.  The output generator template for the object block type is looked up from the list of supported object blocks.
3.  The object block data is parsed out from contents of the object block.
4.  The parsed out object block data is supplied to the output generator template for the object block type.
5.  The HTML generated by the output generator template is inserted into the generated HTML document.

8.2.1. Special Handling for Sample Code Blocks

As a convenient shorthand, blocks that are enclosed in object block enclosing lines but that do not contain an object block type declaration are given special handling as sample code blocks.

8.3. Parts of an Object Block

The three key parts of an object block - the object block enclosing lines, the object block type declaration, and the object block data - are described in further detail below...

8.3.1. Object Block Enclosing Lines

Object blocks are denoted by enclosing their contents between two enclosing lines - the first of which is the object block opener, and the second of which is the object block closer.

The contents of an object block is contained between the object block enclosing lines and is comprised of the other two key parts of an object block: the the object block type declaration and the object block data. The enclosing lines for an object block must conform to the rules for object block enclosing lines.

The following example of an HTML object block shows the two enclosing lines of the block made up of a series of "." (period) characters...

EXAMPLE

..............................................................
<< HTML >>

code::
  <div style="font-weight:bold; color:#f00; font-size:20px;">
    This is some Arbitrary HTML
  </div>
..............................................................

8.3.1.1. Rules for Object Block Enclosing Lines

Object block enclosing lines must conform to the following rules...

They must consist of two or more of the same characters - either "." (period), "~" (tilde), "," (comma), ":" (colon), or "`" (backtick) characters. Enclosing lines may not contain a mix of these characters - all the characters must be the same. Furthermore, enclosing lines may not contain any additional superfluous characters (not even whitespace padding interspersed between the permitted characters) - they must be solid from start to end.
Both the block opener and block closer lines must use the same character (but they do not have to be the same length). So, for example, you couldn't open a block using a line consisting of periods, and then close that same block using a line consisting of tildes. You can use different characters for enclosing lines of different blocks, but the characters must be the same for enclosing lines of the same block.
Both the opener and closer enclosing lines for a block must be at the same indent level in the document. This means that you can have a line inside the contents of an object block that uses the same characters as the opener enclosing line for the block, but it will not close the block as long as it's at a deeper indent level.

8.3.1.2. Examples of Different Enclosing Lines

The rules for object block enclosing lines permit the use of periods, tildes, commas, colons, or backticks for the enclosing lines, so all of the examples below are equally valid and would produce the same output...

USING PERIODS

..............................................................
<< HTML >>

code::
  <div style="font-weight:bold; color:#f00; font-size:20px;">
    This is some Arbitrary HTML
  </div>
..............................................................

USING TILDES

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
<< HTML >>

code::
  <div style="font-weight:bold; color:#f00; font-size:20px;">
    This is some Arbitrary HTML
  </div>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

USING COMMAS

,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
<< HTML >>

code::
  <div style="font-weight:bold; color:#f00; font-size:20px;">
    This is some Arbitrary HTML
  </div>
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,

USING COLONS

::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
<< HTML >>

code::
  <div style="font-weight:bold; color:#f00; font-size:20px;">
    This is some Arbitrary HTML
  </div>
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

USING BACKTICKS

``````````````````````````````````````````````````````````````
<< HTML >>

code::
  <div style="font-weight:bold; color:#f00; font-size:20px;">
    This is some Arbitrary HTML
  </div>
``````````````````````````````````````````````````````````````

8.3.1.3. Prettiness of Object Block Enclosing Lines

While the rules for object block enclosing lines no not require that the lines be of any particular length (besides being two or more characters), it is a convention to make the block opener and block closer lines match in length, and both be as long as the longest line in the contents of the block.

This "prettiness" convention is in the spirit of the human readability and human friendliness of SimpleDoc documents. So, while the following example block is technically correct and perfectly acceptable, the second version below it is admittedly prettier to look at and is, therefore, the recommended style. When scanning one's eyes through a SimpleDoc document, blocks with the longer enclosing lines stand out more effectively as blocks.

TECHNICALLY CORRECT

..
<< HTML >>

code::
  <div style="font-weight:bold; color:#f00; font-size:20px;">
    This is some Arbitrary HTML
  </div>
..

PRETTIER (RECOMMENDED)

..............................................................
<< HTML >>

code::
  <div style="font-weight:bold; color:#f00; font-size:20px;">
    This is some Arbitrary HTML
  </div>
..............................................................

8.3.2. Object Block Type Declaration

The type of an object block is specified in the Object Block Type Declaration, which appears at the head of the contents of an object block.

EXAMPLE

..............................................................
<< HTML >>

code::
  <div style="font-weight:bold; color:#f00; font-size:20px;">
    This is some Arbitrary HTML
  </div>
..............................................................

In the above example, the line "<< HTML >>" is the object block type declaration, which in this case declares the block to be an HTML object block.

8.3.2.1. Rules for the Object Block Type Declaration

The following rules apply to the object block type declaration (which are discussed in further detail in the sections below)...

It must be first line of object block's contents.
The type declaration is case-insensitive.
All whitespace padding in the type declaration is ignored.
Any blocks of unrecognized type are ignored.
8.3.2.1.1. Must be First Line of Object Block's Contents

The object block type declaration must be the first line of the object block's contents.

One implication of this rule is that any subsequent lines that may look like an object block type declaration will not treated as such. Consider the following example...

SOURCE

................
<< samplecode >>

code::
  << html >>
................

In the above example, the line "<< html >>" is not the first line of the object block's contents, so it's treated just like any other text would be treated in the same place. In this case, it's the value of the code property for the samplecode object block.

HOW IT LOOKS

<< html >>
8.3.2.1.2. Type Declaration is Case-insensitive

The object block type declaration is case-insensitive, so you can lowercase, uppercase, capitalize, camelCase, or otherwise case the name of the object block type - it's a matter of personal taste.

This means that the following three examples are effectively equivalent and would produce the same output...

ALL UPPERCASE

..............................................................
<< HTML >>

code::
  <div style="font-weight:bold; color:#f00; font-size:20px;">
    This is some Arbitrary HTML
  </div>
..............................................................

ALL LOWERCASE

..............................................................
<< html >>

code::
  <div style="font-weight:bold; color:#f00; font-size:20px;">
    This is some Arbitrary HTML
  </div>
..............................................................

MIXED CASE

..............................................................
<< Html >>

code::
  <div style="font-weight:bold; color:#f00; font-size:20px;">
    This is some Arbitrary HTML
  </div>
..............................................................
8.3.2.1.3. Whitespace Padding in the Type Declaration is Ignored

Whitespace padding around and inside the object block type declaration is simply ignored (however, the type name, itself, may not contain added spaces).

This means that the following three examples are effectively equivalent and would produce the same output...

LEADING WHITESPACE

..............................................................
                           <<HTML>>

code::
  <div style="font-weight:bold; color:#f00; font-size:20px;">
    This is some Arbitrary HTML
  </div>
..............................................................

SPACES AROUND THE TYPE NAME

..............................................................
<< HTML >>

code::
  <div style="font-weight:bold; color:#f00; font-size:20px;">
    This is some Arbitrary HTML
  </div>
..............................................................

NO WHITESPACE

..............................................................
<<HTML>>

code::
  <div style="font-weight:bold; color:#f00; font-size:20px;">
    This is some Arbitrary HTML
  </div>
..............................................................
8.3.2.1.4. Blocks of Unrecognized Type Are Ignored

If the type specified in the object block type declaration is not recognized as a supported object block type, then the object block is simply ignored - it generates no output.

Consider the following example...

SOURCE

.........................
<< foobar >>

sillyProperty::
  Bar, bar, black sheep,
  Have you any foo?
  Yes sir, yes sir,
  three bags foo.
.........................

HOW IT LOOKS

As you'll notice, "how it looks" is like nothing. That's because SimpleDoc doesn't support a foobar object block as one of its built-in object blocks (perhaps it should, but one is left to wonder as to what it might do).

8.3.3. Object Block Data

The data for an object block is specified in the Object Block Data section, which appears right after the object block type declaration line.

EXAMPLE

..............................................................
<< HTML >>

code::
  <div style="font-weight:bold; color:#f00; font-size:20px;">
    This is some Arbitrary HTML
  </div>
..............................................................

In the above example, the object block data for the HTML object block is all the text following the "<< HTML >>" type declaration, up until the block closer line. The data, which is specified in SimpleData format, defines a value for the code property that is supported by the HTML object block.

8.3.3.1. Rules for Object Block Data

Object block data must conform to the following rules...

Object block data must be specified using either SimpleData format or JSON format.
The specific properties that can be specified in the object block data will depend on the type of the object block.
Unlike in the case of the object block type declaration, property names for object block data are case-sensitive and must be specified using the correct case (as defined by the specific type of object block being used).
The order of properties specified in the object block data is not important - they are like attributes of HTML tags in this sense and can appear in any order.
Any properties specified in the object block data that are not supported by the type of object block being used (including properties that are specified using the incorrect case) will simply be ignored.

8.3.3.2. SimpleData Format for Object Block Data

In the cleanest form, object block data can be specified in SimpleData format as follows...

EXAMPLE

...........................................
<< widget >>

widgetClass: Uize.Widgets.Calculator.Widget
size: small
...........................................

Bear in mind that using SimpleData format does not allow you to differentiate between string, number, and boolean types for property values - all non-array and non-object values for nodes in a SimpleData data structure are string. If it is important to the object block type that some properties of the object block data have non-string type values, then you will need to use JSON format for object block data.

8.3.3.3. JSON Format for Object Block Data

In cases where type for property values of the object block data is important (ie. boolean vs number vs string, etc.), the data can be specified in JSON format as follows...

.................................................
<< widget >>

{
  widgetClass: 'Uize.Widgets.Calculator.Widget',
  size: 'small'
}
.................................................

This provision can be particularly useful for object block types where it is important to specify values using specific value types, such as when specifying widget properties in a widget object block.

8.3.3.4. Open Curly Brace Means JSON

Choosing between treating the object block data as JSON formatted versus SimpleData formatted follows a very simple rule: if the first non-whitespace character of the object block data is a "{" (open curly bracket) character, then the data is treated as being JSON formatted.

Technically, this means that you couldn't have an object block type whose data supports root-level properties whose names begin with a curly brace and then use SimpleData format for specifying the object block data when embedding that object block type in documents. In practice, this just isn't a concern worth worrying about.

8.4. Built-in Object Blocks

The SimpleDoc HTML document generator supports a number of built-in object blocks, including the HTML object block, the samplecode object block, and the table object block.

8.4.1. HTML Object Block

The HTML Object Block is one of the built-in object blocks and allows the insertion of arbitrary chunks of HTML into the HTML document generated from a SimpleDoc document.

The HTML object block is useful in cases where the formatting rules of SimpleDoc are just not capable of doing something that can be done in some slick HTML code. In these situations, the HTML object block lets you bypass the formatting process of SimpleDoc for a specific block of raw HTML code that you would like to drop into the generated HTML document as is.

The HTML object block is arguably the simplest of all the built-in object blocks. There is only one property that can be specified for its object block data - namely, the code property, which lets you specify the raw HTML code you'd like inserted into the generated HTML document. Consider the following example...

SOURCE

....................................................
<< HTML >>

code::
  <div style="font-weight:bold; color:#f00;">
    <span style="font-size:14px;">This</span>
    &nbsp;
    <span style="font-size:18px;">is</span>
    &nbsp;
    <span style="font-size:22px;">some</span>
    &nbsp;
    <span style="font-size:26px;">arbitrary</span>
    &nbsp;
    <span style="font-size:30px;">HTML</span>
  </div>
....................................................

HOW IT LOOKS

This   is   some   arbitrary   HTML

What you'll notice from the above example is that the multi-line value format is being used for specifying the value of the code property of the object block data. This format involves placing a "::" (double colon) after the property's name, then specifying the multi-line value starting on a new line, with the entire multi-line value indented a level deeper - don't worry, the extra indent is removed by the SimpleData parser.

8.4.2. samplecode Object Block

The samplecode Object Block is one of the built-in object blocks and allows the insertion of sample code into the HTML document generated from a SimpleDoc document.

Sample code that is inserted using the samplecode object block is formatted in the same way as sample code blocks (sample code blocks are actually just a convenient shorthand syntax for defining samplecode object blocks without the more formal syntax of the samplecode object block). The sample code, itself, is specified using the code property. Consider the following example...

SOURCE

...........................
<< samplecode >>

code::
  This is some sample code
  This is some sample code
  This is some sample code
...........................

HOW IT LOOKS

This is some sample code
This is some sample code
This is some sample code

While the syntax for sample code blocks is simpler and cleaner, the formal samplecode object block syntax is useful in cases where the first line of sample code looks like an object block type declaration (see the section When Sample Code Blocks Look Like Object Blocks), or when the sample code may contain lines that look like object block enclosing lines that would inadvertantly terminate the sample code blocks (see the section Dodging Conflicts in Enclosing Line Characters). In these situations, the samplecode object block is the fail-safe and truly robust way to include sample code without having to worry about the aforementioned issues.

8.4.3. table Object Block

The table Object Block is one of the built-in object blocks and allows the insertion of tabular data into the HTML document generated from a SimpleDoc document.

The table object block provides a way to insert tabular data in a way that is human readable inside a SimpleDoc document, and that is also formatted appropriately as a table in the HTML document generated from a SimpleDoc document. Consider the following example...

SOURCE

...........................................................................................
<< table >>

title: Nutritional Information for Various Fruits
data
:| Name     | Calories | Fat    | Carbs  | Fiber | Sugars | Protein | Calcium | Potassium |
:| Apples   | 52 kcal  | .17g   | 13.81g | 2.4g  | 10.39g | .26g    | 6g      | 107mg     |
:| Avocados | 160 kcal | 14.66g | 8.53g  | 6.7g  | .66g   | 2g      | 12g     | 485mg     |
:| Bananas  | 89 kcal  | .33g   | 22.84g | 2.6g  | 12.23g | 1.09g   | 5g      | 358mg     |
:| Dates    | 277 kcal | .15g   | 74.97g | 6.7g  | 66.47g | 1.81g   | 64g     | 696mg     |
:| Oranges  | 49 kcal  | .15g   | 12.54g | 2.2g  | 8.5g   | .91g    | 43g     | 166mg     |
:| Pears    | 58 kcal  | .12g   | 15.46g | 3.1g  | 9.8g   | .38g    | 9g      | 119mg     |
:| Plums    | 46 kcal  | .28g   | 11.42g | 1.4g  | 9.92g  | .7g     | 6g      | 157mg     |
...........................................................................................

HOW IT LOOKS

Nutritional Information for Various Fruits
Name Calories Fat Carbs Fiber Sugars Protein Calcium Potassium
Apples 52 kcal .17g 13.81g 2.4g 10.39g .26g 6g 107mg
Avocados 160 kcal 14.66g 8.53g 6.7g .66g 2g 12g 485mg
Bananas 89 kcal .33g 22.84g 2.6g 12.23g 1.09g 5g 358mg
Dates 277 kcal .15g 74.97g 6.7g 66.47g 1.81g 64g 696mg
Oranges 49 kcal .15g 12.54g 2.2g 8.5g .91g 43g 166mg
Pears 58 kcal .12g 15.46g 3.1g 9.8g .38g 9g 119mg
Plums 46 kcal .28g 11.42g 1.4g 9.92g .7g 6g 157mg

8.4.3.1. table Object Block Properties

The table object block supports two properties in its object block data: the title property and the data property.

8.4.3.1.1. title

The title property of the table object block allows an optional title to be specified for the table.

The title property is optional - if it is not specified, the table will simply not have a title. If a title is specified, then the specified title will appear in a title row at the top of the table. Like column values specified in the row data for the table, the title is a non-formatted area.

WITH A TITLE

Fruits Table
Name Calories Fat Carbs
Apples 52 kcal .17g 13.81g
Avocados 160 kcal 14.66g 8.53g

WITHOUT A TITLE

Name Calories Fat Carbs
Apples 52 kcal .17g 13.81g
Avocados 160 kcal 14.66g 8.53g
8.4.3.1.2. data

The data property of the table object block is required and allows the row data for the table to be specified.

8.4.3.1.2.1. Table Data is a Two Dimensional Array

The value of the data property must be a two dimensional array (ie. an array of arrays), where the outer array represents the rows of the table, and where each element of this rows array is an array of column values.

Because the object block data is specified using the SimpleData format, there are numerous available options for expressing the two dimensional table data array (see the section Alternative Table Rows Formatting), including the most common / suggested form shown in the earlier example.

8.4.3.1.2.2. First Row is Treated as Column Headings

The first row of the table data is treated as the headings row - the values in the array for the first row are the heading names and are styled as such when the table object block is processed and a real HTML table is generated from it.

8.4.3.1.2.3. Must Be at Least Two Rows

A limitation of the table object block is that there must be at least two rows of table data specified.

This is not usually a problem, however, as the first row is treated as column headings.

8.4.3.1.2.4. Column Values Are Non-formatted Areas

As with the title property, column values specified in the row data for the table are non-formatted areas.

This means that you can't do bolding, italicizing, linking, etc. inside column values.

8.4.3.2. Alternative Table Rows Formatting

Table data specified in the data property of a table object block is declared using the SimpleData format, and this versatile yet easily readable format offers numerous alternatives for expressing a two dimensional array of data, some of which are shown in the sections below...

8.4.3.2.1. Standard Array Syntax for Rows, But Without Prettifying

While the pipe-delimited array value syntax of SimpleData allows row data to be formatted so that the pipes of successive rows line up, this is by no means required.

If you don't want to fuss with lining up pipes and maintaining a pretty table form in the SimpleDoc source as new table rows are added or as column values are changed, you don't have to. The following example shows how the table row data can be specified using the pipe syntax, but without the pretty padding that would line up the pipes to create the appearance of a table in the SimpleDoc source...

SOURCE

.................................
<< table >>

title: Fruits Table
data
:|Name|Calories|Fat|Carbs|
:|Apples|52 kcal|.17g|13.81g|
:|Avocados|160 kcal|14.66g|8.53g|
.................................

Now, the table data may not look pretty in the SimpleDoc source, but you still get a nice table in the generated HTML...

HOW IT LOOKS

Fruits Table
Name Calories Fat Carbs
Apples 52 kcal .17g 13.81g
Avocados 160 kcal 14.66g 8.53g
8.4.3.2.2. Repeating the Key Name

The SimpleData format allows an array of valuea to be specified for a key at a certain level by specifying multiple values for the same key at that level.

The SimpleData format also allows the key name to be omitted when specifying multiple values for the same key in a row. While that facility proves to be attractive for specifying row data for a table object block, the following example shows how the key can be specified each time...

SOURCE

..............................................
<< table >>

title: Fruits Table
data:| Name     | Calories | Fat    | Carbs  |
data:| Apples   | 52 kcal  | .17g   | 13.81g |
data:| Avocados | 160 kcal | 14.66g | 8.53g  |
..............................................

HOW IT LOOKS

Fruits Table
Name Calories Fat Carbs
Apples 52 kcal .17g 13.81g
Avocados 160 kcal 14.66g 8.53g
8.4.3.2.3. Using the One-element-per-line Syntax

The SimpleData format allows array values to be specified using a special syntax where each line of an indented, multi-line section is treated as an array element.

This special syntax, which uses the special continuation value ">", is shown in the example below...

SOURCE

...................
<< table >>

title: Fruits Table
data
:>
  Name
  Calories
  Fat
  Carbs
:>
  Apples
  52 kcal
  .17g
  13.81g
:>
  Avocados
  160 kcal
  14.66g
  8.53g
...................

There are two things going on in the above example: one is the omission of the data key in multiple successive assignments to it, and the other is the special ">" syntax for specifying arrays for each data row of the table using indented, multi-line sections.

HOW IT LOOKS

Fruits Table
Name Calories Fat Carbs
Apples 52 kcal .17g 13.81g
Avocados 160 kcal 14.66g 8.53g
8.4.3.2.4. Using the Nested Array Syntax

The SimpleData format provides an elegant and uncluttered syntax for specifying nested arrays, which is shown in the example below...

SOURCE

...................
<< table >>

title: Fruits Table
data
:
  : Name
  : Calories
  : Fat
  : Carbs
:
  : Apples
  : 52 kcal
  : .17g
  : 13.81g
:
  : Avocados
  : 160 kcal
  : 14.66g
  : 8.53g
...................

HOW IT LOOKS

Fruits Table
Name Calories Fat Carbs
Apples 52 kcal .17g 13.81g
Avocados 160 kcal 14.66g 8.53g
8.4.3.2.5. Using the Nested Array Syntax With Multi-line Value Syntax

When using the nested array syntax of the SimpleData format for specifying table row data, column values can be specified using the multiline value syntax.

This special syntax, which uses the special continuation value ":", is shown in the example below...

SOURCE

...................
<< table >>

title: Fruits Table
data
:
  ::
    Name
  ::
    Calories
  ::
    Fat
  ::
    Carbs
:
  ::
    Apples
  ::
    52 kcal
  ::
    .17g
  ::
    13.81g
:
  ::
    Avocados
  ::
    160 kcal
  ::
    14.66g
  ::
    8.53g
...................

HOW IT LOOKS

Fruits Table
Name Calories Fat Carbs
Apples 52 kcal .17g 13.81g
Avocados 160 kcal 14.66g 8.53g

8.4.4. widget Object Block

SimpleDoc supports widget object blocks, allowing you to embed encapsulated widgets in SimpleDoc documents.

In order to embed a widget at some place in a SimpleDoc document, simply add an object block of type "widget" and specify the properties for the widget using either SimpleData format or JSON format, paying attention to specify a valid widget class name using the widgetClass property.

EXAMPLE

...........................................
<< widget >>

widgetClass: Uize.Widgets.Calculator.Widget
size: tiny
...........................................

HOW IT LOOKS

Voila! A fully functioning calculator widget inside this SimpleDoc document.

8.4.4.1. Specify Widget Properties

Just like any other types of object blocks, object block data for widget object blocks can be specified using SimpleData format or JSON format.

So, for example, the following widget object block...

...........................................
<< widget >>

widgetClass: Uize.Widgets.Calculator.Widget
size: tiny
...........................................

...could also be written as...

.................................................
<< widget >>

{
  widgetClass: 'Uize.Widgets.Calculator.Widget',
  size: 'tiny'
}
.................................................

Because the SimpleData format does not allow you to differentiate between string, number, and boolean types for property values - all non-array and non-object values for nodes in a SimpleData data structure are string - you may wish to stick with JSON format whenever embedding a widget object block, since there's a good change that some widget classes will require certain properties to be of specific types.

8.4.4.2. Encapsulated Widgets

In order for widget object blocks to be of practical use, the widget classes used will need to be for encapsulated widgets - widgets that encapsulate their associated HTML and CSS.

To preview UIZE's built-in encapsulated widgets, consult the Widget Visual Samplers example page.

9. Sample Code Blocks

Sample Code Blocks are a convenient way to insert blocks of sample code into a SimpleDoc document, using a concise shorthand syntax.

9.1. Sample Code Blocks Are Special Object Blocks

Sample code blocks are simply object blocks that are missing an object block type declaration, and such blocks are given special handling.

When an object block is missing an object block type declaration, it is treated as a samplecode Object Block where the entire contents of the block is used as the value for the code property that is supported by the samplecode Object Block.

This means that the following two examples are effectively equivalent and would produce the same output...

SAMPLE CODE BLOCK - SHORTHAND SYNTAX

...........................
Look, ma! Some sample code!
...........................

SAMPLE CODE BLOCK - FORMAL OBJECT BLOCK SYNTAX

..............................
<< samplecode >>

code::
  Look, ma! Some sample code!
..............................

9.2. No Inline Formatting Inside Sample Code Blocks

Text inside sample code blocks cannot be formatted (for a more detailed discussion on this, see the section Sample Code Blocks Are Non-formatted Areas).

9.3. When Sample Code Blocks Look Like Object Blocks

Sample code blocks may not start with text of the form "<< block type >>" as the first line of their contents, or that line would be confused for an object block type declaration of the more formal syntax for object blocks.

In the rare event that you need to start the contents of a sample code block with a line of text that follows the syntax of an object block type declaration (ie. "<< block type >>"), you can used the built-in samplecode Object Block, as follows...

INSTEAD OF...

.................................................................................
<< notIntendedToBeAnObjectBlock >>

This block may look like an object block because of the format of the first line.
.................................................................................

USE...

....................................................................................
<< samplecode >>

code::
  << notIntendedToBeAnObjectBlock >>

  This block may look like an object block because of the format of the first line.
....................................................................................

9.3.1. Only When First Line Looks Like Object Block Type Declaration

Because the rules for the object block type declaration require that the type declaration be the first line of the contents of an object block, having lines inside sample code blocks that look like an object block type declaration only becomes an issue if such lines are at the head of the contents.

So, for example, the following sample code block is perfectly ok and would not be confused with the formal object block syntax...

SOURCE

.......................................................................................
These lines that look like object block type declarations are treated as sample code...

<< html >>
<< samplecode >>
<< table >>
.......................................................................................

HOW IT LOOKS

These lines that look like object block type declarations are treated as sample code...

<< html >>
<< samplecode >>
<< table >>

9.4. Dodging Conflicts in Enclosing Line Characters

Conflicts between object block enclosing lines and the contents of sample code blocks can be avoided by switching to different characters for the enclosing lines, or by using the formal samplecode object block.

According to the rules for object block enclosing lines, object block enclosing lines may be made up of two or more periods, tildes, commas, colons, or backticks. Which character you use is mostly just a matter of personal preference, however, this support for different 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. Consider the following example...

INCORRECT

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|      FRUIT NUTRITION INFORMATION      |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|   NAME   | CALORIES |   FAT  | CARBS  |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
| Apples   | 52 kcal  | .17g   | 13.81g |
| Avocados | 160 kcal | 14.66g | 8.53g  |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The above sample code block is problematic, because its object block enclosing lines consist of tildes while the text only table inside the block's contents also has lines consisting of tildes. This will confuse the SimpleDoc parser regarding where the block actually ends - it will be terminated early. This problem can be solved quite easily by switching the enclosing lines to use periods instead of tildes, as shown below...

CORRECT

.........................................
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|      FRUIT NUTRITION INFORMATION      |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|   NAME   | CALORIES |   FAT  | CARBS  |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
| Apples   | 52 kcal  | .17g   | 13.81g |
| Avocados | 160 kcal | 14.66g | 8.53g  |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.........................................

Of course, another way to avoid the issue of conflicting enclosing line characters is to use the formal samplecode object block, as shown below...

ALSO CORRECT

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
<< samplecode >>

code::
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  |      FRUIT NUTRITION INFORMATION      |
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  |   NAME   | CALORIES |   FAT  | CARBS  |
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  | Apples   | 52 kcal  | .17g   | 13.81g |
  | Avocados | 160 kcal | 14.66g | 8.53g  |
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In this case, the multi-line value of the code property is indented, and the rules for object block enclosing lines require that the opener and closer enclosing lines for a block be at the same indent level. This means that none of the lines in the multi-line value of the code property can confuse the parser, and so this is the fail-safe and truly robust way to include sample code without having to worry about enclosing line character conflicts. Of course, such conflicts are not generally a practical concern, and the formal samplecode object block is a little less elegant / simple, so it is not used as often.

10. Comments

Portions of SimpleDoc documents can be commented out in two key ways: section commenting, and region commenting.

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

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

10.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.
#)

10.2.2. Flexible Opener and Closer Markers

Flexibility in the opener and closer markers allows us 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 "#>>".

INCORRECT

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.

10.3. Nested Comments

Comments using both the section commenting and the region commenting syntax can be nested together in various ways.

10.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.
  #]

10.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.
  #]
#]]

11. SimpleDoc Previewing Utility

As part of the UIZE JavaScript Framework's documentation system, a SimpleDoc previewing utility is provided to assist with authoring and editing SimpleDoc documents.

Why a previewing utility? Certainly, once one has gotten the hang of writing documentation in the SimpleDoc format, one hardly has any hunger for WYSIWYG editing. That said, it is nice to see an updated preview of a document one is working on after key changes are made. The previewing utility makes it easy to work on SimpleDoc documents in the text editor of your choice, while simultaneously viewing automatically updated previews of the document in a browser window. The utility is a simple WSH (Windows Script Host) based script, so no new software needs to be installed.

Using the utility in Windows is dead easy - just follow these simple steps...

1.  Load a .simple file (or a .js file containing SimpleDoc documentation comments) into the text editor of your choice.
2.  Drag that same file onto the _test-simpledoc.js script file that is located at the root of the UIZE JavaScript Framework's UIZE-JavaScript-Framework folder (assuming you've already downloaded and unzipped the latest version of the framework).
3.  After dropping the file onto the SimpleDoc previewing utility, an alert dialog will be displayed, informing you that the file is now being watched for modifications by the utility.
4.  Click the OK button in the alert dialog and an Internet Explorer browser window will be opened up, which will contain a styled preview of the HTML generated from the SimpleDoc documentation.
5.  Now you can proceed with editing the file in your text editor, and watch as the preview is automatically updated in the browser window each time you save your changes.
6.  Once you're done with editing the document, you can simply close the browser window. The temporary HTML file that was created for previewing purposes, and that was stored in the same folder as the file being edited, will then be removed.

11.1. Use it Just for Quick Previews

You're not limited to only using the previewing utility when you're actively editing SimpleDoc documentation.

You can also use the utility to just get a quick preview of some SimpleDoc documentation, without having to load the source file into a text editor. Just drag the source file onto the previewing utility and the browser window will be launched for viewing the preview. Close the window when you're done. It's as simple as that.

11.2. For Mac Users

For Mac users who wish to use this utility, you will need to use bootcamp to boot into Windows, or have virtualization software like Parallels Desktop or WMWare Fusion installed.