[ Programmer's Guide ]

[ Manual ]

Manual Markup #

This section describes the XML markup which is used in the source XML document (Max2Manual.xml) of this manual. You're assumed to have a basic understanding of XML but if you are only familiar with HTML you can think of XML as being an application specific form of that but with stricter rules:

The description here is rather general. For more details see the two transformation stylesheets: PreProc.xsl and Manual.xsl, and, slightly more readably but somewhat less definitively, the validation control file Manual.rng.

Namespace #

All of the element names in the manual XML file are in the namespace:

(For the curious, this is a Tag URI, something a bit like a URL except that it is just used for identification, not for actual retrieval.)

This is the default namespace in the source document so no prefixes are needed on the individual elements. In the XSLT stylesheets, though, the prefix max: is used to reference this namespace.

Markup Levels #

The following sections describe each of the element types which appear in the document. For ease of understanding they can be divided into three levels:

Structural #

The root <document-content> element and the <section> elements within it.

Block #

Paragraphs (<p>) and similar level elements such as tables, lists and images.

In-line #

Fragments of text within a paragraph, table or list which have particular special significance, such as cross-references, code, symbols or emphasised words.

These levels nest: structural elements only appear at the root or in other structural elements, block level elements within structural elements and in-line elements within blocks or within other in-line elements. The operation of the main XSLT transformation used to generate the HTML pages reflects this nesting; any elements not properly nested are likely to result in an error message being displayed by this process (though the checking is not necessarily bullet proof).

Structural elements #

<document-content> #

This is the top level element of the whole document. Its only attribute is title - the title of the document. Its contents are the top level <section> elements.

<section> #

These nested elements describe the bulk of the document structure. Their attributes are:

By the time the XML gets to the Main XSLT Transform every <section> must have an id attribute. However, the Pre-processing XSLT Transform will fill in the id in certain circumstances:

Sections can contain other sections or block elements. In some cases sections contain introductory block elements (paragraphs usually) then one or more sub-sections. In a few lower level sections, there can be some paragraphs after the last sub-section of a section. In general, a section contains zero or more block elements followed by zero or more section elements then zero or more paragraphs.

Block elements #

Block elements appear directly within an enclosing <section> element. Some contain sub-elements, as noted below.

<p> #

Normal paragraph. Contents are text and in-line elements.

<image> #

Like an HTML <img> element with src, width and height attributes (all of which should be present). Used to create HTML <img> elements in the output and also used by the Image Copy operation.

<bullet-list> #

Contents are a sequence of <bullet> items each of which should contain in-line content.

<labelled-item-list> #

Contains a sequence of <labelled-item> elements, each of which contains a <label> element followed by an <item>. The <label> can have a format attribute whose value must be code.

<table> #

May have a title attribute. Contains a sequence of <tr> elements, each of which contains one or more <th> or <td> elements, each of which contains inline text and elements.

<code-block> #

Used to display multiline code fragments. Lines are represented by the contained <code> and <text> elements. <code> elements represent lines of code whereas <text> elements represent lines of interjected text. Each can contain text and inline elements.

<limit> #

Used to document numerical limits in the program in Appendix C - Limits. Has four or more child elements:

By the time of the Main XSLT Transform step the <value> and <symbol> elements must be present but they can be filled in by the Pre-processing XSLT Transform if they're not present and the value is defined in the max2meta.xml file. Either:

<ebnf-rule-list> #

This, rather specialized, element is used to format the Extended Backus Naur Form productions in Appendix D - Export Account Information File Format. The contents are <ebnf-rule> elements which, in turn, contain <ebnf-rule-line> elements. The <ebnf-rule> elements have an id attribute which must be unique amongst all the <ebnf-rule> and <section> elements in the document. If you need to mess with these you know enough to work out the rest for yourself.

In-line elements #

In-line elements appear inside block level elements and also in some other in-line elements. They can contain text consisting of actual text and <nbsp> elements and, in some cases, other in-line elements.

Some can be marked with sample="true" attributes so that, if any processing is needed to extract the actual values for some purposes, the ones which are not real but just describe the format of this document can be ignored.

<nbsp> #

This empty element inserts a non-breaking space character in the output document. It can appear anywhere that text can appear (including in in-line elements which cannot normally contain other elements).

<caption> #

Used to mark up references to captions and similar text which appear in program windows. Content is text plus the <key> element which is used to underline the letter used to activate menu items, etc.

<trans-field> #

Used to mark up references by name to fields in Max transactions. Content is text.

<code> #

Used to mark up literal source code fragments. Content is text.

<symbol> #

Used to mark up individual symbols which appear in the program source code. Content is text.

<element> #

Used to mark up names of HTML or XML element types. Angle brackets are wrapped round the contents as part of the conversion to HTML. Content is text and other in-line elements.

<tag> #

Used to mark up samples of HTML and XML tags. Angle brackets are wrapped round the contents as part of the conversion to HTML. Content is text and other in-line elements.

<a> #

Used to mark up links to web documents outside this manual. The single required attribute is href which contains the target URL. The content is text and other in-line elements.

<todo> #

Used to mark up locations in the manual where more work is required. Empty element.

<emph> #

Used to mark up text which is to be shown in a way to indicate its importance or significance. Content is text.

<line-break> #

Used to indicate where a line-break is to be output. Empty element.

<xref> #

Used to mark up links within the manual. The target can be specified by id using the idref attribute or, if the idref attribute is not present, by title using the element's contents.

The form using the title for reference is intended for old links brought forward from the Microsoft Works version of this manual. Use of the idref attribute is recommended for any new text.

If the element is empty then the title of the target section is used as the contents.

Some examples of references to the first second-level section: