The lambtex Manual

Dario Teixeira

June 2016

Table of Contents

lambtex is a document description language. It is largely inspired by LaTeX[1], both in its syntax and in the approach taken for the description of documents. In basic terms, the source for a lambtex document is composed of plain utf-8 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. lambtex 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.

This manual is divided into two parts: a lambtex tutorial and an appendix. 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.

lambtex tutorial

1 The anatomy of lambtex documents

A lambtex 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.

Many blocks are composed of inline text. 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 block-level and inline-level elements in a lambtex document.

Inline-level elements are declared by simple commands, while block-level elements may be declared by either simple or environment commands(1). The former take the generic shape \command{...} , 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 \begin{command} , while the final tag is \end{command} .

Besides the (normally mandatory) primary parameters, both simple and environment commands accept three other kinds of (usually optional(2)) 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, Tab. 1 lists all the classes of parameters and the characters used for enclosing them.

Markers Parameter Begin End Order ( ) Label [ ] Style < > Primary { } Tab. 1: The four classes of parameters that may be given to lambtex 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.

Style parameters come in two varieties: key-value pairs and classnames. The former variety takes the form ' key=value ', 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 html classnames in a straightforward way, and are available for every command. If, for example, you were to provide ' important ' as the style parameter to a command, this would be interpreted as a classname declaration, and translated into the html classname ' doc_class_important ' (the prefix ' doc_class_ ' 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 ' - ' (dash), or the character ' _ ' (underscore).

Bear in mind that lambtex is agnostic on the validity and semantics of each command/classname combination. Nevertheless, lambdoc — the library that provides lambtex support for applications — does have facilities for restricting the set of acceptable command/classname combinations. Therefore, you may find yourself using lambtex 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 css shipped with lambdoc includes declarations for the most common customisations. These are described in detail in the section that describes each command.

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 ' , ' (comma) may be given.

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.

2 Paragraph blocks

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 \paragraph or its synonym \p . Should you choose the simple command, the paragraph contents are to be specified inside the mandatory curly brackets. Consider thus the following lambtex source fragment:

This is the first example of a paragraph. Note that it is composed of inline text. Lines can be broken at any point, because a paragraph is only terminated by a blank line. \br It is however possible to manually insert a line break without terminating the paragraph. \p{There is also a simple command that allows the explicit declaration of a paragraph.}

The result produced by the composer is as follows:

This is the first example of a paragraph. Note that it is composed of inline text. Lines can be broken at any point, because a paragraph is only terminated by a blank line.

It is however possible to manually insert a line break without terminating the paragraph. There is also a simple command that allows the explicit declaration of a paragraph.

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 \br simple command, as demonstrated.

Using the command \paragraph (or its synonym \p ) 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.

The default css shipped with lambdoc supports three style customisations for paragraphs. The associated classnames are initial , indent , and noindent . The first declares that the first letter of the paragraph should be rendered as an initial. 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 indent classname as a style parameter, you are declaring that the paragraph should always be indented regardless of context. Similarly, the noindent classname indicates that the paragraph should not be indented no matter what.

3 Formatting inline text

As shown by Tab. 2, lambtex 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 — 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 \bold you can also just type \b .

Command Example \bold{inline} You can make some passages be bold.

(Synonyms: \strong and \b ) \emph{inline} Here's another way to emphasise text.

(Synonyms: \em and \i ) \mono{inline} You can also imitate a typewriter .

(Synonym: \tt ) \caps{inline} lambtex supports text in small-caps. \ins{inline} Sometimes it's very handy to insert new text. \del{inline} You may also fix annoying incorrect passages. \sup{inline} The 1st of January has a superscript. \sub{inline} H 2 O requires a subscript. \mbox{inline} This inline sequence should not be split across lines. \span{inline} You may create spans with custom semantics. \code{raw} You can use syntax-highlighted code like type t = Alpha | Beta in an inline context. See Section 11 for details. Tab. 2: 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.

While most commands listed in the table above should have a straightforward application, a few clarifying words concerning \span are in order. This command translates directly into an xhtml span element, and exists for the sole purpose of associating a span of text with a custom semantic meaning beyond those listed in Tab. 2.

4 Special characters

lambtex allows the direct use of html entities via the same notation used in html. More precisely, entities are to be enclosed between the characters ' & ' (ampersand) and ' ; ' (semicolon), and may be specified by the so-called character entity reference (ie, the entity's name), or by numeric character reference (ie, a unicode code point in decimal or hexadecimal notation). As an example, if the euro symbol ' € ' is not readily available in your keyboard, you may enter it in either of the following three manners:

Name Decimal Hexadecimal € € €

The reader will have noted that lambtex must interpret the character ' & ' (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 lambtex, and as such also require a special escaping sequence. These characters are ' \ ' (backslash), ' { ' (opening curly bracket), ' } ' (closing curly bracket), and ' | ' (pipe). The character used for escaping is the backslash, which means that displaying an ampersand, for example, is achieved with \& . Another option in this particular case is of course to use the & html entity(3).

Besides individual characters, there are also some multi-character sequences that are interpreted differently by lambtex. Tab. 3 lists all of them. Remember to use the escape character if you wish to input any of these sequences literally.

Sequence Translation $$ Delimiter for inline TeX mathematics --- Typographic em-dash -- Typographic en-dash `` Opening double quotes '' Closing double quotes Tab. 3: Special character sequences and their lambtex interpretation. Remember to use the backslash for escaping if you wish to input any of these sequences verbatim. Also, see Section 13 for details about entering mathematics.

What if the glyph you wish to enter is not part of the unicode character set? The solution in this case is to declare an inline image; this feature is covered in detail in Section 14.1.

5 Hyperlinks to external resources

The simple command \link (or its synonym \a ) allows the creation of hyperlinks into any external resource. It takes the form \link{uri}{inline} , where uri is the raw text containing the address (uri) of the target, and inline 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!(4)

Note that in the preceeding paragraph, the sequence uri is described as raw 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 ' } ' is interpreted specially. Escaping is also possible, and thus the backslash character is also special.

lambtex supports also internal targets and hyperlinks. These are discussed in Section 17.

6 List environments

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 lambtex come in three varieties: ordered, unordered, and description lists. These are declared using the environment commands enumerate , itemize , and description , respectively. As shown by the following lambtex source, items in ordered and unordered lists must be preceded by the parameterless simple command \item . As for description lists, each item must be preceded also by the simple command \item . 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 Appendix A for a detailed description concerning the structure of lambtex documents). Consider thus the following source:

Here is a list of small furry mammals: \begin{itemize} \item Cat \item Some dog breeds: \begin{description} \item{poodle:} Small dogs kept for company \item{greyhound:} Running dogs \end{description} \item Various rodents ordered by size: \begin{enumerate} \item Capivara \item Rat \item Mouse \end{enumerate} \end{itemize}

The output generated by the composer is as follows:

Here is a list of small furry mammals: Cat

Some dog breeds: poodle: Small dogs kept for company greyhound: Running dogs

Various rodents ordered by size: Capivara Rat Mouse



For the sake of brevity and for compatibility with html habits, you may also use the synonyms ol , ul , dl , and \li , for enumerate , itemize , description , and \item , respectively. Moreover, the British spelling itemise may be used for ordered lists. However, the start and end tags must still match: though, for example, ol is a synonym for enumerate , if you start an ordered list with \begin{ol} you must terminate it with \end{ol} .

The default css shipped with lambtex 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 \begin{itemize} or \begin{enumerate} commands. Below is the list of classnames available out-of-the-box for itemize environments:

Value Type of bullet disc A filled circle. circle An empty circle. square A square. none Ommit the bullet altogether.

And the corresponding list for itemize environments:

Value Type of numbering decimal Decimal numbers. lower-roman Lower-case Roman numerals. upper-roman Upper-case Roman numerals. lower-alpha Lower-case letters in the Latin alphabet. upper-alpha Upper-case letters in the Latin alphabet. none Ommit the numbering altogether.

7 Q&A environments

Somewhat related to lists, Q&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 qanda , and expects a sequence of question and answer blocks, delimited by the simple commands \question and \answer , 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&A, there is an alternative to repeating it with each \question and \answer pair: you may instead use the parameterless simple commands \rquestion and \ranswer . These simply reuse the sequence declared in the previous question or answer. The following example illustrates the pattern:

\begin{qanda} \question{Egg Gazette:} On which side of the egg opening debate are you? \answer{John McAuthor:} I sustain that eggs should be opened by their small-end, of course. \question{EG:} What's your opinion on the contrarian position, that eggs should be opened by their large-end? \answer{JM:} Sheer madness! \rquestion Could you elaborate? \ranswer I don't believe that to be necessary; the reasons are self-evident. \end{qanda}

The generated output is as follows:

Egg Gazette: On which side of the egg opening debate are you? John McAuthor: I sustain that eggs should be opened by their small-end, of course. EG: What's your opinion on the contrarian position, that eggs should be opened by their large-end? JM: Sheer madness! Could you elaborate? I don't believe that to be necessary; the reasons are self-evident.

8 Verse environments

The environment verse 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 \br . Therefore, if you wished to typeset the first couple of stanzas from Virgil's Aeneid, this would be the lambtex source:

\begin{verse} Arma virumque cano, Troiae qui primus ab oris \br Italiam, fato profugus, Laviniaque venit \br litora, multum ille et terris iactatus et alto \br vi superum saevae memorem Iunonis ob iram; \br multa quoque et bello passus, dum conderet urbem, \br inferretque deos Latio, genus unde Latinum, \br Albanique patres, atque altae moenia Romae. Musa, mihi causas memora, quo numine laeso, \br quidve dolens, regina deum tot volvere casus \br insignem pietate virum, tot adire labores \br impulerit. Tantaene animis caelestibus irae? \br \end{verse}

The result would be the following:

Arma virumque cano, Troiae qui primus ab oris

Italiam, fato profugus, Laviniaque venit

litora, multum ille et terris iactatus et alto

vi superum saevae memorem Iunonis ob iram;

multa quoque et bello passus, dum conderet urbem,

inferretque deos Latio, genus unde Latinum,

Albanique patres, atque altae moenia Romae. Musa, mihi causas memora, quo numine laeso,

quidve dolens, regina deum tot volvere casus

insignem pietate virum, tot adire labores

impulerit. Tantaene animis caelestibus irae?



9 Quotations

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 quote environment, and may enclose not only plain text paragraphs, but also lists or any of the so-called quotable blocks, as Appendix A describes in greater detail. Consider thus the following lambtex source:

This is what you said: \begin{quote} Eggs should be opened by their large end. Any other method is heresy. It is therefore my opinion that John McAuthor is a heretic. \end{quote}

This is the output produced:

This is what you said: Eggs should be opened by their large end. Any other method is heresy. It is therefore my opinion that John McAuthor is a heretic.

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.

10 Verbatim environments

Like their LaTeX counterparts or the html pre element, verbatim environments allow the insertion of blocks where the text is shown as is, 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 ascii-art. Another application is to display text-only technical diagrams as commonly found on Internet rfcs, for example.

The command name for the verbatim environment is verbatim , and being an environment command the text must be enclosed between \begin{verbatim} and \end{verbatim} markers. The synonym pre may also be used. Below is an example of a diagram drawn using only ascii characters, and rendered using a verbatim environment:

N /|\ / | \ / | \ / | \ / | \ / | \ N '+' L /|\ | / | \ | / | \ | / | \ | L '+' L '3' | | '1' '2'

We say there is almost no interpretation of the contents of the verbatim environment because there is one exception. The string \end{verbatim} is used as the end marker, and therefore the lambtex 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 lambtex is reminescent of the heredoc approach used by other languages. Basically, the markers that delimit verbatim environments need only use verbatim as a prefix. The only condition for termination is that the end marker matches the begin marker. Therefore, to include the string \end{verbatim} within a verbatim environment, you can simply delimitate that environment with, for example, \begin{verbatim1} and \end{verbatim1} . Note that only lowercase Roman letters, digits, and the character ' _ ' (underscore) may be used as suffix characters.

The css shipped with lambtex defines a series of classnames for exclusive use with verbatim environments. These are mult0 , mult1 , and so forth until mult9 . The integer indicates a multiplying factor for the contents of the environment. For a factor of x , the actual scaling relative to normal size is given by 2 x . The default factor is 0, which corresponds to normal size. One common application of this feature is to display unicode characters as full-sized pictures. As an example, this is what the unicode snowman (code point U+2603) looks like with a multiplier of 7, corresponding to a font size 11.3 times larger than normal:

☃

In addition, the default css also allows floatation specifiers to be used with verbatim blocks. Floating specifiers take the form of classname style parameters ' center ', ' left ', and ' right '. 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 css float declarations.

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.

11 Presenting source-code

Section 3 briefly introduced the simple inline command \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 ' lang ', which allows the specification of the language used for syntax-highlighting.

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, lambtex 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 source , 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 lambtex source code, albeit without line numbers or syntax highlighting. Suppose thus you wish to pretty-print an OCaml fragment. You can declare a source-code environment the following way:

\begin<lang=caml>{source} type 'a tree = | Leaf | Node of 'a tree * 'a * 'a tree let rec count = function | Leaf -> 0 | Node (left, x, right) -> 1 + count left + count right \end{source}

Note that the source language is specified via an optional key-value style parameter ' lang '. Also, the same heredoc-like technique used for verbatim environments can be used in a source environment if you wish to include the string \end{source} 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 lambtex — we do eat our own dog food). As for the actual result produced by the composer, it is as follows:

type 'a tree = | Leaf | Node of 'a tree * 'a * 'a tree let rec count = function | Leaf -> 0 | Node ( left , x , right ) -> 1 + count left + count right

Another optional key-value style parameter accepted by source environments is ' nums '. It accepts a boolean value, and dictates whether line numbers should be added to the source code listing. Valid boolean values are ' true ', ' yes ' and ' on ' for truth value true and ' false ', ' no ' and ' off ' for truth value false. It defaults to false.

The css shipped with lambtex offers additional customisation options for the appearance of source environments. These are all available as classname style parameters, as follows:

' plain ' 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. ' boxed ' Declares that the source code listing should be shown inside a decorative box. Example: type 'a tree = | Leaf of 'a | Node of 'a tree * 'a tree let rec count_leaves = function | Leaf _ -> 1 | Node ( a , b ) -> count_leaves a + count_leaves b ' zebra ' Besides placing the source-code inside a decorative box, this style will in addition give a different background to even and odd numbered rows: type 'a tree = | Leaf of 'a | Node of 'a tree * 'a tree let rec count_leaves = function | Leaf _ -> 1 | Node ( a , b ) -> count_leaves a + count_leaves b ' console ' This style is appropriate if the code block should actually mimick the output from a command line console: dario@localhost:~/lambtex$ make lambcmd -f lambtex -t html -i sample.lambtex -o index.html dario@localhost:~/lambtex$ file index.html index.html: HTML document text

Finally, note that lambtex 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 printout environment, and is part of the advanced features of the language discussed in Section 21.

12 Tabular environments

Presenting data in a tabular format is indispensable for many classes of documents. With this in mind, lambtex offers a special tabular environment which allows you to format tables in a simple and concise way, while retaining most of the capabilities offered by LaTeX and xhtml tables.

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:

Name Phone Address John 123456 London Mary 234567 Paris Mark 345678 Moscow Jane 456789 Sydney

Inside a tabular environment, a row is terminated when the character ' | ' (pipe) is the last on a line of text; within each row, each cell must also be prefixed by the ' | ' character. This means that you'll need to escape it if you wish to display an actual pipe character.

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 \head , \body , and \foot 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 \body 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 css stylesheet will visibly separate each group.

The code below is the source for the tabular environment listed above. Note the use of the \head and \body commands to delineate row classes, and how the character ' | ' is used to separate cells and rows. Note also that all rows have the same number of columns. This is mandatory, though provisions exist for making a cell span multiple columns (see below).

\begin{tabular} \head | Name | Phone | Address | \body | John | 123456 | London | | Mary | 234567 | Paris | | Mark | 345678 | Moscow | | Jane | 456789 | Sydney | \end{tabular}

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 ' cols '. 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 ' cols=lll '. If, for example, you had four columns aligned respectively to the left, right, center, and left again, the style parameter would be ' cols=lrcl '. Consult Tab. 4 for a list of all available column specifiers.

Specifier Formatting l Column is left-aligned. L Column is left-aligned and strong. r Column is right-aligned. R Column is right-aligned and strong. c Column is centre-aligned. C Column is centre-aligned and strong. j Column is justified. J Column is justified and strong. Tab. 4: List of available column specifiers for tabular environments. A specifier tells lambtex how each column should be formatted.

Some tables may require more sophisticated formatting. The most common requirement is for multi-column cells, and lambtex does support them. This feature is enabled by a special syntax that allows the customisation of each individual cell. More precisely, the pipe character ' | ' that precedes each cell is optionally followed by an angle bracketed style parameter.

Recall that style parameters come in two varieties: classnames and key-value pairs. You may of course use the former to customise the css of an individual cell. As for the latter, cells offer a single option, whose key is named ' cell ', 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 Tab. 4; last and optional are the characters ' _ ' (underscore) and/or ' ^ ' (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 digit+ spec ( '_' | '^' | '_^' | '^_' )? .

This discussion would not be complete without the presentation of a complete example illustrating the application of advanced cell formatting. Consider thus the lambtex fragment below, whose output is displayed in Tab. 5. Besides the use of header, footer, and multiple body rows, also noteworthy are the cell style parameters cell=2c_ and cell=2c^ , which configure their corresponding cells to span two columns, be centered, and show a horizontal line below and above, respectively.

\begin<cols=rll>{tabular} \head | |<cell=2c_> Scientific name | | Common name | Genus | Species | \body | Wolf | \emph{Canis} | \emph{lupus} | | Cat | \emph{Felis} | \emph{catus} | | Lion | \emph{Panthera} | \emph{leo} | \body | English oak | \emph{Quercus} | \emph{robur} | | Cork oak | \emph{Quercus} | \emph{suber} | | European yew | \emph{Taxus} | \emph{baccata} | \foot | Common name | Genus | Species | | |<cell=2c^> Scientific name | \end{tabular}

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 table . This is part of the advanced features of the language, and is discussed in Section 21.

Scientific name Common name Genus Species Common name Genus Species Scientific name Wolf Canis lupus Cat Felis catus Lion Panthera leo English oak Quercus robur Cork oak Quercus suber European yew Taxus baccata Tab. 5: The classification of some common animals and plants. This table illustrates the use of the advanced formatting facilities that enable customisation of individual cells.

13 Mathematical formulas

lambtex also supports the inclusion of equations and mathematical formulas in a document. Mathematics are to be entered using either MathML[3] or the TeX[4] format. The former was chosen because an increasing number of tools has the ability to export MathML. As for the latter, it is the de facto standard for manually typing mathematical expressions.

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 \mathtexinl and \mathmlinl may be used for inputting mathematics in the TeX or MathML formats, respectively. For the sake of convenience, TeX mathematics may also be entered by delimiting them between the characters ' $$ '. Though lambtex 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 a x 2 + b x + c = 0 .

TeX and MathML mathematical expressions in a block context are specified via the mathtexblk and mathmlblk environments, respectively. Furthermore, because both these environments expect their content to be raw text that should be parsed verbatim, they accept the heredoc 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 TeX format, the code would be the following:

\begin{mathtexblk} x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a} \end{mathtexblk}

The equivalent Presentation MathML markup is listed below. Note that it is also acceptable to provide Content MathML instead of Presentation MathML. In either case, just make sure the markup conforms to version 2.0 of the MathML standard, and that the math top-level element that wraps the MathML contents is provided as part of the markup. These requirements also apply to the MathML markup specified in an inline context. On the other hand, giving an explicit namespace to the MathML markup is not necessary, since namespacing requirements are automatically taken care of.

\begin{mathmlblk} <math> <mrow> <mi>x</mi> <mo>=</mo> <mfrac> <mrow> <mo form="prefix">−</mo> <mi>b</mi> <mo>±</mo> <msqrt> <msup> <mi>b</mi> <mn>2</mn> </msup> <mo>−</mo> <mn>4</mn> <mo>⁢</mo> <mi>a</mi> <mo>⁢</mo> <mi>c</mi> </msqrt> </mrow> <mrow> <mn>2</mn> <mo>⁢</mo> <mi>a</mi> </mrow> </mfrac> </mrow> </math> \end{mathmlblk}

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, lambtex also supports named mathematical expressions that may be numbered and referenced from anywhere in a document. For that you need to wrap a mathtexblk or mathmlblk environment inside an equation block. This technique is part of the advanced features of the language and is discussed with greater detail in Section 21.

x = - b ± b 2 - 4 a c 2 a

14 Images

lambtex 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 unicode set, and is for this reason denoted as a glyph. The latter case includes images used as illustrations, diagrams, photographs, etc. These are known as pictures.

14.1 Glyphs

The simple command \glyph is used for inserting an image into an inline context. It takes the form \glyph{identifier}{alt}{title} , where identifier is the name of the glyph (typically the filename), and alt 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 title 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.

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.

14.2 Pictures

The insertion of block images into a document is done via the simple command \picture , which in its basic usage is identical to the afore described \glyph . Namely, it takes the form \picture{identifier}{alt}{title} , where identifier is the name of the picture (typically the filename), and alt 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 title consists also of raw text, but is optional.

The command \picture differs from \glyph 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!

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:

\picture{circle.png}{This is a circle}{Thank you for hovering!}

The size of the picture can be controlled by the optional key-value style parameter width . Its value is either auto 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 auto , 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 uri is that of the picture itself. This is useful, for example, for seeing at their full size pictures that were scaled down with the width parameter or that did not fit into the width of the page.

The default css shipped with lambtex offers an additional customisation options for pictures. As its name suggests, the classname style parameter ' frame ' 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 ' center ', ' left ', and ' right ' may also be used.

It is a common practice to add a numbered caption to a picture. To achieve this in lambtex you must wrap the picture block inside a figure , as described in Section 21.

15 Sub-pages

Another interesting lambtex feature is the ability to display child documents inside a framed block. These nested documents, termed sub-pages, are offered by the subpage 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 lambtex — they are indispensable.

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 Sections 24 and 25) declared inside a sub-page are still associated with the main document. Finally, take into consideration that lambtex 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 Section 16 and Section 21, respectively).

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 section on paragraph blocks.

\begin{subpage} This is the first example of a paragraph. Note that it is composed of inline text. Lines can be broken at any point, because a paragraph is only terminated by a blank line. \br It is however possible to manually insert a line break without terminating the paragraph. \p{There is also a simple command that allows the explicit declaration of a paragraph.} \end{subpage}

16 Parts and sections

lambtex supports three different levels of sectioning: sections, sub-sections, and sub-sub-sections. The simple commands used for declaring each one are \section , \subsection , and \subsubsection , respectively. These are automatically ordered by lambtex. 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 Appendix D for details).

In addition to sections, lambtex documents may also be divided into parts. 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 \part , and that it does not reset the section counter. In similarity to sections, parts can also be unordered.

Another common requirement associated with sectioning is the ability to refer to a given part or section in a document. With that in mind, lambtex allows you to label a given part or section declaration, and as described in the following section, 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:

\part{Prelude} \section{Introduction} For more details, please check Section \dref{sec:details}. \subsection[sec:details]{This is a sub-section} \subsubsection(){This is an unordered sub-sub-section} The quick brown fox jumps over the lazy brown dog.

The output produced by the lambtex composer is as follows:

I Prelude 1 Introduction For more details, please check Section 1.1. 1.1 This is a sub-section This is an unordered sub-sub-section The quick brown fox jumps over the lazy brown dog.

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 ' : ' (colon), ' - ' (dash), and ' _ ' (underscore). Also note that all labels share the same namespace; we recommend adopting the LaTeX custom of using a prefix indicating the target type. In the example above, the prefix sec: is used for the sectioning family of commands.

lambtex supports hyperlinks both to external resources and into targets in the same document. The former is provided by the already described simple command \link , whereas the latter relies on a set of different simple commands, each one tailored for a different use and/or kind of target. Tab. 6 lists all available hyperlinks commands, and the following source illustrates their use:

You can easily insert a link into an external resource such as \link{http://www.wikipedia.com/}{Wikipedia}. Internal links come into several guises: they can be references to notes\see{note:meta}; bibliographic references like those available in \caps{LaTeX}\cite{bib:latex}; pointers to labelled figures, tables, printouts, equations, or sections such as \mbox{Section \dref{sec:anatomy}}; smart references to those same elements such as \sref{sec:anatomy}; and finally, references where the order is not automatically added (for example, you may refer yet again \mref{sec:anatomy}{to that same section}).

The corresponding output of the composer is the following:

You can easily insert a link into an external resource such as Wikipedia. Internal links come into several guises: they can be references to notes(5); bibliographic references like those available in LaTeX[1]; pointers to labelled figures, tables, printouts, equations, or sections such as Section 1; smart references to those same elements such as Section 1; and finally, references where the order is not automatically added (for example, you may refer yet again to that same section).

Bear in mind that the use of the smart references offered by command \sref is strongly recommended over the manual references provided by command \dref . 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 \mbox command, or use the html 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.

On a related note, we recommend that \see and \cite commands not be separated from the preceding element by spaces. The default css stylesheet shipped with lambtex already adds a small margin, and by not having spaces you avoid the split across line breaks or the need to resort to the \mbox command or the nbsp html entity.

Finally, though lambtex offers no explicit support for subfigures, links towards them are accommodated via the optional inline sequence accepted by commands \dref and \sref . This inline sequence is appended to the link text, thus allowing you to specify a subfigure identifier (such as 'a', 'b', etc) when making a link to the subfigure.

18 Pull-quotes

Weaseling out of things is important to learn: it's what separates us from the animals. Except the weasel. — Homer Simpson

In typography, the special quotations such as the one above are termed pull-quotes or lift-out quotes. Pull-quotes serve different purposes than the regular quotation blocks introduced in a previous 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.

This block type is declared using the pull 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:

\begin{pull}{Homer Simpson} Weaseling out of things is important to learn: it's what separates us from the animals. Except the weasel. \end{pull}

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 css shipped with lambtex allows for the style parameters of a pull-quote to declare one of the previously discussed floatation specifiers.

19 Declaring and using boxouts

Warning: Boxout overload Boxouts are like quotation blocks: they are most effective when not abused!

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

ewboxout . Moreover, boxouts are optionally titled and may be given an automatic ordering.

The command

ewboxout 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 heredoc technique (namely verbatim , source , mathtexblk , and mathmlblk ). Moreover, the name must begin with a lowercase Roman letter and be composed only of lowercase Roman letters, digits, and the character ' _ ' (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 Section 16. Counter identifiers do nevertheless reside in their own separate namespace, independent of that of labels.

Subsequent to its declaration, using a new boxout named name is simply a matter of wrapping its contents between \begin{name} and \end{name} . The begin tag accepts an optional primary parameter with an extra title to assign to the boxout. If the

ewboxout 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

ewboxout 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.

Suppose thus you wished to display a warning boxout like the one that opens this section. It makes sense to name it warning , and for each instance of the boxout to include the generic title “Warning”. 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 “Boxout overload” 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:



ewboxout{warning}{Warning} \begin{warning}{Boxout overload} Boxouts are like quotation blocks: they are most effective when not abused! \end{warning}

At this point you may be wondering where does the customised warning sign come from. Its origin is simple: for each boxout named name , the html output driver from the lambdoc library will include the classname doc_boxout_env_name in the div element that encapsulates the boxout. The css supplied with the library takes advantage of this metadata, and contains sample customisation for boxouts named warning and tip . This trick provides an easy way to customise your own boxouts. The default css also allows for boxouts to use the floatation classname specifiers described in Section 10.

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 ' () '. Labelled boxouts may be referenced from anywhere in the document via the simple commands \dref , \sref , or \mref (the two former commands may only be used for numbered boxouts, obviously).

20 Theorem-like environments

Theorems and their kin such as corollaries, lemmas, etc, are a staple of mathematical and computer-science writing. For this reason, lambtex 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

ewtheorem . Moreover, theorems must always have a title, and therefore the declaration has two mandatory primary parameters. Similarly to boxouts,

ewtheorem 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.

Suppose thus you wish to create a theorem named theorem , and whose title is, unsurprisingly, “Theorem”. Moreover, you want the theorem to be numbered, and its counter to be called ' cnt:theorem '. One particular instantiation of this theorem has the extra title “John McAuthor”, reflecting its authorship. This is the lambtex source you may use:



ewtheorem{theorem}{Theorem}{cnt:theorem} \begin{theorem}{John McAuthor} Let an egg be defined as an ellipsoid whose radii across the $$x$$, $$y$$, and $$z$$ axes are respectively $$a$$, $$b$$, and $$c$$. Furthermore, the egg satisfies the scalene condition, and therefore $$a > b > c$$. All such eggs are optimally opened by their small-end. \end{theorem}

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 css for particular classes of theorems, you may make use of the same technique described for boxouts. Note, however, that for a theorem named name , the associated classname is doc_theorem_env_name .

Theorem 1 (John McAuthor). Let an egg be defined as an ellipsoid whose radii across the x , y , and z axes are respectively a , b , and c . Furthermore, the egg satisfies the scalene condition, and therefore a > b > c . All such eggs are optimally opened by their small-end.

21 Wrappers

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, lambtex offers a special kind of block known as a wrapper, which as its name implies, is essentially just a wrapper around any of the above listed wrappable blocks. There are four different classes of wrappers available:

Equations These are declared via the environment command equation , and may be used for wrapping mathtexblk and mathmlblk blocks. Printouts These are used for wrapping source environments, and are declared with the environment command printout . Tables Tables may only be used for wrapping tabular environments, and are declared with the environment command table . Figures Finally, figures are declared with the environment command figure , and may be used for wrapping verbatim , picture , and subpage blocks.

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 figure wrapper around a picture block:

\begin[fig:example]{figure}{This is the figure's caption.} \picture{circle.png}{This is a circle} \end{figure}

You can refer to the above declared figure from anywhere in the document by using the label ' fig:example ' with any of the simple commands \dref , \sref , and \mref . The resulting figure (Fig. 1) is shown below:

Fig. 1: This is the figure's caption.

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 ' () ' 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.

It is perfectly reasonable and common for wrapped blocks to be floated on the sides of the page. Therefore, the default css shipped with lambtex allows for the floatation specifiers ' center ', ' left ', and ' right ' to be provided as style parameters to any wrapper. Note that with the exception of picture and verbatim environments, with the default css one can only float wrappable blocks when they are actually placed inside a wrapper. The rationale was discussed in Section 10: 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.

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 source block. It carries no context by itself, and thus must be integrated into the main flow, or wrapped inside a printout 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.

22 Frontmatter: title, abstract, and table of contents

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 frontmatter. These elements are titles and sub-titles, the abstract, and the table of contents.

Titles in lambtex are declared via the aptly named \title command. This is a simple command that takes an inline sequence as parameter. Closely related is the also simple command \subtitle . It is typically used for showing the document's author, date, or actual sub-titles.

LaTeX 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, lambtex sits further along than plain TeX 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 \subtitle command instead of multiple commands tailored to each particular application.

Abstracts are commonly found on scientific papers, and lambtex supports them as well. An abstract is declared by enclosing one or more embeddable blocks within an abstract environment. Please consult Appendix A for more details on what constitutes a embeddable block, and note the source fragment below for an example of the various frontmatter blocks.

\title{Small-endian vs big-endian: the solution} \subtitle{John McAuthor} \subtitle{February 2009} \begin{abstract} 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. (...) \end{abstract}

This is the result produced by the lambtex composer:

Small-endian vs big-endian: the solution John McAuthor February 2009 Abstract 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. (...)

Finally, you can request that a table of contents be printed by issueing the parameterless simple command \toc . 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 \toc lacks any primary parameters (which in lambtex 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 table of contents.

23 Rules

A typographic rule is commonly used in fiction pieces to clearly separate unrelated paragraphs. For the sake of completeness, lambtex supports also this feature. You may declare it using the \rule simple command, or its synonym \hr . These commands are completely parameterless, as the code sample below demonstrates:

This is a paragraph. \rule This is another paragraph.

The generated xhtml result depends of course on the installed css. The default stylesheet produces the following result:

This is a paragraph. This is another paragraph.

24 Adding notes to a document

Markup languages such as LaTeX, whose roots stem from page-oriented designs, have the concept of a footnote. lambtex is targeted at web publishing, a domain where the concept of a document being composed of individual pages is not meaningful. For this reason, lambtex's equivalent concept is that of notes attached to the end of the document.

A note is declared via the environment command note . Notes can of course be labelled, and may be referenced from anywhere in the document via the simple command \see . The latter takes at least one primary parameter, and therefore you may reference multiple notes simply by providing additional primary parameters.

One important feature to remember is that the location where the note is declared is not the same as where it will be appear in the rendered document (for this reason, notes are termed ghost blocks). Instead, all notes will be printed together wherever the simple commands

otes or \rawnotes are declared (the sole difference between the two is that

otes will also create an eponymously named unordered section, just like the one present in this manual, whereas \rawnotes 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.

The sample code below illustrates a note being referenced inside a paragraph and being defined afterwards. The example concludes with the simple command

otes requesting the printing of the eponymous section together with the defined note.

This is a normal\see{note:example} paragraph that references an end-document note. You may read all notes declared in the document \mref{sec:notes}{in this section}. \begin[note:example]{note} And by 'normal' we mean 'not normal'. \end{note}

otes[sec:notes]

25 Adding a bibliography

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 \bibliography or \rawbibliography . 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.

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 lbib , which itself accepts three sub-blocks, defined by the simple commands \who , \what , and \where . 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 \sbib , which takes inline text as the mandatory parameter.

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 \cite . Also, and in similarity to the command \see , it is possible to reference multiple entries with a single invocation of \cite , since this command accepts multiple primary parameters.

Lambtex is largely inspired by LaTeX\cite{bib:latex}, and is available in the Lambdoc library\cite{bib:lambdoc}. \begin[bib:latex]{lbib} \who{Leslie Lamport} \what{LaTeX: a Document Preparation System (2\sup{nd} edition)} \where{Addison-Wesley Professional, 1994, ISBN 0-201-52983-1} \end{lbib} \sbib[bib:lambdoc]{\link{http://lambdoc.forge.ocamlcore.org/}}

Whereas BibTeX[5] offers a very rich set of tags for bibliographic entries (author, title, journal volume, page numbers, conference location, etc), lambtex limits this set to only three main tags, even when using the long form lbib . Those familiar with BibTeX may feel constrained by this paucity. However, one must take into account that lambtex 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 \where 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 \sbib .

26 Creating an appendix

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 Section 24). In other situations, however, it may make more sense to attach them as appendices to the main document. In lambtex, creating an appendix is simply a matter of issueing the simple parameterless command \appendix . 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 \section (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 \appendix .

You can see an example of appendiced sections in this very manual. Note how all sections declared after the appendix marker are automatically ordered using alphabetic characters instead of numbers, as per the usual convention. Smart references produced by command \sref automatically adjust as well — yet another reason why you should avoid its “dumb” counterpart \dref .

27 Macros

lambtex 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.

Before being used, a macro must be declared via the simple command

ewmacro . 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 ' _ ' (underscore).

Should the macro take any arguments, these can be referenced from inside the macro text by the alias \arg{num} , where the num between curly brackets is an integer indicating the argument number. Obviously, a macro with n arguments may not reference an argument n + 1 or higher. Moreover, arguments are expanded as inline sequences.

Wherever an inline sequence is accepted, a macro named name can be invoked via the simple command

ame . 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 name with arguments inline1 and inline2 is done with

ame{inline1}{inline2} . 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.

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 super that expands to the text “super”. Now, you wish to concatenate the invocation of this macro with the text “market”. However, entering \super market produces an unwanted space, whereas \supermarket produces an error, since the macro supermarket 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 < > after the macro name. Concatenation in this example can thus be achieved by entering \super< >market .

Let us now consider a full example of macro declaration. We wish to define a macro author that when invoked expands to the full name of an author. We also define a macro named greet that takes two arguments and produces a greeting. These two macros are then used in a small sample document. This is the lambtex source:



ewmacro{author}{0}{John McAuthor}

ewmacro{greet}{2}{Greetings \bold{\arg{1}}, and welcome to \arg{2}} It was then that \author reached his destination. The gatekeeper said, ``\greet{\author}{this land}'', and there was much rejoicing.

And this is the resulting output:

It was then that John McAuthor reached his destination. The gatekeeper said, “Greetings John McAuthor, and welcome to this land”, and there was much rejoicing.

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.

28 Concluding remarks

You are now familiar with the all the features available in the lambtex 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.

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. Appendix A, for example, discusses at length the structure of the lambtex documents, while Appendix B summarises all command synonyms available, and Appendix C covers all you need to know concerning optional arguments. Finally, unless you are writing about lambtex itself, there is little chance you will need the information contained in Appendix D. But if you do, it focuses on the somewhat arcane aspects concerning numbering in sub-pages.

Appendix

A The structure of lambtex documents

We described a lambtex 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 lambtex document.

Blocks come in different types. Moreover, it is possible to establish a subtyping hierarchy that relates the different block types. Fig. 2 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.

Fig. 2: The subtyping hierarchy for lambtex 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.

Note the list attached to each of the block types, which indicates the actual document blocks that belong to that type. An embeddable block, 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 of ... declaration after their name; these blocks — termed recursive blocks — are those whose contents are other blocks.

If a lambtex 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, any 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 lambtex document has a few constraints in place. As you shall see, these constraints are however fairly minor and still allow for very flexible documents.

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 of ... declaration after the block name. Let us consider, for example, a quote block. It only allows a list of quotable blocks 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 (embeddable blocks, 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 listable block. The exception to this rule is the subpage block, which resets the hierarchy.

B Command synonyms

For reference purposes, Tab. 7 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 begin and end tags, even if they are synonyms.

Canonical name Synonyms \bold \strong , \b \mono \tt \emph \em , \i \item \li \link \a \paragraph \p \rule \hr \section \h1 \subsection \h2 \subsubsection \h3 description dl enumerate ol itemize itemise , ul verbatim pre Tab. 7: List of all available command synonyms.

C Command parameters

The typical simple command in lambtex 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.

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. Tab. 9 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 Tab. 8.

Permission Definition ≈ The parameter is optional, but may not be empty if present. ✔ ø The parameter is mandatory, but it may be empty. ✘ The parameter is altogether forbidden. ✘ ø The parameter is forbidden, unless it is empty. Tab. 8: Definition of the various permissions. These terms are used in Tab. 9.

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 Section 27.

D Notes on ordering

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

Only numbered elements may be referred to using \dref and \sref commands: 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. 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 \dref and \sref . On the other hand, because \mref does not output a number, it is always allowed. You must explicitly provide a manual ordering for sub-paged wrappers, sectional blocks, or custom blocks: A sub-paged element is one that is declared inside a subpage block (see Section 15). 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. You may not provide a manual ordering for wrappers, sectional blocks, or custom blocks defined outside a sub-page: This rule is complementary to the previous one. Because these blocks are numbered automatically by lambtex 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.

Backmatter

Notes

(1) As stated, any given command may either be expressed by the simple notation or as an environment. This should be interpreted an exclusive-or 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: The command may be the parent of at least one block-level element.

The command declares a verbatim-like environment using the heredoc technique for delimitation (see Section 10 for an example). (2) While the qualifier typically 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 Appendix D for details). (3) 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.

Bibliography