|1Document Construction|

|if|hide|
|"<span style="color:red;font-size:130%;">
As you can now see, this was inside a <kbd>|hide|</kbd>, now revealed due to the
<kbd>?nohide=1</kbd> query string.</span>||
|endif|

|^ |'wasdoc.wasDOC| source is intended to be edited using a simple, plain-text
editor of choice |--| a.k.a. EDT, TPU, etc.

|^ Document markup should regularly be checked by keeping a browser open on
the document and |/refreshing| the page as required.

|^ The first file should contain document "prologue" content, primarily style
sheet data.

|^ Document style, for example the fonts used, background colour or image,
margins and spacings, etc., should be handled through the style sheet prologue. 
"Hard-wiring" style using constructs such as
|=\|"<div style="background-color:red;">\||| is also possible but should be
specific in purpose and carefully considered before being employed.  If
absolutely needed, add a class to the style sheet and
|=\|"<div class="..">\|||.

|^ Sections of a document may be kept hidden from casual viewing using the
|=\|hide\|| tag.  This allows ongoing document development on a "live" resource. 
To access the hidden portion of the document under development access the
document with

|if|dynamic|
(click this)
// bit messy but generates a link
"|"<a class="link" target="_blank" href="||\
|insert|cgi=WWW_REQUEST_URI||\
|"?nohide=1#documentconstruction">nohide=1</a>||"
|else|
|=nohide=1|
|endif|

in a query string.  Most markup errors inside a hidden section will not affect
the rendering of the rest of the document.  They will only be visible when
accessing via |=?nohide||.  An |=\|exit\|| terminates document processing.

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

|2Control|

|^ A number of directives are used to control |'wasdoc.wasDOC| behaviour.

|table|
|~_ |: Purpose |: Syntax |: Comment
|~

|~ |.>> break source
   |. |=\|break\||
   |. break as if source was exhausted

|~ |.>> exit document processing
   |. |=\|exit\||
   |. terminate document processing

|~ |.>> tag stack
   |. |=\|insight!\||
   |. for document "debugging" purposes (see |link|Document Insights||)

|~ |.>> text and HTML reveal 
   |. |=\|insight@\||
   |. display |'_button.TEXT| and |'_button.HTML| buttons

|~ |.>> print
   |. |=\|print\||
   |. included only when printed

|~ |.>> no print
   |. |=\|noprint\||
   |. omitted when printed

|!table|

|0Settings|

|^ The specific |=\|set\|| directive is used to set and reset various document
processing functionality.  |*Most should be used early in the document| as they
determine document processing characteristics.

|table&width:90%|
|~_ |:&width:12em;. Purpose|: Syntax |: Comment
|~

|~ |.>> document in major sections
   |. |=\|set\|chunked=-1\||
   |. document is |*not| to be provided in major heading chunks

|~#^* |. 
   |. |=\|set\|chunked=0\||
   |. let the client decide (|=./000/||)

|~#^* |.
   |. |=\|set\|chunked=1\||
   |. will be provided in major heading chunks

|~ |.>> set default "|/this| in |/that||" reference
   |.>> |=\|set\|found=|/string||\||
   |. default is " in "

|~ |.>> index columns
   |.>> |=\|set\|idx=cols=|/integer||\||
   |. number of columns in the index

|~ |.>> index collation
   |.>> |=\|set\|idx=collation=|/string||\||
   |. default is 26 Latin alphabetics (see |link|Document Index||)

|~ |.>> set informational comments
   |.>> |=\|set\|insight=|/integer||\||
   |. 1, 2, 3, 4 and 5 (see |link|Document Insights||)

|9character set|
|9Locale, in particular character set|
|~ |. locale
   |. |=\|set\|locale=all=|/string||\||
   |. all locale aspects as defined by C-RTL function setlocale()

|~#^* |.
   |. |=\|set\|locale=ctype=|/string||\||
   |. document character set only
|^- i.e. those defined by SYS$I18N_LOCALE
|^- e.g. EN_US_ISO8859-1, EN_GB_ISO8859-1, DE_DE_ISO8859-1-EURO,
NL_NL_ISO8859-1, SV_SE_ISO8859-1 

|~ |. provide navigation arrows
   |.>> |=\|set\|navigate=0\||
   |. disable per sub-TOC navigation arrows

|~#^* |.
   |.>> |=\|set\|navigate=1\||
   |. enable navigation arrows

|~#^* |. 
   |.>> |=\|set\|navigate=2\||
   |. enable in printed documents \
|^-this will allow PDFs with active links to be navigated

|~ |.>> set default note heading
   |.>> |=\|set\|note=|/string||\||
   |. default is "Note"

|~ |. set pagination
   |.>> |=\|set\|paginate=1\||
   |. insert page rule at each major section

|~ |. default table alignment
   |.>> |=\|set\|table=margin=|/flag||\||
   |. where |/flag| is + (plus) or - (minus) or empty

|~ |.>> set explicit document title
   |.>> |=\|set\|title=|/string||\||
   |. default is the content of the document first heading

|~ |.>> table of content columns
   |.>> |=\|set\|toc=cols=|/integer||\||
   |. number of columns in TOC

|~ |.>> table of content format
   |.>> |=\|set\|toc=format=|/string||\||
   |. default is |/number| |/text|

|~ |. enable secondary TOC
   |. |=\|set\|toc2=1\||
   |. each major section has its own TOC table showing headings

|~#^* |. 
   |. |=\|set\|toc2=2\||
   |. include each unnumbered heading as well

|~ |.>> secondary TOC columns
   |.>> |=\|set\|toc2=cols=|/integer||\||
   |. number of columns in TOC

|!table|

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

|2FLAGs|

|^ FLAGs are ad hoc, all-upper-case strings that may be |=\|set\|| with string
values and later used with the |=\|insert\|| tag (|link|FLAG Insertion||), as
well as to control document processing in similar ways to the |=\|dynamic\|||,
|=\|static\||| and similar conditionals (see |link|Conditional Content||).  If
the value is zero (or empty) document content is excluded. If the value is one
or else non-zero (or not empty) document content is included.  The intent is to
allow a value to be set early in the document that then affects what is or
isn't included throughout the rest of the document.

|^ A usage example is the generation of PDF versions of this document.  This is
performed using the Safari browser on a macOS desktop.  The macOS PDF engine
does a very respectable job of creating a navigable (clickable-link) version
of a document. To attribute the PDF version the following "PDF" FLAG is set at
the beginning of the document and then later used to include the text.  The
|/static| setting is also used to set document processing appropriately. 
Normally set 0, both are modified to 1.  Also, the navigation arrows, normally
not |/printed||, are a desirable facility in a PDF document, with the setting
changed from 1 to 2 to ensure these are included.  The document is then
accessed, printed to PDF, and then set back to the original values.

|asis=<<|
|set|PDF=1|
|set|static=1|
|set|navigate=2|
&vellip;
|PDF|
// macOS PDF print does a good job of preserving the navigation
|^ This PDF version generated by macOS PDF print from Safari. |
|endif|
||||

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

|9Debugging|
|9Insights|
|2.Document Insights|

|^ While competent and capable, |'wasdoc.wasDOC| is not an application with a
sophisticated user interface and diagnostics.  It gets the job done but
sometimes requires significant human analysis when composing the markup.

|note|
|0The most common issue ...|
|...| is either too few or too many tag closures.  That is, most tags operate
on intervening text and the end of that text must be indicated with the earlier
described single Vbar plus white-space, or two consecutive Vbars.  Miss one (or
multiple) or add too many and |'wasdoc.wasDOC| will detect the inbalance at
some stage, report an error, and stop processing.  See |link|stack insight| for
how to view the markup stack.
|!note|

|^ Examining the HTML source will often help, either using the browser
functionality, or the |link|insight buttons| button.  Checking for unbalanced
HTML elements at or about the error report.  A table |=.<table>| not balanced
by a |=.</table>| for instance.

|^ To assist in this |*insight functionality| will provide some embedded
informational data during document processing.

|^ The |inline=| \|set\|insight=|/.<integer>||\| || (|link|Settings||) controls
the facility at a document level.  It should be used at the very front of the
document.  And the |inline=||?insight=|/.<integer>||| query string at the
client level (the former overrides the latter).  Information is embedded in
|"<span class="insight">||coloured background callouts|"</span>|| to the actual
document text in a dynamic document.  Integer values 1|...|5 provide
progressively more detailed insights into the document.

|table|
|~_ |: Level |: Description
|~
|~ |. 0 |. disabled
|~ |. 1 |. not disabled but no insights, allows |=\?insight=|/.<integer>|||
|~ |. 2 |. source file names
|~ |. 3 |. conditional processing
|~ |. 4 |. all highlight and markup tags
|~ |. 5 |. welter more detail
|!table|

|^ |*All| insight functionality may be disabled by placing
|=\|set\|insight=0\|| at the front of the document.

|9insight query string|
|0=.\?insight=|/.<integer>|||

|^ When |inline=| \|set\|insight=|/.<integer>||\| || is one or more, a query
string on a document can be used to control the level of insight provided.
|if|dynamic|
|link%|./?insight=4|This link| to level 4 insight provides an example.  The
query string integer can then be modified to view other levels.
|else|
The dynamic version of this document provides a working example.
|endif|

|9stack insight|
|0=.\|insight!\||

|^ |inline| This tag inserts the current markup stack which at this stage looks like
this |...| |insight!| The \&#9776; symbol indicates a stack entry, the integer
the stack depth, a following \&#10003; (tick) that this is the current stack
level, then two strings each introduced with a \&#8251; symbol.  The first is
the closure HTML tag and the second the markup that introduced this. |!inline|

|9insight buttons|
|0=.\|insight@\||

|^ This tag adds |'_button.TEXT| and |'_button.HTML| buttons, along with some
basic markup statistics. The |'_button.TEXT| button opens a page using the
|=?text=1| query showing the original markup text.  Use the |'_button.HTML|
button to open a page using the |=?html=1| query showing the generated HTML as
plain text.  Reload the now opened pages to refresh the displayed information.

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