metadoctool
Generates a formatted document from a metadocument and XML data.
metadoctool [-html|-xml] metacodefile hasharrayfile [fnfile]
In the commhub ecosystem, metadoctool is a utility based upon the MetaDocument class. It is designed to take a metadocument and convert it into a formatted document. Presently, only HTML is supported on output. However, as computing trends change and other output formats become popular, metadoctool can be updated to output to those formats. It is a portability layer for formatted documents.
Metadoctool requires at least two input files – the metadocument (e.g. *.tpl) and an XML data file. Data from the XML file will be inserted into the formatted document as specified in the metadocument. A metadocument may contain metavariables/metafunctions; typically those are specified inside program code that the MetaDocument class externally calls, however when a metadocument is being created, it may be handy to specify values for those metavariables/metafunctions. For this, the third input may be optionally provided.
Command |
Action |
-html |
Convert the metacodefile into an HTML content (default). Output is sent to stdout. CSS definitions are drawn from http://maeappsite.com/maedoc.css |
-xml |
Output the MetaDocument internal representation for the portable document as XML. This may be handy to understand the raw portable document before it is output as the formatted document. |
A metadocument (metacodefile) typically has the file suffix of .tpl and, by default, resides in /usr/mae/html/template. In practice, it may reside anywhere.
Each line of the metadocument is a command toward generating formatted output. Output text is grouped into blocks. A block may be a paragraph, section, table (a container of blocks), table cell, or similar. Parameters to commands are variables (extracted from XML), literals (strings, numbers), metavariables or metafunctions. Metavariables and functions both begin with $ followed by an identifier. A metafunction additionally has parenthesis with parameters.
Programmatically, blocks are achieved via indentation, like Python. The commands to execute for an if statement will follow it, but be indented. The next command with the same indentation as the if command (or less indentation) implicitly ends the if block.
A line beginning with a # is ignored as a comment line. Commands may have simple terms; there are no expressions like format programming languages; if expressions are needed, you likely need a formal programming language, not metadoctool.
Term Part |
Description | ||||||||||||||||||||||||
style |
A style is defined in a separate configuration file specific to the output format. For example, HTML output uses the CSS file http://maeappsite.com/maedoc.css, which defines the available styles. These styles are built in:
| ||||||||||||||||||||||||
text_term |
A text term may be quoted text, a number, a field, or a metavariable/metafunction.
| ||||||||||||||||||||||||
text_terms |
One or more text_term values, separated by whitespace. | ||||||||||||||||||||||||
xpath |
This is a path through the XML data provided. When used inside a with block, the path is tried from both the current level and the top of the XML data. An XML references each level as it descends into the data structure (the data inside the hasharrayfile command line file with each level separated by “/”. Note that when multiple records exist with the same name (like an array), the desired array offset (starting at 0) may be specified inside square brackets. For example: /record/person[4]. The path may be many levels deep. |
Syntax: { [style]
An open curly bracket signals the beginning of a paragraph – a block of sentences/text. It may optionally be followed by a style name. The style will be applied across the paragraph. A style is defined in a separate configuration file specific to the output format. For example, HTML output uses the CSS file /maedoc.css, which defines the available styles.
Syntax: }
An close curly bracket signals the end of a paragraph.
Syntax: {{ section-type
Begin a document section. A paragraph and table or other block cannot cross a section boundary. A section is typically used for text that is like-wise similarly formatted, but different than other areas of the document. A default document implicitly has one section (1-column), but additional sections may be added. Valid section types are:
Style Type |
Description |
1-column |
Page width will be a single column of text, like a letter or book. |
2-column |
Page width will contain 2 columns. Text will flow down left column, then continue at top of right column. |
3-column |
Page width will contain 3 columns. Text will flow down left column, then continue at top of middle column. After flowing down the middle column, it will continue at the top of the right column. This style is handy for lists of items that are short (shorter than 1/3 page width). |
Syntax: }}
End a document section; return to the default document 1-column section type.
Syntax: h1 text_terms
Output a header line. Headers are indented/hierarchical with h1 being the top level, h2 below that, h3 below that, etc. down to h9. Note that h1 and H1 are both valid.
Syntax: [write] text_terms [using style]
Output text into the flow of the document. Text may be quote text, a number, a field, or a metavariable/metafunction. See text_terms above. If the text should be output a particular way, specify the using term followed by the style (see style above.)
Syntax: table name rows cols [fmt]
Create a table. A name must be provided so it may later be referenced. The size of the table in the rows and columns parameter. Note that more rows may be added to the table (see below). If the fmt parameter is specified, it may be left, right, or center, which aligns the table on the page as flush left, flush right, or balanced in the middle.
Syntax: [tablename](r,c) [using style] [command]
Move to a table cell and perform the command, if specified. A table cell is a block of flowing text; text written into a table cell is added to any text already written to that cell. The table name is optional; if specified, it refers to that table. When no table name is specified, the current table is used. The numbers inside the parenthesis refer to the row and column – specify numbers. A style for the cell may be specified with the using keyword.
Syntax: (,c) [command]
Move to the specified column in the current row. The value of c must be a number.
Syntax: (+,c) [command]
Move down a row and to column c. The value of c must be a number. When there is no additional row, another row is added. This is handy for adding rows when the size of the table is not known when the table is started. After moving to the new table cell, the command is processed, if specified.
Syntax: (,+) [command]
Move right a column in the same row. When there is no additional column, it stays in the current cell.
Finish Table / Move to End of Table / Move to End of Document
Syntax: ()
When inside a table, this moves text flow to immediately after the table. When outside a table, this moves text flow to the end of the document.
Syntax: if text_term
If the text_term resolves to non-null text, then process the indented commands following the if line.
Syntax: else
When inside an if block, the commands inside the else block are processed when the if condition is false (null text). Strictly speaking, the else block is executed if the preceding if or else block was not processed.
Syntax: foreach text_term
Loops through the indendent commands following foreach for each value in the text_term. If the text is a CSV list, then each value in the list will be used for looping. Otherwise, only one iteration will be performed with the text provided. If no text is provided, the block or commands is not processed. Inside the foreach block, use the metavariable $i to reference the current value for the loop. For embedded foreach loops, use $j (1st nested block), $k (2nd nested block), etc. to $n.
Syntax: with xpath
Move into an XML structure so more fields can be referenced. If /people/person[3] references the 4th array element of the array of person records under people, then the properties of that array element are available as a field for text_term. This is like the Pascal with statement.
Syntax: witheach xpath
This command combines foreach and with - it processes an array of XML records, making each iterated record available as a field for term_text. If the XML data contains people which contains an array of person record, then "witheach people/person" will iterator over each person record.
The fncode file contains a list of metafunction names with their code blocks. For the metafunction, just specify the leading “$” followed by the function name. For example:
$Weapons
{
write "Weapon Table Here"
}