<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>The Lambtex Manual</title><meta charset="utf-8"/><link rel="stylesheet" href="css/lambdoc.css" media="all" title="Default"/></head><body><div class="doc doc_valid"><h1 class="doc_title">The <span class="doc_caps">lambtex</span> Manual</h1><h2 class="doc_title">Dario Teixeira</h2><h2 class="doc_title">June 2016</h2><h1 id="doc:m:sec:toc" class="doc_sec"><span>Table of Contents</span></h1><ul class="doc_toc"><li class="doc_item doc_level0"><a class="doc_lnk" href="#doc:m:part:tutorial"><span class="doc_caps">lambtex</span> tutorial</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:m:sec:anatomy"><span class="doc_order">1</span>The anatomy of <span class="doc_caps">lambtex</span> documents</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:m:sec:paragraphs"><span class="doc_order">2</span>Paragraph blocks</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:m:sec:inline"><span class="doc_order">3</span>Formatting inline text</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:a:1"><span class="doc_order">4</span>Special characters</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:a:2"><span class="doc_order">5</span>Hyperlinks to external resources</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:a:3"><span class="doc_order">6</span>List environments</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:m:sec:qanda"><span class="doc_order">7</span>Q&amp;A environments</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:m:sec:verse"><span class="doc_order">8</span>Verse environments</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:m:sec:quotations"><span class="doc_order">9</span>Quotations</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:m:sec:verbatim"><span class="doc_order">10</span>Verbatim environments</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:m:sec:code"><span class="doc_order">11</span>Presenting source-code</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:a:4"><span class="doc_order">12</span>Tabular environments</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:m:sec:math"><span class="doc_order">13</span>Mathematical formulas</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:a:5"><span class="doc_order">14</span>Images</a></li><li class="doc_item doc_level2"><a class="doc_lnk" href="#doc:m:sec:glyphs"><span class="doc_order">14.1</span>Glyphs</a></li><li class="doc_item doc_level2"><a class="doc_lnk" href="#doc:a:6"><span class="doc_order">14.2</span>Pictures</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:m:sec:subpage"><span class="doc_order">15</span>Sub-pages</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:m:sec:headings"><span class="doc_order">16</span>Parts and sections</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:m:sec:intlinks"><span class="doc_order">17</span>Internal hyperlinks</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:m:sec:pull"><span class="doc_order">18</span>Pull-quotes</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:m:sec:boxouts"><span class="doc_order">19</span>Declaring and using boxouts</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:m:sec:theorems"><span class="doc_order">20</span>Theorem-like environments</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:m:sec:wrappers"><span class="doc_order">21</span>Wrappers</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:m:sec:frontmatter"><span class="doc_order">22</span>Frontmatter: title, abstract, and table of contents</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:a:12"><span class="doc_order">23</span>Rules</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:m:sec:onnotes"><span class="doc_order">24</span>Adding notes to a document</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:m:sec:onbiblio"><span class="doc_order">25</span>Adding a bibliography</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:m:sec:onappendix"><span class="doc_order">26</span>Creating an appendix</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:m:sec:macros"><span class="doc_order">27</span>Macros</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:a:13"><span class="doc_order">28</span>Concluding remarks</a></li><li class="doc_item doc_level0"><a class="doc_lnk" href="#doc:m:part:theappendix">Appendix</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:m:sec:structure"><span class="doc_order">A</span>The structure of <span class="doc_caps">lambtex</span> documents</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:m:sec:synonyms"><span class="doc_order">B</span>Command synonyms</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:m:sec:parameters"><span class="doc_order">C</span>Command parameters</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:m:sec:order"><span class="doc_order">D</span>Notes on ordering</a></li><li class="doc_item doc_level0"><a class="doc_lnk" href="#doc:a:14">Backmatter</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:m:sec:thenotes">Notes</a></li><li class="doc_item doc_level1"><a class="doc_lnk" href="#doc:m:sec:thebiblio">Bibliography</a></li></ul><hr class="doc_rule"/><p class="doc_par doc_class_initial"><span class="doc_caps">lambtex</span> is a document description language. It is largely inspired by <span class="doc_caps">LaTeX</span><span class="doc_cite">[<a class="doc_lnk" href="#doc:m:bib:latex">1</a>]</span>, both in its syntax and in the approach taken for the description of documents. In basic terms, the source for a <span class="doc_caps">lambtex</span> document is composed of plain <span class="doc_caps">utf-8</span> text annotated with special commands that attach a precise semantical meaning to elements. There are commands for formating passages in a special manner (emphasised, superscript, etc), and commands that declare high-level constructs such as section headings, quotation blocks, boxouts, or pictures. <span class="doc_caps">lambtex</span> was especially designed to be used in web applications, and as such it supports fully hyperlinked documents. Moreover, its syntax is simple, consistent, and designed with brevity in mind.</p><p class="doc_par">This manual is divided into two parts: a <a class="doc_lnk" href="#doc:m:part:tutorial"><span class="doc_caps">lambtex</span> tutorial</a> and an <a class="doc_lnk" href="#doc:m:part:theappendix">appendix</a>. The tutorial introduces all the principles and features of the language, whereas the appendix provides reference information concerning miscelaneous issues which do not fit into the main flow of the manual.</p><h1 id="doc:m:part:tutorial" class="doc_part"><span><span class="doc_caps">lambtex</span> tutorial</span></h1><h1 id="doc:m:sec:anatomy" class="doc_sec"><span class="doc_order">1</span><span>The anatomy of <span class="doc_caps">lambtex</span> documents</span></h1><p class="doc_par">A <span class="doc_caps">lambtex</span> document is essentially a sequence of blocks. A block is for example a paragraph of text, a section heading, a figure, or a table. Blocks typically occupy the full width of the page and are vertically separated from other blocks by a small margin. In the document source, whitespace is irrelevant when it comes to the separation of blocks.</p><p class="doc_par">Many blocks are composed of <i class="doc_emph">inline text</i>. Paragraphs and section headings are good examples of such blocks. Inline text is a sequence of plain text and special characters intermixed with sequences of emphasised text, superscript text, etc. You can thus speak of <i class="doc_emph">block-level</i> and <i class="doc_emph">inline-level</i> elements in a <span class="doc_caps">lambtex</span> document.</p><p class="doc_par">Inline-level elements are declared by <i class="doc_emph">simple</i> commands, while block-level elements may be declared by either simple or <i class="doc_emph">environment</i> commands<span class="doc_see">(<a class="doc_lnk" href="#doc:m:note:commands">1</a>)</span>. The former take the generic shape <code class="doc_mono">\<i class="doc_emph">command</i>{...}</code>, where the content inside the curly brackets constitutes the parameters to the command. Note that some simple commands may take more than one parameter (in which case more than one set of curly brackets is used), while others exist that take no parameters at all. As for environment commands, they are composed of two parts: an initial and a final tag, which together delineate the contents of the environment. The initial tag takes the form <code class="doc_mono">\begin{<i class="doc_emph">command</i>}</code>, while the final tag is <code class="doc_mono">\end{<i class="doc_emph">command</i>}</code>.</p><p class="doc_par">Besides the (normally mandatory) primary parameters, both simple and environment commands accept three other kinds of (usually optional<span class="doc_see">(<a class="doc_lnk" href="#doc:m:note:optional">2</a>)</span>) parameters: order parameters, label parameters, and style parameters. The first are enclosed by round brackets and are used to override the automatic ordering associated with blocks such as sections and equations. The second are enclosed by square brackets and are used for assigning a label to any block that may be referenced from somewhere else in the document. Finally, style parameters are enclosed between angle brackets and provide the mechanism for customising the appearance of individual document elements. For the sake of reference, <a class="doc_lnk" href="#doc:m:tab:parameters">Tab.&#xa0;1</a> lists all the classes of parameters and the characters used for enclosing them.</p><div id="doc:m:tab:parameters" class="doc_wrapper doc_floatable doc_table"><div class="doc_tab"><div class="doc_tab_aux"><table><thead class="doc_tgroup"><tr><td class="doc_cell_c"></td><td class="doc_uline doc_cell_c" colspan="2">Markers</td></tr><tr><td class="doc_cell_c">Parameter</td><td class="doc_cell_c">Begin</td><td class="doc_cell_c">End</td></tr></thead><tbody class="doc_tgroup"><tr><td class="doc_cell_c">Order</td><td class="doc_cell_c"><code class="doc_mono">(</code></td><td class="doc_cell_c"><code class="doc_mono">)</code></td></tr><tr><td class="doc_cell_c">Label</td><td class="doc_cell_c"><code class="doc_mono">[</code></td><td class="doc_cell_c"><code class="doc_mono">]</code></td></tr><tr><td class="doc_cell_c">Style</td><td class="doc_cell_c"><code class="doc_mono">&lt;</code></td><td class="doc_cell_c"><code class="doc_mono">&gt;</code></td></tr><tr><td class="doc_cell_c">Primary</td><td class="doc_cell_c"><code class="doc_mono">{</code></td><td class="doc_cell_c"><code class="doc_mono">}</code></td></tr></tbody></table></div></div><div class="doc_caption doc_caption_long"><div class="doc_caption_aux"><h1 class="doc_caption_head">Tab.&#xa0;1:</h1><p class="doc_caption_body">The four classes of parameters that may be given to <span class="doc_caps">lambtex</span> commands. Primary parameters are typically mandatory and are enclosed by curly brackets. Order, label, and style parameters are usually optional and are enclosed by round, square, and angle brackets, respectively.</p></div></div></div><p class="doc_par">Style parameters come in two varieties: key-value pairs and classnames. The former variety takes the form '<code class="doc_mono"><i class="doc_emph">key</i>=<i class="doc_emph">value</i></code>', and is available only for some commands. Moreover, what constitutes a valid key-value combination is command dependent, and is described in more detail in the section that describes each of those commands. As for classname parameters, they map to <span class="doc_caps">html</span> classnames in a straightforward way, and are available for every command. If, for example, you were to provide '<code class="doc_mono">important</code>' as the style parameter to a command, this would be interpreted as a classname declaration, and translated into the <span class="doc_caps">html</span> classname '<code class="doc_mono">doc_class_important</code>' (the prefix '<code class="doc_mono">doc_class_</code>' is preppended to every custom classname declaration to prevent name clashes). Note that classnames must begin with a lowercase Roman letter, and may contain only lowercase Roman letters, digits, the character '<code class="doc_mono">-</code>' (dash), or the character '<code class="doc_mono">_</code>' (underscore).</p><p class="doc_par">Bear in mind that <span class="doc_caps">lambtex</span> is agnostic on the validity and semantics of each command/classname combination. Nevertheless, <span class="doc_caps">lambdoc</span> — the library that provides <span class="doc_caps">lambtex</span> support for applications — does have facilities for restricting the set of acceptable command/classname combinations. Therefore, you may find yourself using <span class="doc_caps">lambtex</span> in an application that may forbid classname style parameters altogether, or that at least severely limits their use. Note also that because some block customisations are so widespread, the default <span class="doc_caps">css</span> shipped with <span class="doc_caps">lambdoc</span> includes declarations for the most common customisations. These are described in detail in the section that describes each command.</p><p class="doc_par">In the case of order and label parameters, the attributed value is necessarily singular, as it makes no sense to give multiple orderings to the same command nor it is possible to assign multiple labels to one command. In the case of style parameters, however, multiple attributions separated by a '<code class="doc_mono">,</code>' (comma) may be given.</p><p class="doc_par">Not all of the optional parameters are available for all commands. There are in fact many commands for which only style parameters are applicable. Moreover, for those commands where one or more optional arguments are accepted, they may be specified in any order as long as they appear before any of the primary (curly bracketed) parameters.</p><h1 id="doc:m:sec:paragraphs" class="doc_sec"><span class="doc_order">2</span><span>Paragraph blocks</span></h1><p class="doc_par">Paragraphs are the simplest of all blocks, typically being composed of just a sequence of inline text terminated by a blank line. It is however also possible to declare a paragraph via the simple command <code class="doc_mono">\paragraph</code> or its synonym <code class="doc_mono">\p</code>. Should you choose the simple command, the paragraph contents are to be specified inside the mandatory curly brackets. Consider thus the following <span class="doc_caps">lambtex</span> source fragment:</p><div class="doc_src_block doc_class_boxed"><pre class="doc_src_code">
<code class="doc_src_line doc_src_dummy"></code>
<code class="doc_src_line">This is the first example of a paragraph.  Note that</code>
<code class="doc_src_line">it is composed of inline text.</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">Lines can be broken at any point, because a paragraph</code>
<code class="doc_src_line">is only terminated by a blank line. \br</code>
<code class="doc_src_line">It is however possible to manually insert a line break</code>
<code class="doc_src_line">without terminating the paragraph.</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">\p{There is also a simple command that allows the</code>
<code class="doc_src_line">explicit declaration of a paragraph.}</code>
<code class="doc_src_line doc_src_dummy"></code></pre></div><p class="doc_par">The result produced by the composer is as follows:</p><div class="doc_subpage"><p class="doc_par">This is the first example of a paragraph. Note that it is composed of inline text.</p><p class="doc_par">Lines can be broken at any point, because a paragraph is only terminated by a blank line. <br class=""/> It is however possible to manually insert a line break without terminating the paragraph.</p><p class="doc_par">There is also a simple command that allows the explicit declaration of a paragraph.</p></div><p class="doc_par">Note that the line breaks within the text are irrelevant for the composer; all that it cares about are that blank lines separate paragraphs. if you wish for a line break within a paragraph (ie, without terminating the current paragraph), use the <code class="doc_mono">\br</code> simple command, as demonstrated.</p><p class="doc_par">Using the command <code class="doc_mono">\paragraph</code> (or its synonym <code class="doc_mono">\p</code>) to declare a paragraph is usually neither necessary nor recommended. This method exists for the sole reason that it may be desirable to provide the composer with style parameters for the paragraph.</p><p class="doc_par">The default <span class="doc_caps">css</span> shipped with <span class="doc_caps">lambdoc</span> supports three style customisations for paragraphs. The associated classnames are <code class="doc_mono">initial</code>, <code class="doc_mono">indent</code>, and <code class="doc_mono">noindent</code>. The first declares that the first letter of the paragraph should be rendered as an <a class="doc_lnk" href="http://en.wikipedia.org/wiki/Initial">initial</a>. The second and third indicate whether the default paragraph indentation rules should be overriden. By default, a paragraph is only indented when immediately preceded by another paragraph. By providing the <code class="doc_mono">indent</code> classname as a style parameter, you are declaring that the paragraph should always be indented regardless of context. Similarly, the <code class="doc_mono">noindent</code> classname indicates that the paragraph should not be indented no matter what.</p><h1 id="doc:m:sec:inline" class="doc_sec"><span class="doc_order">3</span><span>Formatting inline text</span></h1><p class="doc_par">As shown by <a class="doc_lnk" href="#doc:m:tab:inline">Tab.&#xa0;2</a>, <span class="doc_caps">lambtex</span> offers a broad set of text formatting commands. Remember that besides their application inside paragraph blocks, any of these commands may also be used in a context where inline text is allowed. That means you may use them in section titles, figure captions, inside tables, etc. Note that with the exception of <code class="doc_mono">\code</code> — which takes raw text as parameter — all inline formatting commands take as parameter a sequence of inline text. It is thus perfectly possible to nest these commands without any restrictions. Moreover, some of these commands have (typically shorter) synonyms. Therefore, instead of <code class="doc_mono">\bold</code> you can also just type <code class="doc_mono">\b</code>.</p><div id="doc:m:tab:inline" class="doc_wrapper doc_floatable doc_table"><div class="doc_tab"><div class="doc_tab_aux"><table><thead class="doc_tgroup"><tr><td class="doc_cell_r">Command</td><td class="doc_cell_l">Example</td></tr></thead><tbody class="doc_tgroup"><tr><td class="doc_cell_r"><code class="doc_mono">\bold{<i class="doc_emph">inline</i>}</code></td><td class="doc_cell_l">You can make some passages be <b class="doc_bold">bold</b>.<br class=""/> (Synonyms: <code class="doc_mono">\strong</code> and <code class="doc_mono">\b</code>)</td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\emph{<i class="doc_emph">inline</i>}</code></td><td class="doc_cell_l">Here's another way to <i class="doc_emph">emphasise</i> text.<br class=""/> (Synonyms: <code class="doc_mono">\em</code> and <code class="doc_mono">\i</code>)</td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\mono{<i class="doc_emph">inline</i>}</code></td><td class="doc_cell_l">You can also imitate a <code class="doc_mono">typewriter</code>.<br class=""/> (Synonym: <code class="doc_mono">\tt</code>)</td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\caps{<i class="doc_emph">inline</i>}</code></td><td class="doc_cell_l"><span class="doc_caps">lambtex</span> supports text in small-caps.</td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\ins{<i class="doc_emph">inline</i>}</code></td><td class="doc_cell_l">Sometimes it's <ins class="doc_ins">very</ins> handy to insert new text.</td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\del{<i class="doc_emph">inline</i>}</code></td><td class="doc_cell_l">You may also fix <del class="doc_del">annoying</del> incorrect passages.</td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\sup{<i class="doc_emph">inline</i>}</code></td><td class="doc_cell_l">The 1<sup class="doc_sup">st</sup> of January has a superscript.</td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\sub{<i class="doc_emph">inline</i>}</code></td><td class="doc_cell_l">H<sub class="doc_sub">2</sub>O requires a subscript.</td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\mbox{<i class="doc_emph">inline</i>}</code></td><td class="doc_cell_l"><span class="doc_mbox">This inline sequence should not be split across lines.</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\span{<i class="doc_emph">inline</i>}</code></td><td class="doc_cell_l"><span class="">You may create spans with custom semantics.</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\code{<i class="doc_emph">raw</i>}</code></td><td class="doc_cell_l">You can use syntax-highlighted code like <span class="doc_src_inline"><span class="doc_src_Kwd">type</span> t <span class="doc_src_Sym">=</span> <span class="doc_src_Type">Alpha</span> <span class="doc_src_Sym">|</span> <span class="doc_src_Type">Beta</span></span> in an inline context. See <a class="doc_lnk" href="#doc:m:sec:code">Section&#xa0;11</a> for details.</td></tr></tbody></table></div></div><div class="doc_caption doc_caption_long"><div class="doc_caption_aux"><h1 class="doc_caption_head">Tab.&#xa0;2:</h1><p class="doc_caption_body">List of all text formatting commands, including synonyms where applicable. All these commands take one parameter enclosed in curly brackets. The parameter is a sequence of inline text.</p></div></div></div><p class="doc_par">While most commands listed in the table above should have a straightforward application, a few clarifying words concerning <code class="doc_mono">\span</code> are in order. This command translates directly into an <span class="doc_caps">xhtml</span> <code class="doc_mono">span</code> element, and exists for the sole purpose of associating a span of text with a custom semantic meaning beyond those listed in <a class="doc_lnk" href="#doc:m:tab:inline">Tab.&#xa0;2</a>.</p><h1 id="doc:a:1" class="doc_sec"><span class="doc_order">4</span><span>Special characters</span></h1><p class="doc_par"><span class="doc_caps">lambtex</span> allows the direct use of <span class="doc_caps">html</span> entities via the same notation used in <span class="doc_caps">html</span>. More precisely, entities are to be enclosed between the characters '<code class="doc_mono">&amp;</code>' (ampersand) and '<code class="doc_mono">;</code>' (semicolon), and may be specified by the so-called <i class="doc_emph">character entity reference</i> (ie, the entity's name), or by <i class="doc_emph">numeric character reference</i> (ie, a <span class="doc_caps">unicode</span> code point in decimal or hexadecimal notation). As an example, if the <span class="doc_caps">euro</span> symbol '<code class="doc_mono">€</code>' is not readily available in your keyboard, you may enter it in either of the following three manners:</p><div class="doc_tab"><div class="doc_tab_aux"><table><thead class="doc_tgroup"><tr><td class="doc_cell_c">Name</td><td class="doc_cell_c">Decimal</td><td class="doc_cell_c">Hexadecimal</td></tr></thead><tbody class="doc_tgroup"><tr><td class="doc_cell_c"><code class="doc_mono">&amp;euro;</code></td><td class="doc_cell_c"><code class="doc_mono">&amp;#8364;</code></td><td class="doc_cell_c"><code class="doc_mono">&amp;#x20ac;</code></td></tr></tbody></table></div></div><p class="doc_par">The reader will have noted that <span class="doc_caps">lambtex</span> must interpret the character '<code class="doc_mono">&amp;</code>' (ampersand) differently, and therefore you need a workaround if you want to input an actual ampersand. In fact, there are other characters besides the ampersand that are interpreted differently by <span class="doc_caps">lambtex</span>, and as such also require a special escaping sequence. These characters are '<code class="doc_mono">\</code>' (backslash), '<code class="doc_mono">{</code>' (opening curly bracket), '<code class="doc_mono">}</code>' (closing curly bracket), and '<code class="doc_mono">|</code>' (pipe). The character used for escaping is the backslash, which means that displaying an ampersand, for example, is achieved with <code class="doc_mono">\&amp;</code>. Another option in this particular case is of course to use the <code class="doc_mono">&amp;amp;</code> <span class="doc_caps">html</span> entity<span class="doc_see">(<a class="doc_lnk" href="#doc:m:note:ampersand">3</a>)</span>.</p><p class="doc_par">Besides individual characters, there are also some multi-character sequences that are interpreted differently by <span class="doc_caps">lambtex</span>. <a class="doc_lnk" href="#doc:m:tab:seq">Tab.&#xa0;3</a> lists all of them. Remember to use the escape character if you wish to input any of these sequences literally.</p><div id="doc:m:tab:seq" class="doc_wrapper doc_floatable doc_table"><div class="doc_tab"><div class="doc_tab_aux"><table><thead class="doc_tgroup"><tr><td class="doc_cell_c">Sequence</td><td class="doc_cell_l">Translation</td></tr></thead><tbody class="doc_tgroup"><tr><td class="doc_cell_c"><code class="doc_mono">$$</code></td><td class="doc_cell_l">Delimiter for inline <span class="doc_caps">TeX</span> mathematics</td></tr><tr><td class="doc_cell_c"><code class="doc_mono">---</code></td><td class="doc_cell_l">Typographic em-dash</td></tr><tr><td class="doc_cell_c"><code class="doc_mono">--</code></td><td class="doc_cell_l">Typographic en-dash</td></tr><tr><td class="doc_cell_c"><code class="doc_mono">``</code></td><td class="doc_cell_l">Opening double quotes</td></tr><tr><td class="doc_cell_c"><code class="doc_mono">''</code></td><td class="doc_cell_l">Closing double quotes</td></tr></tbody></table></div></div><div class="doc_caption doc_caption_long"><div class="doc_caption_aux"><h1 class="doc_caption_head">Tab.&#xa0;3:</h1><p class="doc_caption_body">Special character sequences and their <span class="doc_caps">lambtex</span> interpretation. Remember to use the backslash for escaping if you wish to input any of these sequences verbatim. Also, see <a class="doc_lnk" href="#doc:m:sec:math">Section&#xa0;13</a> for details about entering mathematics.</p></div></div></div><p class="doc_par">What if the glyph you wish to enter is not part of the <span class="doc_caps">unicode</span> character set? The solution in this case is to declare an inline image; this feature is covered in detail in <a class="doc_lnk" href="#doc:m:sec:glyphs">Section&#xa0;14.1</a>.</p><h1 id="doc:a:2" class="doc_sec"><span class="doc_order">5</span><span>Hyperlinks to external resources</span></h1><p class="doc_par">The simple command <code class="doc_mono">\link</code> (or its synonym <code class="doc_mono">\a</code>) allows the creation of hyperlinks into any external resource. It takes the form <code class="doc_mono">\link{<i class="doc_emph">uri</i>}{<i class="doc_emph">inline</i>}</code>, where <code class="doc_mono"><i class="doc_emph">uri</i></code> is the raw text containing the address (<span class="doc_caps">uri</span>) of the target, and <code class="doc_mono"><i class="doc_emph">inline</i></code> is the sequence of inline text that will actually be displayed. Should the two be the same, you may ommit the second parameter altogether. Moreover, note that in no circumstances may you nest a link inside another!<span class="doc_see">(<a class="doc_lnk" href="#doc:m:note:links">4</a>)</span></p><p class="doc_par">Note that in the preceeding paragraph, the sequence <code class="doc_mono"><i class="doc_emph">uri</i></code> is described as <i class="doc_emph">raw</i> text, not an inline sequence. In brief, a raw sequence is one whose contents are parsed verbatim, without (almost) any attempt to expand special characters and where inline formatting commands do not apply. In similarity to their inline counterparts, raw sequences are delimited by curly brackets. Therefore, the end of sequence character '<code class="doc_mono">}</code>' is interpreted specially. Escaping is also possible, and thus the backslash character is also special.</p><p class="doc_par"><span class="doc_caps">lambtex</span> supports also internal targets and hyperlinks. These are discussed in <a class="doc_lnk" href="#doc:m:sec:intlinks">Section&#xa0;17</a>.</p><h1 id="doc:a:3" class="doc_sec"><span class="doc_order">6</span><span>List environments</span></h1><p class="doc_par">All the commands we have seen so far are simple commands, and therefore the declaration of lists will provide us with the first example of environment commands. Lists in <span class="doc_caps">lambtex</span> come in three varieties: ordered, unordered, and description lists. These are declared using the environment commands <code class="doc_mono">enumerate</code>, <code class="doc_mono">itemize</code>, and <code class="doc_mono">description</code>, respectively. As shown by the following <span class="doc_caps">lambtex</span> source, items in ordered and unordered lists must be preceded by the parameterless simple command <code class="doc_mono">\item</code>. As for description lists, each item must be preceded also by the simple command <code class="doc_mono">\item</code>. However, in this latter case the command takes a mandatory inline sequence as parameter. Finally, lists may be nested, and each item may itself be composed of several blocks (see <a class="doc_lnk" href="#doc:m:sec:structure">Appendix&#xa0;A</a> for a detailed description concerning the structure of <span class="doc_caps">lambtex</span> documents). Consider thus the following source:</p><div class="doc_src_block doc_class_boxed"><pre class="doc_src_code">
<code class="doc_src_line doc_src_dummy"></code>
<code class="doc_src_line">Here is a list of small furry mammals:</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">\begin{itemize}</code>
<code class="doc_src_line">\item Cat</code>
<code class="doc_src_line">\item Some dog breeds:</code>
<code class="doc_src_line">    \begin{description}</code>
<code class="doc_src_line">    \item{poodle:} Small dogs kept for company</code>
<code class="doc_src_line">    \item{greyhound:} Running dogs</code>
<code class="doc_src_line">    \end{description}</code>
<code class="doc_src_line">\item Various rodents ordered by size:</code>
<code class="doc_src_line">    \begin{enumerate}</code>
<code class="doc_src_line">    \item Capivara</code>
<code class="doc_src_line">    \item Rat</code>
<code class="doc_src_line">    \item Mouse</code>
<code class="doc_src_line">    \end{enumerate}</code>
<code class="doc_src_line">\end{itemize}</code>
<code class="doc_src_line doc_src_dummy"></code></pre></div><p class="doc_par">The output generated by the composer is as follows:</p><div class="doc_subpage"><p class="doc_par">Here is a list of small furry mammals:</p><ul class="doc_itemize"><li class="doc_item"><p class="doc_par">Cat</p></li><li class="doc_item"><p class="doc_par">Some dog breeds:</p><dl class="doc_description"><dt class="doc_item">poodle:</dt><dd class="doc_item"><p class="doc_par">Small dogs kept for company</p></dd><dt class="doc_item">greyhound:</dt><dd class="doc_item"><p class="doc_par">Running dogs</p></dd></dl></li><li class="doc_item"><p class="doc_par">Various rodents ordered by size:</p><ol class="doc_enumerate"><li class="doc_item"><p class="doc_par">Capivara</p></li><li class="doc_item"><p class="doc_par">Rat</p></li><li class="doc_item"><p class="doc_par">Mouse</p></li></ol></li></ul></div><p class="doc_par">For the sake of brevity and for compatibility with <span class="doc_caps">html</span> habits, you may also use the synonyms <code class="doc_mono">ol</code>, <code class="doc_mono">ul</code>, <code class="doc_mono">dl</code>, and <code class="doc_mono">\li</code>, for <code class="doc_mono">enumerate</code>, <code class="doc_mono">itemize</code>, <code class="doc_mono">description</code>, and <code class="doc_mono">\item</code>, respectively. Moreover, the British spelling <code class="doc_mono">itemise</code> may be used for ordered lists. However, the start and end tags must still match: though, for example, <code class="doc_mono">ol</code> is a synonym for <code class="doc_mono">enumerate</code>, if you start an ordered list with <code class="doc_mono">\begin{ol}</code> you must terminate it with <code class="doc_mono">\end{ol}</code>.</p><p class="doc_par">The default <span class="doc_caps">css</span> shipped with <span class="doc_caps">lambtex</span> allows for the customisation of the bullet used in unordered lists or the numbering system used in ordered lists. To do so you need to pass a style parameter to either the <code class="doc_mono">\begin{itemize}</code> or <code class="doc_mono">\begin{enumerate}</code> commands. Below is the list of classnames available out-of-the-box for itemize environments:</p><div class="doc_tab"><div class="doc_tab_aux"><table><thead class="doc_tgroup"><tr><td class="doc_cell_r">Value</td><td class="doc_cell_l">Type of bullet</td></tr></thead><tbody class="doc_tgroup"><tr><td class="doc_cell_r"><code class="doc_mono">disc</code></td><td class="doc_cell_l">A filled circle.</td></tr><tr><td class="doc_cell_r"><code class="doc_mono">circle</code></td><td class="doc_cell_l">An empty circle.</td></tr><tr><td class="doc_cell_r"><code class="doc_mono">square</code></td><td class="doc_cell_l">A square.</td></tr><tr><td class="doc_cell_r"><code class="doc_mono">none</code></td><td class="doc_cell_l">Ommit the bullet altogether.</td></tr></tbody></table></div></div><p class="doc_par">And the corresponding list for itemize environments:</p><div class="doc_tab"><div class="doc_tab_aux"><table><thead class="doc_tgroup"><tr><td class="doc_cell_r">Value</td><td class="doc_cell_l">Type of numbering</td></tr></thead><tbody class="doc_tgroup"><tr><td class="doc_cell_r"><code class="doc_mono">decimal</code></td><td class="doc_cell_l">Decimal numbers.</td></tr><tr><td class="doc_cell_r"><code class="doc_mono">lower-roman</code></td><td class="doc_cell_l">Lower-case Roman numerals.</td></tr><tr><td class="doc_cell_r"><code class="doc_mono">upper-roman</code></td><td class="doc_cell_l">Upper-case Roman numerals.</td></tr><tr><td class="doc_cell_r"><code class="doc_mono">lower-alpha</code></td><td class="doc_cell_l">Lower-case letters in the Latin alphabet.</td></tr><tr><td class="doc_cell_r"><code class="doc_mono">upper-alpha</code></td><td class="doc_cell_l">Upper-case letters in the Latin alphabet.</td></tr><tr><td class="doc_cell_r"><code class="doc_mono">none</code></td><td class="doc_cell_l">Ommit the numbering altogether.</td></tr></tbody></table></div></div><h1 id="doc:m:sec:qanda" class="doc_sec"><span class="doc_order">7</span><span>Q&amp;A environments</span></h1><p class="doc_par">Somewhat related to lists, Q&amp;A environments are used to mark a sequence of questions and accompanying answers, as typically found in interviews. The environment is bounded by the start/end tag <code class="doc_mono">qanda</code>, and expects a sequence of question and answer blocks, delimited by the simple commands <code class="doc_mono">\question</code> and <code class="doc_mono">\answer</code>, respectively. Both these commands accept an inline sequence delimited by curly brackets as optional parameter. If present, this sequence indicates the text that should appear before the actual question or answer; it is used to indicate the name of the interviewer or the interviewee, respectively. Should this sequence be fixed for the entire length of the Q&amp;A, there is an alternative to repeating it with each <code class="doc_mono">\question</code> and<code class="doc_mono">\answer</code> pair: you may instead use the parameterless simple commands <code class="doc_mono">\rquestion</code> and <code class="doc_mono">\ranswer</code>. These simply reuse the sequence declared in the previous question or answer. The following example illustrates the pattern:</p><div class="doc_src_block doc_class_boxed"><pre class="doc_src_code">
<code class="doc_src_line doc_src_dummy"></code>
<code class="doc_src_line">\begin{qanda}</code>
<code class="doc_src_line">\question{Egg Gazette:}</code>
<code class="doc_src_line">On which side of the egg opening debate are you?</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">\answer{John McAuthor:}</code>
<code class="doc_src_line">I sustain that eggs should be opened by their small-end, of course.</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">\question{EG:}</code>
<code class="doc_src_line">What's your opinion on the contrarian position,</code>
<code class="doc_src_line">that eggs should be opened by their large-end?</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">\answer{JM:}</code>
<code class="doc_src_line">Sheer madness!</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">\rquestion</code>
<code class="doc_src_line">Could you elaborate?</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">\ranswer</code>
<code class="doc_src_line">I don't believe that to be necessary; the reasons are self-evident.</code>
<code class="doc_src_line">\end{qanda}</code>
<code class="doc_src_line doc_src_dummy"></code></pre></div><p class="doc_par">The generated output is as follows:</p><div class="doc_subpage"><dl class="doc_qanda"><dt class="doc_question doc_empty">Egg Gazette:</dt><dd class="doc_question"><p class="doc_par">On which side of the egg opening debate are you?</p></dd><dt class="doc_answer doc_empty">John McAuthor:</dt><dd class="doc_answer"><p class="doc_par">I sustain that eggs should be opened by their small-end, of course.</p></dd><dt class="doc_question doc_empty">EG:</dt><dd class="doc_question"><p class="doc_par">What's your opinion on the contrarian position, that eggs should be opened by their large-end?</p></dd><dt class="doc_answer doc_empty">JM:</dt><dd class="doc_answer"><p class="doc_par">Sheer madness!</p></dd><dt class="doc_question"></dt><dd class="doc_question"><p class="doc_par">Could you elaborate?</p></dd><dt class="doc_answer"></dt><dd class="doc_answer"><p class="doc_par">I don't believe that to be necessary; the reasons are self-evident.</p></dd></dl></div><h1 id="doc:m:sec:verse" class="doc_sec"><span class="doc_order">8</span><span>Verse environments</span></h1><p class="doc_par">The environment <code class="doc_mono">verse</code> is used to typeset poetry, music lyrics, or any other content where conventional typographic rules for verses apply. Inside the environment only paragraph blocks are accepted; each paragraph corresponds to a stanza, and each verse should be terminated by the line break marker <code class="doc_mono">\br</code>. Therefore, if you wished to typeset the first couple of stanzas from Virgil's <i class="doc_emph">Aeneid</i>, this would be the <span class="doc_caps">lambtex</span> source:</p><div class="doc_src_block doc_class_boxed"><pre class="doc_src_code">
<code class="doc_src_line doc_src_dummy"></code>
<code class="doc_src_line">\begin{verse}</code>
<code class="doc_src_line">Arma virumque cano, Troiae qui primus ab oris \br</code>
<code class="doc_src_line">Italiam, fato profugus, Laviniaque venit \br</code>
<code class="doc_src_line">litora, multum ille et terris iactatus et alto \br</code>
<code class="doc_src_line">vi superum saevae memorem Iunonis ob iram; \br</code>
<code class="doc_src_line">multa quoque et bello passus, dum conderet urbem, \br</code>
<code class="doc_src_line">inferretque deos Latio, genus unde Latinum, \br</code>
<code class="doc_src_line">Albanique patres, atque altae moenia Romae.</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">Musa, mihi causas memora, quo numine laeso, \br</code>
<code class="doc_src_line">quidve dolens, regina deum tot volvere casus \br</code>
<code class="doc_src_line">insignem pietate virum, tot adire labores \br</code>
<code class="doc_src_line">impulerit.  Tantaene animis caelestibus irae? \br</code>
<code class="doc_src_line">\end{verse}</code>
<code class="doc_src_line doc_src_dummy"></code></pre></div><p class="doc_par">The result would be the following:</p><div class="doc_subpage"><div class="doc_verse"><div class="doc_verse_aux"><p class="doc_par">Arma virumque cano, Troiae qui primus ab oris <br class=""/> Italiam, fato profugus, Laviniaque venit <br class=""/> litora, multum ille et terris iactatus et alto <br class=""/> vi superum saevae memorem Iunonis ob iram; <br class=""/> multa quoque et bello passus, dum conderet urbem, <br class=""/> inferretque deos Latio, genus unde Latinum, <br class=""/> Albanique patres, atque altae moenia Romae.</p><p class="doc_par">Musa, mihi causas memora, quo numine laeso, <br class=""/> quidve dolens, regina deum tot volvere casus <br class=""/> insignem pietate virum, tot adire labores <br class=""/> impulerit. Tantaene animis caelestibus irae? <br class=""/></p></div></div></div><h1 id="doc:m:sec:quotations" class="doc_sec"><span class="doc_order">9</span><span>Quotations</span></h1><p class="doc_par">Quotation blocks are typically used for including an excerpt from an external source into your document. You may be quoting what someone said in an interview, or providing context when replying to a comment, for example. Quotation bloks are delimited by the <code class="doc_mono">quote</code> environment, and may enclose not only plain text paragraphs, but also lists or any of the so-called <i class="doc_emph">quotable blocks</i>, as <a class="doc_lnk" href="#doc:m:sec:structure">Appendix&#xa0;A</a> describes in greater detail. Consider thus the following <span class="doc_caps">lambtex</span> source:</p><div class="doc_src_block doc_class_boxed"><pre class="doc_src_code">
<code class="doc_src_line doc_src_dummy"></code>
<code class="doc_src_line">This is what you said:</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">\begin{quote}</code>
<code class="doc_src_line">Eggs should be opened by their large end.  Any other method is heresy.</code>
<code class="doc_src_line">It is therefore my opinion that John McAuthor is a heretic.</code>
<code class="doc_src_line">\end{quote}</code>
<code class="doc_src_line doc_src_dummy"></code></pre></div><p class="doc_par">This is the output produced:</p><div class="doc_subpage"><p class="doc_par">This is what you said:</p><blockquote class="doc_quote"><p class="doc_par">Eggs should be opened by their large end. Any other method is heresy. It is therefore my opinion that John McAuthor is a heretic.</p></blockquote></div><p class="doc_par">Note that though undoubtedly indispensable, quotation blocks are prone to being abused. Our advice is to use them only if embeddeding a quotation is essential to carry your message. You may, for example, be commenting on a particular sentence or paragraph in an interview available online; in this case, a quotation block will provide the focus that would have been lost by simply linking to the entire interview.</p><h1 id="doc:m:sec:verbatim" class="doc_sec"><span class="doc_order">10</span><span>Verbatim environments</span></h1><p class="doc_par">Like their <span class="doc_caps">LaTeX</span> counterparts or the <span class="doc_caps">html</span> <code class="doc_mono">pre</code> element, verbatim environments allow the insertion of blocks where the text is shown <i class="doc_emph">as is</i>, ie, without (almost) any attempt at the interpretation of its contents. They are to be displayed using a monospaced font, and as such are ideal for showing <span class="doc_caps">ascii</span>-art. Another application is to display text-only technical diagrams as commonly found on Internet <span class="doc_caps">rfc</span>s, for example.</p><p class="doc_par">The command name for the verbatim environment is <code class="doc_mono">verbatim</code>, and being an environment command the text must be enclosed between <code class="doc_mono">\begin{verbatim}</code> and <code class="doc_mono">\end{verbatim}</code> markers. The synonym <code class="doc_mono">pre</code> may also be used. Below is an example of a diagram drawn using only <span class="doc_caps">ascii</span> characters, and rendered using a <code class="doc_mono">verbatim</code> environment:</p><div class="doc_pre doc_floatable"><div class="doc_pre_aux"><pre class="doc_pre_aux">             N
            /|\
           / | \
          /  |  \
         /   |   \
        /    |    \
       /     |     \
      N     '+'     L
     /|\            |
    / | \           |
   /  |  \          |
  /   |   \         |
 L   '+'   L       '3'
 |         |
'1'       '2'</pre></div></div><p class="doc_par">We say there is <i class="doc_emph">almost</i> no interpretation of the contents of the verbatim environment because there is one exception. The string <code class="doc_mono">\end{verbatim}</code> is used as the end marker, and therefore the <span class="doc_caps">lambtex</span> scanner will exit the environment if it encounters this string. This raises the obvious question of how one can insert that string itself within a verbatim context without triggering the termination of the environment. The solution used by <span class="doc_caps">lambtex</span> is reminescent of the <a class="doc_lnk" href="http://en.wikipedia.org/wiki/Here_document"><span class="doc_caps">heredoc</span></a> approach used by other languages. Basically, the markers that delimit verbatim environments need only use <code class="doc_mono">verbatim</code> as a prefix. The only condition for termination is that the end marker matches the begin marker. Therefore, to include the string <code class="doc_mono">\end{verbatim}</code> within a verbatim environment, you can simply delimitate that environment with, for example, <code class="doc_mono">\begin{verbatim1}</code> and <code class="doc_mono">\end{verbatim1}</code>. Note that only lowercase Roman letters, digits, and the character '<code class="doc_mono">_</code>' (underscore) may be used as suffix characters.</p><p class="doc_par">The <span class="doc_caps">css</span> shipped with <span class="doc_caps">lambtex</span> defines a series of classnames for exclusive use with verbatim environments. These are <code class="doc_mono">mult0</code>, <code class="doc_mono">mult1</code>, and so forth until <code class="doc_mono">mult9</code>. The integer indicates a multiplying factor for the contents of the environment. For a factor of <span class="doc_math_inl"><math
xmlns="http://www.w3.org/1998/Math/MathML"
><mi
>x</mi
></math
></span>, the actual scaling relative to normal size is given by <span class="doc_math_inl"><math
xmlns="http://www.w3.org/1998/Math/MathML"
><msup
><msqrt
><mn
>2</mn
></msqrt
><mi
>x</mi
></msup
></math
></span>. The default factor is 0, which corresponds to normal size. One common application of this feature is to display <span class="doc_caps">unicode</span> characters as full-sized pictures. As an example, this is what the <span class="doc_caps">unicode</span> snowman (code point <span class="doc_caps">U+2603</span>) looks like with a multiplier of 7, corresponding to a font size 11.3 times larger than normal:</p><div class="doc_pre doc_class_mult7 doc_floatable"><div class="doc_pre_aux"><pre class="doc_pre_aux">☃</pre></div></div><p class="doc_par">In addition, the default <span class="doc_caps">css</span> also allows floatation specifiers to be used with verbatim blocks. Floating specifiers take the form of classname style parameters '<code class="doc_mono">center</code>', '<code class="doc_mono">left</code>', and '<code class="doc_mono">right</code>'. They declare that the block should be displayed either centered and occupying the entire width of the page (this is the default), floating on the left, or floating on the right, respectively. Note that they map directly to <span class="doc_caps">css</span> <code class="doc_mono">float</code> declarations.</p><p class="doc_par">Floatation specifiers are not exclusive to verbatim environments, and in subsequent sections we shall encounter other block types that also accept them. The property all these block types have in common is the reasonable expectation that they may be placed outside the main flow of the document without a loss of context. In a sense, for a block to be floatable, it must be able to carry its own context. This is the case for verbatim blocks, since they can be used for purely decorative purposes.</p><h1 id="doc:m:sec:code" class="doc_sec"><span class="doc_order">11</span><span>Presenting source-code</span></h1><p class="doc_par"><a class="doc_lnk" href="#doc:m:sec:inline">Section&#xa0;3</a> briefly introduced the simple inline command <code class="doc_mono">\code</code>, whose purpose is to format with syntax-highlighting a short sequence of source-code. The only configuration available for this command is the optional key-value style parameter '<code class="doc_mono">lang</code>', which allows the specification of the language used for syntax-highlighting.</p><p class="doc_par">Suppose now that you have a long source-code listing that you wish to pretty-print. While it is of course possible to input source-code listings using verbatim environment discussed above, <span class="doc_caps">lambtex</span> features a dedicated facility that besides being semantically more appropriate has in addition a number of tricks up its sleave. This new environment is named <code class="doc_mono">source</code>, and offers the possibility of adding line numbers to the code listing and highlighting the source according to the syntax of most popular languages. You have in fact already encountered this environment multiple times in this document: it has been used for formatting <span class="doc_caps">lambtex</span> source code, albeit without line numbers or syntax highlighting. Suppose thus you wish to pretty-print an <a class="doc_lnk" href="http://ocaml.org/">OCaml</a> fragment. You can declare a source-code environment the following way:</p><div class="doc_src_block doc_class_boxed"><pre class="doc_src_code">
<code class="doc_src_line doc_src_dummy"></code>
<code class="doc_src_line">\begin&lt;lang=caml&gt;{source}</code>
<code class="doc_src_line">type 'a tree =</code>
<code class="doc_src_line">    | Leaf</code>
<code class="doc_src_line">    | Node of 'a tree * 'a * 'a tree</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">let rec count = function</code>
<code class="doc_src_line">    | Leaf                  -&gt; 0</code>
<code class="doc_src_line">    | Node (left, x, right) -&gt; 1 + count left + count right</code>
<code class="doc_src_line">\end{source}</code>
<code class="doc_src_line doc_src_dummy"></code></pre></div><p class="doc_par">Note that the source language is specified via an optional key-value style parameter '<code class="doc_mono">lang</code>'. Also, the same <span class="doc_caps">heredoc</span>-like technique used for verbatim environments can be used in a source environment if you wish to include the string <code class="doc_mono">\end{source}</code> itself. The astute reader will have noticed that this trick must have been used in the source for this manual to display the code above (this manual is itself written in <span class="doc_caps">lambtex</span> — we do eat our own dog food). As for the actual result produced by the composer, it is as follows:</p><div class="doc_src_block"><pre class="doc_src_code">
<code class="doc_src_line doc_src_dummy"></code>
<code class="doc_src_line"><span class="doc_src_Kwd">type</span> 'a tree <span class="doc_src_Sym">=</span></code>
<code class="doc_src_line">    <span class="doc_src_Sym">|</span> <span class="doc_src_Type">Leaf</span></code>
<code class="doc_src_line">    <span class="doc_src_Sym">|</span> <span class="doc_src_Type">Node</span> <span class="doc_src_Kwd">of</span> 'a tree <span class="doc_src_Sym">*</span> 'a <span class="doc_src_Sym">*</span> 'a tree</code>
<code class="doc_src_line"></code>
<code class="doc_src_line"><span class="doc_src_Kwd">let</span> <span class="doc_src_Kwd">rec</span> count <span class="doc_src_Sym">=</span> <span class="doc_src_Kwd">function</span></code>
<code class="doc_src_line">    <span class="doc_src_Sym">|</span> <span class="doc_src_Type">Leaf</span>                  <span class="doc_src_Sym">-&gt;</span> <span class="doc_src_Num">0</span></code>
<code class="doc_src_line">    <span class="doc_src_Sym">|</span> <span class="doc_src_Type">Node</span> <span class="doc_src_Sym">(</span>left<span class="doc_src_Sym">,</span> x<span class="doc_src_Sym">,</span> right<span class="doc_src_Sym">)</span> <span class="doc_src_Sym">-&gt;</span> <span class="doc_src_Num">1</span> <span class="doc_src_Sym">+</span> count left <span class="doc_src_Sym">+</span> count right</code>
<code class="doc_src_line doc_src_dummy"></code></pre></div><p class="doc_par">Another optional key-value style parameter accepted by source environments is '<code class="doc_mono">nums</code>'. It accepts a boolean value, and dictates whether line numbers should be added to the source code listing. Valid boolean values are '<code class="doc_mono">true</code>', '<code class="doc_mono">yes</code>' and '<code class="doc_mono">on</code>' for truth value <i class="doc_emph">true</i> and '<code class="doc_mono">false</code>', '<code class="doc_mono">no</code>' and '<code class="doc_mono">off</code>' for truth value <i class="doc_emph">false</i>. It defaults to false.</p><p class="doc_par">The <span class="doc_caps">css</span> shipped with <span class="doc_caps">lambtex</span> offers additional customisation options for the appearance of source environments. These are all available as classname style parameters, as follows:</p><dl class="doc_description"><dt class="doc_item">'<code class="doc_mono">plain</code>'</dt><dd class="doc_item"><p class="doc_par">This classname indicates that the listing should be displayed in plain style. This is the default, as previously shown. It is better suited for source-code fragments that one wishes to integrate tightly with the flow of the document.</p></dd><dt class="doc_item">'<code class="doc_mono">boxed</code>'</dt><dd class="doc_item"><p class="doc_par">Declares that the source code listing should be shown inside a decorative box. Example:</p><div class="doc_src_block doc_class_boxed"><pre class="doc_src_code">
<code class="doc_src_line doc_src_dummy"></code>
<code class="doc_src_line"><span class="doc_src_Kwd">type</span> 'a tree <span class="doc_src_Sym">=</span></code>
<code class="doc_src_line">    <span class="doc_src_Sym">|</span> <span class="doc_src_Type">Leaf</span> <span class="doc_src_Kwd">of</span> 'a</code>
<code class="doc_src_line">    <span class="doc_src_Sym">|</span> <span class="doc_src_Type">Node</span> <span class="doc_src_Kwd">of</span> 'a tree <span class="doc_src_Sym">*</span> 'a tree</code>
<code class="doc_src_line"></code>
<code class="doc_src_line"><span class="doc_src_Kwd">let</span> <span class="doc_src_Kwd">rec</span> count_leaves <span class="doc_src_Sym">=</span> <span class="doc_src_Kwd">function</span></code>
<code class="doc_src_line">    <span class="doc_src_Sym">|</span> <span class="doc_src_Type">Leaf</span> _      <span class="doc_src_Sym">-&gt;</span> <span class="doc_src_Num">1</span></code>
<code class="doc_src_line">    <span class="doc_src_Sym">|</span> <span class="doc_src_Type">Node</span> <span class="doc_src_Sym">(</span>a<span class="doc_src_Sym">,</span> b<span class="doc_src_Sym">)</span> <span class="doc_src_Sym">-&gt;</span> count_leaves a <span class="doc_src_Sym">+</span> count_leaves b</code>
<code class="doc_src_line doc_src_dummy"></code></pre></div></dd><dt class="doc_item">'<code class="doc_mono">zebra</code>'</dt><dd class="doc_item"><p class="doc_par">Besides placing the source-code inside a decorative box, this style will in addition give a different background to even and odd numbered rows:</p><div class="doc_src_block doc_class_zebra"><pre class="doc_src_code">
<code class="doc_src_line doc_src_dummy"></code>
<code class="doc_src_line"><span class="doc_src_Kwd">type</span> 'a tree <span class="doc_src_Sym">=</span></code>
<code class="doc_src_line">    <span class="doc_src_Sym">|</span> <span class="doc_src_Type">Leaf</span> <span class="doc_src_Kwd">of</span> 'a</code>
<code class="doc_src_line">    <span class="doc_src_Sym">|</span> <span class="doc_src_Type">Node</span> <span class="doc_src_Kwd">of</span> 'a tree <span class="doc_src_Sym">*</span> 'a tree</code>
<code class="doc_src_line"></code>
<code class="doc_src_line"><span class="doc_src_Kwd">let</span> <span class="doc_src_Kwd">rec</span> count_leaves <span class="doc_src_Sym">=</span> <span class="doc_src_Kwd">function</span></code>
<code class="doc_src_line">    <span class="doc_src_Sym">|</span> <span class="doc_src_Type">Leaf</span> _      <span class="doc_src_Sym">-&gt;</span> <span class="doc_src_Num">1</span></code>
<code class="doc_src_line">    <span class="doc_src_Sym">|</span> <span class="doc_src_Type">Node</span> <span class="doc_src_Sym">(</span>a<span class="doc_src_Sym">,</span> b<span class="doc_src_Sym">)</span> <span class="doc_src_Sym">-&gt;</span> count_leaves a <span class="doc_src_Sym">+</span> count_leaves b</code>
<code class="doc_src_line doc_src_dummy"></code></pre></div></dd><dt class="doc_item">'<code class="doc_mono">console</code>'</dt><dd class="doc_item"><p class="doc_par">This style is appropriate if the code block should actually mimick the output from a command line console:</p><div class="doc_src_block doc_class_console"><pre class="doc_src_code">
<code class="doc_src_line doc_src_dummy"></code>
<code class="doc_src_line">dario@localhost:~/lambtex$ make</code>
<code class="doc_src_line">lambcmd -f lambtex -t html -i sample.lambtex -o index.html</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">dario@localhost:~/lambtex$ file index.html</code>
<code class="doc_src_line">index.html: HTML document text</code>
<code class="doc_src_line doc_src_dummy"></code></pre></div></dd></dl><p class="doc_par">Finally, note that <span class="doc_caps">lambtex</span> offers also the possibility for code environments to be numbered and referenced from anywhere in the document. This can be done by wrapping them inside a <code class="doc_mono">printout</code> environment, and is part of the advanced features of the language discussed in <a class="doc_lnk" href="#doc:m:sec:wrappers">Section&#xa0;21</a>.</p><h1 id="doc:a:4" class="doc_sec"><span class="doc_order">12</span><span>Tabular environments</span></h1><p class="doc_par">Presenting data in a tabular format is indispensable for many classes of documents. With this in mind, <span class="doc_caps">lambtex</span> offers a special <code class="doc_mono">tabular</code> environment which allows you to format tables in a simple and concise way, while retaining most of the capabilities offered by <span class="doc_caps">LaTeX</span> and <span class="doc_caps">xhtml</span> tables.</p><p class="doc_par">Suppose then that our tabular data had three different attributes — a person's name, a phone number, and an address — and that we had this information about four different people. We wish to present the attributes as table columns, whereas each record will be shown in a different row. In brief, a table just like this one:</p><div class="doc_tab"><div class="doc_tab_aux"><table><thead class="doc_tgroup"><tr><td class="doc_cell_l">Name</td><td class="doc_cell_l">Phone</td><td class="doc_cell_l">Address</td></tr></thead><tbody class="doc_tgroup"><tr><td class="doc_cell_l">John</td><td class="doc_cell_l">123456</td><td class="doc_cell_l">London</td></tr><tr><td class="doc_cell_l">Mary</td><td class="doc_cell_l">234567</td><td class="doc_cell_l">Paris</td></tr><tr><td class="doc_cell_l">Mark</td><td class="doc_cell_l">345678</td><td class="doc_cell_l">Moscow</td></tr><tr><td class="doc_cell_l">Jane</td><td class="doc_cell_l">456789</td><td class="doc_cell_l">Sydney</td></tr></tbody></table></div></div><p class="doc_par">Inside a tabular environment, a row is terminated when the character '<code class="doc_mono">|</code>' (pipe) is the last on a line of text; within each row, each cell must also be prefixed by the '<code class="doc_mono">|</code>' character. This means that you'll need to escape it if you wish to display an actual pipe character.</p><p class="doc_par">There are three different classes of rows available: header, body, and footer rows. Besides formatting each one differently, smart enough browsers will know that table headers are to be repeated if the tabular environment spans more than one printed page. The parameterless simple commands <code class="doc_mono">\head</code>, <code class="doc_mono">\body</code>, and <code class="doc_mono">\foot</code> are used inside a tabular environment to mark the beginning of each class. Note that header and footer rows are optional (in which case the <code class="doc_mono">\body</code> marker is also optional, since rows are assumed by default to be body rows). Moreover, you can declare more than one group of body rows, and the default <span class="doc_caps">css</span> stylesheet will visibly separate each group.</p><p class="doc_par">The code below is the source for the tabular environment listed above. Note the use of the <code class="doc_mono">\head</code> and <code class="doc_mono">\body</code> commands to delineate row classes, and how the character '<code class="doc_mono">|</code>' is used to separate cells and rows. Note also that all rows have the same number of columns. This is <b class="doc_bold">mandatory</b>, though provisions exist for making a cell span multiple columns (see below).</p><div class="doc_src_block doc_class_boxed"><pre class="doc_src_code">
<code class="doc_src_line doc_src_dummy"></code>
<code class="doc_src_line">\begin{tabular}</code>
<code class="doc_src_line">\head</code>
<code class="doc_src_line">| Name      | Phone     | Address   |</code>
<code class="doc_src_line">\body</code>
<code class="doc_src_line">| John      | 123456    | London    |</code>
<code class="doc_src_line">| Mary      | 234567    | Paris     |</code>
<code class="doc_src_line">| Mark      | 345678    | Moscow    |</code>
<code class="doc_src_line">| Jane      | 456789    | Sydney    |</code>
<code class="doc_src_line">\end{tabular}</code>
<code class="doc_src_line doc_src_dummy"></code></pre></div><p class="doc_par">All the columns in the tabular environment above are left-aligned and the column text is shown in normal text. You may, however, specify otherwise using the key-value style parameter '<code class="doc_mono">cols</code>'. Its value consists of a string whose length equals the number of columns and where each character specifies the formatting that should be applied to each column. The example above features three left-aligned columns; the corresponding style parameter is '<code class="doc_mono">cols=lll</code>'. If, for example, you had four columns aligned respectively to the left, right, center, and left again, the style parameter would be '<code class="doc_mono">cols=lrcl</code>'. Consult <a class="doc_lnk" href="#doc:m:tab:tabular">Tab.&#xa0;4</a> for a list of all available column specifiers.</p><div id="doc:m:tab:tabular" class="doc_wrapper doc_floatable doc_table"><div class="doc_tab"><div class="doc_tab_aux"><table><thead class="doc_tgroup"><tr><td class="doc_cell_r">Specifier</td><td class="doc_cell_l">Formatting</td></tr></thead><tbody class="doc_tgroup"><tr><td class="doc_cell_r"><code class="doc_mono">l</code></td><td class="doc_cell_l">Column is left-aligned.</td></tr><tr><td class="doc_cell_r"><code class="doc_mono">L</code></td><td class="doc_cell_l">Column is left-aligned and strong.</td></tr><tr><td class="doc_cell_r"><code class="doc_mono">r</code></td><td class="doc_cell_l">Column is right-aligned.</td></tr><tr><td class="doc_cell_r"><code class="doc_mono">R</code></td><td class="doc_cell_l">Column is right-aligned and strong.</td></tr><tr><td class="doc_cell_r"><code class="doc_mono">c</code></td><td class="doc_cell_l">Column is centre-aligned.</td></tr><tr><td class="doc_cell_r"><code class="doc_mono">C</code></td><td class="doc_cell_l">Column is centre-aligned and strong.</td></tr><tr><td class="doc_cell_r"><code class="doc_mono">j</code></td><td class="doc_cell_l">Column is justified.</td></tr><tr><td class="doc_cell_r"><code class="doc_mono">J</code></td><td class="doc_cell_l">Column is justified and strong.</td></tr></tbody></table></div></div><div class="doc_caption doc_caption_long"><div class="doc_caption_aux"><h1 class="doc_caption_head">Tab.&#xa0;4:</h1><p class="doc_caption_body">List of available column specifiers for tabular environments. A specifier tells <span class="doc_caps">lambtex</span> how each column should be formatted.</p></div></div></div><p class="doc_par">Some tables may require more sophisticated formatting. The most common requirement is for multi-column cells, and <span class="doc_caps">lambtex</span> does support them. This feature is enabled by a special syntax that allows the customisation of each individual cell. More precisely, the pipe character '<code class="doc_mono">|</code>' that precedes each cell is optionally followed by an angle bracketed style parameter.</p><p class="doc_par">Recall that style parameters come in two varieties: classnames and key-value pairs. You may of course use the former to customise the <span class="doc_caps">css</span> of an individual cell. As for the latter, cells offer a single option, whose key is named '<code class="doc_mono">cell</code>', and whose value is a formatting expression composed of three parts. The first part is an integer indicating how many columns the cell should span; the second is a single character matching one of the specifiers listed in <a class="doc_lnk" href="#doc:m:tab:tabular">Tab.&#xa0;4</a>; last and optional are the characters '<code class="doc_mono">_</code>' (underscore) and/or '<code class="doc_mono">^</code>' (caret), which if present indicate that a horizontal line should be put above and/or below the cell. Note that the formatting should satisfy the regular expression <span class="doc_mbox"><code class="doc_mono"><i class="doc_emph">digit</i>+ <i class="doc_emph">spec</i> ( '_' | '^' | '_^' | '^_' )?</code></span>.</p><p class="doc_par">This discussion would not be complete without the presentation of a complete example illustrating the application of advanced cell formatting. Consider thus the <span class="doc_caps">lambtex</span> fragment below, whose output is displayed in <a class="doc_lnk" href="#doc:m:tab:species">Tab.&#xa0;5</a>. Besides the use of header, footer, and multiple body rows, also noteworthy are the cell style parameters <code class="doc_mono">cell=2c_</code> and <code class="doc_mono">cell=2c^</code>, which configure their corresponding cells to span two columns, be centered, and show a horizontal line below and above, respectively.</p><div class="doc_src_block doc_class_boxed"><pre class="doc_src_code">
<code class="doc_src_line doc_src_dummy"></code>
<code class="doc_src_line">\begin&lt;cols=rll&gt;{tabular}</code>
<code class="doc_src_line">\head</code>
<code class="doc_src_line">|               |&lt;cell=2c_&gt; Scientific name              |</code>
<code class="doc_src_line">| Common name   | Genus                 | Species        |</code>
<code class="doc_src_line">\body</code>
<code class="doc_src_line">| Wolf          | \emph{Canis}          | \emph{lupus}   |</code>
<code class="doc_src_line">| Cat           | \emph{Felis}          | \emph{catus}   |</code>
<code class="doc_src_line">| Lion          | \emph{Panthera}       | \emph{leo}     |</code>
<code class="doc_src_line">\body</code>
<code class="doc_src_line">| English oak   | \emph{Quercus}        | \emph{robur}   |</code>
<code class="doc_src_line">| Cork oak      | \emph{Quercus}        | \emph{suber}   |</code>
<code class="doc_src_line">| European yew  | \emph{Taxus}          | \emph{baccata} |</code>
<code class="doc_src_line">\foot</code>
<code class="doc_src_line">| Common name   | Genus                 | Species        |</code>
<code class="doc_src_line">|               |&lt;cell=2c^&gt; Scientific name              |</code>
<code class="doc_src_line">\end{tabular}</code>
<code class="doc_src_line doc_src_dummy"></code></pre></div><p class="doc_par">To conclude, note that if you wish for a tabular environment to be numbered and referenced from anywhere in the document, you need to wrap it inside a <code class="doc_mono">table</code>. This is part of the advanced features of the language, and is discussed in <a class="doc_lnk" href="#doc:m:sec:wrappers">Section&#xa0;21</a>.</p><div id="doc:m:tab:species" class="doc_wrapper doc_floatable doc_table"><div class="doc_tab"><div class="doc_tab_aux"><table><thead class="doc_tgroup"><tr><td class="doc_cell_r"></td><td class="doc_uline doc_cell_c" colspan="2">Scientific name</td></tr><tr><td class="doc_cell_r">Common name</td><td class="doc_cell_l">Genus</td><td class="doc_cell_l">Species</td></tr></thead><tfoot class="doc_tgroup"><tr><td class="doc_cell_r">Common name</td><td class="doc_cell_l">Genus</td><td class="doc_cell_l">Species</td></tr><tr><td class="doc_cell_r"></td><td class="doc_oline doc_cell_c" colspan="2">Scientific name</td></tr></tfoot><tbody class="doc_tgroup"><tr><td class="doc_cell_r">Wolf</td><td class="doc_cell_l"><i class="doc_emph">Canis</i></td><td class="doc_cell_l"><i class="doc_emph">lupus</i></td></tr><tr><td class="doc_cell_r">Cat</td><td class="doc_cell_l"><i class="doc_emph">Felis</i></td><td class="doc_cell_l"><i class="doc_emph">catus</i></td></tr><tr><td class="doc_cell_r">Lion</td><td class="doc_cell_l"><i class="doc_emph">Panthera</i></td><td class="doc_cell_l"><i class="doc_emph">leo</i></td></tr></tbody><tbody class="doc_tgroup"><tr><td class="doc_cell_r">English oak</td><td class="doc_cell_l"><i class="doc_emph">Quercus</i></td><td class="doc_cell_l"><i class="doc_emph">robur</i></td></tr><tr><td class="doc_cell_r">Cork oak</td><td class="doc_cell_l"><i class="doc_emph">Quercus</i></td><td class="doc_cell_l"><i class="doc_emph">suber</i></td></tr><tr><td class="doc_cell_r">European yew</td><td class="doc_cell_l"><i class="doc_emph">Taxus</i></td><td class="doc_cell_l"><i class="doc_emph">baccata</i></td></tr></tbody></table></div></div><div class="doc_caption doc_caption_long"><div class="doc_caption_aux"><h1 class="doc_caption_head">Tab.&#xa0;5:</h1><p class="doc_caption_body">The classification of some common animals and plants. This table illustrates the use of the advanced formatting facilities that enable customisation of individual cells.</p></div></div></div><h1 id="doc:m:sec:math" class="doc_sec"><span class="doc_order">13</span><span>Mathematical formulas</span></h1><p class="doc_par"><span class="doc_caps">lambtex</span> also supports the inclusion of equations and mathematical formulas in a document. Mathematics are to be entered using either <span class="doc_caps">MathML</span><span class="doc_cite">[<a class="doc_lnk" href="#doc:m:bib:mathml">3</a>]</span> or the <span class="doc_caps">TeX</span><span class="doc_cite">[<a class="doc_lnk" href="#doc:m:bib:tex">4</a>]</span> format. The former was chosen because an increasing number of tools has the ability to export <span class="doc_caps">MathML</span>. As for the latter, it is the <i class="doc_emph">de facto</i> standard for manually typing mathematical expressions.</p><p class="doc_par">Mathematical expressions may be entered in an inline context (embedded inside a paragraph, for example), or in a block context. In the former case, the simple commands <code class="doc_mono">\mathtexinl</code> and <code class="doc_mono">\mathmlinl</code> may be used for inputting mathematics in the <span class="doc_caps">TeX</span> or <span class="doc_caps">MathML</span> formats, respectively. For the sake of convenience, <span class="doc_caps">TeX</span> mathematics may also be entered by delimiting them between the characters '<code class="doc_mono">$$</code>'. Though <span class="doc_caps">lambtex</span> does not enforce it, common sense dictates that inline mathematics should restrict themselves to expressions that fit comfortably in a single line. One example is the quadratic equation <span class="doc_math_inl"><math
xmlns="http://www.w3.org/1998/Math/MathML"
><mrow
><mi
>a</mi
><mspace
width="0"
></mspace
><msup
><mi
>x</mi
><mn
>2</mn
></msup
><mo
lspace="0.222em"
rspace="0.222em"
>+</mo
><mi
>b</mi
><mspace
width="0"
></mspace
><mi
>x</mi
><mo
lspace="0.222em"
rspace="0.222em"
>+</mo
><mi
>c</mi
><mo
lspace="0.278em"
rspace="0.278em"
>=</mo
><mn
>0</mn
></mrow
></math
></span>.</p><p class="doc_par"><span class="doc_caps">TeX</span> and <span class="doc_caps">MathML</span> mathematical expressions in a block context are specified via the <code class="doc_mono">mathtexblk</code> and <code class="doc_mono">mathmlblk</code> environments, respectively. Furthermore, because both these environments expect their content to be raw text that should be parsed verbatim, they accept the <span class="doc_caps">heredoc</span> technique for delimiting the environment. Suppose thus you wished to enter a math block containing the quadratic formula that solves the equation listed above. Specified in the <span class="doc_caps">TeX</span> format, the code would be the following:</p><div class="doc_src_block doc_class_boxed"><pre class="doc_src_code">
<code class="doc_src_line doc_src_dummy"></code>
<code class="doc_src_line">\begin{mathtexblk}</code>
<code class="doc_src_line">x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}</code>
<code class="doc_src_line">\end{mathtexblk}</code>
<code class="doc_src_line doc_src_dummy"></code></pre></div><p class="doc_par">The equivalent Presentation <span class="doc_caps">MathML</span> markup is listed below. Note that it is also acceptable to provide Content <span class="doc_caps">MathML</span> instead of Presentation <span class="doc_caps">MathML</span>. In either case, just make sure the markup conforms to version 2.0 of the <span class="doc_caps">MathML</span> standard, and that the <code class="doc_mono">math</code> top-level element that wraps the <span class="doc_caps">MathML</span> contents is provided as part of the markup. These requirements also apply to the <span class="doc_caps">MathML</span> markup specified in an inline context. On the other hand, giving an explicit namespace to the <span class="doc_caps">MathML</span> markup is <b class="doc_bold">not</b> necessary, since namespacing requirements are automatically taken care of.</p><div class="doc_src_block doc_class_boxed"><pre class="doc_src_code">
<code class="doc_src_line doc_src_dummy"></code>
<code class="doc_src_line">\begin{mathmlblk}</code>
<code class="doc_src_line">&lt;math&gt;</code>
<code class="doc_src_line">    &lt;mrow&gt;</code>
<code class="doc_src_line">        &lt;mi&gt;x&lt;/mi&gt;</code>
<code class="doc_src_line">        &lt;mo&gt;=&lt;/mo&gt;</code>
<code class="doc_src_line">        &lt;mfrac&gt;</code>
<code class="doc_src_line">        &lt;mrow&gt;</code>
<code class="doc_src_line">            &lt;mo form=&quot;prefix&quot;&gt;&amp;minus;&lt;/mo&gt;</code>
<code class="doc_src_line">            &lt;mi&gt;b&lt;/mi&gt;</code>
<code class="doc_src_line">            &lt;mo&gt;&amp;PlusMinus;&lt;/mo&gt;</code>
<code class="doc_src_line">            &lt;msqrt&gt;</code>
<code class="doc_src_line">            &lt;msup&gt;</code>
<code class="doc_src_line">                &lt;mi&gt;b&lt;/mi&gt;</code>
<code class="doc_src_line">                &lt;mn&gt;2&lt;/mn&gt;</code>
<code class="doc_src_line">            &lt;/msup&gt;</code>
<code class="doc_src_line">            &lt;mo&gt;&amp;minus;&lt;/mo&gt;</code>
<code class="doc_src_line">            &lt;mn&gt;4&lt;/mn&gt;</code>
<code class="doc_src_line">            &lt;mo&gt;&amp;InvisibleTimes;&lt;/mo&gt;</code>
<code class="doc_src_line">            &lt;mi&gt;a&lt;/mi&gt;</code>
<code class="doc_src_line">            &lt;mo&gt;&amp;InvisibleTimes;&lt;/mo&gt;</code>
<code class="doc_src_line">            &lt;mi&gt;c&lt;/mi&gt;</code>
<code class="doc_src_line">            &lt;/msqrt&gt;</code>
<code class="doc_src_line">        &lt;/mrow&gt;</code>
<code class="doc_src_line">        &lt;mrow&gt;</code>
<code class="doc_src_line">            &lt;mn&gt;2&lt;/mn&gt;</code>
<code class="doc_src_line">            &lt;mo&gt;&amp;InvisibleTimes;&lt;/mo&gt;</code>
<code class="doc_src_line">            &lt;mi&gt;a&lt;/mi&gt;</code>
<code class="doc_src_line">        &lt;/mrow&gt;</code>
<code class="doc_src_line">        &lt;/mfrac&gt;</code>
<code class="doc_src_line">    &lt;/mrow&gt;</code>
<code class="doc_src_line">&lt;/math&gt;</code>
<code class="doc_src_line">\end{mathmlblk}</code>
<code class="doc_src_line doc_src_dummy"></code></pre></div><p class="doc_par">The equation resulting from either of the above sources is shown below. To conclude, bear in mind that in similarity with other types of blocks, <span class="doc_caps">lambtex</span> also supports named mathematical expressions that may be numbered and referenced from anywhere in a document. For that you need to wrap a <code class="doc_mono">mathtexblk</code> or <code class="doc_mono">mathmlblk</code> environment inside an <code class="doc_mono">equation</code> block. This technique is part of the advanced features of the language and is discussed with greater detail in <a class="doc_lnk" href="#doc:m:sec:wrappers">Section&#xa0;21</a>.</p><div class="doc_math_blk"><math
xmlns="http://www.w3.org/1998/Math/MathML"
><mrow
><mi
>x</mi
><mo
lspace="0.278em"
rspace="0.278em"
>=</mo
><mfrac
><mrow
><mo
lspace="0"
rspace="0"
>-</mo
><mi
>b</mi
><mo
lspace="0"
rspace="0"
>±</mo
><msqrt
><msup
><mi
>b</mi
><mn
>2</mn
></msup
><mo
lspace="0"
rspace="0"
>-</mo
><mn
>4</mn
><mi
>a</mi
><mspace
width="0"
></mspace
><mi
>c</mi
></msqrt
></mrow
><mrow
><mn
>2</mn
><mi
>a</mi
></mrow
></mfrac
></mrow
></math
></div><h1 id="doc:a:5" class="doc_sec"><span class="doc_order">14</span><span>Images</span></h1><p class="doc_par"><span class="doc_caps">lambtex</span> allows the insertion of images either in inline contexts or in block contexts. In the former case, the image is typically the representation of a character which is unavailable in the <span class="doc_caps">unicode</span> set, and is for this reason denoted as a <i class="doc_emph">glyph</i>. The latter case includes images used as illustrations, diagrams, photographs, etc. These are known as <i class="doc_emph">pictures</i>.</p><h2 id="doc:m:sec:glyphs" class="doc_sec"><span class="doc_order">14.1</span><span>Glyphs</span></h2><p class="doc_par">The simple command <code class="doc_mono">\glyph</code> is used for inserting an image into an inline context. It takes the form <code class="doc_mono">\glyph{<i class="doc_emph">identifier</i>}{<i class="doc_emph">alt</i>}{<i class="doc_emph">title</i>}</code>, where <code class="doc_mono"><i class="doc_emph">identifier</i></code> is the name of the glyph (typically the filename), and <code class="doc_mono"><i class="doc_emph">alt</i></code> is the alternative text to be displayed if the browser cannot or is not configured to display images. Both parameters consist of raw text and are mandatory. The final parameter <code class="doc_mono"><i class="doc_emph">title</i></code> consists also of raw text, but is optional. It can be used to provide a small description which pops up when the user hovers the mouse over the image.</p><p class="doc_par">Because glyphs are embedded into a paragraph or other inline context, the image should be of comparable size to the text. This is simply a recommendation, however, as it is not enforced.</p><h2 id="doc:a:6" class="doc_sec"><span class="doc_order">14.2</span><span>Pictures</span></h2><p class="doc_par">The insertion of block images into a document is done via the simple command <code class="doc_mono">\picture</code>, which in its basic usage is identical to the afore described <code class="doc_mono">\glyph</code>. Namely, it takes the form <code class="doc_mono">\picture{<i class="doc_emph">identifier</i>}{<i class="doc_emph">alt</i>}{<i class="doc_emph">title</i>}</code>, where <code class="doc_mono"><i class="doc_emph">identifier</i></code> is the name of the picture (typically the filename), and <code class="doc_mono"><i class="doc_emph">alt</i></code> is the alternative text to be displayed if the browser cannot or is not configured to display images. Both parameters consist of raw text and are mandatory. The final parameter <code class="doc_mono"><i class="doc_emph">title</i></code> consists also of raw text, but is optional.</p><p class="doc_par">The command <code class="doc_mono">\picture</code> differs from <code class="doc_mono">\glyph</code> in that it must be used in a block context and that it supports some additional configuration via key-value style parameters. The bitmap below illustrates the use of a image block. Please do try hovering the mouse over the image!</p><div class="doc_pic doc_floatable" title="Thank you for hovering!"><a href="circle.png" class="doc_pic_lnk"><img src="circle.png" alt="This is a circle" class="doc_pic"/></a></div><p class="doc_par">Note that in most browsers you cannot see the alternative text unless the browser is configured not to display images. As for the code that produced the picture, it is as simple as this:</p><div class="doc_src_block doc_class_boxed"><pre class="doc_src_code">
<code class="doc_src_line doc_src_dummy"></code>
<code class="doc_src_line">\picture{circle.png}{This is a circle}{Thank you for hovering!}</code>
<code class="doc_src_line doc_src_dummy"></code></pre></div><p class="doc_par">The size of the picture can be controlled by the optional key-value style parameter <code class="doc_mono">width</code>. Its value is either <code class="doc_mono">auto</code> or an integer between 1 and 100 (inclusive), indicating the percentage of the total width of the page that the picture should occupy (minus a small margin common to all non-text blocks). The default is <code class="doc_mono">auto</code>, which translates into a picture occupying its natural width in pixels (up to the maximum width of the page). Note that block images are always clickable and that the target <span class="doc_caps">uri</span> is that of the picture itself. This is useful, for example, for seeing at their full size pictures that were scaled down with the <code class="doc_mono">width</code> parameter or that did not fit into the width of the page.</p><p class="doc_par">The default <span class="doc_caps">css</span> shipped with <span class="doc_caps">lambtex</span> offers an additional customisation options for pictures. As its name suggests, the classname style parameter '<code class="doc_mono">frame</code>' adds a small framed shadow to the picture. It is off by default, and esthetically it is more sensible for rectangular pictures such as photographs. In addition, the floatation classnames '<code class="doc_mono">center</code>', '<code class="doc_mono">left</code>', and '<code class="doc_mono">right</code>' may also be used.</p><p class="doc_par">It is a common practice to add a numbered caption to a picture. To achieve this in <span class="doc_caps">lambtex</span> you must wrap the <code class="doc_mono">picture</code> block inside a <code class="doc_mono">figure</code>, as described in <a class="doc_lnk" href="#doc:m:sec:wrappers">Section&#xa0;21</a>.</p><h1 id="doc:m:sec:subpage" class="doc_sec"><span class="doc_order">15</span><span>Sub-pages</span></h1><p class="doc_par">Another interesting <span class="doc_caps">lambtex</span> feature is the ability to display child documents inside a framed block. These nested documents, termed <i class="doc_emph">sub-pages</i>, are offered by the <code class="doc_mono">subpage</code> environment. While in general their usage is very limited and it is unlikely you will ever need to use sub-pages, for some applications — namely writing manuals about <span class="doc_caps">lambtex</span> — they are indispensable.</p><p class="doc_par">Sub-pages are not completely independent documents. You may refer to elements inside a sub-page from the main document and vice-versa. Moreover, any notes and bibliography entries (see <span class="doc_mbox">Sections <a class="doc_lnk" href="#doc:m:sec:onnotes">24</a> and <a class="doc_lnk" href="#doc:m:sec:onbiblio">25</a></span>) declared inside a sub-page are still associated with the main document. Finally, take into consideration that <span class="doc_caps">lambtex</span> will not automatically assign an ordering for sections and wrapper blocks declared inside sub-pages (these blocks are part of the advanced language features and are discussed in <a class="doc_lnk" href="#doc:m:sec:headings">Section&#xa0;16</a> and <a class="doc_lnk" href="#doc:m:sec:wrappers">Section&#xa0;21</a>, respectively).</p><p class="doc_par">You have already encountered several examples of sub-pages while reading this document, as they have been used to illustrate the output of the composer in association with each code sample. The example below is the code that was used to produce the very first sub-page you have encountered in this document, back in the <a class="doc_lnk" href="#doc:m:sec:paragraphs">section on paragraph blocks</a>.</p><div class="doc_src_block doc_class_boxed"><pre class="doc_src_code">
<code class="doc_src_line doc_src_dummy"></code>
<code class="doc_src_line">\begin{subpage}</code>
<code class="doc_src_line">This is the first example of a paragraph.  Note that</code>
<code class="doc_src_line">it is composed of inline text.</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">Lines can be broken at any point, because a paragraph</code>
<code class="doc_src_line">is only terminated by a blank line. \br</code>
<code class="doc_src_line">It is however possible to manually insert a line break</code>
<code class="doc_src_line">without terminating the paragraph.</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">\p{There is also a simple command that allows the</code>
<code class="doc_src_line">explicit declaration of a paragraph.}</code>
<code class="doc_src_line">\end{subpage}</code>
<code class="doc_src_line doc_src_dummy"></code></pre></div><h1 id="doc:m:sec:headings" class="doc_sec"><span class="doc_order">16</span><span>Parts and sections</span></h1><p class="doc_par"><span class="doc_caps">lambtex</span> supports three different levels of sectioning: sections, sub-sections, and sub-sub-sections. The simple commands used for declaring each one are <code class="doc_mono">\section</code>, <code class="doc_mono">\subsection</code>, and <code class="doc_mono">\subsubsection</code>, respectively. These are automatically ordered by <span class="doc_caps">lambtex</span>. If you want to declare an unordered section, you must use an empty ordering parameter. Remember that ordering parameters are usually optional, and are declared by enclosing between parenthesis the order you want to attribute. An empty order simply means that only the opening and closing parenthesis should be present, without any characters between them. (Sectional commands declared inside sub-pages do require an explicit ordering parameter, empty or not; check <a class="doc_lnk" href="#doc:m:sec:order">Appendix&#xa0;D</a> for details).</p><p class="doc_par">In addition to sections, <span class="doc_caps">lambtex</span> documents may also be divided into <i class="doc_emph">parts</i>. Parts are a higher-level division than sections, and are typically only used in fairly complex documents. This manual, for example, uses parts for making a clear distinction between the language tutorial and the appendix sections. Note that a new part is declared with the homonymous simple command <code class="doc_mono">\part</code>, and that it does not reset the section counter. In similarity to sections, parts can also be unordered.</p><p class="doc_par">Another common requirement associated with sectioning is the ability to refer to a given part or section in a document. With that in mind, <span class="doc_caps">lambtex</span> allows you to label a given part or section declaration, and as described in the <a class="doc_lnk" href="#doc:m:sec:intlinks">following section</a>, provides also a set of commands that create hyperlinks to a given label. The label parameter is always optional and is enclosed in square brackets:</p><div class="doc_src_block doc_class_boxed"><pre class="doc_src_code">
<code class="doc_src_line doc_src_dummy"></code>
<code class="doc_src_line">\part{Prelude}</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">\section{Introduction}</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">For more details, please check Section \dref{sec:details}.</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">\subsection[sec:details]{This is a sub-section}</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">\subsubsection(){This is an unordered sub-sub-section}</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">The quick brown fox jumps over the lazy brown dog.</code>
<code class="doc_src_line doc_src_dummy"></code></pre></div><p class="doc_par">The output produced by the <span class="doc_caps">lambtex</span> composer is as follows:</p><div class="doc_subpage"><h1 id="doc:a:7" class="doc_part"><span class="doc_order">I</span><span>Prelude</span></h1><h1 id="doc:a:8" class="doc_sec"><span class="doc_order">1</span><span>Introduction</span></h1><p class="doc_par">For more details, please check Section 1.1.</p><h2 id="doc:m:sec:details" class="doc_sec"><span class="doc_order">1.1</span><span>This is a sub-section</span></h2><h3 id="doc:a:9" class="doc_sec"><span>This is an unordered sub-sub-section</span></h3><p class="doc_par">The quick brown fox jumps over the lazy brown dog.</p></div><p class="doc_par">To conclude, and since this is our first encounter with label parameters, the reader should note that labels have two constraints. First, the starting character must be a lowercase Roman letter. Second, the allowed character set for subsequent characters is limited to lowercase Roman letters, digits, and the characters '<code class="doc_mono">:</code>' (colon), '<code class="doc_mono">-</code>' (dash), and '<code class="doc_mono">_</code>' (underscore). Also note that all labels share the same namespace; we recommend adopting the <span class="doc_caps">LaTeX</span> custom of using a prefix indicating the target type. In the example above, the prefix <code class="doc_mono">sec:</code> is used for the sectioning family of commands.</p><h1 id="doc:m:sec:intlinks" class="doc_sec"><span class="doc_order">17</span><span>Internal hyperlinks</span></h1><p class="doc_par"><span class="doc_caps">lambtex</span> supports hyperlinks both to external resources and into targets in the same document. The former is provided by the already described simple command <code class="doc_mono">\link</code>, whereas the latter relies on a set of different simple commands, each one tailored for a different use and/or kind of target. <a class="doc_lnk" href="#doc:m:tab:hyperlinks">Tab.&#xa0;6</a> lists all available hyperlinks commands, and the following source illustrates their use:</p><div class="doc_src_block doc_class_boxed"><pre class="doc_src_code">
<code class="doc_src_line doc_src_dummy"></code>
<code class="doc_src_line">You can easily insert a link into an external resource such</code>
<code class="doc_src_line">as \link{http://www.wikipedia.com/}{Wikipedia}.  Internal</code>
<code class="doc_src_line">links come into several guises: they can be references to</code>
<code class="doc_src_line">notes\see{note:meta}; bibliographic references like those</code>
<code class="doc_src_line">available in \caps{LaTeX}\cite{bib:latex}; pointers to</code>
<code class="doc_src_line">labelled figures, tables, printouts, equations, or sections</code>
<code class="doc_src_line">such as \mbox{Section \dref{sec:anatomy}}; smart references to</code>
<code class="doc_src_line">those same elements such as \sref{sec:anatomy}; and finally,</code>
<code class="doc_src_line">references where the order is not automatically added (for</code>
<code class="doc_src_line">example, you may refer yet again \mref{sec:anatomy}{to that</code>
<code class="doc_src_line">same section}).</code>
<code class="doc_src_line doc_src_dummy"></code></pre></div><p class="doc_par">The corresponding output of the composer is the following:</p><div class="doc_subpage"><p class="doc_par">You can easily insert a link into an external resource such as <a class="doc_lnk" href="http://www.wikipedia.com/">Wikipedia</a>. Internal links come into several guises: they can be references to notes<span class="doc_see">(<a class="doc_lnk" href="#doc:m:note:meta">5</a>)</span>; bibliographic references like those available in <span class="doc_caps">LaTeX</span><span class="doc_cite">[<a class="doc_lnk" href="#doc:m:bib:latex">1</a>]</span>; pointers to labelled figures, tables, printouts, equations, or sections such as <span class="doc_mbox">Section <a class="doc_lnk" href="#doc:m:sec:anatomy">1</a></span>; smart references to those same elements such as <a class="doc_lnk" href="#doc:m:sec:anatomy">Section&#xa0;1</a>; and finally, references where the order is not automatically added (for example, you may refer yet again <a class="doc_lnk" href="#doc:m:sec:anatomy">to that same section</a>).</p></div><p class="doc_par">Bear in mind that the use of the smart references offered by command <code class="doc_mono">\sref</code> is strongly recommended over the manual references provided by command <code class="doc_mono">\dref</code>. The reason is three-fold. First, because smart references ensure the consistent use of one naming scheme over an entire document and across several documents. Second, because smart references automatically make sure that a non-breaking space is inserted between the element name and its ordering number, thus preventing their separation by a line break (to achieve the same effect with manual references, the user must explicitly place both elements inside an <code class="doc_mono">\mbox</code> command, or use the <code class="doc_mono">&amp;nbsp;</code> <span class="doc_caps">html</span> entity). Third and last, because smart references will make a hyperlink of both the name and the ordering, which is friendlier for mouse clicking and arguably esthetically more pleasant.</p><p class="doc_par">On a related note, we recommend that <code class="doc_mono">\see</code> and <code class="doc_mono">\cite</code> commands not be separated from the preceding element by spaces. The default <span class="doc_caps">css</span> stylesheet shipped with <span class="doc_caps">lambtex</span> already adds a small margin, and by not having spaces you avoid the split across line breaks or the need to resort to the <code class="doc_mono">\mbox</code> command or the <code class="doc_mono">nbsp</code> <span class="doc_caps">html</span> entity.</p><p class="doc_par">Finally, though <span class="doc_caps">lambtex</span> offers no explicit support for subfigures, links towards them are accommodated via the optional inline sequence accepted by commands <code class="doc_mono">\dref</code> and <code class="doc_mono">\sref</code>. This inline sequence is appended to the link text, thus allowing you to specify a subfigure identifier (such as '<i class="doc_emph">a</i>', '<i class="doc_emph">b</i>', etc) when making a link to the subfigure.</p><div id="doc:m:tab:hyperlinks" class="doc_wrapper doc_floatable doc_table"><div class="doc_tab"><div class="doc_tab_aux"><table><thead class="doc_tgroup"><tr><td class="doc_cell_r">Command</td><td class="doc_cell_l">Description</td></tr></thead><tbody class="doc_tgroup"><tr><td class="doc_cell_r"><span class="doc_mbox"><code class="doc_mono">\link{<i class="doc_emph">uri</i>}</code></span></td><td class="doc_cell_l">Inserts a link to an external resource.</td></tr><tr><td class="doc_cell_r"><span class="doc_mbox"><code class="doc_mono">\link{<i class="doc_emph">uri</i>}{<i class="doc_emph">inline</i>}</code></span></td><td class="doc_cell_l">Alternate form of <code class="doc_mono">\link</code>, which displays the inline sequence instead of the <span class="doc_caps">uri</span>.</td></tr><tr><td class="doc_cell_r"><span class="doc_mbox"><code class="doc_mono">\see{<i class="doc_emph">label</i>}</code>...</span></td><td class="doc_cell_l">Refers to a document note (see <a class="doc_lnk" href="#doc:m:sec:onnotes">Section&#xa0;24</a>).</td></tr><tr><td class="doc_cell_r"><span class="doc_mbox"><code class="doc_mono">\cite{<i class="doc_emph">label</i>}</code>...</span></td><td class="doc_cell_l">Cites a bibliographic reference (see <a class="doc_lnk" href="#doc:m:sec:onbiblio">Section&#xa0;25</a>).</td></tr><tr><td class="doc_cell_r"><span class="doc_mbox"><code class="doc_mono">\dref{<i class="doc_emph">label</i>}</code></span></td><td class="doc_cell_l">Inserts a link to a numbered section, part, equation, printout, table, figure, boxout, or theorem. The text under the hyperlink is the order of the reference.</td></tr><tr><td class="doc_cell_r"><span class="doc_mbox"><code class="doc_mono">\dref{<i class="doc_emph">label</i>}{<i class="doc_emph">inline</i>}</code></span></td><td class="doc_cell_l">Alternate form of <code class="doc_mono">\dref</code>, which appends the inline sequence to the link text. Useful for subfigures, for example.</td></tr><tr><td class="doc_cell_r"><span class="doc_mbox"><code class="doc_mono">\sref{<i class="doc_emph">label</i>}</code></span></td><td class="doc_cell_l">Inserts a <i class="doc_emph">smart</i> reference to numbered section, part, equation, printout, table, figure, boxout, or theorem. Besides the order, smart references also include the name of the kind of reference they are linking to.</td></tr><tr><td class="doc_cell_r"><span class="doc_mbox"><code class="doc_mono">\sref{<i class="doc_emph">label</i>}{<i class="doc_emph">inline</i>}</code></span></td><td class="doc_cell_l">Alternate form of <code class="doc_mono">\sref</code>, which appends the inline sequence to the link text. Useful for subfigures, for example.</td></tr><tr><td class="doc_cell_r"><span class="doc_mbox"><code class="doc_mono">\mref{<i class="doc_emph">label</i>}{<i class="doc_emph">inline</i>}</code></span></td><td class="doc_cell_l">Inserts a reference to a section, part, equation, printout, table, figure, boxout, or theorem, but without including the order. Instead, the description provided as the second mandatory parameter is used for the hyperlink.</td></tr></tbody></table></div></div><div class="doc_caption doc_caption_long"><div class="doc_caption_aux"><h1 class="doc_caption_head">Tab.&#xa0;6:</h1><p class="doc_caption_body">The various hyperlinking commands available in <span class="doc_caps">lambtex</span>. Note that the <code class="doc_mono"><i class="doc_emph">uri</i></code> and <code class="doc_mono"><i class="doc_emph">label</i></code> sequences are interpreted as raw text.</p></div></div></div><h1 id="doc:m:sec:pull" class="doc_sec"><span class="doc_order">18</span><span>Pull-quotes</span></h1><div class="doc_pull doc_floatable"><div class="doc_pull_aux"><p class="doc_par">Weaseling out of things is important to learn: it's what separates us from the animals. Except the weasel.</p><h1 class="doc_pull_head">&#x2014;&#x2002;Homer Simpson</h1></div></div><p class="doc_par">In typography, the special quotations such as the one above are termed <i class="doc_emph">pull-quotes</i> or <i class="doc_emph">lift-out quotes</i>. Pull-quotes serve different purposes than the regular quotation blocks introduced in a <a class="doc_lnk" href="#doc:m:sec:quotations">previous</a> section. Whereas quotation blocks are almost exclusively used to quote a sizeable excerpt from an external source, pull-quotes are either used to make a brief and named quotation such as the one that opens this section, or to emphasize a passage from the very same document where they are defined.</p><p class="doc_par">This block type is declared using the <code class="doc_mono">pull</code> environment command, and accepts an optional primary parameter consisting of an inline sequence specifying the authorship of the quote. Therefore, to produce a pull-quote like the one that opens this section, you can simply provide the following code:</p><div class="doc_src_block doc_class_boxed"><pre class="doc_src_code">
<code class="doc_src_line doc_src_dummy"></code>
<code class="doc_src_line">\begin{pull}{Homer Simpson}</code>
<code class="doc_src_line">Weaseling out of things is important to learn:</code>
<code class="doc_src_line">it's what separates us from the animals.</code>
<code class="doc_src_line">Except the weasel.</code>
<code class="doc_src_line">\end{pull}</code>
<code class="doc_src_line doc_src_dummy"></code></pre></div><p class="doc_par">In similarity to their regular counterparts, the usefulness of pull-quotes carries with it a warning against abuse. Though one may be tempted to make heavy use of this feature, bear in mind that its effectiveness goes down as their usage is increased. Moreover, it tends to make more sense for longer documents, and/or when it is floated to the left or right. For the latter reason, the default <span class="doc_caps">css</span> shipped with <span class="doc_caps">lambtex</span> allows for the style parameters of a pull-quote to declare one of the previously discussed floatation specifiers.</p><h1 id="doc:m:sec:boxouts" class="doc_sec"><span class="doc_order">19</span><span>Declaring and using boxouts</span></h1><div id="doc:a:10" class="doc_boxout doc_boxout_env_warning doc_class_right doc_floatable"><h1 class="doc_boxout_head">Warning:&#xa0;Boxout overload</h1><div class="doc_boxout_body"><p class="doc_par">Boxouts are like quotation blocks: they are most effective when not abused!</p></div></div><p class="doc_par">Boxout blocks allow you emphasise a document fragment by placing it inside a box. Boxouts are useful for warnings, notices, tips, reminders, etc. Boxouts are custom environments, in the sense that the command name that appears in the begin/end pairs is not built-in and is instead defined in the document itself. Therefore, before a boxout is used, it must first be declared via the simple command <code class="doc_mono">\newboxout</code>. Moreover, boxouts are optionally titled and may be given an automatic ordering.</p><p class="doc_par">The command <code class="doc_mono">\newboxout</code> accepts at least one, and up to three primary parameters. The first parameter is the name of the boxout environment; this is the same name that must subsequently be used inside the begin/end pairs. Obviously, you may not name a boxout with the same designation of an existing command, or with a designation that begins with the name of an environment that uses the <span class="doc_caps">heredoc</span> technique (namely <code class="doc_mono">verbatim</code>, <code class="doc_mono">source</code>, <code class="doc_mono">mathtexblk</code>, and <code class="doc_mono">mathmlblk</code>). Moreover, the name must begin with a lowercase Roman letter and be composed only of lowercase Roman letters, digits, and the character '<code class="doc_mono">_</code>' (underscore). The second parameter, if present, is an inline sequence indicating a fixed title that will appear in all boxouts of this name. Finally, the third parameter may be used to assign a counter to this boxout. If not present, the boxout is unnumbered; moreover, different boxouts may share the same counter. Note that the third parameter may only be given for boxouts that do have a title, and thus also a second parameter. In addition, bear in mind that counter identifiers must follow the same rules laid out for labels, as described in <a class="doc_lnk" href="#doc:m:sec:headings">Section&#xa0;16</a>. Counter identifiers do nevertheless reside in their own separate namespace, independent of that of labels.</p><p class="doc_par">Subsequent to its declaration, using a new boxout named <code class="doc_mono"><i class="doc_emph">name</i></code> is simply a matter of wrapping its contents between <code class="doc_mono">\begin{<i class="doc_emph">name</i>}</code> and <code class="doc_mono">\end{<i class="doc_emph">name</i>}</code>. The begin tag accepts an optional primary parameter with an extra title to assign to the boxout. If the <code class="doc_mono">\newboxout</code> boxout declaration did not include a title, then this extra title becomes the sole title for this particular instance of the boxout. If on the other hand <code class="doc_mono">\newboxout</code> already declared a generic title, then the extra title is appended to the generic title. Should neither a generic nor an extra title be given, then the boxout will be titleless.</p><p class="doc_par">Suppose thus you wished to display a warning boxout like the one that opens this section. It makes sense to name it <code class="doc_mono">warning</code>, and for each instance of the boxout to include the generic title <i class="doc_emph">“Warning”</i>. Moreover, you do not wish for warnings to be numbered, so you should not assign a counter to it. As for this particular instance of the boxout, you wish the extra title <i class="doc_emph">“Boxout overload”</i> to be appended to the generic title (note that the colon separating the generic and instance-specific titles is automatically inserted as needed, so you do not need to include it manually). All these considerations can be realised with the following code:</p><div class="doc_src_block doc_class_boxed"><pre class="doc_src_code">
<code class="doc_src_line doc_src_dummy"></code>
<code class="doc_src_line">\newboxout{warning}{Warning}</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">\begin{warning}{Boxout overload}</code>
<code class="doc_src_line">Boxouts are like quotation blocks:</code>
<code class="doc_src_line">they are most effective when not abused!</code>
<code class="doc_src_line">\end{warning}</code>
<code class="doc_src_line doc_src_dummy"></code></pre></div><p class="doc_par">At this point you may be wondering where does the customised warning sign come from. Its origin is simple: for each boxout named <code class="doc_mono"><i class="doc_emph">name</i></code>, the <span class="doc_caps">html</span> output driver from the <span class="doc_caps">lambdoc</span> library will include the classname <code class="doc_mono">doc_boxout_env_<i class="doc_emph">name</i></code> in the <span class="doc_caps">div</span> element that encapsulates the boxout. The <span class="doc_caps">css</span> supplied with the library takes advantage of this metadata, and contains sample customisation for boxouts named <code class="doc_mono">warning</code> and <code class="doc_mono">tip</code>. This trick provides an easy way to customise your own boxouts. The default <span class="doc_caps">css</span> also allows for boxouts to use the floatation classname specifiers described in <a class="doc_lnk" href="#doc:m:sec:verbatim">Section&#xa0;10</a>.</p><p class="doc_par">To conclude note that boxouts may be labelled, and that you may request the supression of ordering for individual instances of numbered boxouts. The latter is achieved in the same manner as with sections and parts: by providing the empty ordering declaration '<code class="doc_mono">()</code>'. Labelled boxouts may be referenced from anywhere in the document via the simple commands <code class="doc_mono">\dref</code>, <code class="doc_mono">\sref</code>, or <code class="doc_mono">\mref</code> (the two former commands may only be used for numbered boxouts, obviously).</p><h1 id="doc:m:sec:theorems" class="doc_sec"><span class="doc_order">20</span><span>Theorem-like environments</span></h1><p class="doc_par">Theorems and their kin such as corollaries, lemmas, etc, are a staple of mathematical and computer-science writing. For this reason, <span class="doc_caps">lambtex</span> also supports them. In practice, theorem-like environments are declared and used in pretty much the same way as boxouts. The major difference is that the declaration of a new theorem is done via the simple command <code class="doc_mono">\newtheorem</code>. Moreover, theorems must always have a title, and therefore the declaration has two mandatory primary parameters. Similarly to boxouts, <code class="doc_mono">\newtheorem</code> may optionally include a third primary parameter specifying the counter if you wish the theorem to be numbered. Note that even though the same counter may be shared between multiple theorem-like environments, you may not share a counter between a boxout and a theorem. Because all counters share the same namespace, you must make sure collisions do not occur.</p><p class="doc_par">Suppose thus you wish to create a theorem named <code class="doc_mono">theorem</code>, and whose title is, unsurprisingly, <i class="doc_emph">“Theorem”</i>. Moreover, you want the theorem to be numbered, and its counter to be called '<code class="doc_mono">cnt:theorem</code>'. One particular instantiation of this theorem has the extra title <i class="doc_emph">“John McAuthor”</i>, reflecting its authorship. This is the <span class="doc_caps">lambtex</span> source you may use:</p><div class="doc_src_block doc_class_boxed"><pre class="doc_src_code">
<code class="doc_src_line doc_src_dummy"></code>
<code class="doc_src_line">\newtheorem{theorem}{Theorem}{cnt:theorem}</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">\begin{theorem}{John McAuthor}</code>
<code class="doc_src_line">Let an egg be defined as an ellipsoid whose radii across the $$x$$,</code>
<code class="doc_src_line">$$y$$, and $$z$$ axes are respectively $$a$$, $$b$$, and $$c$$.</code>
<code class="doc_src_line">Furthermore, the egg satisfies the scalene condition, and therefore</code>
<code class="doc_src_line">$$a &gt; b &gt; c$$.  All such eggs are optimally opened by their small-end.</code>
<code class="doc_src_line">\end{theorem}</code>
<code class="doc_src_line doc_src_dummy"></code></pre></div><p class="doc_par">The resulting output is shown below. Note that in theorems the extra title is displayed between parentheses, in accordance to convention. Should you wish to customise the <span class="doc_caps">css</span> for particular classes of theorems, you may make use of the same technique described for boxouts. Note, however, that for a theorem named <code class="doc_mono"><i class="doc_emph">name</i></code>, the associated classname is <code class="doc_mono">doc_theorem_env_<i class="doc_emph">name</i></code>.</p><div class="doc_subpage"><div id="doc:a:11" class="doc_theorem doc_theorem_env_theorem"><h1 class="doc_theorem_head"><span class="doc_thmname">Theorem&#xa0;1</span><span class="doc_thmextra">(John McAuthor).</span></h1><div class="doc_theorem_body"><p class="doc_par">Let an egg be defined as an ellipsoid whose radii across the <span class="doc_math_inl"><math
xmlns="http://www.w3.org/1998/Math/MathML"
><mi
>x</mi
></math
></span>, <span class="doc_math_inl"><math
xmlns="http://www.w3.org/1998/Math/MathML"
><mi
>y</mi
></math
></span>, and <span class="doc_math_inl"><math
xmlns="http://www.w3.org/1998/Math/MathML"
><mi
>z</mi
></math
></span> axes are respectively <span class="doc_math_inl"><math
xmlns="http://www.w3.org/1998/Math/MathML"
><mi
>a</mi
></math
></span>, <span class="doc_math_inl"><math
xmlns="http://www.w3.org/1998/Math/MathML"
><mi
>b</mi
></math
></span>, and <span class="doc_math_inl"><math
xmlns="http://www.w3.org/1998/Math/MathML"
><mi
>c</mi
></math
></span>. Furthermore, the egg satisfies the scalene condition, and therefore <span class="doc_math_inl"><math
xmlns="http://www.w3.org/1998/Math/MathML"
><mrow
><mi
>a</mi
><mo
lspace="0.278em"
rspace="0.278em"
>&gt;</mo
><mi
>b</mi
><mo
lspace="0.278em"
rspace="0.278em"
>&gt;</mo
><mi
>c</mi
></mrow
></math
></span>. All such eggs are optimally opened by their small-end.</p></div></div></div><h1 id="doc:m:sec:wrappers" class="doc_sec"><span class="doc_order">21</span><span>Wrappers</span></h1><p class="doc_par">Consider the previously discussed math blocks, source-code listings, tabular environments, picture blocks, verbatim environments, and subpages. All of these are anonymous blocks, in the sense they do not have an associated label and therefore cannot be referenced from elsewhere in the document. It is however common for one to wish to reference any of these block types from elsewhere in the document and/or to provide them with a caption. with this in mind, <span class="doc_caps">lambtex</span> offers a special kind of block known as a <i class="doc_emph">wrapper</i>, which as its name implies, is essentially just a wrapper around any of the above listed <i class="doc_emph">wrappable</i> blocks. There are four different classes of wrappers available:</p><dl class="doc_description"><dt class="doc_item">Equations</dt><dd class="doc_item"><p class="doc_par">These are declared via the environment command <code class="doc_mono">equation</code>, and may be used for wrapping <code class="doc_mono">mathtexblk</code> and <code class="doc_mono">mathmlblk</code> blocks.</p></dd><dt class="doc_item">Printouts</dt><dd class="doc_item"><p class="doc_par">These are used for wrapping <code class="doc_mono">source</code> environments, and are declared with the environment command <code class="doc_mono">printout</code>.</p></dd><dt class="doc_item">Tables</dt><dd class="doc_item"><p class="doc_par">Tables may only be used for wrapping <code class="doc_mono">tabular</code> environments, and are declared with the environment command <code class="doc_mono">table</code>.</p></dd><dt class="doc_item">Figures</dt><dd class="doc_item"><p class="doc_par">Finally, figures are declared with the environment command <code class="doc_mono">figure</code>, and may be used for wrapping <code class="doc_mono">verbatim</code>, <code class="doc_mono">picture</code>, and <code class="doc_mono">subpage</code> blocks.</p></dd></dl><p class="doc_par">All these classes have two features in common: they may all be captioned, and each class has an associated counter that is automatically incremented whenever a new ordered wrapper is declared. Note also that the wrapper itself may be labelled, as illustrated by the code below, which shows the use of a <code class="doc_mono">figure</code> wrapper around a <code class="doc_mono">picture</code> block:</p><div class="doc_src_block doc_class_boxed"><pre class="doc_src_code">
<code class="doc_src_line doc_src_dummy"></code>
<code class="doc_src_line">\begin[fig:example]{figure}{This is the figure's caption.}</code>
<code class="doc_src_line">\picture{circle.png}{This is a circle}</code>
<code class="doc_src_line">\end{figure}</code>
<code class="doc_src_line doc_src_dummy"></code></pre></div><p class="doc_par">You can refer to the above declared figure from anywhere in the document by using the label '<code class="doc_mono">fig:example</code>' with any of the simple commands <code class="doc_mono">\dref</code>, <code class="doc_mono">\sref</code>, and <code class="doc_mono">\mref</code>. The resulting figure (<a class="doc_lnk" href="#doc:m:fig:example">Fig.&#xa0;1</a>) is shown below:</p><div id="doc:m:fig:example" class="doc_wrapper doc_floatable doc_figure"><div class="doc_pic"><a href="circle.png" class="doc_pic_lnk"><img src="circle.png" alt="This is a circle" class="doc_pic"/></a></div><div class="doc_caption doc_caption_long"><div class="doc_caption_aux"><h1 class="doc_caption_head">Fig.&#xa0;1:</h1><p class="doc_caption_body">This is the figure's caption.</p></div></div></div><p class="doc_par">Remember that captioning is optional. When present, the caption is an inline sequence declared as a primary parameter of the wrapper environment. Should it not be given, the counter associated with the wrapper is displayed between parentheses below the wrapped block. However, note that a caption-less wrapper must have an associated order, and therefore if you declare the wrapper to have an empty ordering via the '<code class="doc_mono">()</code>' specification, then you must provide it with a caption. This restriction is in place so that every wrapper has some form of context, either in the form of an ordering or a caption.</p><p class="doc_par">It is perfectly reasonable and common for wrapped blocks to be floated on the sides of the page. Therefore, the default <span class="doc_caps">css</span> shipped with <span class="doc_caps">lambtex</span> allows for the floatation specifiers '<code class="doc_mono">center</code>', '<code class="doc_mono">left</code>', and '<code class="doc_mono">right</code>' to be provided as style parameters to any wrapper. Note that with the exception of picture and verbatim environments, with the default <span class="doc_caps">css</span> one can only float wrappable blocks when they are actually placed inside a wrapper. The rationale was discussed in <a class="doc_lnk" href="#doc:m:sec:verbatim">Section&#xa0;10</a>: in brief, floating a block is predicated on the block carrying its own context, and thus being safely removable from the main flow of the document.</p><p class="doc_par">Note that context-carrying blocks are not tied to a precise location of the document (that is, it won't matter much if they are placed a couple of paragraphs above or below, as long as they can be found in the relevant section), and they have a fair degree of independence from the contents in the main flow. It is for this reason that you may not directly float, say, a <code class="doc_mono">source</code> block. It carries no context by itself, and thus must be integrated into the main flow, or wrapped inside a <code class="doc_mono">printout</code> whose caption and/or ordering provide the needed context. Theorems — even though they have some independence and provide their own context — are excluded from the set of blocks allowed to float. The rationale stems mainly from customary usage, where theorems are integrated into the main flow of the document.</p><h1 id="doc:m:sec:frontmatter" class="doc_sec"><span class="doc_order">22</span><span>Frontmatter: title, abstract, and table of contents</span></h1><p class="doc_par">This section addresses three semantic elements associated with large manuscripts and which are placed before the main body of the document, at the so-called <i class="doc_emph">frontmatter</i>. These elements are titles and sub-titles, the abstract, and the table of contents.</p><p class="doc_par">Titles in <span class="doc_caps">lambtex</span> are declared via the aptly named <code class="doc_mono">\title</code> command. This is a simple command that takes an inline sequence as parameter. Closely related is the also simple command <code class="doc_mono">\subtitle</code>. It is typically used for showing the document's author, date, or actual sub-titles.</p><p class="doc_par"><span class="doc_caps">LaTeX</span> users are familiar with a richer set of sub-titles that includes special commands for specifying the author and date. There is obviously a trade-off between increasing language complexity and improving semantic richness. On this continuum, <span class="doc_caps">lambtex</span> sits further along than plain <span class="doc_caps">TeX</span> on the direction towards semantic richness. However, the awareness of increased language complexity is ever-present, and weights heavily on decisions such as this one. It is for this reason that the language offers a catch-all <code class="doc_mono">\subtitle</code> command instead of multiple commands tailored to each particular application.</p><p class="doc_par">Abstracts are commonly found on scientific papers, and <span class="doc_caps">lambtex</span> supports them as well. An abstract is declared by enclosing one or more embeddable blocks within an <code class="doc_mono">abstract</code> environment. Please consult <a class="doc_lnk" href="#doc:m:sec:structure">Appendix&#xa0;A</a> for more details on what constitutes a <i class="doc_emph">embeddable block</i>, and note the source fragment below for an example of the various frontmatter blocks.</p><div class="doc_src_block doc_class_boxed"><pre class="doc_src_code">
<code class="doc_src_line doc_src_dummy"></code>
<code class="doc_src_line">\title{Small-endian vs big-endian: the solution}</code>
<code class="doc_src_line">\subtitle{John McAuthor}</code>
<code class="doc_src_line">\subtitle{February 2009}</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">\begin{abstract}</code>
<code class="doc_src_line">This paper presents an irrefutable solution to the age-old question</code>
<code class="doc_src_line">of whether eggs should be opened by the small-end or the big-end.</code>
<code class="doc_src_line">Many insightful arguments shall be presented. (...)</code>
<code class="doc_src_line">\end{abstract}</code>
<code class="doc_src_line doc_src_dummy"></code></pre></div><p class="doc_par">This is the result produced by the <span class="doc_caps">lambtex</span> composer:</p><div class="doc_subpage"><h1 class="doc_title">Small-endian vs big-endian: the solution</h1><h2 class="doc_title">John McAuthor</h2><h2 class="doc_title">February 2009</h2><div class="doc_abstract"><h1 class="doc_sec">Abstract</h1><p class="doc_par">This paper presents an irrefutable solution to the age-old question of whether eggs should be opened by the small-end or the big-end. Many insightful arguments shall be presented. (...)</p></div></div><p class="doc_par">Finally, you can request that a table of contents be printed by issueing the parameterless simple command <code class="doc_mono">\toc</code>. This can be done at any place in the document, though convention and reason suggest that it be placed at the very beginning. Note that even though <code class="doc_mono">\toc</code> lacks any primary parameters (which in <span class="doc_caps">lambtex</span> are always enclosed in curly brackets), it does accepts an optional label parameter. This is useful for referencing the table of contents from anywhere in the document. Also, bear in mind that the table of contents itself does not appear in the table of contents! You may verify this fact in this manual's own <a class="doc_lnk" href="#doc:m:sec:toc">table of contents</a>.</p><h1 id="doc:a:12" class="doc_sec"><span class="doc_order">23</span><span>Rules</span></h1><p class="doc_par">A typographic rule is commonly used in fiction pieces to clearly separate unrelated paragraphs. For the sake of completeness, <span class="doc_caps">lambtex</span> supports also this feature. You may declare it using the <code class="doc_mono">\rule</code> simple command, or its synonym <code class="doc_mono">\hr</code>. These commands are completely parameterless, as the code sample below demonstrates:</p><div class="doc_src_block doc_class_boxed"><pre class="doc_src_code">
<code class="doc_src_line doc_src_dummy"></code>
<code class="doc_src_line">This is a paragraph.</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">\rule</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">This is another paragraph.</code>
<code class="doc_src_line doc_src_dummy"></code></pre></div><p class="doc_par">The generated <span class="doc_caps">xhtml</span> result depends of course on the installed <span class="doc_caps">css</span>. The default stylesheet produces the following result:</p><div class="doc_subpage"><p class="doc_par">This is a paragraph.</p><hr class="doc_rule"/><p class="doc_par">This is another paragraph.</p></div><h1 id="doc:m:sec:onnotes" class="doc_sec"><span class="doc_order">24</span><span>Adding notes to a document</span></h1><p class="doc_par">Markup languages such as <span class="doc_caps">LaTeX</span>, whose roots stem from page-oriented designs, have the concept of a <i class="doc_emph">footnote</i>. <span class="doc_caps">lambtex</span> is targeted at web publishing, a domain where the concept of a document being composed of individual pages is not meaningful. For this reason, <span class="doc_caps">lambtex</span>'s equivalent concept is that of notes attached to the end of the document.</p><p class="doc_par">A note is declared via the environment command <code class="doc_mono">note</code>. Notes can of course be labelled, and may be referenced from anywhere in the document via the simple command <code class="doc_mono">\see</code>. The latter takes at least one primary parameter, and therefore you may reference multiple notes simply by providing additional primary parameters.</p><p class="doc_par">One important feature to remember is that the location where the note is declared is <b class="doc_bold">not</b> the same as where it will be appear in the rendered document (for this reason, notes are termed <i class="doc_emph">ghost blocks</i>). Instead, all notes will be printed together wherever the simple commands <code class="doc_mono">\notes</code> or <code class="doc_mono">\rawnotes</code> are declared (the sole difference between the two is that <code class="doc_mono">\notes</code> will also create an eponymously named unordered section, just like <a class="doc_lnk" href="#doc:m:sec:thenotes">the one present</a> in this manual, whereas <code class="doc_mono">\rawnotes</code> simply dumps a listing of the document's notes, without any heading). Note that the “ghostly” character of note blocks allows them to be declared anywhere in the document, a handy feature if you wish to keep a note declaration close to the place where it is declared.</p><p class="doc_par">The sample code below illustrates a note being referenced inside a paragraph and being defined afterwards. The example concludes with the simple command <code class="doc_mono">\notes</code> requesting the printing of the eponymous section together with the defined note.</p><div class="doc_src_block doc_class_boxed"><pre class="doc_src_code">
<code class="doc_src_line doc_src_dummy"></code>
<code class="doc_src_line">This is a normal\see{note:example} paragraph that references</code>
<code class="doc_src_line">an end-document note.  You may read all notes declared in the</code>
<code class="doc_src_line">document \mref{sec:notes}{in this section}.</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">\begin[note:example]{note}</code>
<code class="doc_src_line">And by 'normal' we mean 'not normal'.</code>
<code class="doc_src_line">\end{note}</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">\notes[sec:notes]</code>
<code class="doc_src_line doc_src_dummy"></code></pre></div><h1 id="doc:m:sec:onbiblio" class="doc_sec"><span class="doc_order">25</span><span>Adding a bibliography</span></h1><p class="doc_par">Similarly to notes, bibliographic entries are also ghost blocks. Therefore, you may declare them anywhere in the document, and they will only be printed when you issue either of the simple commands <code class="doc_mono">\bibliography</code> or <code class="doc_mono">\rawbibliography</code>. The former version is preferred, as it automatically takes care of creating also a section heading. The latter version simply dumps the contents of the bibliography.</p><p class="doc_par">Each individual bibliographic entry can take either of two forms: a long form or a short form. The long form is contained within an environment command <code class="doc_mono">lbib</code>, which itself accepts three sub-blocks, defined by the simple commands <code class="doc_mono">\who</code>, <code class="doc_mono">\what</code>, and <code class="doc_mono">\where</code>. These blocks are used for defining the author, the title, and the location (journal, proceedings, web page) of the bibliographic reference, respectively. The short form is defined by the simple command <code class="doc_mono">\sbib</code>, which takes inline text as the mandatory parameter.</p><p class="doc_par">The code below illustrates the declaration of two bibliographic entries, one long and one short. Note that the entries can be referenced by the simple command <code class="doc_mono">\cite</code>. Also, and in similarity to the command <code class="doc_mono">\see</code>, it is possible to reference multiple entries with a single invocation of <code class="doc_mono">\cite</code>, since this command accepts multiple primary parameters.</p><div class="doc_src_block doc_class_boxed"><pre class="doc_src_code">
<code class="doc_src_line doc_src_dummy"></code>
<code class="doc_src_line">Lambtex is largely inspired by LaTeX\cite{bib:latex},</code>
<code class="doc_src_line">and is available in the Lambdoc library\cite{bib:lambdoc}.</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">\begin[bib:latex]{lbib}</code>
<code class="doc_src_line">\who{Leslie Lamport}</code>
<code class="doc_src_line">\what{LaTeX: a Document Preparation System (2\sup{nd} edition)}</code>
<code class="doc_src_line">\where{Addison-Wesley Professional, 1994, ISBN 0-201-52983-1}</code>
<code class="doc_src_line">\end{lbib}</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">\sbib[bib:lambdoc]{\link{http://lambdoc.forge.ocamlcore.org/}}</code>
<code class="doc_src_line doc_src_dummy"></code></pre></div><p class="doc_par">Whereas <span class="doc_caps">BibTeX</span><span class="doc_cite">[<a class="doc_lnk" href="#doc:m:bib:bibtex">5</a>]</span> offers a very rich set of tags for bibliographic entries (author, title, journal volume, page numbers, conference location, etc), <span class="doc_caps">lambtex</span> limits this set to only three main tags, even when using the long form <code class="doc_mono">lbib</code>. Those familiar with <span class="doc_caps">BibTeX</span> may feel constrained by this paucity. However, one must take into account that <span class="doc_caps">lambtex</span> was designed with the web as a foremost application area. In this context, one can have satisfactory — in the sense that they are readily accessible — bibliographic entries based solely on a hyperlink. The long form's <code class="doc_mono">\where</code> command can therefore be used for linking to an external web resource, or if not available online, to provide all the miscelaneous information required to locate the resource in “dead tree world”. In fact, most bibliography needs in the web domain are satisfied completely by the short form <code class="doc_mono">\sbib</code>.</p><h1 id="doc:m:sec:onappendix" class="doc_sec"><span class="doc_order">26</span><span>Creating an appendix</span></h1><p class="doc_par">Large document typically have fragments that do not fit into the main flow. In many cases, these fragments can satisfactorily be included as notes (remember <a class="doc_lnk" href="#doc:m:sec:onnotes">Section&#xa0;24</a>). In other situations, however, it may make more sense to attach them as appendices to the main document. In <span class="doc_caps">lambtex</span>, creating an appendix is simply a matter of issueing the simple parameterless command <code class="doc_mono">\appendix</code>. Besides declaring an unordered part of the same name, this command also marks all subsequent sections as belonging to the appendix. This means that an appendiced section is declared the usual way, via the command <code class="doc_mono">\section</code> (the same applies to sub-sections and sub-sub-sections, of course). The only distinguishing aspect that makes it an appendiced section is being declared after <code class="doc_mono">\appendix</code>.</p><p class="doc_par">You can see an example of appendiced sections in this very manual. Note how all sections declared after the <a class="doc_lnk" href="#doc:m:part:theappendix">appendix marker</a> are automatically ordered using alphabetic characters instead of numbers, as per the usual convention. Smart references produced by command <code class="doc_mono">\sref</code> automatically adjust as well — yet another reason why you should avoid its “dumb” counterpart <code class="doc_mono">\dref</code>.</p><h1 id="doc:m:sec:macros" class="doc_sec"><span class="doc_order">27</span><span>Macros</span></h1><p class="doc_par"><span class="doc_caps">lambtex</span> offers limited macro functionality. Macros provide simple textual replacement, possibly parameterised. Note that these are not full-blown programming constructs, being instead aimed at reducing boilerplate and ensuring consistent formatting of common text patterns.</p><p class="doc_par">Before being used, a macro must be declared via the simple command <code class="doc_mono">\newmacro</code>. This command takes three mandatory primary parameters: the name of the macro, the number of arguments, and an inline sequence containing the text of the macro. Macro names must obviously be unique and not overlap with the names of built-in commands, but they live in their own private namespace. Moreover, and similarly to boxouts and theorems, the name must begin with a lowercase Roman letter and be followed by any combination of lowercase Roman letters, digits, and the character '<code class="doc_mono">_</code>' (underscore).</p><p class="doc_par">Should the macro take any arguments, these can be referenced from inside the macro text by the alias <code class="doc_mono">\arg{<i class="doc_emph">num</i>}</code>, where the <code class="doc_mono"><i class="doc_emph">num</i></code> between curly brackets is an integer indicating the argument number. Obviously, a macro with <span class="doc_math_inl"><math
xmlns="http://www.w3.org/1998/Math/MathML"
><mi
>n</mi
></math
></span> arguments may not reference an argument <span class="doc_math_inl"><math
xmlns="http://www.w3.org/1998/Math/MathML"
><mrow
><mi
>n</mi
><mo
lspace="0.222em"
rspace="0.222em"
>+</mo
><mn
>1</mn
></mrow
></math
></span> or higher. Moreover, arguments are expanded as inline sequences.</p><p class="doc_par">Wherever an inline sequence is accepted, a macro named <code class="doc_mono">name</code> can be invoked via the simple command <code class="doc_mono">\name</code>. The invocation of the macro causes the macro's text to be inserted at invocation point. Should the macro have any arguments, these must follow the macro's name immediately, being each one bracketed individually. Therefore, the invocation of macro <code class="doc_mono">name</code> with arguments <code class="doc_mono">inline1</code> and <code class="doc_mono">inline2</code> is done with <span class="doc_mbox"><code class="doc_mono">\name{inline1}{inline2}</code></span>. Note that because macros can be invoked wherever an inline sequence is accepted and the text of a macro is an inline sequence itself, it follows that macros may invoke other macros. However, because a macro must be declared before being invoked, mutual recursion is not allowed. Moreover, a macro may not invoke itself either. These restrictions are in place to ensure that macro expansion always terminates.</p><p class="doc_par">While token concatenation with parameterised macros is straightforward, you may wonder how it can be achieved with parameterless macros. To illustrate this issue, suppose you have defined a macro <code class="doc_mono">super</code> that expands to the text <i class="doc_emph">“super”</i>. Now, you wish to concatenate the invocation of this macro with the text <i class="doc_emph">“market”</i>. However, entering <code class="doc_mono">\super market</code> produces an unwanted space, whereas <code class="doc_mono">\supermarket</code> produces an error, since the macro <code class="doc_mono">supermarket</code> is undefined. Note that if the macro had any arguments this problem would be moot, since the brackets naturally delimitate the macro name. Therefore one solution is to always declare macros with at least one parameter, even if it is a dummy that can be discarded. There is however a better alternative, one which takes advantage of the fact that all commands accept (at least) an empty sequence as extra parameters: simply put <code class="doc_mono">&lt;</code> <code class="doc_mono">&gt;</code> after the macro name. Concatenation in this example can thus be achieved by entering <span class="doc_mbox"><code class="doc_mono">\super&lt;</code> <code class="doc_mono">&gt;market</code></span>.</p><p class="doc_par">Let us now consider a full example of macro declaration. We wish to define a macro <code class="doc_mono">author</code> that when invoked expands to the full name of an author. We also define a macro named <code class="doc_mono">greet</code> that takes two arguments and produces a greeting. These two macros are then used in a small sample document. This is the <span class="doc_caps">lambtex</span> source:</p><div class="doc_src_block doc_class_boxed"><pre class="doc_src_code">
<code class="doc_src_line doc_src_dummy"></code>
<code class="doc_src_line">\newmacro{author}{0}{John McAuthor}</code>
<code class="doc_src_line">\newmacro{greet}{2}{Greetings \bold{\arg{1}}, and welcome to \arg{2}}</code>
<code class="doc_src_line"></code>
<code class="doc_src_line">It was then that \author reached his destination.  The gatekeeper said,</code>
<code class="doc_src_line">``\greet{\author}{this land}'', and there was much rejoicing.</code>
<code class="doc_src_line doc_src_dummy"></code></pre></div><p class="doc_par">And this is the resulting output:</p><div class="doc_subpage"><p class="doc_par">It was then that John McAuthor reached his destination. The gatekeeper said, “Greetings <b class="doc_bold">John McAuthor</b>, and welcome to this land”, and there was much rejoicing.</p></div><p class="doc_par">Note that the arguments to a macro are inline text, and thus it is possible for the argument to consist of the invocation of a macro. On the other hand, macros cannot be used to replace non-inline sequences of a command.</p><h1 id="doc:a:13" class="doc_sec"><span class="doc_order">28</span><span>Concluding remarks</span></h1><p class="doc_par">You are now familiar with the all the features available in the <span class="doc_caps">lambtex</span> markup language. We hope you will find it rich enough to cover your web publishing needs, while still being simple enough to dispense a significant investment of time learning it.</p><p class="doc_par">We advise that you peruse the appendices attached to this manual. There you can find some reference material that did not fit into the flow of the main body of the document. <a class="doc_lnk" href="#doc:m:sec:structure">Appendix&#xa0;A</a>, for example, discusses at length the structure of the <span class="doc_caps">lambtex</span> documents, while <a class="doc_lnk" href="#doc:m:sec:synonyms">Appendix&#xa0;B</a> summarises all command synonyms available, and <a class="doc_lnk" href="#doc:m:sec:parameters">Appendix&#xa0;C</a> covers all you need to know concerning optional arguments. Finally, unless you are writing about <span class="doc_caps">lambtex</span> itself, there is little chance you will need the information contained in <a class="doc_lnk" href="#doc:m:sec:order">Appendix&#xa0;D</a>. But if you do, it focuses on the somewhat arcane aspects concerning numbering in sub-pages.</p><h1 id="doc:m:part:theappendix" class="doc_part"><span>Appendix</span></h1><h1 id="doc:m:sec:structure" class="doc_sec"><span class="doc_order">A</span><span>The structure of <span class="doc_caps">lambtex</span> documents</span></h1><p class="doc_par">We described a <span class="doc_caps">lambtex</span> document as being composed of a list of blocks, with some of these blocks being themselves composed of other blocks. We have, however, glossed over some of the restrictions imposed on this structure. The goal of this section is therefore to rectify that omission by providing a full account of the structure of a <span class="doc_caps">lambtex</span> document.</p><p class="doc_par">Blocks come in different types. Moreover, it is possible to establish a subtyping hierarchy that relates the different block types. <a class="doc_lnk" href="#doc:m:fig:hierarchy">Fig.&#xa0;2</a> illustrates that hierarchy, showing block types inside rounded rectangles. Concerning the subtyping relation, an arrow pointing from a source block into a target block should be interpreted as meaning that the source block is a subtype of the target, and dually, that the target is a supertype of the source. In practice, this means that a subtype block may be used in any circumstance where its supertype is allowed. However, the converse is not true.</p><div id="doc:m:fig:hierarchy" class="doc_wrapper doc_floatable doc_figure"><div class="doc_pic"><a href="hierarchy.png" class="doc_pic_lnk"><img src="hierarchy.png" alt="Hierarchy" class="doc_pic"/></a></div><div class="doc_caption doc_caption_long"><div class="doc_caption_aux"><h1 class="doc_caption_head">Fig.&#xa0;2:</h1><p class="doc_caption_body">The subtyping hierarchy for <span class="doc_caps">lambtex</span> blocks. An arrow pointing from a source block to a target block indicates that the source is a subtype of the target and is therefore accepted in any circumstances where the target would be accepted.</p></div></div></div><p class="doc_par">Note the list attached to each of the block types, which indicates the actual document blocks that belong to that type. An <i class="doc_emph">embeddable block</i>, for example, can be either a paragraph, an itemize, enumerate, or description list, a verse block, a block containing mathematics, etc. Notice that many blocks have a <i class="doc_emph"><code class="doc_mono">of</code> ...</i> declaration after their name; these blocks — termed <i class="doc_emph">recursive blocks</i> — are those whose contents are other blocks.</p><p class="doc_par">If a <span class="doc_caps">lambtex</span> document were unconstrained, one would expect a recursive block to be composed of a list of super blocks. Because super blocks sit at the top of the hierarchy, <b class="doc_bold">any</b> block can be used where a super block is allowed. Therefore, in an unconstrained scenario, it would be perfectly legal for a quotation block to be the parent of a section, or for an abstract block to include another. Needless to say, an unconstrained document would accommodate for pathological situations bearing no resemblance to any reasonable real-world documents. It is for this reason that a <span class="doc_caps">lambtex</span> document has a few constraints in place. As you shall see, these constraints are however fairly minor and still allow for very flexible documents.</p><p class="doc_par">In basic terms, documents are constrained by limiting the types of blocks accepted as children of recursive blocks. The exact subtype allowed for each recursive block is shown in the figure as an <i class="doc_emph"><code class="doc_mono">of</code> ...</i> declaration after the block name. Let us consider, for example, a quote block. It only allows a list of <i class="doc_emph">quotable blocks</i> as children. This means that you cannot quote a figure nor an abstract, but you can do so with any of the quotable blocks or subtypes (<i class="doc_emph">embeddable blocks</i>, namely). Furthermore, these rules apply to the entire descendant tree. This means that if an itemize block is the child of a quote block, then the most restricted rules of the parent apply also to the child's descendants. In this case that would mean that the itemize block would also only accept quotable blocks as children instead of its usually more permissive allowance of any <i class="doc_emph">listable block</i>. The exception to this rule is the <code class="doc_mono">subpage</code> block, which resets the hierarchy.</p><h1 id="doc:m:sec:synonyms" class="doc_sec"><span class="doc_order">B</span><span>Command synonyms</span></h1><p class="doc_par">For reference purposes, <a class="doc_lnk" href="#doc:m:tab:synonyms">Tab.&#xa0;7</a> lists all existing synonyms for both simple and environment commands (the former's name is prefixed by a backslash). Remember that in the case of environment commands, the same name must be used for the <code class="doc_mono">begin</code> and <code class="doc_mono">end</code> tags, even if they are synonyms.</p><div id="doc:m:tab:synonyms" class="doc_wrapper doc_floatable doc_table"><div class="doc_tab"><div class="doc_tab_aux"><table><thead class="doc_tgroup"><tr><td class="doc_cell_r">Canonical name</td><td class="doc_cell_l">Synonyms</td></tr></thead><tbody class="doc_tgroup"><tr><td class="doc_cell_r"><code class="doc_mono">\bold</code></td><td class="doc_cell_l"><code class="doc_mono">\strong</code>, <code class="doc_mono">\b</code></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\mono</code></td><td class="doc_cell_l"><code class="doc_mono">\tt</code></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\emph</code></td><td class="doc_cell_l"><code class="doc_mono">\em</code>, <code class="doc_mono">\i</code></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\item</code></td><td class="doc_cell_l"><code class="doc_mono">\li</code></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\link</code></td><td class="doc_cell_l"><code class="doc_mono">\a</code></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\paragraph</code></td><td class="doc_cell_l"><code class="doc_mono">\p</code></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\rule</code></td><td class="doc_cell_l"><code class="doc_mono">\hr</code></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\section</code></td><td class="doc_cell_l"><code class="doc_mono">\h1</code></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\subsection</code></td><td class="doc_cell_l"><code class="doc_mono">\h2</code></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\subsubsection</code></td><td class="doc_cell_l"><code class="doc_mono">\h3</code></td></tr></tbody><tbody class="doc_tgroup"><tr><td class="doc_cell_r"><code class="doc_mono">description</code></td><td class="doc_cell_l"><code class="doc_mono">dl</code></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">enumerate</code></td><td class="doc_cell_l"><code class="doc_mono">ol</code></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">itemize</code></td><td class="doc_cell_l"><code class="doc_mono">itemise</code>, <code class="doc_mono">ul</code></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">verbatim</code></td><td class="doc_cell_l"><code class="doc_mono">pre</code></td></tr></tbody></table></div></div><div class="doc_caption doc_caption_long"><div class="doc_caption_aux"><h1 class="doc_caption_head">Tab.&#xa0;7:</h1><p class="doc_caption_body">List of all available command synonyms.</p></div></div></div><h1 id="doc:m:sec:parameters" class="doc_sec"><span class="doc_order">C</span><span>Command parameters</span></h1><p class="doc_par">The typical simple command in <span class="doc_caps">lambtex</span> has one or two primary parameters enclosed between curly brackets. In addition, many commands (both simple and environment) accept also optional parameters that specify an ordering, a label, or any style information. When present, optional parameters may be specified in any order, as long as they precede any of the primary parameters. Moreover, each class of optional parameter is distinguished by the set of characters used for delimitation. Ordering parameters are enclosed in curved brackets, labelling parameters in square brackets, and style parameters between angle brackets.</p><p class="doc_par">Note that not all optional parameters are meaningful for all existing commands. This is especially the case for order and label parameters, which are available only for some commands. <a class="doc_lnk" href="#doc:m:tab:permlist">Tab.&#xa0;9</a> lists the classes accepted for each of all existing commands, both simple and environment ones. An exact definition of the terms used is shown in <a class="doc_lnk" href="#doc:m:tab:permdesc">Tab.&#xa0;8</a>.</p><div id="doc:m:tab:permdesc" class="doc_wrapper doc_floatable doc_table"><div class="doc_tab"><div class="doc_tab_aux"><table><thead class="doc_tgroup"><tr><td class="doc_cell_c">Permission</td><td class="doc_cell_l">Definition</td></tr></thead><tbody class="doc_tgroup"><tr><td class="doc_cell_c"><span class="doc_class_optional">≈</span></td><td class="doc_cell_l">The parameter is optional, but may not be empty if present.</td></tr><tr><td class="doc_cell_c"><span class="doc_class_mandatory">✔<sub class="doc_sub">ø</sub></span></td><td class="doc_cell_l">The parameter is mandatory, but it may be empty.</td></tr><tr><td class="doc_cell_c"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l">The parameter is altogether forbidden.</td></tr><tr><td class="doc_cell_c"><span class="doc_class_forbidden">✘<sub class="doc_sub">ø</sub></span></td><td class="doc_cell_l">The parameter is forbidden, unless it is empty.</td></tr></tbody></table></div></div><div class="doc_caption doc_caption_long"><div class="doc_caption_aux"><h1 class="doc_caption_head">Tab.&#xa0;8:</h1><p class="doc_caption_body">Definition of the various permissions. These terms are used in <a class="doc_lnk" href="#doc:m:tab:permlist">Tab.&#xa0;9</a>.</p></div></div></div><p class="doc_par">Note that it is always possible to specify empty extra parameters for any command. This is done so that token concatenation is possible for simple commands that take no primary parameters, as is often the case with user-defined macros. A practical application of this feature is described in <a class="doc_lnk" href="#doc:m:sec:macros">Section&#xa0;27</a>.</p><div id="doc:m:tab:permlist" class="doc_wrapper doc_floatable doc_table"><div class="doc_tab"><div class="doc_tab_aux"><table><thead class="doc_tgroup"><tr><td class="doc_cell_r">Command</td><td class="doc_cell_l">Order</td><td class="doc_cell_l">Label</td></tr></thead><tbody class="doc_tgroup"><tr><td class="doc_cell_r"><code class="doc_mono">\answer</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\appendix</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_optional">≈</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\arg</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\bibliography</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_optional">≈</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\body</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\bold</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\br</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\caps</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\cite</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\mono</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\del</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\dref</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\foot</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\glyph</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\head</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\ins</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\item</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\link</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono"><i class="doc_emph">\macro</i></code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\mbox</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\mref</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\notes</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_optional">≈</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\paragraph</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\part</code></td><td class="doc_cell_l"><a class="doc_lnk" href="#doc:m:sec:order"><span class="doc_class_forbidden">✘<sub class="doc_sub">ø</sub></span>/<span class="doc_class_mandatory">✔<sub class="doc_sub">ø</sub></span></a></td><td class="doc_cell_l"><span class="doc_class_optional">≈</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\picture</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\question</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\ranswer</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\rquestion</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\rule</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\section</code></td><td class="doc_cell_l"><a class="doc_lnk" href="#doc:m:sec:order"><span class="doc_class_forbidden">✘<sub class="doc_sub">ø</sub></span>/<span class="doc_class_mandatory">✔<sub class="doc_sub">ø</sub></span></a></td><td class="doc_cell_l"><span class="doc_class_optional">≈</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\see</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\span</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\sref</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\sub</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\subsection</code></td><td class="doc_cell_l"><a class="doc_lnk" href="#doc:m:sec:order"><span class="doc_class_forbidden">✘<sub class="doc_sub">ø</sub></span>/<span class="doc_class_mandatory">✔<sub class="doc_sub">ø</sub></span></a></td><td class="doc_cell_l"><span class="doc_class_optional">≈</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\subsubsection</code></td><td class="doc_cell_l"><a class="doc_lnk" href="#doc:m:sec:order"><span class="doc_class_forbidden">✘<sub class="doc_sub">ø</sub></span>/<span class="doc_class_mandatory">✔<sub class="doc_sub">ø</sub></span></a></td><td class="doc_cell_l"><span class="doc_class_optional">≈</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\subtitle</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\sup</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\title</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\toc</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_optional">≈</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\what</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\where</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">\who</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr></tbody><tbody class="doc_tgroup"><tr><td class="doc_cell_r"><code class="doc_mono">abstract</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">bib</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_optional">≈</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono"><i class="doc_emph">boxout</i></code></td><td class="doc_cell_l"><a class="doc_lnk" href="#doc:m:sec:order"><span class="doc_class_forbidden">✘<sub class="doc_sub">ø</sub></span>/<span class="doc_class_mandatory">✔<sub class="doc_sub">ø</sub></span></a></td><td class="doc_cell_l"><span class="doc_class_optional">≈</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">decor</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">description</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">enumerate</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">equation</code></td><td class="doc_cell_l"><a class="doc_lnk" href="#doc:m:sec:order"><span class="doc_class_forbidden">✘<sub class="doc_sub">ø</sub></span>/<span class="doc_class_mandatory">✔<sub class="doc_sub">ø</sub></span></a></td><td class="doc_cell_l"><span class="doc_class_optional">≈</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">figure</code></td><td class="doc_cell_l"><a class="doc_lnk" href="#doc:m:sec:order"><span class="doc_class_forbidden">✘<sub class="doc_sub">ø</sub></span>/<span class="doc_class_mandatory">✔<sub class="doc_sub">ø</sub></span></a></td><td class="doc_cell_l"><span class="doc_class_optional">≈</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">itemize</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">mathmlblk</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">mathtexblk</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">note</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_optional">≈</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">quote</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">printout</code></td><td class="doc_cell_l"><a class="doc_lnk" href="#doc:m:sec:order"><span class="doc_class_forbidden">✘<sub class="doc_sub">ø</sub></span>/<span class="doc_class_mandatory">✔<sub class="doc_sub">ø</sub></span></a></td><td class="doc_cell_l"><span class="doc_class_optional">≈</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">pull</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">qanda</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">source</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">subpage</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">table</code></td><td class="doc_cell_l"><a class="doc_lnk" href="#doc:m:sec:order"><span class="doc_class_forbidden">✘<sub class="doc_sub">ø</sub></span>/<span class="doc_class_mandatory">✔<sub class="doc_sub">ø</sub></span></a></td><td class="doc_cell_l"><span class="doc_class_optional">≈</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">tabular</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono"><i class="doc_emph">theorem</i></code></td><td class="doc_cell_l"><a class="doc_lnk" href="#doc:m:sec:order"><span class="doc_class_forbidden">✘<sub class="doc_sub">ø</sub></span>/<span class="doc_class_mandatory">✔<sub class="doc_sub">ø</sub></span></a></td><td class="doc_cell_l"><span class="doc_class_optional">≈</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">verbatim</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr><tr><td class="doc_cell_r"><code class="doc_mono">verse</code></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td><td class="doc_cell_l"><span class="doc_class_forbidden">✘</span></td></tr></tbody></table></div></div><div class="doc_caption doc_caption_long"><div class="doc_caption_aux"><h1 class="doc_caption_head">Tab.&#xa0;9:</h1><p class="doc_caption_body">The permissions associated with the various <span class="doc_caps">lambtex</span> commands for order and label optional parameters. Note that simple commands are shown prefixed with a backslash, whereas environment commands are enclosed inside brackets. Within each category, commands are shown alphabetically. Furthermore, the commands <code class="doc_mono"><i class="doc_emph">\macro</i></code>, <code class="doc_mono"><i class="doc_emph">boxout</i></code> and <code class="doc_mono"><i class="doc_emph">theorem</i></code> are shown in italics because the actual command name is user-defined.</p></div></div></div><h1 id="doc:m:sec:order" class="doc_sec"><span class="doc_order">D</span><span>Notes on ordering</span></h1><p class="doc_par">This section applies to those blocks that may have an associated ordering, namely wrapper blocks, sectional blocks, and the custom blocks (boxouts and theorems). Recall that there are four elements in <span class="doc_caps">lambtex</span> that are categorised as wrappers: equations, printouts, tables, and figures. As for sectional blocks, these are the ones that produce parts, sections, sub-sections, and sub-sub-sections. There are some special — though as you shall see based on common sense — rules that must be followed concerning the order parameter and the hyperlinking of blocks with associated ordering, particularly in the context of sub-pages. The rules are as follows:</p><ol class="doc_enumerate"><li class="doc_item"><p class="doc_par">Only numbered elements may be referred to using <code class="doc_mono">\dref</code> and <code class="doc_mono">\sref</code> commands:</p><p class="doc_par doc_class_noindent">Unless the user explicitly demanded an empty ordering, sectional commands and wrappers have by default a number. In the case of custom environments, the situation varies.</p><p class="doc_par">It makes sense that the hyperlinking commands that are supposed to produce a number should only be used with numbered wrappers, numbered sectional blocks, or numbered custom environments. These commands are <code class="doc_mono">\dref</code> and <code class="doc_mono">\sref</code>. On the other hand, because <code class="doc_mono">\mref</code> does not output a number, it is always allowed.</p></li><li class="doc_item"><p class="doc_par">You must explicitly provide a manual ordering for sub-paged wrappers, sectional blocks, or custom blocks:</p><p class="doc_par doc_class_noindent">A sub-paged element is one that is declared inside a <code class="doc_mono">subpage</code> block (see <a class="doc_lnk" href="#doc:m:sec:subpage">Section&#xa0;15</a>). Because they lie outside the main flow of the document, these elements are not automatically numbered. You must therefore explicitly provide them with an ordering parameter by inserting the numbering between parentheses. Specifying an empty ordering is of course also allowed.</p></li><li class="doc_item"><p class="doc_par">You may not provide a manual ordering for wrappers, sectional blocks, or custom blocks defined outside a sub-page:</p><p class="doc_par doc_class_noindent">This rule is complementary to the previous one. Because these blocks are numbered automatically by <span class="doc_caps">lambtex</span> when present in the main document, you may not interfere with that automatism by providing an explicit ordering. Note, however, that an empty ordering is always allowed.</p></li></ol><h1 id="doc:a:14" class="doc_part"><span>Backmatter</span></h1><h1 id="doc:m:sec:thenotes" class="doc_sec"><span>Notes</span></h1><ol class="doc_notes"><li id="doc:m:note:commands" class="doc_note"><span class="doc_note_head">(1)</span><div class="doc_note_body"><p class="doc_par">As stated, any given command may either be expressed by the simple notation or as an environment. This should be interpreted an exclusive-<span class="doc_caps">or</span> condition, meaning that no command exists that can be expressed as both. However, the choice of adopting one or the other notation was not an arbitrary one. Due to its syntactic terseness, the simple notation was preferred. The more verbose environment notation was chosen only for those commands that satisfied at least one of the two following conditions:</p><ul class="doc_itemize"><li class="doc_item"><p class="doc_par">The command may be the parent of at least one block-level element.</p></li><li class="doc_item"><p class="doc_par">The command declares a verbatim-like environment using the <span class="doc_caps">heredoc</span> technique for delimitation (see <a class="doc_lnk" href="#doc:m:sec:verbatim">Section&#xa0;10</a> for an example).</p></li></ul></div></li><li id="doc:m:note:optional" class="doc_note"><span class="doc_note_head">(2)</span><div class="doc_note_body"><p class="doc_par">While the qualifier <i class="doc_emph">typically</i> implies a degree of uncertainty concerning the optionality of these parameters, in practice you may treat them as truly optional. The qualifier exists because there is one (and only one!) exception, which applies to environments not normally used in regular documents. Namely, inside sub-pages the order parameter is mandatory for a number of blocks (see <a class="doc_lnk" href="#doc:m:sec:order">Appendix&#xa0;D</a> for details).</p></div></li><li id="doc:m:note:ampersand" class="doc_note"><span class="doc_note_head">(3)</span><div class="doc_note_body"><p class="doc_par">Note that in most practical situations you can get away with inputting an ampersand directly without escaping. This is because the scanner will only interpret an ampersand as the beginning of an entity declaration if it is immediately followed by an alphabetic or numeric sequence terminated by a semicolon. If it is not, then the ampersand is interpreted as plain text.</p></div></li><li id="doc:m:note:links" class="doc_note"><span class="doc_note_head">(4)</span><div class="doc_note_body"><p class="doc_par">The <span class="doc_caps">xhtml</span> standard forbids nested links. Curiously enough, however, the <span class="doc_caps">w3c</span>'s own famous <a class="doc_lnk" href="http://validator.w3.org/">validator</a> is unable to detect such violations of the specification.</p></div></li><li id="doc:m:note:meta" class="doc_note"><span class="doc_note_head">(5)</span><div class="doc_note_body"><p class="doc_par">This is a meta-note, a note about notes. It is used to demonstrate the declaration of notes.</p></div></li></ol><h1 id="doc:m:sec:thebiblio" class="doc_sec"><span>Bibliography</span></h1><ol class="doc_bibs"><li id="doc:m:bib:latex" class="doc_bib"><span class="doc_bib_head">[1]</span><p class="doc_bib_body"><span class="doc_bib_author">Leslie Lamport</span><span class="doc_bib_title">LaTeX: a Document Preparation System (2<sup class="doc_sup">nd</sup> edition)</span><span class="doc_bib_resource">Addison-Wesley Professional, 1994. ISBN 0-201-52983-1.</span></p></li><li id="doc:m:bib:lambdoc" class="doc_bib"><span class="doc_bib_head">[2]</span><p class="doc_bib_body"><span class="doc_bib_short"><a class="doc_lnk" href="http://lambdoc.forge.ocamlcore.org/">http://lambdoc.forge.ocamlcore.org/</a></span></p></li><li id="doc:m:bib:mathml" class="doc_bib"><span class="doc_bib_head">[3]</span><p class="doc_bib_body"><span class="doc_bib_short"><a class="doc_lnk" href="bah">http://www.w3.org/Math/</a></span></p></li><li id="doc:m:bib:tex" class="doc_bib"><span class="doc_bib_head">[4]</span><p class="doc_bib_body"><span class="doc_bib_author">Donald E. Knuth</span><span class="doc_bib_title">The TeXbook (Computers and Typesetting, Volume A)</span><span class="doc_bib_resource">Addison-Wesley, 1984. ISBN 0-201-13448-9.</span></p></li><li id="doc:m:bib:bibtex" class="doc_bib"><span class="doc_bib_head">[5]</span><p class="doc_bib_body"><span class="doc_bib_author">Oren Patashnik</span><span class="doc_bib_title">BibTeXing</span><span class="doc_bib_resource"><a class="doc_lnk" href="blah">http://www.ctan.org/get/biblio/bibtex/contrib/doc/btxdoc.pdf</a></span></p></li></ol></div></body></html>
