NOTE: SOME FUNCTIONALITY EMPLOYS JAVASCRIPT

WASD Documentation Processor

The wasDOC document processing system is a CLI and CGI application that processes its own markup syntax into HTML. Documents are generated from multiple source files, with cross-referencing, table of content and navigation, is economical and concise in its syntax, while allowing a full(-ish) range of document capabilities, along with presentation customisation using style sheets (CSS).

Published July 2020 for wasDOC v2.0

Document generated using wasDOC v2.0.0

wasDOC © Mark G. Daniel 2019,2020

Apache License, Version 2.0
License

Licensed under the Apache License, Version 2.0 (the "License");

you may not use this software except in compliance with the License. You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Mark.Daniel@wasd.vsm.com.au
A pox on the houses of all spamers. Make that two poxes.

document formats

This is a static (file), single document.
Alternative multi-part static and dynamic documents.

Links followed by ⤤ open in a new page.

Table of Content

1.………………WASD Documentation Processor — wasDOC
1.1………………YAML (Yet Another Markup Language)
1.2………………Deploying wasDOC
1.2.1………………Dynamic Document
1.2.2………………Static Document
2.………………Markup Fundamentals
2.1………………Document Sections
2.1.1………………Other Section Numbers
2.2………………Text Highlight
2.3………………Breaks
2.4………………Blocks
2.5………………Notes
2.6………………Lists
2.7………………Insertion
2.7.1………………Spawned Command
2.7.2………………FLAG Insertion
2.7.3………………System Data
2.8………………|" and |asis|
2.9………………Other Markup
2.10………………Images
2.11………………Box Drawing
2.12………………Document Style
3.………………Tables
4.………………Links
4.1………………The Essential Fragment
4.2………………Links to Other Documents
5.………………Conditional Content
5.1………………Match Conditional
5.1.1………………Regex Basics
5.2………………Spawn Conditional
5.3………………Time Conditional
6.………………Document Navigation
6.1………………Primary TOC
6.2………………Secondary TOC
6.3………………Navigation Icons
6.4………………Document Index
7.………………Document Construction
7.1………………Control
7.2………………FLAGs
7.3………………Document Insights
8.………………Quick Reference
9.………………Index


1.WASD Documentation Processor — wasDOC

1.1YAML (Yet Another Markup Language)
1.2Deploying wasDOC
1.2.1Dynamic Document
1.2.2Static Document

For the first twenty-five years WASD documentation was largely maintained using first the VAX, then DEC Document layered product (sold to Touch Technologies, Inc.). With the demise of the TTI DEC Document a couple of decades ago, it tenuously hanging on in legacy Alpha kits, without a port to Itanium and certainly no prospect to x86-64, while there being no vendor-supplied equivalent documentation system on VMS, or suggested else elsewhere, then guess-what? Roll one's own, fit-for-purpose, CLI and CGI document system. The browser having become ubiquitous in the couple of decades since the birth of WASD and with HTML the lingua franca of markup languages — use those!

1.1YAML (Yet Another Markup Language)

In WASD's inimitable style of course  

No, not that one. This one is a markup processor. The vertical bar character is used to delimit markup tags and commonly the text they are applied to. For example, this bold text was formatted using |*bold text| and that explanation formatted using |=\|*bold text\||. Note the use of the backslash character. It is all fairly straight-forward but more detail shortly.

If wasDOC is intended for browsers then why not just write HTML or use an HTML editor? Sure. But wasDOC is more than just markup. It is a processing system that integrates documents from multiple source files, manages cross-referencing and table of content, is economical and concise in its syntax while allowing a full(-ish) range of document capabilities, along with presentation customisation using style sheets (CSS). All on VMS. All using a preferred text editor.

A knowledge of HTML and CSS is definitely not necessary for authoring using wasDOC – but may help understand some design decisions – and some understanding of CSS essential to customise the look and feel of a document.

Unreservedly, wasDOC was designed and is intended for maintaining general WASD documentation. Any other utility is incidental and secondary.

Other wasDOC Advantages

Being a CGI application, quick and inexpensive when rendering, it is simple to check editing changes as they are made. Just maintain a browser page on the document and refresh.

The same CGI basis makes it a ready tool for creating dynamic documents. External files, from anywhere the scripting account has access, can be included. Other dynamic content, such as the current date/time – Sat, 11 Jul 2020 09:12:19 – is also available.

At the same time wasDOC can be used on the command-line and the rendered HTML output to a file (or files) allowing static documents to be generated.

Every browser's ability to print to PDF easily provides documents in this format if required. Other document format conversion tools can be used to render a static HTML document to whatever.

This document is a little overblown for the following reasons; it demonstrates as many aspects of wasDOC as possible, exercises those same aspects, and was employed as a development use case.

IMHO; It really is a delight to use.

1.2Deploying wasDOC

Each document should be contained in its own directory. A document comprises one or more .WASDOC type files containing marked-up text. File names beginning with an underscore are ignored.

.WASDOC

The .WASDOC file type seemed an obvious choice.
To have these recognised as plain-text, established WASD sites will need to add .WASDOC to global configuration.
# WASD_CONFIG_GLOBAL ⋮ # -CONTENT TYPES- ⋮ .VMS text/plain plain text .WASDOC text/plain wasDOC Markup Language ⇦ HERE

A rendered document (HTML) is constructed by reading each of multiple document files in directory order, creating an in-memory composite which is then processed from beginning to end. Hence, the files

1_INTRODUCTION.WASDOC 2_DETAIL.WASDOC 3_SOLUTION.WASDOC 9_CONCLUSION.WASDOC
generate a document that begins (suggested by file name) with an introduction, some detail and a solution, and finishes up with a conclusion – all due to each file being read and processed in order. Of course it could be confined to a single file but this allows larger documents to have the source organised into more managable chunks. There is no relationship between section numbering and any numbering used in source file names. Document files, distinguished by the file type (extension), may be mixed with other files in a directory.

A blog might be organised, with more recent entries listed before older, by a set of files such as the following.

1_OVERVIEW.WASDOC 5_996_2019FEB23.WASDOC 5_997_2019FEB09.WASDOC 5_998_2019JAN26.WASDOC 5_999_2019JAN12.WASDOC 9_POSTSCRIPT.WASDOC
Adding a new blog entry would be a matter creating a file with a name in the "5" group, a number one less than the existing "latest" entry and then the remaining file name, here suggested to be the actual date of the entry. Hence, a file for a March 9th entry would be named 5_995_2019MAR09.WASDOC and the first markup |hide| while the entry was edited – see 7. Document Construction.

1.2.1Dynamic Document

Apache server
OSU server

These are documents which when accessed are generated and provided by a (CGI) scripting application. The WASDOC.EXE is placed into the server scripting location and document directories mapped to become the PATH_TRANSLATED CGI variable provided to it. wasDOC CGI is suitable for use with VMS Apache, OSU and of course is a default component of WASD. This document only considers WASD but the few principles readily translate to the others. WASD CGIplus mapping may also be used. You are currently viewing a static document.

The simplest approach is just to provide the script with an already-mapped file-system location. To process wasDOC's own documentation using this approach the URL would be

https://the.host.name/cgi-bin/wasdoc/wasd_root/src/wasdoc/doc/

may work or not depending on site configuarion

A document URI can be explicitly mapped to the document processor. This allows the document to be "transparently" accessed (i.e. it's not immediately obvious a script is being used).

map /wasdoc/ /cgi-bin/wasdoc/wasd_root/src/wasdoc/doc/
The URL used to access that document would be
https://the.host.name/wasdoc/
Note that the directory specification is parsed from the translated path so anything following this is ignored. Continuing with the above mapping, all the following are all equivalent and would return the rendered document from WASD_ROOT:[SRC.WASDOC.DOC] directory.
https://the.host.name/wasdoc/ https://the.host.name/wasdoc/wasdoc.html https://the.host.name/wasdoc/Fred+Flintstone
Large Document

A large document may be presented in major section "chunks". The advantage is to have the client dealing with more manageable quantities of the document in their browser at any one time rather than the whole thing, possibly over many, many scrollable pages. Really just a personal preference. The content remains the same. Note that a document is fully generated with each access, even if only a portion is output to the client.

This behaviour is controlled using the |set|chunked=| document setting.

Setting Behaviour
|set|chunked=1| the document is always supplied chunked
|set|chunked=0| chunking is determined by a numeric value trailing the URL
for example: /wasd_root/src/wasdoc/wasdoc/doc/000/
|set|chunked=-1| chunking is disabled

1.2.2Static Document

A static document is one produced at the command-line and then accessed as any other HTML document. You are currently viewing a static document. The wasDOC executable can be activated directly from the script location, or any other, using a foreign command or the MCR utility.

$ wasdoc == "$cgi_exe:wasdoc.exe"
If a file name is specified using the output= qualifier the generated HTML is stored in that. else it is sent to SYS$OUTPUT.
$ set default wasd_root:[src.wasdoc] $ wasdoc [.doc] /output=[.doc]wasdoc.html $ mcr cgi_exe:wasdoc.exe [.doc] /output=[.doc]wasdoc.html
Then the static content is available (continuing the example) via
https://the.host.name/wasd_root/src/wasdoc/doc/wasdoc.html
Multipart Document

As with dynamic documents, large static documents may be presented in major section "chunks". This means the document is written as a series of files with document navigation adjusting internal referencing to the required file. Each file contains the document prologue (e.g. style data) and so is in some sense a standalone sub-document requiring no further external resources. The chunked qualifier is used as with the following example.

$ set default wasd_root:[src.wasdoc] $ wasdoc [.doc] /output=[.doc]wasdoc.html /chunked

This would produce a series of related files similar to the following:

wasdoc.html wasdoc000.html wasdoc001.html wasdoc002.html wasdoc003.html wasdoc004.html

The unnumbered file is identical to the 000 file and is provided for more obvious access to the document. To suppress this file use /NOMAIN and to specify and alternate file name use /MAIN=name qualifier.

Static Insight

7.3 Document Insights may also be added to static documents using the /INSIGHT=<integer> qualifier. Using /INSIGHT alone just lists the document as it is processed.


2.Markup Fundamentals

2.1Document Sections
2.1.1Other Section Numbers
2.2Text Highlight
2.3Breaks
2.4Blocks
2.5Notes
2.6Lists
2.7Insertion
2.7.1Spawned Command
2.7.2FLAG Insertion
2.7.3System Data
2.8|" and |asis|
2.9Other Markup
2.10Images
2.11Box Drawing
2.12Document Style

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.

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 employed the dollar symbol which in comparison made the source text look and feel very crowded.)

A note regarding the use of the | vertical bar symbol & \ backslash character (explicit |this|)
Vbars 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 ‘Vbars can be messy...’ in 2.9 Other Markup.
a 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.

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

section numbers 1...4
Heading 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

1.    A Major Heading
1.1    Subsection Heading
1.1.1    The Further Subsection
1.1.1.1    Lowest Subsection

These also generate table of content (TOC) and Index entries. See ‘Table of Content’ in WASD Documentation Processor and 6. 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 ‘TOC Numbering’ in 6.1 Primary TOC).

section number 0

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

section 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 ‘|9...|’ in 6.4 Document Index.

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

2.1.1Other Section Numbers

Numbers 5…8 are currently reserved.

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

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 HTML-escape text |"No <a href="JavaScript:alert('HELLO')">HTML-escape</a> text||
only terminated by (two) ||
Strike text |-Strike text|
Underline text |_Underline text|
wasDOC |'class.text| explicit class — see below

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#*|This example is backlit using the contained syntax.||

Backlighting table rows operates slightly differently. See ‘table row highlight’ in 3. Tables.

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

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

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

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

Blocks of text (see ‘Blocks of Text’ in 2.3 Breaks) may be styled using the same mechanism.

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

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

The word wasDOC has a specific styling
was implemented using the marked-up text
The word |'_wasdoc.wasDOC| has a specific styling
and a style element (see ‘style sheets’ in 2.11 Box Drawing)
|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 CSS classes, it is recommended that document-specific classes are named using a leading underscore.

2.3Breaks

Paragraph, line and page breaks may be inserted using

|^ |^+ |^- |ppage|

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.

Blocks of Text

2.4Blocks

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

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 ‘text just as it is’ in 2.7.3 System Data

Text blocks may be styled using the mechanisms described in 2.2 Text Highlight, sections ‘Explicit Styling’ in 2.2 Text Highlight and ‘Explicit Class’ in 2.2 Text Highlight. Also see 2.12 Document Style.

2.5Notes

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 6.4 Document Index).

Explicit Note Heading

This note heading was provided using |0Explicit Note Heading|

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

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

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.

2.6Lists

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.

Purpose Syntax
simple list |simple|
|sl|
ordered list |number|
|ol|
unordered list |bullet|
|ul|
list item |item|
|li|
|&

As used in the following examples:

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 ‘Explicit Styling’ in 2.2 Text Highlight for example syntax.

Chapter Insertion

2.7Insertion

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

Purpose Syntax Example
file name * |insert|file=wasd_root:\
[src.wasdoc.doc]hello.txt|
Hello dere!
|insert|file=/wasd_root\
/src/wasdoc/doc/hello.txt|
Hello dere!
FAO time |insert|fao=%T| 09:12:19.89
|insert|fao=5%T| 09:12
FAO date |insert|fao=%D| 11-JUL-2020 09:12:19.89
|insert|fao=17%D| 11-JUL-2020 09:12
FAO repeat |insert|fao=24*~| ~~~~~~~~~~~~~~~~~~~~~~~~
strftime() |insert|time| Sat, 11 Jul 2020 09:12:19
|insert|time=%Y-%m-%dT%H:%M:%S%z| 2020-07-11T09:12:19
locale all |insert|locale| C
locale character set |insert|locale=ctype| C
document directory |insert|wasdoc=directory| wasd_root:[src.wasdoc.doc]
document path |insert|wasdoc=path| /wasd_root/src/wasdoc/doc/
wasDOC executable |insert|wasdoc=software| WASDOC AXP-2.0.0 (CGILIB AXP-2.0.1)
wasDOC version |insert|wasdoc=version| 2.0.0
FLAG value |insert|HOWDY| Hi There!   (see 2.7.2 FLAG Insertion)
CGI variable * |insert|cgi=WWW_SERVER_SOFTWARE| HTTPd-WASD/11.3.0b OpenVMS/AXP SSL**
**static document – edited
C-RTL environment * |insert|env=USER| SYSTEM
logical name * |insert|lnm=SYS$TIMEZONE_NAME| ACST
system data |insert|syi=keyword| see 2.7.3 System Data
spawned command * |insert|spawn=show time| 11-JUL-2020 09:12:19

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

2.7.1Spawned Command

Output from a spawned command may be inserted into the document – with some restriction applied to dynamic documents. Use of 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 ‘Document Authorisation’ in 2.7.1 Spawned Command.

DCL_Tips Information that was previously listed under this help topic is now included under the following individual help topics: HELP DATE (includes time specifications) HELP EXPRESSION HELP FILESPEC HELP INTEGER HELP PRIVILEGE HELP PROTECTION HELP STRING HELP SYMBOL HELP UIC

Using spawned commands without authorisation results in an error reported as

%SYSTEM-F-AUTHFAIL, authorization failure
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.

|insert|spawn=!-"help dcl|

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 5. Conditional Content) the same as any other string (see 5.2 Spawn Conditional).

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

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

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

2.7.2FLAG Insertion

FLAGs are ad hoc, all-upper-case strings that may be |set| with string values (see 7.2 FLAGs) which can then easily be inserted into the document — 𝓉𝒽𝒾𝓈  𝒾𝓈  𝒶𝓃  ℯ𝓍𝒶𝓂𝓅𝓁ℯ.

That example was generated using

|set|EXAMPLE=&tscr;&hscr;&iscr;&sscr;&nbsp; &iscr;&sscr;&nbsp; \ &ascr;&nscr;&nbsp; &escr;&xscr;&ascr;&mscr;&pscr;&lscr;&escr;| ⋮ … inserted into the document |--| |insert|EXAMPLE|.
and this
𝓉𝒽𝒾𝓈  𝒾𝓈  𝒶𝓃  ℯ𝓍𝒶𝓂𝓅𝓁ℯ
using
|insert_&background-color:yellow;font-size:150%;padding:0.3em;|EXAMPLE|
Flags values are always inserted without further processing.
Insert System Data
Cluster System Data

2.7.3System Data

Purpose Syntax Example
VMS version |insert|syi=version| V8.4-2L1
CPU architecure |insert|syi=arch_name| Alpha
cluster member |insert|syi=cluster=member| 0
cluster votes |insert|syi=cluster=votes| 0
cluster nodes |insert|syi=cluster=nodes| 0
cluster quorum |insert|syi=cluster=quorum| 0
cluster evotes |insert|syi=cluster=evotes| 0
system platform |insert|syi=hw_name| Digital Personal WorkStation
memory size |insert|syi=memsize| 1.50GB
node name |insert|syi=nodename| KLAATU
boot time |insert|syi=boottime| 4-JUN-2020 12:06:55
up-time |insert|syi=uptime| 36 21:05:24
text just as it is

2.8|" 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 two consecutive Vbar characters. The escape backslash continues to escape. Primarily it is intended for ad hoc HTML markup. This paragraph was marked up using

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

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 |=.\|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=<<| |^ 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. \||||

2.9Other Markup

Purpose Syntax
insert an en dash – |-|
\&ndash;
insert an em dash — |--|
\&mdash;
insert an ellipsis … |...|
\&hellip;
in fact, insert any HTML entity Α…Ω \&entity;
α…ω \&#integer;
not white-space or anything else! \\\\
(lots of Vbars can get messy, see below)
Vbars 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 ‘Chapter Links’ in 3. Tables) to another part of the document using a description that begins with Vbar-introduced markup.

FLAGS may be employed in 5. Conditional Content.
It might be imagined that this could be accomplished using something like
FLAGS may employ the |link|Conditional Content| construct.
but that is ambiguous to the parser. This works
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 \\\\ (quad-backslash). The solution then becomes
FLAGS may employ the |link|else|\\\\|=\|else\||||| construct.
Messy but does the job! Fortunately the need for such contortions seems infrequent.

2.10Images

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.

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
I like this graphic and if wasDOC was to have an icon this might be it  

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 ‘Explicit Styling’ in 2.2 Text Highlight for example syntax.

2.11Box Drawing

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

         │                          │
                                   
    ┌─────────┐                ┌─────────┐
    │         │── THIS one ──│         │
    │ ONE+one │                │ two-TWO ├───┐
    │         │── this TWO ──│         │   │
    └──┬──────┘                └─────────┘   │ ╌╌╌╌● continuous line
       ╎                                   │
       ╎   │                        │        │
  ┌╌╌ ╎   └────────────────────────│────────┘
  ╎    ╎                            │
  ╎    └╌╌╌╌────────────────────────┘
  ●
  vertical dashed line

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

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

In common with other block presentations, drawings may be styled using the mechanisms described in 2.2 Text Highlight, sections ‘Explicit Styling’ in 2.2 Text Highlight and ‘Explicit Class’ in 2.2 Text Highlight. Also see 2.12 Document Style.

Drawing Characters

The default 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>}.

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)
CSS
Cascading Style Sheets (CSS)
style sheets

2.12Document 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:

|style|* { font-size: 14pt; }|
To create an explicit class
|style|._wasdoc { font-family: "Lucida Console", Monaco, monospace; text-decoration:underline; } ||

As documented in ‘Explicit Styling’ in 2.2 Text Highlight 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

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

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

Multipart Styles

Where documents are presented as independent pages (see ‘Large Document’ in 1.2.1 Dynamic Document and ‘Multipart Document’ in 1.2.2 Static Document—basically the same thing) each section could have individual styles applied using

|multi| |style|html { background-image:url('/path/to/image') }| |!multi|
however, there exists the "shorthand" syntax
|style|chunk=html { background-image:url('/path/to/image') }|
where the style is only applied to chunked documents. May be useful for blogs and the like in customising particular pages.

3.Tables

Tables are one of the more demanding document layout requirements. wasDOC table generation largely uses HTML conventions. Note the alternative tags available. The choice between the longer or shorter variants is purely personal (though the shorter make for less clutter in non-trivial tables). The following table is generated using only the following markup elements.

Purpose Syntax
begin table |table|
|tabular|
row of cells |row| ...
|tr| ...
|~ ...
header cell |head| ...
|th| ...
|: ...
data cell |data| ...
|td| ...
|. ...
end table ||
|!table|

Note that rows and cells do not require and must not have closure. This is a deliberate design decision in an effort to reduce the clutter of tags that else seems to accumulate inside tables. Note also that table syntax is very sparse. Again an effort to reduce clutter around the actual data of interest. Further, that table processing removes and compresses white-space around elements in an effort to present "tidier" HTML.

The table above was generated by the following markup text.

|table| |~_ |: Purpose |: Syntax |~ |~#* |. begin table |. |=\|table\|| |^-|=\|tabular\|| |~ |. row of cells |. |=\|row\| ... | |^-|=\|tr\| ... | |^-|=\|~ ... | |~ |. header cell |. |=\|head\| ... | |^-|=\|th\| ... | |~ |. |. |=\|: ... | |~ |. data cell |. |=\|data\| ... | |^-|=\|td\| ... | |^-|=\|. ... | |~ |. end table |. |=\|\|| |^-|=\|!table\|| |!table|

In common with other "block" elements such as lists, tables are indented from the left margin. This may be suppressed using |table-|. The table can be centered on the page using |table><|. The default table alignment may also be set at any time using |set|table=margin=flag|.

Table headings and data are left aligned. Cells can be right and center aligned using |:> and |.>, and |:>< and |.>< respectively. To align an entire row use |~> and |~><, an entire table |table>| and |table><|. (The redundant left alignment is also accepted.)

A cell may have text protected against wrapping by marking it |:>> or |.>>, and an entire row |~>>.

A cell may be underlined by marking it |:_ or |._, and an entire row |~_. Useful for table headings. The table above had the column headings formatted as shown in the markup example.

table row highlight
R...

Note that alternate rows are optionally highlighted to assist in delineating each row's boundary. This highlight is enabled on a per-table basis using #* on a row tag, as with |~#* (or |row#*|, etc.) and subsequently can be disabled in the same table using #!*. A row may explicitly be set to the same highlight as the preceding row using #^*. Any row at all may have a one-shot highlight applied using #1*.

Cells also can have column and row spanning by specifying a digit 2..9 in the tag. The first digit encountered is the column span. Any second digit is the row span. Use 1 for the column span to specify only the row span. To span two columns |.2, to span three rows |.13, and to span four columns and five rows center aligned |.><45.

To suppress the display of a cell use |:# or |.#, and to suppress an entire row |~#. This may actually contain data (see assertion check below) that just will not be visible.

To add a little extra space between the preceding and succeeding rows use |~ (analagous to a line break).

In common with blocks of text, table elements may have specific styling applied. Also see ‘Explicit Styling’ in 2.2 Text Highlight. The tabular example below illustrates the use on a table row.

tabular example

Using the |tabular| tag, tables also can be used to present tabular data where the cells are right aligned and bordered.

(just to check the assertion above) col 1 col 2 col 3
row 1 10 20 30
row 2 400 500 600
row 3 7,000 8,000 9,000

That table was generated by the following markup text:

|tabular| |~ |:# (just to check the assertion above) |: col 1 |: col 2 |: col 3 |~ |: row 1 |. 10 |. 20 |. 30 |~&background-color:gainsboro;. |: row 2 |. 400 |. 500 |. 600 |~ |: row 3 |. 7,000 |. 8,000 |. 9,000 |!tabular|

Also note that the |:# above has a trailing "(just to check the assertion above)" which is not visible (check the HTML source if requiring verification).

Chapter Links

4.Links

4.1The Essential Fragment
4.2Links to Other Documents

Links to other parts of the document and to external resources are introduced with the usual Vbar symbol.

A URL beginning with a scheme (e.g. https://, ftp://) or a mailto: only requires closure with a delimiting Vbar. If a Vbar-delimitted description does not follow then the URL is used as the descriptor. If the tag ends in, or URL begins with, a % (percent) the link opens in a new browser page.

Syntax Example
|https://wasd.vsm.com.au/| https://wasd.vsm.com.au/
|https://wasd.vsm.com.au/|A link to WASD| A link to WASD
|%https://wasd.vsm.com.au/wasd/| https://wasd.vsm.com.au/wasd/
|%https://wasd.vsm.com.au/wasd/|WASD \
download in a new page|
WASD download in a new page

Where a URL does not begin with a scheme the |link| and |link%| tags must be used. Of course, URLs with schemes can be specfied using |link| as well, the sans-|link| is just a shorthand approach.

A URL beginning with just text (ie. without a URL) is considered a document section and is linked to that.

Syntax Example
|link|Chapter Insertion| ‘Chapter Insertion’ in 2.6 Lists
|link%|Chapter Insertion|jump to Insertion| jump to Insertion
|link*&background-color:azure;|Chapter \
Insertion|bold, coloured link to Insertion|
bold, coloured link to Insertion

A URL beginning with a fragment hash (#) moves the browser context to the specified fragment.

Syntax Example
|link|#tableofcontent|
|link%|#tableofcontent|Jump to \
Table of Content|
Jump to Table of Content

The Vbar-delimitted description can be an image.

Syntax Example
|link%|/wasd_root/src/wasdoc/*.*|image&\
width:3em;|../doc/wasdoc.png|

4.1The Essential Fragment

A wasDOC fragment, being based on the HTML fragment (the string following any # in a URL), is an identified location within a document. wasDOC describes these as identifiers and links to them, either implicitly (internal links) or explicitly (externally into a document), as references.

Each section heading has three identifiers.

  1. a dot-point numeric corresponding to the section number shown in major headings
  2. one derived from the text of the heading (alphanumeric all lower-case string)
  3. combination with a period-separated concatentation of the numeric and text

All internal document links use the concatenated identifier.

The dot-point numeric can change with the addition or deletion of intervening headings but the text-derived fragment identifier only changes when the heading is modified. It is a good choice when making a reference from another part of the document, or from an external document. The internal link (combination) can generally be used as an external reference by just removing the leading numeric element and using the alphanumeric string. The dot-point may also be used as the fragment identifier.

Different headings having the same text will result in duplicate fragment identifiers and generally the first in the document will be targeted by the browser. So as much as practicable, avoid using the same description for multiple headings. If this is unavoidable the location can also be explicitly located with a unique identifier using an explicit cross-reference as mentioned above. Alternatively, prefix the alphanumeric with the dot-point number of the most recent numbered heading.

The above section may be directly accessed using

4.2Links to Other Documents

Links to wasDOC documents are are indicated by a path with a final element (the fragment) beginning with two hashes (/##). The two differentiate it as a wasDOC link and the path and hash are made compliant with wasDOC requirements. One of the hashes is absorbed when generating the link. The fragment can be empty. The links can be relative, or site-absolute, or full URL references. The final element of the path is the fragment reference. This is an example of a link to a document in an adjacent location (directory). The variants are all equivalent.

|link|../Doc Two/##Somewhere Inside It|This is another document| |link|../doc_two/##Somewhere Inside It|This is another document| |link|../Doc Two/##somewhereinsideit|This is another document| |link|../doc_two/##somewhereinsideit|This is another document| |link|/wasd_root/src/wasdoc/Doc Two/##Somewhere Inside It|This is another document| |link|/wasd_root/src/wasdoc/doc_two/##somewhereinsideit|This is another document|
In thse examples, the translated name of the directory containing the document would be the equivalent of [-.doc_two] and the fragment reference somewhereinsideit. The browser would use the URI and it looks and behaves something like this
This is another document
Start of Document

To link to the beginning of a document just include an empty hash

|link|../Doc Two/##|
For this to work without additional mapping by the server there needs to be a one-to-one correspondence between the referenced document and the translated path to that document. So a rule such as
pass /documents/* /doc_root/*
would provide access to document locations
/documents/document_one/ /documents/document_two/ /documents/yet_another_document/

Of course additional mappings may be in place to locate the documents just about anywhere.

Specific Section of Whole Document

Using the syntax described below a link to a section of another document may be coupled with a separate link to the whole document. Two lots of two consecutive plus symbols delineate the section link, the conjunction, and the title of the document.

|link%|../Doc Two/##Somewhere Inside It++in++Document Two|

and it looks and behaves something like this

Somewhere Inside It in Document Two

5.Conditional Content

5.1Match Conditional
5.1.1Regex Basics
5.2Spawn Conditional
5.3Time Conditional

wasDOC provides for content to be included and excluded based on specified critera. This has already been demonstrated when the document was described as static (a file) using a construct such as

This has already been demonstrated when the document was described as |if|dynamic| |*dynamic| (a CGI script) |else| |*static| (a file) |endif| using a construct such as
as well as in the document prologue where alternative formats were suggested based on the current presentation.

The mechanism is the very familiar ifelifelseendif structure, where tests using if and elif resolving to true or false, control inclusion of related portions of the document. Conditionals may be nested. A conditional may be negated by prefixing it with ! (an exclamation point). A conditional structure may not span major sections (|1heading|).

Condition Comment
|apache| include if … Apache server
|cgi=<name>[:<keyword>/<regex>]| … CGI variable **
|dynamic| … executing as CGI script
|hide| … only if the query string contains nohide=1
|lnm=<name>[:<keyword>/<regex>]| … logical name value **
|multi| … document presented in major-heading portions
|osu| … OSU server
|single| … full document
|spawn=<command>[:<keyword>/<regex>]| … output from spawned command ** (see 5.2 Spawn Conditional)
|static| … from a file (i.e. not a CGI script)
|syi=<name>[:<keyword>/<regex>]| … any system value that can be inserted ** (see 2.7.3 System Data)
|time:<pattern>| … time value (see 5.3 Time Conditional)
|wasd| … WASD server
|FLAG[:<keyword>/<regex>]| … flag content ** (see 7.2 FLAGs)
|0| unconditional exclusion
|1| unconditional inclusion
**see 5.1 Match Conditional

Another example showing nested conditionals

|if|dynamic| this dynamic document has been brought to you by the |if|apache| Apache |elif|osu| OSU |elif|wasd| WASD |endif| server executing on a |if|syi=cluster=member| clustered |else| non-clustered |endif| \ |insert|syi=arch_name||. |else| this document is just from a flat, ol' file, originally generated on a |if|syi=cluster=member| clustered |else| non-clustered |endif| \ |insert|syi=arch_name||. |endif|
and now in motion … this document is just from a flat, ol' file, originally generated on a non-clustered Alpha.
Conditional keyword match

5.1Match Conditional

The simple conditions such as |dynamic| and |multi| allow fairly "flat" documents to adapt presentation to basic variations in document access. To use wasDOC for more sophisticated dynamic documents more sophisticated variants need to be supported.

The cgi, trnlnm and FLAG conditions may all have the associated value matched to a keyword or regular expression (see 5.1.1 Regex Basics).

In general, if the conditional <name> does not exist the following document content is excluded. If the name exists and no match specified then the content is included. When a colon-separated <keyword> or <regex> is supplied the value is tested against the parameter. If the keyword (or phrase) occurs in the value then the following content is included, otherwise excluded. Likewise if the regular expression matches or does not match the value. Matching is case insensitive.

This example provides something similar to the one above.

|if|dynamic| This dynamic document served by\ |if|cgi=SERVER_SOFTWARE:WASD| WASD. |else| something |*other| than WASD. |endif| |else| This document is from a static file. |endif|

This document is from a static file.

Conditional regular expression match

5.1.1Regex Basics

A regular expression, or regex, is a sequence of characters that define a search pattern. A detailed tutorial on regular expression capabilities and usage is well beyond the scope of this document. Many such hard-copy and on-line documents are available.

http://en.wikipedia.org/wiki/Regular_expression

A regular expression is differentiated from a keyword by a leading ^ (caret) character. Regex equivalent to the preceding example.

|if|dynamic| This dynamic document served by\ |if|cgi=SERVER_SOFTWARE:^.*WASD.*| WASD. |else| something |*other| than WASD. |endif| |else| This document is from a static file. |endif|

This document is from a static file.

wasDOC regular expressions support the following elements. Escape wasDOC-reserved characters (i.e. | and \).

Operator Overview
Description Usage
Match-self Operator Ordinary characters.
Match-any-character Operator .
Concatenation Operator Juxtaposition.
Repetition Operators * + ? {}
Alternation Operator |
List Operators [...] [^...]
Grouping Operators (...)
Back-reference Operator ^digit
Anchoring Operators ^ $
Backslash Operator Escape meta-character; i.e. ^ ^ . $ | [ (

The following operators are used to match one, or in conjunction with the repetition operators more, characters of the target string. These single and leading characters are reserved meta-characters and must be escaped using a leading backslash ("^") if required as a literal character in the matching pattern. Note that this does not apply to the range hyphen; to include a hyphen in a range ensure the character is the first or last in the range.

Matching Operators
Expression Purpose
^ Match the beginning of the line
. Match any character
$ Match the end of the line
| Alternation (or)
[abc] Match only a, b or c
[^abc] Match anything except a, b and c
[a-z0-9] Match any character in the range a to z or 0 to 9

Repetition operators control the extent, or number, of whatever the matching operators match. These are also reserved meta-characters and must be escaped using a leading backslash if required as a literal character.

Repetition Operators
Expression Function
* Match 0 or more times
+ Match 1 or more times
? Match 1 or zero times
{n} Match exactly n times
{n,} Match at least n times
{n,m} Match at least n but not more than m times

5.2Spawn Conditional

Output from a spawned command may be tested using keyword and regex matching the same as other strings (see 2.7.1 Spawned Command). Output also can be reused for further matching or output by specifying the & (ampersand) character instead of a command. This will not only avoid additional overhead but also presents the exact same data used for the conditional.

This system has a C compiler available:
VSI C V7.4-002 on OpenVMS Alpha V8.4-2L1
|if|spawn=!-cc/version| |*This system has a C compiler available:| |else| |*This system does not have a C compiler available:| |endif| |^- |mono-#*#::##3| |insert|spawn=!&| |!mono|

5.3Time Conditional

The time conditional allows document content to change according to the time of day, week, or even year. It compares the supplied parameter to the current system time in one of three ways.

  1. The supplied parameter is in the form "1200-1759", which should be read as "twelve noon to five fifty-nine PM" (i.e. as a time range in minutes, generalized as hhmm-hhmm), where the first is the start time and the second the end time. If the current time is within that range (inclusive) the conditional returns true, otherwise false. If the range doesn't look correct false is always returned.
    |if|time:0000-0000| it's midnight |elif|time:0001-1159| it's AM |elif|time:1200-1200| it's noon |else| it's PM |endif|
  2. If the supplied parameter is a single digit (or series of digits) it is compared to the VMS day of the week (1-Monday, 2-Tuesday … 7-Sunday).
    |if|time:6,7| it's the weekend |else| it's the working week |endif|
  3. If the supplied string is not in either of the formats described above it is treated as a string match with a VMS comparision time (i.e. yyyy-mm-dd hh-mm-ss.hh) using C-RTL decc$match_wild() or ^regex).
    |if|time:%%%%-07-*| it's the month of July |endif|

These are combined in the following example.

At time of rendering it was Saturday, July 11 09:12
Which makes it the weekend.
And so many are not concerned about the workplace.  
|^+ |if|dynamic| Currently it is |else| At time of rendering it was |endif|\ |insert*|time=%A, %B %d %H:%M| // largely teased out into separate, continued lines for clarity |^- Which makes it \ |if|time:6,7| |*the weekend||. |^- And so many are |*not concerned| about the workplace. |'_smiley.\ | |else| during the working week.\ |^- And as it's \ |if|time:0000-0859| early morning\ |elif|time:0900-1700| between 9AM and 5PM\ |else| late in the day \ |endif| also likely \ |if|!time:0900-1700| |*_not| |endif| |*working hours||. |endif|

Clear as mud? Thought it might be.

Document Navigation 2

6.Document Navigation

6.1Primary TOC
6.2Secondary TOC
6.3Navigation Icons
6.4Document Index

wasDOC provides a variety of navigation mechanisms.

Each of these is described in the following sections.

6.1Primary TOC

The tags |1 through to |4 divides the document into titled sections and and generates a hierarchical primary table of content (TOC). Each generates a corresponding (HTML) heading containing the section title.

|0 tags do not generate primary TOC entries. Optionally these can be included in secondary TOCs.

Any heading tag can be prefixed with a zero to suppress the primary TOC entry while inserting that style heading.

The primary TOC is presented in two columns. This may be reduced to a single column or increased to three or four using |set|toc=cols=integer|.

The table of content is inserted wherever the |toc| tag is placed. If not included then no primary TOC is generated.

TOC Numbering

By default the Table of Content is numbered as section and subsections (see 2.1 Document Sections). Using the setting |set|toc=format=0| this can be disabled, resulting in no section numbering. Explicitly (re)enable using |set|toc=format=1|.

In addition, a numeric TOC can have a separator inserted after the section number up to the section heading, making a TOC entry look something like the next (faux) heading.

6.1.1 ......... Obscure Embellishments

The syntax |set|toc=format=1....................| will introduce a space filled with the specified text between the entry number and title. Just make sure there is enough of the separator characters to span the space between the section number and text (hint: a ragged edge at the right indicates too few). While simple characters such as periods and hyphens are obvious choices some HTML entities are more aesthetically pleasing. The following seem to work well;  &nldr; ‥  &ctdot; ⋯  &hellip; … (used in this document)  &bull; •  &compfn; ∘  &hyphen; ‐  &lowbar; _  and &period; . — just remember to have enough entities to fill that intervening space!

•  A Simple Bullet

Alternatively, it can be set to a literal string which is prefixed to the heading title. This is intended to allow an HTML entity to delineate the headings, as in |set|toc=format=&bull;&nbsp;&nbsp;|.

6.2Secondary TOC

A secondary table of content can be placed at the beginning of each major section providing navigation to the |2 and |4 headings within that section. This document has secondary TOC enabled.

The secondary TOC is enabled using the |set|toc2=integer| setting. The integer specifies the level of inclusion. Using |set|toc2=1| includes the primary TOC entries, |set|toc2=2| includes all headings. The TOC is presented in two columns. This may be reduced to a single column or increased to three or four using |set|toc2=cols=integer|.

6.3Navigation Icons

Navigation icons provide the   ↩︎  ↖︎  ↑︎  ↘︎  ↪︎    which left to right represent; history backward, previous major section, start of document (often primary TOC), next major section, history forward. Navigation items are enabled using |set|navigate=1|. This document has navigation items enabled as can be seen below the 6. Document Navigation (this) heading.

6.4Document Index

This provides an alphabetically arranged set of links into various parts of the document, collated on the first character of the reference description. Any and all headings are included (|0, |1|4 and |9).

Unnumbered headings (i.e. |0) are placed into context by including the preceding numbered heading in the entry. For example, the heading |0Contextual Example| in this section would appear in the index as: ‘Contextual Example’ in 6.4 Document Index.

To suppress the context, just using the heading, prefix the section number 9 digit with a leading 9 (nine) digit (i.e. |99).

To suppress the index entry completely while still inserting a document reference, prefix the section number 9 digit with a 0 (zero) digit (i.e. |09).

|9...|

A heading |9...| uses the following document text as the Index item. If an explicit alphabetic character precedes the ellipsis this is used as the Index collating character. Therefore

|9X...| This is just an example!
would place "This is just an example!" into the "X" section of the Index.

The Index is inserted wherever the |index| tag is placed (usually towards the end of the document as with this one). If not included then no Index is generated.

The index is presented in two columns. This may be reduced to a single column or increased to three or four using |set|idx=cols=integer|.

The default index is collated using the 26 alphabetics of the English language Latin alphabet. This may be modified using the setting |set|idx=collate=string| where string is a list of 8 bit Latin 1 characters. Each character to be collated must have two listed, the first an upper-case version, followed by the lower-case equivalent. The first of the two characters is listed in the index. If the character specified does not have one or the other then just repeat the character. The default English language collation sequence is

AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

If the sequence is prefixed with a plus symbol (i.e. |set|idx=collate=+string|) then the parameter is appended to any existing sequence. Without the plus the collation sequence is replaced.

To include entries beginning with integers use |set|idx=collate=+00112233445566778899|.


7.Document Construction

7.1Control
7.2FLAGs
7.3Document 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.1Control

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

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


8.Quick Reference

The term closure refers to the need to terminate a tag's effect on intervening content. As described in 2. Markup Fundamentals the closure is a vertical bar followed by white-space, or two Vbars if not followed by white-space. Annotated closure using |! is also available. In these tables required means exactly that, none resulting in an error if tried, and implied that the tag contains all the markup data required in itself (often with a parameter).

Highlight
Description Syntax Example Reference
bold text |*...| bold text 2.2 Text Highlight
center text |><...| center text
italicise text |/...| italicised text
monospace text |=...| monospaced text
no-wrap text |>>...| this text will not wrap no matter what!
strike text |-...| strike text
underline text |_...| underlined text
special class text |'class=...| wasDOC
Pagination
Description Syntax Closure Reference
paragraph * |^<white-space> none 2.3 Breaks
new line |^- none
new page |page| none
new page when printed |ppage| none
end of document |epage| none
* Paragraphs will take a trailing (plus) symbol to indent.
Quick Reference Blocks
Blocks
Description Syntax Closure Reference
text as written |asis| |||| (four on a line by themselves) 2.4 Blocks
some text as a block |block| required
code example |code| required
example |example| required
inline text |inline| required
monospace pre-formatted |mono| required
obvious note |note| required
proportional pre-formatted |prop| required
quoted text |quote| required
All will take additional styling (see ‘Explicit Styling’ in 2.2 Text Highlight)
Quick Reference Lists
Lists
Description Syntax Closure Reference
simple |simple| required 2.6 Lists
|sl| required
numeric |number| required
|ol| required
bulleted |bullet| required
|ul| required
item |item| none
|li| none
|& none
All will take additional styling (see ‘Explicit Styling’ in 2.2 Text Highlight)
Quick Reference Tables
Tables
Description Syntax Closure Reference
begin table |table| required 3. Tables
|tabular| required
begin row |~ none
|tr| none
|row| none
header cell |:| none
|th| none
|head| none
data cell |.| none
|td| none
|data| none
All will take additional styling (see ‘Explicit Styling’ in 2.2 Text Highlight)
Quick Reference Links
Links
Description Syntax Closure Reference
external resource |link|https://host/path| implied 4. Links
external with description |link|https://host/path|\
A link to WASD|
implied
external in new page |link%|https://host/path| implied
internal reference |link|Document Style| implied
to equivalent fragment |link|#documentstyle| implied
to another document |link|../doc_two/\
#Somewhere Inside It|\
This is another document|
implied
another in new page |link%|../doc_two/\
#Somewhere Inside It|\
This is another document|
implied
Quick Reference Various
Various
Description Syntax Closure Reference
text as-is |=...| required 2.8 |" and |asis|
insert data |insert|keyword=| implied 2.7 Insertion
|insert|spawn=DCL command| implied 2.7.1 Spawned Command
insert image |image|image URI/L implied 2.10 Images
draw box diagram |draw| required 2.11 Box Drawing
comment line |// none 7.1 Control
Quick Reference Control
Control
Description Syntax Closure Reference
break source |break| implied
exit document processing |exit| implied
tag stack |insight!| implied 7.3 Document Insights
text and HTML reveal |insight@| implied
only when printed |print| implied
omit when printed |noprint| implied
Quick Reference Settings
Settings
Description Syntax Closure Reference
document in major sections |set|chunked=-1| implied ‘Settings’ in 7.1 Control
|set|chunked=0|
|set|chunked=1|
index of content columns |set|idx=cols=integer| implied 6.4 Document Index
|set|idx=collate=|
informational content |set|insight=integer| implied 7.3 Document Insights
localization |set|locale=string| implied
navigation arrows |set|navigate=0| implied
|set|navigate=1|
|set|navigate=2|
default note heading |set|note=Attention!| implied
pagination |set|paginate=1| implied
dynamic review period |set|review=number| implied
document as if static |set|static=1| implied
set default table margin |set|table=flag| implied
explicit document title |set|title=This Is The Title| implied
table of content columns |set|toc=cols=integer| implied 6.1 Primary TOC
table of content format |set|toc=format=string|
secondary TOC |set|toc2=1| implied 6.2 Secondary TOC
|set|toc2=2|
|set|toc2=cols=|
set a FLAG value |set|AFLAG=integer| implied 7.2 FLAGs
|set|AFLAG=string|
The Document Index

9.Index

A‘A note regarding the use of the | vertical bar symbol & \ backslash character (explicit |this|)’ in 2. Markup Fundamentals
 ‘a paragraph!’ in 2. Markup Fundamentals
 ‘Apache License, Version 2.0’ in WASD Documentation Processor
 ‘Apache server’ in 1.2.1 Dynamic Document
B2.4 Blocks
 ‘Blocks’ in 8. Quick Reference
 ‘Blocks of Text’ in 2.3 Breaks
 2.11 Box Drawing
 2.3 Breaks
C‘Cascading Style Sheets (CSS)’ in 2.11 Box Drawing
 ‘Chapter Insertion’ in 2.6 Lists
 ‘Chapter Links’ in 3. Tables
 ‘character set’ in 7.1 Control
 ‘Cluster System Data’ in 2.7.2 FLAG Insertion
 5. Conditional Content
 ‘Conditional keyword match’ in 5. Conditional Content
 ‘Conditional regular expression match’ in 5.1 Match Conditional
 7.1 Control
 ‘Control’ in 8. Quick Reference
 ‘CSS’ in 2.11 Box Drawing
D‘Debugging’ in 7.2 FLAGs
 1.2 Deploying wasDOC
 ‘Document Authorisation’ in 2.7.1 Spawned Command
 7. Document Construction
 ‘document formats’ in WASD Documentation Processor
 6.4 Document Index
 7.3 Document Insights
 6. Document Navigation
 ‘Document Navigation 2’ in 5.3 Time Conditional
 2.1 Document Sections
 2.12 Document Style
 ‘Drawing Characters’ in 2.11 Box Drawing
 1.2.1 Dynamic Document
E‘Explicit Class’ in 2.2 Text Highlight
 ‘Explicit Note Heading’ in 2.5 Notes
 ‘Explicit Styling’ in 2.2 Text Highlight
F2.7.2 FLAG Insertion
 7.2 FLAGs
H‘Heading Cross-Reference’ in 2.1 Document Sections
 ‘Highlight’ in 8. Quick Reference
I‘|insight!|’ in 7.3 Document Insights
 ‘|insight@|’ in 7.3 Document Insights
 2.10 Images
 ‘In WASD's inimitable style of course  ’ in 1.1 YAML (Yet Another Markup Language)
 9. Index
 ‘Insert System Data’ in 2.7.2 FLAG Insertion
 2.7 Insertion
 ‘insight buttons’ in 7.3 Document Insights
 ‘insight query string’ in 7.3 Document Insights
 ‘Insights’ in 7.2 FLAGs
L‘Large Document’ in 1.2.1 Dynamic Document
 ‘License’ in WASD Documentation Processor
 4. Links
 ‘Links’ in 8. Quick Reference
 4.2 Links to Other Documents
 2.6 Lists
 ‘Lists’ in 8. Quick Reference
 ‘Locale, in particular character set’ in 7.1 Control
M2. Markup Fundamentals
 5.1 Match Conditional
 ‘Matching Operators’ in 5.1.1 Regex Basics
 ‘Multipart Document’ in 1.2.2 Static Document
 ‘Multipart Styles’ in 2.12 Document Style
N6.3 Navigation Icons
 ‘Note’ in 2.5 Notes
 2.5 Notes
O‘Operator Overview’ in 5.1.1 Regex Basics
 ‘OSU server’ in 1.2.1 Dynamic Document
 ‘Other wasDOC Advantages’ in 1.1 YAML (Yet Another Markup Language)
 2.9 Other Markup
 2.1.1 Other Section Numbers
P‘Pagination’ in 8. Quick Reference
 6.1 Primary TOC
Q8. Quick Reference
 ‘Quick Reference Blocks’ in 8. Quick Reference
 ‘Quick Reference Control’ in 8. Quick Reference
 ‘Quick Reference Links’ in 8. Quick Reference
 ‘Quick Reference Lists’ in 8. Quick Reference
 ‘Quick Reference Settings’ in 8. Quick Reference
 ‘Quick Reference Tables’ in 8. Quick Reference
 ‘Quick Reference Various’ in 8. Quick Reference
R‘R...’ in 3. Tables
 5.1.1 Regex Basics
 ‘Repetition Operators’ in 5.1.1 Regex Basics
S6.2 Secondary TOC
 ‘section number 0’ in 2.1 Document Sections
 ‘section number 9’ in 2.1 Document Sections
 ‘section numbers 1...4’ in 2.1 Document Sections
 ‘Settings’ in 7.1 Control
 ‘Settings’ in 8. Quick Reference
 5.2 Spawn Conditional
 2.7.1 Spawned Command
 ‘Specific Section of Whole Document’ in 4.2 Links to Other Documents
 ‘stack insight’ in 7.3 Document Insights
 ‘Start of Document’ in 4.2 Links to Other Documents
 1.2.2 Static Document
 ‘Static Insight’ in 1.2.2 Static Document
 ‘style sheets’ in 2.11 Box Drawing
 2.7.3 System Data
T‘Table of Content’ in WASD Documentation Processor
 ‘table row highlight’ in 3. Tables
 3. Tables
 ‘Tables’ in 8. Quick Reference
 ‘tabular example’ in 3. Tables
 2.2 Text Highlight
 ‘text just as it is’ in 2.7.3 System Data
 ‘The Document Index’ in 8. Quick Reference
 4.1 The Essential Fragment
 ‘The most common issue ...’ in 7.3 Document Insights
 5.3 Time Conditional
 ‘TOC Numbering’ in 6.1 Primary TOC
V‘Various’ in 8. Quick Reference
 ‘Vbars and Escapes’ in 2. Markup Fundamentals
 ‘Vbars can be messy...’ in 2.9 Other Markup
W‘WASD Documentation Processor’ in WASD Documentation Processor
 1. WASD Documentation Processor — wasDOC
 ‘Why the Vbar?’ in 2. Markup Fundamentals
Y1.1 YAML (Yet Another Markup Language)
6‘6.1.1 ......... Obscure Embellishments’ in 6.1 Primary TOC
9‘|9...|’ in 6.4 Document Index
WASD Documentation Processor