# WASD Documentation Processor

# 4.Links

4.1 The Essential Fragment
4.2 Links to Other Documents

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

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.

Syntax | Example
--- | ---
|https://wasd.vsm.com.au/| | https://wasd.vsm.com.au/
|https://wasd.vsm.com.au/|A link to WASD| | 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| | WASD download in a new page

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.

Syntax | Example
--- | ---
|link|Chapter Insertion| | ‘Chapter Insertion’ in 2.6 Lists
|link%|Chapter Insertion|jump to Insertion| | jump to Insertion
|link*&background-color:azure;|Chapter \ Insertion|bold, coloured link to Insertion| | bold, coloured link to Insertion

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

Syntax | Example
--- | ---
|link|#tableofcontent| |
|link%|#tableofcontent|Jump to \ Table of Content| | Jump to Table of Content

The Vbar-delimitted description can be an image.

Syntax | Example
--- | ---
|link%|/wasd_root/src/wasdoc/*.*|image&\ width:3em;|../doc/wasdoc.png| |

## 4.1 The Essential Fragment

A wasDOC fragment, being based on the HTML fragment (the string following any # in a URL), is an identified location within a document. 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.

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

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

- #4.1
- #4.1.theessentialfragment
- #theessentialfragment

## 4.2 Links to Other Documents

Links to 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 link and the path and hash are made compliant with 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.

|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
This is another document

##### Start of Document

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

|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
pass /documents/* /doc_root/*
would provide access to document locations
/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.

##### Specific 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.

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

and it looks and behaves something like this

Somewhere Inside It in Document Two

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