WASD Documentation Processor

2.Markup Fundamentals

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

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

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

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.

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.

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.

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.

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

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

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

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

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

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

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

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.

As used in the following examples:

• Simple list (like this one)

  one two three

  |simple| |& one |& two |& three ||

• Ordered (numbered) list

  one two three

  |number| |& one |& two |& three ||

• Unordered (bullet point) list

  one two three

  |bullet| |& one |& two |& three ||

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

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

Using spawned commands without authorisation results in an error reported as

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.

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.

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

Insert System Data

Cluster System Data

2.7.3System Data

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

2.9Other Markup

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.

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.

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.

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

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

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:

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

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