# WASD Documentation Processor

# 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

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

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.1 YAML (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: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.

## 1.2 Deploying 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.1 Dynamic 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.2 Static 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.

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