# WASD Documentation Processor

# 7.Document Construction

7.1 Control
7.2 FLAGs
7.3 Document Insights

↩︎ | ↖︎ | ↑︎ | ↘︎ | ↪︎

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 nohide=1 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.

## 7.1 Control

A number of directives are used to control wasDOC behaviour.

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 7.3 Document Insights)
text and HTML reveal | |insight@| | display TEXT and HTML buttons
print | |print| | included only when printed
no print | |noprint| | omitted when printed

##### Settings

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.

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 6.4 Document Index)
set informational comments | |set|insight=integer| | 1, 2, 3, 4 and 5 (see 7.3 Document Insights) ###### character set ###### Locale, 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

## 7.2 FLAGs

FLAGs are ad hoc, all-upper-case strings that may be |set| with string values and later used with the |insert| tag (2.7.2 FLAG Insertion), as well as to control document processing in similar ways to the |dynamic|, |static| and similar conditionals (see 5. 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.

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

###### Debugging

###### Insights

## 7.3 Document Insights

While competent and capable, 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.

##### The 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 will detect the inbalance at some stage, report an error, and stop processing. See ‘stack insight’ in 7.3 Document Insights for how to view the markup stack.

Examining the HTML source will often help, either using the browser functionality, or the ‘insight buttons’ in 7.3 Document Insights 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 |set|insight=<integer>| (‘Settings’ in 7.1 Control) controls the facility at a document level. It should be used at the very front of the document. And the ?insight=<integer> query string at the client level (the former overrides the latter). Information is embedded in coloured background callouts to the actual document text in a dynamic document. Integer values 1…5 provide progressively more detailed insights into the document.

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

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

###### insight query string

##### ?insight=<integer>

When |set|insight=<integer>| is one or more, a query string on a document can be used to control the level of insight provided. The dynamic version of this document provides a working example.

###### stack insight

##### |insight!|

This tag inserts the current markup stack which at this stage looks like this … ☰3 ※</span> ※|/.<integer>|||☰2 ※</span> ※|/.<integer>||\| || is one or more, a query☰1✓ ※</span> ※|inline| This tag inserts the current markup stack which at this stage looks like The ☰ symbol indicates a stack entry, the integer the stack depth, a following ✓ (tick) that this is the current stack level, then two strings each introduced with a ※ symbol. The first is the closure HTML tag and the second the markup that introduced this.

###### insight buttons

##### |insight@|

This tag adds TEXT and HTML buttons, along with some basic markup statistics. The TEXT button opens a page using the text=1 query showing the original markup text. Use the 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.

↩︎ | ↖︎ | ↑︎ | ↘︎ | ↪︎