NOTE: SOME FUNCTIONALITY EMPLOYS JAVASCRIPT WASD Documentation Processor – 4. Links
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.7 Insertion
|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| #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.1The Essential Fragment

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

A...

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 ‘Heading Cross-Reference’  in  2.1 Document Sections.

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.

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.

|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
/documents/doc_two/##somewhereinsideit
and it looks and behaves something like this
This is another 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.

↩︎ ↖︎ ↑︎ ↘︎ ↪︎