| 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!
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.
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:20 – 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.
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.
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
A blog might be organised, with more recent entries listed before older, by a set of files such as the following.
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
† 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).
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 |
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.
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.
This would produce a series of related files similar to the following:
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.
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.
| ↩︎ | ↖︎ | ↑︎ | ↘︎ | ↪︎ |