//-----------------------------------------------------------------------------

|1WASD Documentation Processor |--| |'wasdoc.wasDOC| |

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

//.............................................................................

|2YAML (Yet Another Markup Language)|

|0In WASD's inimitable style of course |'_smiley.\ |||

|^ 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.wasDOC| is intended for browsers then why not just write HTML or
use an HTML editor?  Sure. But |'wasdoc.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.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.wasDOC| was designed and is intended for maintaining
general WASD documentation.  Any other utility is incidental and secondary.

|0Other |'wasdoc.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 |-|
|insert|time| |-| is also available.

|^ At the same time |'wasdoc.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.wasDOC| as possible, |*exercises|
those same aspects, and was employed as a |*development use case||.

|^ |*IMHO; It really is a delight to use.|

//.............................................................................

|2Deploying |'wasdoc.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.

|note|
|0=..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.
|code|
# WASD_CONFIG_GLOBAL
|:::|
# -CONTENT TYPES-
|:::|
.VMS  text/plain  plain text
.WASDOC  text/plain  wasDOC Markup Language |insert|HERE|
|:::|
|!code|
|!note|

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

|mono|
1_INTRODUCTION.WASDOC
2_DETAIL.WASDOC
3_SOLUTION.WASDOC
9_CONCLUSION.WASDOC
|!mono|

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.

|mono|
1_OVERVIEW.WASDOC
5_996_2019FEB23.WASDOC
5_997_2019FEB09.WASDOC
5_998_2019JAN26.WASDOC
5_999_2019JAN12.WASDOC
9_POSTSCRIPT.WASDOC
|!mono|

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

|3Dynamic Document|

|9Apache server|
|9OSU 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.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.
|if|dynamic|
|*You are currently viewing a dynamic document|
(courtesy of |insert|cgi=server_software|).
|else|
|*You are currently viewing a static document.|
|endif|

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

|mono|
https://the.host.name|"<a class="link" target="_blank" \
href="/cgi-bin/wasdoc/wasd_root/src/wasdoc/doc/">\
/cgi-bin/wasdoc/wasd_root/src/wasdoc/doc/</a>|| \&dagger;
|!mono|

|^+ \&dagger; |/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).

|mono|
map /wasdoc/ /cgi-bin/wasdoc/wasd_root/src/wasdoc/doc/
|!mono|

The URL used to access that document would be

|mono|
https://the.host.name/wasdoc/
|!mono|

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

|mono|
https://the.host.name/wasdoc/
https://the.host.name/wasdoc/wasdoc.html
https://the.host.name/wasdoc/Fred+Flintstone
|!mono|

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

|table|
|~_ |: 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
|!table|

|3Static Document|

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

|mono|
$ wasdoc == "$cgi_exe:wasdoc.exe"
|!mono|

If a file name is specified using the |=/output=| qualifier the generated HTML
is stored in that.  else it is sent to SYS$OUTPUT.

|mono|
$ set default wasd_root:[src.wasdoc]
$ wasdoc [.doc] /output=[.doc]wasdoc.html
$ mcr cgi_exe:wasdoc.exe [.doc] /output=[.doc]wasdoc.html
|!mono|

Then the static content is available (continuing the example) via

|mono|
https://the.host.name|"<a target="_blank" \
href="/wasd_root/src/wasdoc/doc/wasdoc.html">\
/wasd_root/src/wasdoc/doc/wasdoc.html</a>||
|!mono|

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

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

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

|mono|
wasdoc.html
wasdoc000.html
wasdoc001.html
wasdoc002.html
wasdoc003.html
wasdoc004.html
|!mono|

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

|0Static Insight|

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

//-----------------------------------------------------------------------------