Using DocLite

by murlen


[Previous] [Contents] [Next]

DocLite Tags

Introduction and philosophy

DocLite introduces a small number of new tags that control content, page creation, and header/footer formatting. Other than that normal HTML tags are used, with the restriction that they are also well formed XML (all tags closed, tags closed in same order opened etc.)

Note that while all HTML is valid it is not necessarily a good idea to make the page too complex - typically the documentation is created with a text editor, and so should be readily readable. There should be no need to use much in the way of page layout (this is a documentation creation system not a web page generator). Stick to basic tags such as P,I,B,LI and maybe simple TABLEs.

This documentation was created using DocLite and should be consulted as an example, it is shipped in the distribution as doc.xml.

doclite

The doclite tag is the top level XML tag for a DocLite document, the (mandatory) 'name' attribute of this tag is the overall name for the document. Which is used as the contents page's HTLM TITLE and also can be used in headers and footers.

page

The page tag is used to indicate a new page, it also causes a top level entry to be made in the contents page. The 'name' attribute is mandatory, and is used as the html TITLE for the page and also in the contents page entry. e.g.

<page name="Main Page">foo bar foo bar</page>

section

The section tag is used to initiate a new section in the document, it has a mandatory 'name' attribute that is used to create the contents entry and also a H4 level heading in the page. It is possible to nest section tags, which will work in the contents (in terms of indentation), but the visual effect on the page may not be correct as H4 heading tags will still be used for the name. The subsection tag may be used in this case (see below)

For example:

<section name="My New Section">

header and footer

The header and footer tags control what appears at the top and bottom of the page. DocLite comes with sensible defaults for these, but you may wish to override them, for example the header for this documentation is:

<header> <center><h2>_TITLE_</h2><i>by murlen</i></center><br/>_NAVIGATE_<hr/> </header>

The _TITLE_ and _NAVIGATE_ tokens are expanded into the document title and the navigation links respectively.

The contents page uses the same header and footer as the first page of the document.

var

The var tag is used to introduce 'variables' typically these are used for blocks of text that may need to be repeated throught the document (for example links to web sites). These variables all share the same scope, so it is typical to define them at the start of the document

To define a variable set it's name attribute:

<var name="myvar">My Value for variable</var>

To use this variable in your text reference it by setting the ref attribute:

Variable text inserted after here <var ref="myvar"/> but before here
[Previous] [Contents] [Next]

created with DocLite