|1Markup Fundamentals| 

|^ Markup directives, otherwise referred to as |/tags||, are introduced using a
|*vertical bar| followed by a symbol, a single digit, or a string.  Most are
concluded, or |/closed||, using another vertical bar followed by white-space
(space, newline, etc).  Where no white-space follows two consecutive vertical
bar characters must be used. The |/vertical bar| hereafter will be referred to
as the |*Vbar||.

|0 Why the Vbar?|

|^ Importantly, the markup introducing character needs to be uncommonly used. 
Needing to escape every tenth character would very quickly become very tedious. 
Additionally, the source text should look as uncluttered as possible.  The Vbar
seems eminently suited.  (Early development of |'wasdoc.wasDOC| employed the
dollar symbol which in comparison made the source text look and feel very
crowded.)

|if|dynamic|
Have a |"<a class="link" target="_blank" \
href="|||insert|cgi=REQUEST_URI|||"?text=1">look</a>||
at the source text of this document.  It is relatively clear and uncluttered.
|endif|

|9A note regarding the use of the \| vertical bar symbol & \\ backslash
character (explicit \|this\|)|

|note|
|0Vbars and Escapes|
Vbar characters to be displayed as that must always be escaped using a leading
backslash.  In fact, any character may be escaped using a leading backslash,
including the backslash.  A backslash then space inserts a hard (non-breaking)
space, like\ \ \ \ \ these, while a backslash as the final character on a line
continues that line unbroken (by |/suppressing| the new line).  Also see
|link|vbars can be messy...||. 
|!note|

|9a paragraph!|
|^ When nested tags become complex and sometimes confusing it is often useful
to document for the author which tag is being closed.  This can be done using
the |=\|!| tag |-| annotated closure |-| which accepts ad hoc text terminated
with the usual Vbar.  For  example, for clarity in the source text, the |/Vbars
and Escapes| note above was begun with a |=\|note\|| tag and closed with a
|=\|!note\|||.  But be aware, you can put anything you like after the |=\|!|
and before the closing |=\|||.  The text is really only commentary.

//.............................................................................

|2Document Sections|

|^ Documents are generally divided into major sections (can be considered
chapters) and subsections.  For example, the |/Markup Fundamentals| (above) is a
major section and the |/Document Sections| (immediately above) is a second-level
(sub) section, with |/Other Section Numbers| (below) a further level of subsection.  A
maximum of four levels is possible.

|^ A section is introduced with the usual Vbar followed by a digit.

|9section numbers 1...4|
|9Heading Cross-Reference|
|^ Section |*numbers 1|...|4| generate numbered headings.  For example, |=\|1A
Major Heading\|||, |=\|2Subsection Heading\|||, |=\|3The Further
Subsection\||| and |=\|4Lowest Subsection\|||, result in headings similar to
the following 

|block"|
<div style="font-size:115%;font-weight:bold;">1.&nbsp;&nbsp;&nbsp;
<span style="text-decoration:underline;">A Major Heading</span></div> 
<div style="font-size:110%;font-weight:bold;">1.1&nbsp;&nbsp;&nbsp;
Subsection Heading</div> 
<div style="font-size:105%;font-weight:bold;">1.1.1&nbsp;&nbsp;&nbsp;
The Further Subsection</div> 
<div style="font-size:105%;font-weight:bold;">1.1.1.1&nbsp;&nbsp;&nbsp;
Lowest Subsection</div> 
||

|^ These also generate table of content (TOC) and Index entries.  See
|link|Table of Content| and |link|Document Navigation||.  To suppress the TOC
entry prefix the section heading digit with a |=0| (zero) digit.  Section
numbering can be suppressed altogether with a TOC setting of zero (see
|link|TOC Numbering||).

|9section number 0|
|^ Section |*number 0 (zero)| generates a heading equivalient to 4 but without
an associated TOC entry or numbering.

|9section number 9|
|^ Section |*number 9 (nine)| generates a heading for index and reference
purposes but one that does not display in the document.  In addition to the
visible headings 0..4 the 9 heading allows the creation of a generously
cross-referenced document.  To suppress the index entry while still inserting a
reference, prefix the section number 9 digit with a |=0| (zero) digit (i.e.
|=\|09||).  A section number 9 may also be prefixed with another 9 (i.e.
|=\|99||) to further modify the reference.  Also see |link|\|9...\|||. 

|^ Section headings are left-aligned but can be center-aligned or right-aligned
by appending |=\>\<| or |=\>| to the leading digit.

|3Other Section Numbers|

|^ Numbers 5|...|8 are currently reserved.

//.............................................................................

|2Text Highlight|

|^ Tags having text highlight flags are brief and inline.  Like most other tags
they are terminated by a Vbar followed by white-space, or two consecutive Vbar
characters if white-space not immediately adjacent.

|table|
|~ |: |_Appearance| |: |_Syntax| |: |_Note|
|~
|~ |. |*Bold text| 
   |. |=\|*Bold text\||
|~ |.><Center text
   |. |=\|><Center text\||
   |. |/ability to center depends on the context|
|~ |. |/Italicise text||
   |. |=\|/Italicise text\|| 
|~ |.>>= Monospace text
   |. |=\|=Monospace text\||
|~ |. no-wrap text
   |. |=\|>>no-wrap text\|| 
   |. |>>/white-space will not cause this text to be wrapped|
|~ |. |"No <a href="JavaScript:alert('HELLO')">HTML-escape</a> text||
   |.3; |=\|\"No  <a href="JavaScript:alert('HELLO')">HTML-escape</a> text\|\||
|~ |.2 |. |/only terminated by (two)| \|\|
|~ |. |-Strike text|
   |. |=\|-Strike text\|| 
|~ |. |_Underline text|
   |. |=\|_Underline text\||
|~ |. |'_wasdoc.wasDOC|
   |. |=\|'|/class||.text\||
   |. |/explicit class |--| see below|
|!table|

|^ Text highlight flags may be combined in meaningful ways.  |*_=This text is
obviously bolded, underlined, and in a monospaced font||, all by |=.\|*_=This
text is obviously bolded, underlined, and in a monospaced font\|||.  The flags
are terminated by the first alphanumeric encountered, or explicitly by using a
period, as with |/_.(example)| marked-up using |=.\|/_.(example)\|||.

|^ The flag |=.#*| applies standard background highlighting to an element.
This example is backlit using the demonstrated syntax.

|code#*|
\|code#*\|This example is backlit using the contained syntax.\|\|
|!code|

|^ Backlighting table rows operates slightly differently.
See |link|table row highlight||.

|^ The flag |=.##|/.<integer>||| applies the specified number of 0.1em padding
to an element.  This example backlights and pads by 0.8em.

|code#*##8|\|code#*##8\|This example backlights and pads by 0.8em.\||

|0Explicit Styling|

|^ Text elements also may have specific styling applied.  The & (ampersand)
character introduces a string of CSS style markup.  This
|_&font-size:1.3em;.must be| the final element of the tag and delimited by a
style semi-colon and following period.  Implemented as in the following example.

|code|
This \|_&font-size:1.3em;.must be\| the final element of the tag
|!code|

|^ Blocks of text (see |link|Blocks of Text||) may be styled using the same
mechanism.

|code&background-color:azure;width:35em;padding:0.5em;|
\|code&background-color:azure;width:35em;padding:0.5em;\|
and so on...
\|!code\|
|!code|

|0Explicit Class|

|style|._wasdoc { font-size:1.2em; background-color:yellow;
                  padding:0 0.5em; 0 0.5em; }|

|^ The explicit class |=\|'| (single quote) highlight applies a named CSS
styling to the text following.  The word |'_wasdoc.wasDOC| has a specific
styling applied when used with the |/explicit class| tag.  So the phrase

|prop| The word |'_wasdoc.wasDOC| has a specific styling ||

was implemented using the marked-up text

|asis=|
The word |'_wasdoc.wasDOC| has a specific styling
||||

and a style element (see |link|style sheets||)

|asis=<<|
|style|._wasdoc { font-size:1.2em; background-color:yellow;
                  padding:0 0.5em 0 0.5em; }|
||||

|^ Multiple explicit classes may be applied to a text element, each introduced
using the |=.\'| (single quote).

|^ |*To avoid clashing| with current or future |'wasdoc.wasDOC| CSS classes, it
is recommended that document-specific classes are |*named using a leading
underscore||.

//.............................................................................

|2Breaks|

|^ Paragraph, line and page breaks may be inserted using

|mono|
\|^
\|^+
\|^-
\|ppage\|
|!mono|

|^ Breaks require no closure.  The |=\|^\ || creates a paragraph break (note
the trailing space), with |=\|^+| an indented paragraph. The |=\|^-| provides a
line break.  A |=\|ppage\|| generates a page break only in a printed document. 
A backslash as the last character on a line suppresses the new line.

//.............................................................................

|9Blocks of Text|
|2Blocks|

|^ Blocks of text can have specific presentations.  By default each of these is
indented but can be directed to the current left margin by appending a |=.-|
(minus) character, as in the example |=\|code-\|||.  A simple paragraph,
ordinarily at the left margin, may be indented using |=\|^+||.

|table|
|~_ |: Purpose |: Syntax
|~
|~ |. block of text 
   |. |=\|block\| ... \||
|~ |. code example 
   |. |=\|code\| ... \||
|~ |. example text 
   |. |=\|example\| ... \||
|~ |. inline, not indented
   |. |=\|inline\| ... \||
|~ |. monospace preformatted 
   |. |=\|mono\| ... \||
|~ |. proportional preformatted 
   |. |=\|prop\| ... \||
|~ |. quotation 
   |. |=\|quote\| ... \||
|~ |. text just as it is 
   |. see |link|text just as it is|
|!table|

|^ Text blocks may be styled using the mechanisms described in |link|Text
Highlight||, sections |link|Explicit Styling| and |link|Explicit Class||.  Also
see |link|Document Style||.

|2Notes|

|note><|
The |=\|note\|| tag is used to draw attention to something considered important.
||

|^ The delimiting horizontal bars make it difficult to overlook. A note always
has an associated heading.  This defaults to "Note" (or to
|=\|set\|note=|/string||\|||) but can (and often should) be explicitly supplied
to clearly identify why it is considered important.  Explicit note headings
also appear in the Index (see |link|Document Index||).

|note><|
|0Explicit Note Heading|
This note heading was provided using |=\|0Explicit Note Heading\||
|!note|

|^ An explicit heading is a zero-level section introduced immediately in the
note.  Any other text will result in the default heading.

|code|
|asis|
|note><|
|0Explicit Note Heading|
This note heading was provided using |=\|0Explicit Note Heading\||
|!note|
||||
|!code|

|^ Note also that notes with little text often work better if centered.  This
was accomplished by appending the characters |=.><| to the tag as illustrated
above.

//.............................................................................

|2Lists|

|^ |'wasdoc.wasDOC| provides three list types; simple, ordered (numbered) and
unordered (bulleted).  Lists themselves must be closed using |=\|\|| or the
equivalent, while |/items| do not require and must not be closed.  Note the
alternative tags available.   The choice between the longer or shorter variants
is purely personal.                                              

|table|
|~_ |: Purpose |: Syntax
|~
|~ |. simple list
   |. |=\|simple\||
|~ |. 
   |. |=\|sl\||
|~ |. ordered list 
   |. |=\|number\||
|~ |. 
   |. |=\|ol\||
|~ |. unordered list 
   |. |=\|bullet\||
|~ |. 
   |. |=\|ul\||
|~ |. list item 
   |. |=\|item\||
|~ |.
   |. |=\|li\||
|~ |.
   |. |=\|&|
|!table|

|^ As used in the following examples:

|simple|

|item| Simple list (like this one)
|table|
|~ |.
|sl| |& one |& two |& three ||
|.
|asis=<<|
|simple|
|& one
|& two
|& three
||
||||
|!table|

|item| Ordered (numbered) list
|table|
|~ |.
|number| |& one |& two |& three ||
|.
|asis=<<|
|number|
|& one
|& two
|& three
||
||||
|!table|

|item| Unordered (bullet point) list
|table|
|~ |.
|bullet| |& one |& two |& three |!ul|
|.
|asis=<<|
|bullet|
|& one
|& two
|& three
||
||||
|!table|

|!number|

|^ By default, lists have additional vertical space between items.  To specify
a list with minimal space, append a hash character to the list type (i.e.
|=\|bullet#\|||, |=\|numeric#\||| and |=\|simple#\|||).

|^ In common with blocks of text, lists may have specific styling applied. 
List |/items| using styling must use the longer version (e.g. |=\|item\|||).
See |link|Explicit Styling|| for example syntax.

//.............................................................................

|9Chapter Insertion|
|2Insertion|

|^ Other files and content can be |=\|insert\|||ed into the document.  The tag
accepts relevant highlight flags (see |link|Text Highlight||). 

|table|
|~_ |: Purpose |: Syntax |: Example
|~

|~#* |. file name * 
   |. |=\|insert\|file=wasd_root:\\|^-[src.wasdoc.doc]hello.txt\||
   |. |insert|file=wasd_root:\
[src.wasdoc.doc]hello.txt|

|~ |. 
   |. |=\|insert\|file=/wasd_root\\|^-/src/wasdoc/doc/hello.txt\||
   |. |insert|file=/wasd_root\
/src/wasdoc/doc/hello.txt|

|~ |. FAO time 
   |. |=\|insert\|fao=%T\|||
   |. |insert|fao=%T|
|~ |. 
   |. |=\|insert\|fao=5%T\|||
   |. |insert|fao=5%T|
|~ |. FAO date 
   |. |=\|insert\|fao=%D\|||
   |. |insert|fao=%D|
|~ |. 
   |. |=\|insert\|fao=17%D\|||
   |. |insert|fao=17%D|

|~ |. FAO repeat
   |. |=\|insert\|fao=24*~\|||
   |. |insert|fao=24*~|

|~ |. strftime() 
   |. |=\|insert\|time\|||
   |. |insert|time|
|~ |. 
   |.>> |=\|insert\|time=%Y-%m-%dT%H:%M:%S%z\|||
   |. |insert|time=%Y-%m-%dT%H:%M:%S%z|

|~ |. locale all
   |. |=\|insert\|locale\|||
   |. |insert|locale|
|~ |. locale character set 
   |. |=\|insert\|locale=ctype\|||
   |. |insert|locale=ctype|

|~ |. document directory 
   |. |=\|insert\|wasdoc=directory\||
   |. |insert|wasdoc=directory|
|~ |. document path 
   |. |=\|insert\|wasdoc=path\||
|if|dynamic|
   |. |insert|wasdoc=path|
|else|
   |. /wasd_root/src/wasdoc/doc/
|endif|

|~ |. |'wasdoc.wasDOC| executable 
   |. |=\|insert\|wasdoc=software\||
   |. |insert|wasdoc=software|
|~ |. |'wasdoc.wasDOC| version 
   |. |=\|insert\|wasdoc=version\||
   |. |insert|wasdoc=version| 

|set|HOWDY=Hi There!|

|~ |. FLAG value 
   |. |=\|insert\|HOWDY\||
   |. |insert|HOWDY| \ \ (see |link|FLAG Insertion||)

|~ |. CGI variable * 
   |. |=\|insert\|cgi=WWW_SERVER_SOFTWARE\|||
|if|dynamic|
   |. |insert|cgi=WWW_SERVER_SOFTWARE|
|else|
   |. HTTPd-WASD/11.3.0b OpenVMS/AXP SSL**
|^-**|/static document |-| edited|
|endif|

|~>> |. C-RTL environment * 
   |. |=\|insert\|env=USER\||
   |. |insert|env=USER|

|~>> |. logical name * 
   |. |=\|insert\|lnm=SYS$TIMEZONE_NAME\||
   |. |insert|lnm=!"SYS$TIMEZONE_NAME|

|~ |. system data 
   |. |=\|insert\|syi=|/keyword||\||
   |. see |link|System Data|

|~ |. spawned command * 
   |. |=\|insert\|spawn=show time\||
   |. |insert|spawn=!show time|

|!table|

|^ |"<sup>*</sup>|| By default these items have content inserted with
significant HTML characters escaped.  This may be suppressed by prefixing the
parameter with a |=."| (quotation) symbol.  Output is then included as-is. 
Also, an encountered error will stop document processing.  Prefixing the
parameter with a |=.!| (exclamation) symbol will result in it continuing.

//.............................................................................

|3Spawned Command|

|^ Output from a spawned command may be inserted into the document |-| with
some restriction applied to dynamic documents.  Use of |'wasdoc.wasDOC| at the
command line has none.  If the account can successfully issue the command the
output can be captured and inserted into the static document being generated. 
|*CAUTION!|  For a dynamic document the document location must be authorised to
do so.  |*MORE CAUTION ADVISED!|  A document author may then spawn any command 
as the scripting account.  This may and |/probably should be| a consideration.
See |link|document authorisation||.

|mono|
|insert|spawn=!-"help dcl|
|!mono|

|^ Using spawned commands without authorisation results in an error reported as

|mono|
%SYSTEM-F-AUTHFAIL, authorization failure
|!mono|

and will stop document generation.  In fact, any error returned by the spawned
command will stop document processing unless the command is prefixed by a |=.!|
(exclamation) symbol.  When prefixed the document inserts the error message and
continues.  If seeing the above message instead of |=DCL_tips| help then the
document can be authorised as described below.

|^ Output from spawned commands is inserted with meaningful HTML characters
escaped.  This may be suppressed by prefixing the command with a |=."|
(quotation) symbol.  Output is then included as-is.  Command output is often
formatted for terminal display and includes white-space unnecessary for a
document.  This can be trimmed by prefixing the command with a |=\-| (hyphen)
symbol.  This is an example using all three (output above).  Order is not
significant.

|mono|
\|insert\|spawn=!-"help dcl\|
|!mono|

|^ For dynamic documents, spawned commands add overhead and significantly
extend document generation times.

|^ The output from a spawned command may be tested using keyword and regex
matching (see |link|Conditional Content||) the same as any other string (see
|link|Spawn Conditional||).

|^ The output from a previous spawn may be reused by specifying the |=.&|
(ampersand) character instead of a command.

|0Document Authorisation|

|^ A dynamic document, generated under a scripting account, must be authorised
to insert the output from a spawned command.  This is performed by adding its
VMS file specification location to the multi-valued logical name
|=WASDOC_SPAWN| located in the |=LNM$SYSTEM table||.  This contrived example
shows this document being authorised to spawn.

|mono|
$ define /system WASDOC_SPAWN some:[other], -
                              wasd_root:[src.wasdoc.doc], -
                              and:[this.one]
|!mono|

//.............................................................................

|3FLAG Insertion|

|set|EXAMPLE=&tscr;&hscr;&iscr;&sscr;&nbsp; &iscr;&sscr;&nbsp; \
&ascr;&nscr;&nbsp; &escr;&xscr;&ascr;&mscr;&pscr;&lscr;&escr;|

|^ FLAGs are ad hoc, all-upper-case strings that may be |=\|set\|| with string
values (see |link|FLAGs||) which can then easily be inserted into the document
|--| |insert|EXAMPLE||.

|^ That example was generated using

|asis=<<|
|set|EXAMPLE=&amp;tscr;&amp;hscr;&amp;iscr;&amp;sscr;&amp;nbsp; &amp;iscr;&amp;sscr;&amp;nbsp; \
&amp;ascr;&amp;nscr;&amp;nbsp; &amp;escr;&amp;xscr;&amp;ascr;&amp;mscr;&amp;pscr;&amp;lscr;&amp;escr;|
&vellip;
&hellip; inserted into the document |--| |insert|EXAMPLE|.
||||

and this

|block|
|insert_&background-color:yellow;font-size:150%;padding:0.3em;|EXAMPLE|
||

using

|asis=<<|
|insert_&background-color:yellow;font-size:150%;padding:0.3em;|EXAMPLE|
||||

Flags values are always inserted without further processing.

//.............................................................................

|9Insert System Data|
|9Cluster System Data|
|3System Data|

|table|
|~_ |: Purpose |: Syntax |: Example
|~
|~ |. VMS version 
   |. |=\|insert\|syi=version\||
   |. |insert|syi=version|
|~ |. CPU architecure 
   |. |=\|insert\|syi=arch_name\||
   |. |insert|syi=arch_name|
|~ |. cluster member 
   |. |=\|insert\|syi=cluster=member\||
   |. |insert|syi=cluster=member|
|~ |. cluster votes 
   |. |=\|insert\|syi=cluster=votes\||
   |. |insert|syi=cluster=votes|
|~ |. cluster nodes 
   |. |=\|insert\|syi=cluster=nodes\||
   |. |insert|syi=cluster=nodes|
|~ |. cluster quorum 
   |. |=\|insert\|syi=cluster=quorum\||
   |. |insert|syi=cluster=quorum|
|~ |. cluster evotes 
   |. |=\|insert\|syi=cluster=evotes\||
   |. |insert|syi=cluster=evotes|
|~ |. system platform 
   |. |=\|insert\|syi=hw_name\||
   |. |insert|syi=hw_name|
|~ |. memory size 
   |. |=\|insert\|syi=memsize\||
   |. |insert|syi=memsize|
|~ |. node name 
   |. |=\|insert\|syi=nodename\||
   |. |insert|syi=nodename|
|~ |. boot time 
   |. |=\|insert\|syi=boottime\||
   |. |insert|syi=boottime|
|~ |. up-time 
   |. |=\|insert\|syi=uptime\||
   |. |insert|syi=uptime|
|!table|

//.............................................................................

|9text just as it is|
|2\|" and \|asis\||

|^ Text just as it is |-| or perhaps characters just as they are |-| can be
placed in the document using the |=\|"| and |=\|asis\|| tags, with the former
intended for shorter sequences embedded in other text, and the latter for
multi-line blocks of text. Note that significant HTML characters (e.g.
<, >, &) to be rendered as characters must be represented by an entity.

|^ The |=.\|"| closure is |"<span style="font-size:120%">two
consecutive</span>|| Vbar characters.  The escape backslash continues to
escape.   Primarily it is intended for ad hoc HTML markup.  This paragraph was
marked up using 

|asis=<<|
|^ The |=.\|"| closure is |"&lt;span style="font-size:120%"&gt;two
consecutive&lt;/span&gt;|| Vbar characters.  The escape backslash continues to
escape.   Primarily it is intended for ad hoc HTML markup.  This paragraph was
marked up using 
||||

|^ The |=.\|asis\|| closure is four consecutive Vbar characters on a line by
themselves.  The escape backslash |*no longer escapes||.  Content is copied
character for character.

|asis=<<|
|^ The |=.\|asis\|| closure is four consecutive Vbar characters on a line by
themselves.  The escape backslash |*no longer escapes||.  Content is copied
character for character.
||||

|^ The example above was documented using the following markup.

|asis=<<|
|asis=<<|
|^ The |=\|asis\|| closure is four consecutive Vbar characters on a line by
themselves.  The escape backslash no longer escapes.  Content is copied
character for character.
\||||
||||

//.............................................................................

|2Other Markup|

|table|
|~_ |: Purpose |: Syntax
|~
|~ |. insert an en dash |-| 
   |. |=\|-\||
|~ |. 
   |. \\&ndash;
|~ |. insert an em dash |--| 
   |. |=\|--\||
|~ |. 
   |. \\&mdash;
|~ |. insert an ellipsis |...| 
   |. |=\|...\||
|~ |.
   |. \\&hellip;
|~ |.> in fact, insert |*any HTML entity| \&Alpha;|...|\&Omega; 
   |. \\&|/entity||;
|~ |.> \&#945;|...|\&#969; 
   |. \\&|/.#integer||;
|~ |. not white-space or anything else!
   |. |=\&bsol;\&bsol;\&bsol;\&bsol;|
|~ |.2 (|/lots of Vbars can get messy, see below||)
|!table|

|0Vbars can be messy...|

|^ |...| and the quad-backslash escape comes to the rescue.  Vbar characters
back-to-back can start to confound themselves.  Consider the need to link (see
|link|chapter_links||) to another part of the document using a description that
begins with Vbar-introduced markup.

|prop|
FLAGS may be employed in |link|Conditional Content||.
|!prop|

It might be imagined that this could be accomplished using something like

|asis=|
FLAGS may employ the |link|Conditional Content| construct.
||||

but that is ambiguous to the parser.  This works

|asis=<<|
FLAGS may employ the |link|Conditional Content| construct.
||||

but not without adding extraneous white-space.  What is needed is a construct
the parser recognises as NOT-white-space but is else ignored.  Hence the
|=\&bsol;\&bsol;\&bsol;\&bsol;| (quad-backslash).  The solution then becomes

|asis=<<|
FLAGS may employ the |link|else|\\\\|=\|else\||||| construct.
||||

Messy but does the job!  Fortunately the need for such contortions seems
infrequent.

//.............................................................................

|2Images|

|^ Images are inserted using the |=\|image\|| tag.  The image  path follows the
tag.  It can be in-document, relative, absolute or a fully specified URL.

|table|
|~_ |: Type |: Syntax |: Comment
|~
|~ |. in-document 
   |. |=\|image\|wasdoc.png\||
   |. contained in the same directory as the document source text
|~ |. 
   |. |=\|image\|./wasdoc.png\||
   |.
|~ |. relative 
   |. |=\|image\|../doc_two/another.png\||
   |. contained in a directory adjacent to the document
|~ |. 
   |. |=\|image\|../../yetmore.png\||
   |. a directory two "up" from the document
|~ |. absolute
   |. |=\|image\|/wasd_root/src/wasdoc/doc/\\\
|^-wasdoc.png\||
   |. fully qualified path to the image file
|~ |. 
   |. |=\|image\|/wasd_root/src/yetmore.png\||
   |. (hypothetically)
|~ |. full URL
   |. |=\|image\|https://wasd.vsm.com.au\\\
|^-/wasd_root/src/wasdoc/doc/wasdoc.png\||
   |. fully specified URL to the image file
|!table|

|table|
|~ |. |image%%|../doc/wasdoc.png|
   |.#= I like this graphic and if |'wasdoc.wasDOC| was to have an \
icon this might be it |'_smiley.\ |
|!table|

|^ An image may be made a clickable download by using the |=%| (percent)
character.  The above image was marked-up as |=\|image%\|../doc/wasdoc.png\||
(has a transparent background and Chrome renders it as a black page).

|^ In common with blocks of text, images may have specific styling applied. 
See |link|Explicit Styling| for example syntax.

//.............................................................................

|2Box Drawing|

|^ Simple diagrams showing relationships and data flows are often useful to
illustrate, well, relationships and data flows.

|draw-|
         |                          |
         #                          #
    +---------+                +---------+
    |         |<-- THIS one -->|         |
    | ONE\+one |                | two\-TWO +---+
    |         |<-- this TWO -->|         |   |
    +--+------+                +---------+   | <....* {<i>continuous line</i>}
       :   ^                        ^        |
       :   |                        |        |
  +..> :   +------------------------|--------+
  :    :                            |
  :    +....------------------------+
  *
  {<i>vertical dashed line</i>}
|!draw|

|^ |'wasdoc.wasDOC| provides these using a few simple drawing-specific markup
characters.  The above diagram is constructed using:

|mono|
|asis|
|draw|
         |                          |
         #                          #
    +---------+                +---------+
    |         |<-- THIS one -->|         |
    | ONE\+one |                | two\-TWO +---+
    |         |<-- this TWO -->|         |   |
    +--+------+                +---------+   | <....* {&lt;i>continuous line&lt;/i>}
       :   ^                        ^        |
       :   |                        |        |
  +..> :   +------------------------|--------+
  :    :                            |
  :    +....------------------------+
  *
  {&lt;i>vertical dashed line&lt;/i>}
|!draw|
||||
|!mono|

|^ In common with other |link|blocks|block| presentations, drawings may be
styled using the mechanisms described in |link|Text Highlight||, sections
|link|Explicit Styling| and |link|Explicit Class||.  Also see |link|Document
Style||.

|0Drawing Characters|

|^ The default |'wasdoc.wasDOC| |=\|| symbol (Vbar) and directives do not apply
in drawing contexts.  A drawing is terminated only by |=\|!draw\|||.  Reserved
drawing characters used as literals must be backslash-escaped; as seen in the
above example with |=ONE\\+one| and |=two\\-TWO||.  Alternatively, literally
used reserved characters may be placed between curly braces; as seen with the
embedded HTML |= {<i>vertical dashed line</i>}||.

|^ |table|
|~_ |: Purpose |: Character
|~
|~#* |. horizontal line 
   |. - |. (hyphen)
|~#* |. horizontal dashed line 
   |. . |. (period)
|~ |. vertical line  
   |. \| |. (vertical bar)
|~ |. vertical dashed line  
   |. : |. (colon)
|~ |. lines joining or branching  
   |. + |. (plus)
|~ |. left arrow  
   |. < |. (less than)
|~ |. right arrow  
   |. > |. (greater than)
|~ |. up arrow  
   |. ^ |. (caret/circumflex/hat)
|~ |. down arrow  
   |. # |. (hash/pound)
|~ |. black dot  
   |. * |. (asterisk)
|~ |. escape next character  
   |. \\ |. (backslash)
|~ |. escape all between  
   |. { |...| } |. (curly braces)
|!table|

//.............................................................................

|9CSS|
|9Cascading Style Sheets (CSS)|
|9style sheets|
|2Document Style|

|^ There is a default, in-built document style.  If nothing else is set before
the first text output then this is used.  This is the same style seen in this
document.

|^ Style sheet characteristics are set using the |*|=\|style\|||| tag.

|^ To explicitly use the default style then |=\|style\|default\|||.

|^ To insert style sheet data from a document file then
|=\|style\|file=my.css\|||, or using a file external to the document by
providing the full file path, as with
|=\|style\|file=device:[directory]the.css\|||.

|^ To link to external style sheet data then
|=\|style\|sheet=https://the.host.name/path/style.css\|||.

|^ Style elements may be set and reset using the |=\|style\|| tag.  Just
specify the required style sheet syntax.  For example, to modify the default
font size:

|mono|
\|style\|* { font-size: 14pt; }\|
|!mono|

To create an |link|Explicit Class|explicit class|

|mono|
\|style\|._wasdoc
{ font-family: "Lucida Console", Monaco, monospace;
  text-decoration:underline; }
\|\|
|!mono|

|^ As documented in |link|Explicit Styling| it is possible to define a class and
then apply that class to various tags.

|^ Style sheet data is generally set early in the document but can be defined
|-| |*and redefined| |-| at any stage.

|^ And of course, in common with any other HTML, style data can be "injected"
into the document using non-escaped document text.  For example, the same
|=._wasdoc| style as above  could be done using

|mono|
\|"<style type="text/css">._wasdoc \\
{ font-family: "Lucida Console", Monaco, monospace;
  text-decoration:underline; } </style>\|\|
|!mono|

|^ |*To avoid clashing| with current or future |'wasdoc.wasDOC| CSS classes, it
is recommended that document-specific classes are |*named using a leading
underscore||.

|0Multipart Styles|

|^ Where documents are presented as independent pages (see |link|Large
Document| and |link|Multipart Document|||--|basically the same thing) each
section could have individual styles applied using

|mono|
\|multi\|
\|style\|html { background-image:url('/path/to/image') }\|
\|!multi\|
|!mono|

however, there exists the "shorthand" syntax

|mono|
\|style\|chunk=html { background-image:url('/path/to/image') }\|
|!mono|

where the style is only applied to |/chunked| documents.  May be useful for
blogs and the like in customising particular pages.

//-----------------------------------------------------------------------------