|9Chapter Links|
|1Links|

|^ Links to other parts of the document and to external resources are introduced
with the usual Vbar symbol.

|^ A URL beginning with a scheme (e.g. |=https://||, |=ftp://||) or a
|=mailto:|| only requires closure with a delimiting Vbar.  If a
|*Vbar-delimitted description| does not follow then the URL is used as the
descriptor.  If the tag ends in, or URL begins with, a |=.%| (percent) the link
opens in a new browser page.

|table|
|~_ |: Syntax |: Example
|~
|~ |. |=\|https://wasd.vsm.com.au/\|| 
   |. |https://wasd.vsm.com.au/|
|~ |. |=\|https://wasd.vsm.com.au/\|A link to WASD\|| 
   |. |https://wasd.vsm.com.au/|A link to WASD|
|~ |. |=\|%https://wasd.vsm.com.au/wasd/\|| 
   |. |%https://wasd.vsm.com.au/wasd/| 
|~ |.; |=\|%https://wasd.vsm.com.au/wasd/\|WASD \\
|^-download in a new page\|| 
   |. |%https://wasd.vsm.com.au/wasd/|WASD \
download in a new page|
|!table|

|^ Where a URL does not begin with a scheme the |=\|link\|| and |=\|link%\||
tags must be used.  Of course, URLs with schemes can be specfied using
|=\|link\|| as well, the sans-|=\|link\|| is just a shorthand approach.

|^ A URL beginning with just text (ie. without a URL) is considered a document
section and is linked to that.

|table|
|~_ |: Syntax |: Example
|~
|~ |. |=\|link\|Chapter Insertion\|| 
   |. |link|Chapter Insertion|
|~ |.; |=\|link%\|Chapter Insertion\|jump to Insertion\|| 
   |. |link%|Chapter Insertion|jump to Insertion|
|~ |.; |=\|link*&background-color:azure;\|Chapter \\
|^-Insertion\|bold, coloured link to Insertion\|| 
   |. |link*&background-color:azure;|Chapter \
Insertion|bold, coloured link to Insertion|
|!table|

|^ A URL beginning with a |/fragment hash| (|=.#||) moves the browser context
to the specified fragment.

|table|
|~_ |: Syntax |: Example
|~
|~ |. |=\|link\|#tableofcontent\|| 
   |. |link|#tableofcontent|
|~ |. |=\|link%\|#tableofcontent\|Jump to \\
|^-Table of Content\|| 
   |. |link%|#tableofcontent|Jump to \
Table of Content|
|!table|

|^ The Vbar-delimitted description can be an image.

|table|
|~_ |: Syntax |: Example
|~
|~ |. |=\|link%\|/wasd_root/src/wasdoc/*.*\|image&\\|^-
width:3em;\|../doc/wasdoc.png\|| 
   |. |link%|/wasd_root/src/wasdoc/*.*|image&width:3em;|../doc/wasdoc.png|
|!table|

|2The Essential Fragment|

|^ A |'wasdoc.wasDOC| fragment, being based on the HTML fragment, is a named
location within a document.  There are |/implicit| fragments, created and
managed by the document processor, and used to generate the Table of Content
and internal references of the document. Then there are |/explicit| fragments,
locations of significance within the document chosen by the author, that one
part of the document references, or links to, from another.

|^ Each section heading has two implicit fragment identifiers; a dot-point
numeric one used "internally", and another derived from the text of the
heading.  The text is compressed to an all alphanumeric, lower case string. 
The dot-point numeric can change with the addition or deletion of intervening
headings but the text-derived fragment identifier only changes when the heading
is modified.  It is a good choice when making a reference from another part of
the document, or from an external document.

|9A...|
|^ The alphanumeric text fragment is derived from document section headings. 
Many are visible in the document but some are not.  Some are placed by the
author to create meaningful cross-references within the document.  See
|link|Heading Cross-Reference||.

|^ Different headings having the same text will result in duplicate fragment
identifiers and generally the first in the document will be targeted by the
browser.  So avoid using the same description for multiple headings.  If this
is unavoidable the location can also be explicitly located with a unique
identifier using an explicit cross-reference as mentioned above.

|2Links to Other Documents|

|^ Links to |'wasdoc.wasDOC| documents are are indicated by a path with a final
element (the fragment) beginning with two hashes (|=./##||).  The two
differentiate it as a |'wasdoc.wasDOC| link and the path and hash are made
compliant with |'wasdoc.wasDOC| requirements.  One of the hashes is absorbed
when generating the link.  The fragment can be empty.  The links can be
relative, or site-absolute, or full URL references.  The final element of the
path is the fragment reference.  This is an example of a link to a document in
an adjacent location (directory).  The variants are all equivalent.

|mono|
\|link\|../Doc Two/##Somewhere Inside It\|\This is another document\|
\|link\|../doc_two/##Somewhere Inside It\|\This is another document\|
\|link\|../Doc Two/##somewhereinsideit\|\This is another document\|
\|link\|../doc_two/##somewhereinsideit\|\This is another document\|
\|link\|/wasd_root/src/wasdoc/Doc Two/##Somewhere Inside It\|\This is another document\|
\|link\|/wasd_root/src/wasdoc/doc_two/##somewhereinsideit\|\This is another document\|
||

In thse examples, the translated name of the directory containing the
document would be the equivalent of |=.[-.doc_two]| and the fragment
reference |=#somewhereinsideit||.  The browser would use the URI

|mono| /documents/doc_two/##somewhereinsideit ||

and it looks and behaves something like this
|mono| |link%|../Doc Two/##Somewhere Inside It|This is another document| ||

To link to the beginning of a document just include an empty hash

|mono| \|link\|../Doc Two/##\| ||

For this to work without additional mapping by the server there needs to be
a one-to-one correspondence between the referenced document and the translated
path to that document.  So a rule such as

|mono| pass /documents/* /doc_root/* ||

would provide access to document locations

|mono|
/documents/document_one/
/documents/document_two/
/documents/yet_another_document/
||

|^ Of course additional mappings may be in place to locate the documents just
about anywhere.

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