| 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.
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 and buttons |
| |print| | included only when printed | |
| no print | |noprint| | omitted when printed |
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 setLocale, 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 |
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.
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.
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.
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.
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.
This tag adds and buttons, along with some basic markup statistics. The button opens a page using the text=1 query showing the original markup text. Use the 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.
| ↩︎ | ↖︎ | ↑︎ | ↘︎ | ↪︎ |