WASD Documentation Processor

4.Links

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.

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.

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

The Vbar-delimitted description can be an image.

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

4.1The 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.2Links 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.

Start of Document

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

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.

and it looks and behaves something like this