Contributing

The Aqsis documentation is authored as part of this very wiki site. There is a separate section of the wiki, here that forms the official Aqsis documentation. The documentation section of the wiki is also converted periodically to PDF form to be delivered with the various binary packages and made available to those users who prefer printable documentation. The process of converting the wiki content to PDF is automatically handled by the wiki system, and as such is subject to some restrictions and rules. These rules ensure that the documentation, when converted to PDF follows a common standard.

The various regulations when authoring documentation content are now described in detail.

The main documentation index page shows a table of contents that should match that generated as part of the PDF export. However, this table is not actually exported as part of the PDF. The table of contents in the exported content is generated by the system by analysing the various headings used in the linked documentation. The conversion process follows all links from this main page and stores information about the headings used to create a table of contents.

• A H1 heading, identified by surrounding the tile with a matching pair of 6 '=' symbols, i.e. ====== Heading 1 ======, corresponds to a chapter in PDF. An example of this is the Getting Started section of the manual, it has a H1 heading, which will delimit a new chapter in the manual.

  This heading type should only be used to create a new chapter. Consider carefully if the content you are creating belongs under an existing chapter before creating one of these.

• A H2 heading, identified by a matching pair of 5 '=' symbols, i.e. ===== Section =====, corresponds to a section in PDF.

  This heading type should be used to mark the start of a new, unrelated, section of information in the current chapter. That is, the content described after this heading should not be directly related to the previous section. An example is the various aqsis tools described as part of chapter 2. They are all related by being tools in the aqsis suite, that relationship is covered by being in the same chapter, but otherwise are unrelated, the operation of aqsl is not directly related or dependent on the operation of aqsis.

Other headings, H3, H4 H5 and H6, correspond to subsection, subsubsection, paragraph and subparagraph. These are used within a section to control separation of the information within a section. They should be used carefully so as not to create a disjointed reading experience. Only when the following content needs to be separated from the previous to some level should they be used.

The PDF conversion will spot and deal with most of the standard markup available as part of DokuWiki, including basic formatting, lists (ordered and unordered), tables, images, typography, syntax highlighting, footnotes, smileys and acronyms. If you encounter a feature that doesn't work, or doesn't behave as you'd expect when exported to PDF, contact us and we'll try to rectify it.

In addition, the export fully supports the advanced lists syntax provided by the simple universal list plugin. Again, if this conversion doesn't produce PDF that you'd expect, please contact us.