Max2: Programmer's Guide: Manual

[ < Prev | Contents | Next > ]

[ 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:

• Instead of using the element types and attributes of HTML (<p>, <img src="...">, etc.) XML allows application specific names to be used.
• Start tags must always be matched by corresponding end tags (e.g., <p> with a following </p>). An empty element can be written as a single empty tag with a slash at the end (e.g., <line-break/>).
• Names of elements and attributes are case sensitive. In this manual they're all lower case.
• Attribute values must always be present and must be quoted, e.g., <xref sample="true"> rather than <xref sample> or <xref sample=true>.

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:
tag:edavies.nildram.co.uk,2003-08-12:max

(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:

• level: Required. The level within the structure of the document. One of "1", "2", "3", "3.5" or "4". Each section must be at a lower level (higher number) than its containers but in some cases levels can be skipped. Usually level 3.5 is skipped except in sections which require more than four levels.
• title: Required. The title displayed for the section and also used as the target identification in some <xref> elements.
• id: Required, except as described below. Must be distinct from the id of any other <section> or <ebnf-rule> in the manual.
• sub-id: Optional, alternative to the id attribute as described below.
• file: Optional. The root file name of the HTML file to contain the contents of the section, if it is to go in a separate file. The name doesn't contain the extension ("Markup" rather than "Markup.html") for compactness and to allow future changes (e.g., use of different types). Causes a reference to be written to the current output document enclosed in square brackets and in a separate paragraph.
• format: Optional. Only applicable to level 4 sections. It's optional even at level 4. Indicates the style of the title. Where present, it must one of code, caption or trans-field.

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:

• For sections which have a sub-id attribute the id is created by concatenating the sub-id on to the end of the id of the parent section with an intervening underscore. This rule applies recursively up to the top level section, if required, making a long id by chaining sub-ids at each level down.
• The top level sections within procedures within the Procedures section are set automatically from their title text, which must be one of a small list of fixed values: see Format
• Fields in Appendix B - Flight Transaction Fields have their id set automatically from their title and the id of the enclosing section: the title attribute acts like a sub-id attribute in addition to its normal operation.

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:

• <symbol>: Required. The VB or C++ symbol for the limit.
• <value>: Required, but see below. The numerical value of the limit.
• <file>: Required. The VB or C++ source file in which the limit is defined.
• <text>: Required. Textual description of the limit. Content can be plain text or, if it contains any elements, then block level content.
• <type>: Optional. Used to fill in the value in the pre-processing step.
• <field>: Optional. Used to fill in the value in the pre-processing step.

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:

• The <symbol> is used to look up the value in the max2meta.xml file or
• The <type> and <field> are used to look up an individual field within a structure described in the max2meta.xml file. The <symbol> is set to the concatenation of the type and field (separated by double colons in C++ notation) and the <value> is set to the length of the field. Typically this is used for fixed length strings.

<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:

• <xref>Document Layout</xref>: A reference by title which uses the title specified as the link text, like this: Document Layout.
• <xref idref="doc-layout"/>: A reference by id which uses the title specified on the target section for the link text, like this: Document Layout
• <xref idref="doc-layout">layout section</xref>: A reference by id which uses the contents of the <xref> element as the link text, like this: layout section