|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 (the string
following any |=\#| in a URL), is an identified location within a document. 
|'wasdoc.wasDOC| describes these as |/identifiers| and links to them, either
implicitly (internal links) or explicitly (externally into a document), as
|/references||.

|^ |*Each section| heading has |*three identifiers||.

|number#|
|& a dot-point numeric corresponding to the section number shown in major headings
|& one derived from the text of the heading (alphanumeric all lower-case string)
|& combination with a period-separated concatentation of the numeric and text
|!number|

|^ All internal document links use the concatenated identifier. 

|^  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.  The internal link
(combination) can generally be used as an external reference by just removing
the leading numeric element and using the alphanumeric string.  The dot-point
may also be used as the fragment identifier.

|^ 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 as much as practicable, 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.  Alternatively, prefix the alphanumeric with the dot-point number of the
most recent numbered heading.

|^ The above section may be directly accessed using

|simple#|
|& \<a href=\"#4.1\"\>|=.#4.1||\</a\>
|& \<a href=\"#4.1.theessentialfragment\"\>|=.#4.1.theessentialfragment||\</a\> 
|& \<a href=\"#theessentialfragment\"\>|=.#theessentialfragment||\</a\> 
|!simple|

|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

and it looks and behaves something like this

|mono| |link%|../Doc Two/##Somewhere Inside It|This is another document| ||

|0Start of 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.

|0Specific Section of Whole Document|

|^ Using the syntax described below a link to a section of another document may
be coupled with a separate link to the whole document.  Two lots of two
consecutive plus symbols delineate the section link, the conjunction, and the
title of the document.

|mono| \|link%\|../Doc Two/##Somewhere Inside It++in++Document Two\|  ||

|^ and it looks and behaves something like this

|mono| |link%|../Doc Two/##Somewhere Inside It++in++Document Two| ||

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