# Chapter 4: Macros and Document types

The macro package distributed with Yodl is described in this chapter. The macro package consists of a number of definition files, which convert a Yodl document that follows a certain syntax to an output format. The main output formats, currently supported, are:
• HTML;
• LaTeX (plain LaTeX, no latex2e);
• The groff man' format which is used for man pages;
• The groff ms' format which is more expressive;
• Basic, plain text

The following conversion format is in an experimental stage:

• XML, as used by the University of Groningen's so-called webplatform'.

Currently discontinued conversion formats are:

• SGML, although the basic macros are available. SGML can probably be reactivated fairly quickly. Contact the maintainer if support for SGML should be reinstated
• texinfo, mainly due to the fact that the current maintainer doesn't know what the required post-processing actions are.
• tely, since this conversion format is unknown to the current maintainer.

Other formats may be available, but maybe in an unstable state. Contact the the maintainer if you have a new format to add, or want to reanimate formates that were previously available.

## 4.1: General structure of a Yodl document

This section describes the general format of a Yodl document.

First of all, a Yodl document needs a preamble. This part of the document must be at the top, and must define the modifiers and the document type. Modifiers, when present, must appear first.

Modifiers are often specific for a particular target document type (e.g., latexoptions or mailto), but may also have a general nature (e.g., affiliation or abstract). All modifiers are used to modify parameters of document types. Therefore, they must be specified before the document type is defined.

All modifiers are listed in section 4.3.8. In general, you should use as many modifiers as appropriate. E.g., you should define a mailto even when you're not planning to convert your document to HTML. The reason is twofold: first, you might later decide that a HTML version isn't a bad idea after all. Second, later versions of the converters might use mailto even for non-HTML output formats.

Following the modifiers, the document type is defined. The document type is either article, report, book, plainhtml or manpage. Except for the manpage document type, which is a highly specialized document type, described in section 4.1.2, the following rules apply:

A decision about the document type to use should be based on its complexity. If the document's organization becomes too complex, it is probably a good idea to use a document type supporting a more complex organization. E.g., a complex article might be written as an accessible report, combining related sections into chapters. Similarly, the structure of a report having 30 chapters might improve when it's re-organized as a book having parts. To offer a rule of thumb: a document should have no more than approximately ten top-level sections, and each top-level sectioning should have no more than approximately ten subsections, etc..

The document type influences the way Yodl formats the output. An article (or plainhtml) results in one output file. E.g., one final document when converting to HTML. If your article is way too long, then the loading of the HTML document will also take much time. When converting to HTML, Yodl splits reports and books into files each holding a chapter. These can be accessed through the table of contents. So, the document length can also be relevant when you contemplate switching to a report or book.

Documents using special macros, must have defined these macros before they are used. An appropriate location for these macros is immediately beyond the preamble. E.g., see the file Documentation/manual/manual.yo distributed with the Yodl package. This is the main file of this manual, showing the preferred organization of Yodl files.

To answer yes-but-what-if oriented minds, here are two results of the wrong order of text, preamble and modifiers:

• If you put text before the preamble, i.e., before stating the document type, chances are that Yodl will happily translate the file, but subsequent states will probably fail. E.g., the <html> tag would come too late in a HTML conversion, causing the HTML browser to become confused. Or, the \documentstyle definition would be seen too late by the LaTeX typesetter.
• If you put modifiers, such as latexoptions, beyond the document type, then the modifiers will have no effect; though Yodl won't complain either. The reason for this is the definition of such modifiers will be seen following the stage where they are needed..

### 4.1.1: Document types

As distributed, Yodl supports four document types: article, report, book and the manual page. Note that document types have nothing in common with output formats; a book can be converted to each of the output formats, and a manual page can be converted to a .dvi file. Nevertheless, some formats are particularly usefule for some document types. A book converted to the man output format to be processed later with groff won't look too good. Its looks would greatly improve when the document would be converted to ASCII using the ms output format.

Following the preamble and the definition of specialized macros symbols and counters, documents start by specifying the document type. The available macros are:

• article(title)(author)(date): The article document type should be used for short documents. Its arguments specify the document's title, author and date.

In articles, the title page is numbered and the table of contents is on the title page. The sectioning commands sect, subsect etc. are available.

• report(title)(author)(date): The report document type differs from an article in that it has a separate unnumbered title page, a table of contents on a page of its own, and it supports the sectioning command chapter in addition to the ones supported by articles. A report should be used fir larger documents.
• book(title)(author)(date): The book type is for even larger documents. In addition to the sectioning commands supported by report it supports the sectioning command part.
• plainhtml(title): This document type is typically used in HTML output. It's implemented for situations where you only need to create a HTML file, but want to use Yodl to help you by providing useful macros. This document type is similar to article, but does not require you to specify author and date arguments (In fact, you can emulate plainhtml by using an article, using empty author and date arguments).
• manpage(title)(section)(date)(source)(manual): The manpage document type should only be used to write Unix-style manual pages. It uses its own sectioning commands to reflect the necessary sections in a manual page. This document format is described separately in 4.1.2.
These macros provide, globally, three functions: First, the macros generate any commands that need to appear before real' text is sent to the output file. E.g., the LaTeX output needs a \documentstyle preamble, HTML output needs <html> and <body> tags.

Second, the macros define appropriate document-dependent settings. E.g., the LaTeX converter defines the title, author and date using \title etc..

Third, the actual document is started. E.g., for LaTeX this means a \begin{type}, followed by the appropriate commands to generate a the document title and the table of contents. The title setting in the above macros defines the document title which always appears on the front page of the document. For HTML output, this is also the title of the HTML file (or files), as appearing in the HTML <title> tag.

The fact that the macros defining the document type perform many functions means that once the macro is started, nothing extra' can be inserted between, e.g., the generated title and the table of contents. Sometimes this is not what you'd like; as is the case with an abstract. Yodl therefore uses modifiers, appearing before the document type macros, to insert information between the various elements of a document definition.

### 4.1.2: The manpage document type

The manpage document type was implemented to simplify the construction of Unix-style manual pages. A manpage document must be organized as follows:
1. The manual page itself is defined, using the macro
manpage(short title)
(section)
(date)
(source)
(manual)

Its arguments are:

Short title:
This should be the program name or something similar; i.e., whatever the manpage is describing.

Section:
A number, stating the manpage section. The Linux man (7) page recognizes the following manpage sections:
• Section 1 is for commands, like ls;
• Section 2 is for system calls, like fork();
• Section 3 is for library calls, like strdup();
• Section 4 is for special files (like devices);
• Section 5 is for file formats, (like syslog.conf);
• Section 6 is for games;
• Section 7 is for macro packages and conventions;
• Section 8 is for system management commands;
• Section 9 is for other types of manpages, such as kernel commands.

Date:
The date of release.

Source:
The package where the manpage belongs to.

Manual:
The manual to which the package belongs.
The arguments of the manpage macro define, e.g., the headers and footers of the manual page. The date, source and manual arguments can be empty.
2. The subject of the manpage is defined using

manpagename(name)(short description)

The name argument should be a short name (e.g., the program name), and the short description should state the function. The descriptive argument is used by, e.g., the whatis database.
3. The synopsis starts after:

manpagesynopsis()

Following this, an abbreviated usage information is presented. This information should show, e.g., the possible program flags and required arguments; but no more.
4. The description is given after:

manpagedescription()

This is followed by some descriptive text. The descriptive text can e.g. show what the program (function, file, game, etc.) is supposed to do.
5. Options are expected after:

manpageoptions()

The options are typically a descriptive list of possible flags and their meaning. This section lists the information of the synopsis, but also gives an in-depth description. The manpageoptions() section is optional.
6. Necessary files are listed after:

manpagefiles()

manpageseealso()

This is then followed by a list of related manual pages. Here, use the format bf(topic)(sectionnr), e.g., Yodl(1).
8. Diagnostics are described after:

manpagediagnostics()

Diagnostics can state, e.g., what error messages are produced by the program and what the cure is.
9. Known bugs should be mentioned after:

manpagebugs()

This section is optional.
10. Finally, the author is stated after:

manpageauthor()

The manpage document type requires you to follow the above order of commands strictly and to state all the necessary sections (and optionally, to state the not required sections but in their proper sequence). Furthermore, sectioning commands that are available in other document types (sect, subsect etc.) are not allowed in a manpage. You can however insert other sections in the manual page with the macro manpagesection. This macro takes one argument: the title of the extra section. It is suggested that you type the section name in upper case, to conform to the standard.

As an example, the manual page for the yodl program follows (the actual manual page may differ):

manpage(yodl)
(1)
(1996)
(The Yodl Package)
(Yet oneOther Document Language)

manpagename(yodl)(main Yodl convertor)

manpagesynopsis()
tt(Yodl) [-DNAME] [-IDIR] [-oFILE] [-PCMD] [-pPASS] [-t] [-v] [-w] [-h]
[-?]  inputfile [inputfile...]

manpagedescription()
This manual page describes the tt(Yodl) program, the main converter of the
Yodl package. This program is used by the bf(yodl2....) shell scripts,
e.g., bf(yodl2tex) or bf(yodl2html).

manpageoptions()
description(
dit(-DNAME) Defines symbol em(NAME).
dit(-IDIR) Overrules the standard include directory (default
em(/usr/local/lib/yodl)) with em(DIR).
dit(-oFILE) Specifies em(FILE) as the output file (default is stdout).
dit(-PCMD) Preloads' command em(CMD), as if em(CMD) was the first line
of the input.
dit(-pPASS) Defines em(PASS) as the maximum number of passes'; when this
number is exceeded, tt(Yodl) aborts.
dit(-t) Enables tracing mode. Useful for debugging.
dit(-v) Raises the verbosity mode. Useful for debugging.
dit(-w) Enables warning. When enabled, tt(Yodl) will warn when it sees
inconsistencies.
dit(-h, -?) Shows usage information.
dit(inputfile) File to process, use em(-) to instruct tt(Yodl) to read
from stdin.
)

manpagefiles()
The tt(Yodl) program requires no files, but normal' usage of the Yodl package
requires macro files installed (usually in bf(/usr/local/share/yodl)). The
files in this directory are included by the converters bf(yodl2txt) etc..

manpageseealso()
bf(yodl2tex), bf(yodl2html), bf(yodl2man), etc..

manpagediagnostics()
Warnings and errors of tt(Yodl) are too many to enumerate, but all errors
are printed to em(stderr) after which tt(Yodl) exits with a non-zero
status.

manpagebugs()
There may be bugs in the tt(Yodl) program, but that's not very likely.
More likely you'll encounter bugs or omissions in the macro package
itself.

manpageauthor()
Karel Kubat

## 4.2: Predefined macros

This section describes all macros defined by default. Altering or removing these macros may produce unexpected results when converting Yodl documents to other formats. Furthermore, these macros often depend on macros or other symbols defined for internal use.

Many predefined macros depend on symbols start with XX. Therefore, it is strongly advised not to start any locally defined symbol with XX as doing so, or undefining existing symbols starting with XX, may also produce unexpected results.

Here are the default macros, alphabetically ordered:

### 4.2.1: abstract(text)

Defines an abstract for an article or report document. Abstracts are not implemented for books or manpages. Must appear before starting the document with the article or report macro.

Adds text n times to symbol. The value n may also be the name of a defined counter (which itself will not be modified).

### 4.2.3: affiliation(site)

Defines an affiliation, to appear in the document titlepage below the author field. Must appear before starting the document with article, report or book. The affiliation is only printed when the author field is not empty.

### 4.2.4: AfourEnlarged()

Enlarges the usable height of A4 paper by 2 cm.: the top margin is reduced by 2 cm. This macro should be called in the preamble. The macro is available only for LaTeX conversions.

### 4.2.5: appendix()

Starts appendices

### 4.2.6: article(title)(author)(date)

Starts an article. The top-level sectioning command is (n)sect. In HTML conversions only one output file is written.

### 4.2.7: bf(text)

Sets text in boldface.

### 4.2.8: bind(text)

Generate a binding character after text.

### 4.2.9: book(title)(author)(date)

Starts a book document. The top-level sectioning command is (n)chapter, (n)part being optional. In HTML output files are created for each chapter.

### 4.2.10: cell(contents)

Sets a table cell, i.e., one element in a row. With the man/ms converters multiple blanks between cell() macro calls are merged into a single blank character.

### 4.2.11: cells(nColumns)(contents)

Set a table cell over nColumns columns. In html, LaTeX and xml formats the information in the combined cells will be centered. With man/ms conversions the cells() macro simply calls the cell() macro, but here the setmanalign() macro can be used to determine the alignment of multiple cells.

### 4.2.12: cellsline(from)(count)

Sets a horizontal line starting at column number from over count columns in a row. If from is less then the number of columns already added to a row then it is ignored. This macro must be embedded in a row macro defining a table row. To put a line across the table's full width use rowline. To set horizontal lines across columns 1 until 2 and columns 4 until 5 table of a table use:

row(cellsline(1)(2)cellsline(4)(2))

Combining cellsline and cell or cells calls in one row produces undefined results.

### 4.2.13: center(text)

Sets text centered, when the output format permits. Use nl() in the text to break lines.

### 4.2.14: chapter(title)

Starts a new chapter in books or reports.

### 4.2.15: cindex()

Generate an index entry for index c.

### 4.2.16: cite(1)

Sets a citation or quotation

### 4.2.17: clearpage()

Starts a new page, when the output format permits. Under HTML a horizontal line is drawn.

### 4.2.18: code(text)

Sets text in code font, and prevents it from being expanded. For unbalanced parameter lists, use CHAR(40) to get ( and CHAR(41) to get ).

### 4.2.19: columnline(from)(to)

Sets a horizontal line over some columns in a row. Note that columnline defines a row by itself, consisting of just a horizontal line spanning some of its columns, rather than the table's full width, like rowline. The two arguments represent column numbers. It is the responsibility of the author to make sure that the from and to values are sensible. I.e.,

1 <= from <= to <= ncolumns

Note: this macro cannot be used if multiple lines must be set in one row. In those cases the macro colsline should be used.

### 4.2.20: def(macroname)(nrofargs)(redefinition)

Defines macroname as a macro, having nrofargs arguments, and expanding to redefinition. This macro is a shorthand for DEFINEMACRO. An error occurs when the macro is already defined. Use redef() to unconditionally define or redefine a macro.

### 4.2.21: description(list)

Sets list as a description list. Use dit(item) to indicate items in the list.

### 4.2.22: dit(itemname)

Starts an item named itemname in a descriptive list. The list is either enclosed by startdit() and enddit(), or is an argument to description().

### 4.2.23: eit()

Indicates an item in an enumerated list. The eit() macro should be an argument in enumerate().

### 4.2.24: ellipsis()

Sets ellipsis (...).

### 4.2.25: em(text)

Sets text as emphasized, usually italics.

In HTML, this macro sets the address in a <a href="mailto=.."> locator. In other output formats, the address is sent to the output. The email macro is a special case of url.

### 4.2.27: endcenter()

DEPRECATED. Use center().

### 4.2.28: enddit()

DEPRECATED. Use description().

### 4.2.29: endeit()

DEPRECATED. Use enumeration().

### 4.2.30: endit()

DEPRECATED. Use itemization().

### 4.2.32: endtable()

DEPRECATED. Use table().

### 4.2.33: enumerate(list)

DEPRECATED. Use enumeration().

### 4.2.34: enumeration(list)

enumeration() starts an enumerated list. Use eit() in the list to indicate items in the list.

### 4.2.35: euro()

Sets the euro currency symbol in latex, html, (and possibly sgml and xml). In all other conversions EUR which is the official textual abbreviation (cf. http://ec.europa.eu/euro/entry.html) is written. Note that LaTeX may require latexpackage()(eurosym).

### 4.2.36: fig(label)

This macro is a shorthand for figure ref(label) and just makes the typing shorter, as in see fig(schematic) for .. See getfigurestring() and setfigurestring() for the figure text.

### 4.2.37: figure(file)(caption)(label)

Sets the picture in file as a figure in the current document, using the descriptive text caption. The label is defined as a placeholder for the figure number and can be used in a corresponding ref statement. Note that the file must be the filename without extension: By default, Yodl will supply .gif when in HTML mode, or .ps when in LaTeX mode. Figures in other modes may not (yet) haven been implemented.

### 4.2.38: file(text)

Sets text as filename, usually boldface.

### 4.2.39: findex()

Generate an index entry for index f.

### 4.2.40: footnote(text)

Sets text as a footnote, or in parentheses when the output format does not allow footnotes.

### 4.2.41: gagmacrowarning(name name ...)

Prevents the yodl program from printing cannot expand possible user macro. E.g., if you have in your document the file(s) are .. then you might want to put before that: gagmacrowarning(file). Calls NOUSERMACRO.

### 4.2.42: getaffilstring()

Expands to the string that defines the name of Affiliation Information, by default AFFILIATION INFORMATION. Can be redefined for national language support by setaffilstring(). Currently, it is relevant only for txt.

### 4.2.43: getauthorstring()

Expands to the string that defines the name of Author Information, by default AUTHOR INFORMATION. Can be redefined for national language support by setauthorstring(). Currently, it is relevant only for txt.

### 4.2.44: getchapterstring()

Expands to the string that defines a chapter' entry, by default Chapter. Can be redefined for national language support by setchapterstring().

### 4.2.45: getdatestring()

Expands to the string that defines the name of Date Information, by default DATE INFORMATION. Can be redefined for national language support by setdatestring(). Currently, it is relevant only for txt.

### 4.2.46: getfigurestring()

Returns the string that defines a figure' text, in captions or in the fig() macro. The string can be redefined using the setfiguretext() macro.

### 4.2.47: getpartstring()

Expands to the string that defines a part' entry, by default Part. Can be redefined for national language support by setpartstring().

### 4.2.48: gettitlestring()

Expands to the string that defines the name of Title Information, by default TITLE INFORMATION. Can be redefined for national language support by settitlestring(). Currently, it is relevant only for txt.

### 4.2.50: htmlbodyopt(option)(value)

Adds option="value" to the options of the <body ...> tag in HTML files. Useful options are, e.g., fgcolor and bgcolor, whose values are expressed as #rrggbb, where rr are two hexadecimal digits of the red component, gg two hexadecimal digits of the green component, and bb two hexadecimal digits of the blue component.

### 4.2.51: htmlcommand(cmd)

Writes cmd to the output when converting to html. The cmd is not further expanded by Yodl.

Adds the literal text option to the current information in the head section of an HTML document. Option may (or: should) contain plain html text. A commonly occurring head option is link, defining, e.g., a style sheet. Since that option is frequently used, it has received a dedicated macro: htmlstylesheet. Like htmlbodyopt this macro should be placed in the document's preamble.

### 4.2.53: htmlnewfile()

In HTML output, starts a new file. All other formats are not affected. Note that you must take your own provisions to access the new file; say via links. Also, it's safe to start a new file just befoore opening a new section, since sections are accessible from the clickable table of contents. The HTML converter normally only starts new files prior to a chapter definition.

### 4.2.54: htmlstylesheet(url)

Adds a <link rel="stylesheet" type="text/css" ...> element to the head section of an HTML document, using url in its href field. The argument url is not expanded, and should be plain HTML text, without surrounding quotes. The macro htmlheadopt can also be used to put information in the head-section of an HTML document, but htmlheadopt is of a much more general nature. Like htmlbodyopt this macro should be placed in the document's preamble.

### 4.2.55: htmltag(tagname)(start)

Sets tagname as a HTML tag, enclosed by < and >. When start is zero, the tagname is prefixed with /.

### 4.2.56: ifnewparagraph(truelist)(falselist)

The macro ifnewparagraph should be called from the PARAGRAPH macro, if defined. It will insert truelist if a new paragraph is inserted, otherwise falselist is inserted (e.g., following two consecutive calls of PARAGRAPH). This macro can be used to prevent the output of multiple blank lines.

### 4.2.57: includefile(file)

Includes file. The default extension .yo is supplied if necessary.

NOTE: Starting with Yodl version 3.00.0 Yodl's default file inclusion behavior has changed. The current working directory no longer remains fixed at the directory in which Yodl is called, but is volatile, changing to the directory in which a yodl-file is located. This has the advantage that Yodl's file inclusion behavior now matches the way C's #include directive operates; it has the disadvantage that it may break some current documents. Conversion, however is simple but can be avoided altogether if Yodl's -L (--legacy-include) option is used.

Furthermore, the includefile macro no longer defines a label. To define a label just before the file's inclusion use lincludefile.

### 4.2.58: includeverbatim(file)

Include file into the output. No processing is done, file should be in preformatted form, e.g.:

whenhtml(includeverbatim(foo.html))

NOTE: Starting with Yodl version 3.00.0 Yodl's default file inclusion behavior has changed. The current working directory no longer remains fixed at the directory in which Yodl is called, but is volatile, changing to the directory in which a yodl-file is located. This has the advantage that Yodl's file inclusion behavior now matches the way C's #include directive operates; it has the disadvantage that it may break some current documents. Conversion, however is simple but can be avoided altogether if Yodl's -L (--legacy-include) option is used.

### 4.2.59: it()

Indicates an item in an itemized list. The list is either surrounded by startit() and endit(), or it is an argument to itemize().

### 4.2.60: itemization(list)

Sets list as an itemizationd list. Use it() to indicate items in the list.

### 4.2.61: itemize(list)

DEPRECATED. Use itemization().

### 4.2.62: kindex()

Generate an index entry for index k.

### 4.2.63: label(labelname)

Defines labelname as an anchor for a link command, or to stand for the last numbering of a section or figure in a ref command.

Character <

### 4.2.65: languagedutch()

Defines the Dutch-language specific headers. Active this macro via setlanguage(dutch).

### 4.2.66: languageenglish()

Defines the English-language specific headers. Active this macro via setlanguage(english).

### 4.2.67: languageportugese()

Defines the Portugese-language specific headers. Active this macro via setlanguage(portugese).

### 4.2.68: LaTeX()

The LaTeX symbol.

This macro is provided to add Yodl-interpreted text to your own LaTeX layout commands. The command is terminated with an end-of-line. See also the macro latexlayoutcmds()

### 4.2.70: latexcommand(cmd)

Writes cmd plus a white space to the output when converting to LaTeX. The cmd is not further expanded by Yodl.

### 4.2.71: latexdocumentclass(class)

Forces the LaTeX \documentclass{...} setting to class. Normally the class is defined by the macros article, report or book. This macro is an escape route incase you need to specify your own document class for LaTeX. This option is a modifier and must appear before the article, report or book macros.

### 4.2.72: latexlayoutcmds(NOTRANSs)

This macro is provided in case you want to put your own LaTeX layout commands into LaTeX output. The NOTRANSs are pasted right after the \documentclass stanza. The default is, of course, no local LaTeX commands. Note that this macro does not overrule my favorite LaTeX layout. Use nosloppyhfuzz() and standardlayout() to disable my favorite LaTeX layout.

### 4.2.73: latexoptions(options)

Set latex options: documentclass[options]. This command must appear before the document type is stated by article, report, etc..

### 4.2.74: latexpackage(options)(name)

Include latex package(s), a useful package is, e.g., epsf. This command must appear before the document type is stated by article, report, etc..

### 4.2.75: lchapter(label)(title)

Starts a new chapter in books or reports, setting a label at the beginning of the chapter.

### 4.2.76: letter(language)(date)(subject)(opening)(salutation)(author)

Starts a letter written in the indicated language. The date of the letter is set to date', the subject of the letter will be subject'. The letter starts with opening'. It is based on the letter.cls' document class definition. The macro is available for LaTeX only. Preamble command suggestions:

• latexoptions(11pt)
• a4enlarged()
• letterfootitem(phone)(number), maybe e-mail too.
• letterto(addressitem). Use a separate letterto() macro call for each new line of the address.

Adds an addendum at the end of a letter. type' should be bijlagen', cc' or ps'.

Puts yourletterfrom' and yourreference' elements in the letter. If left empty, two dashes are inserted.

### 4.2.79: letterfootitem(name)(value)

Puts a footer at the bottom of letter-pages. Up to three will usually fit. LaTeX only.

Defines the reply to' address in LaTeX or txt-letters.

### 4.2.81: letterto(element)

In HTML output a clickable link with the text description is created that points to the place where labelname is defined using the label macro. Using link is similar to url, except that a hyperlink is set pointing to a location in the same document. For output formats other than HTML, only the description appears.

### 4.2.83: lref(description)(labelname)

This macro is a combination of the ref and link macros. In HTML output a clickable link with the text description and the label value is created that points to the place where labelname is defined using the label macro. For output formats other than HTML, only the description and the label value appears.

### 4.2.84: lsect(label)(title)

Starts a new section, setting a label at the beginning of the section.

### 4.2.85: lsubsect(label)(title)

Starts a new subsection. Other sectioning commands are subsubsect and subsubsubsect. A label is added just before the subsection.

### 4.2.86: lsubsubsect(label)(title)

Starts a sub-subsection, a label is added just before the section

### 4.2.87: lsubsubsubsect(label)(title)

Starts a sub-sub-sub section. This level of sectioning is not numbered, in contrast to higher' sectionings. A label is added just before the subsubsubection.

### 4.2.88: lurl(locator)

An url described by its Locator. For small urls with readable addresses.

Defines the default mailto address for HTML output. Must appear before the document type is stated by article, report, etc..

### 4.2.90: makeindex()

Make index for latex.

### 4.2.91: mancommand(cmd)

Writes cmd to the output when converting to man. The cmd is not further expanded by Yodl.

### 4.2.92: manpage(title)(section)(date)(source)(manual)

Starts a manual page document. The section argument must be a number, stating to which section the manpage belongs to. Most often used are commands (1), file formats (5) and macro packages (7). The sectioning commands in a manpage are not (n)sect etc., but manpage...(). The first section must be the manpagename, the last section must be the manpageauthor. The standard manpage for section 1 contains the following sections (in the given order): manpagename, manpagesynopsis, manpagedescription, manpageoptions, manpagefiles, manpageseealso, manpagediagnostics, manpagebugs, manpageauthor. Optional extra sections can be added with manpagesection. Standard manpageframes for several manpagesections are provided in /usr/local/share/yodl/manframes.

### 4.2.93: manpageauthor()

Starts the AUTHOR entry in a manpage document. Must be the last section of a manpage.

### 4.2.94: manpagebugs()

Starts the BUGS entry in a manpage document.

### 4.2.95: manpagedescription()

Starts the DESCRIPTION entry in a manpage document.

### 4.2.96: manpagediagnostics()

Starts the DIAGNOSTICS entry in a manpage document.

### 4.2.97: manpagefiles()

Starts the FILES entry in a manpage document.

### 4.2.98: manpagename(name)(short description)

Starts the NAME entry in a manpage document. The short description is used by, e.g., the whatis database.

### 4.2.99: manpageoptions()

Starts the OPTIONS entry in a manpage document.

### 4.2.100: manpagesection(SECTIONNAME)

Inserts a non-required section named SECTIONNAME in a manpage document. This macro can be used to augment standard' manual pages with extra sections, e.g., EXAMPLES. Note that the name of the extra section should appear in upper case, which is consistent with the normal typesetting of manual pages.

### 4.2.102: manpagesynopsis()

Starts the SYNOPSIS entry in a manpage document.

### 4.2.103: mbox()

Unbreakable box in LaTeX. Other formats may have different opitions on our unbreakable boxex.

DEPRECATED.

### 4.2.105: metaC(text)

Put a line comment in the output.

### 4.2.106: metaCOMMENT(text)

Write format-specific comment to the output.

DEPRECATED.

### 4.2.108: mscommand(cmd)

Writes cmd to the output when converting to ms. The cmd is not further expanded by Yodl.

### 4.2.109: nchapter(title)

Starts a chapter (in a book or report) without generating a number before the title and without placing an entry for the chapter in the table of contents.

Named email. A more consistent naming for url, lurl, email and nemail would be nice.

### 4.2.111: nl()

Forces a newline; i.e., breaks the current line in two.

### 4.2.112: node(previous)(this)(next)(up)

DEPRECATED Defines a node with name this, and links to nodes previous, next and (up), for the node command.

### 4.2.113: nodeprefix(text)

Prepend text to node names, e.g.

nodeprefix(LilyPond) sect(Overview)
Currently used in texinfo descriptions only.

### 4.2.114: nodeprefix(text)

Prepend text to node names, e.g.

nodeprefix(LilyPond) sect(Overview)
Currently used in texinfo descriptions only.

### 4.2.115: nodetext(text)

Use text as description for the next node, e.g.

nodetext(The GNU Music Typesetter)chapter(LilyPond)
Currently used in texinfo descriptions only.

### 4.2.116: nop(text)

Expand to text, to avoid spaces before macros e.g.: a2. Although a+sups(2) should have the same effect.

### 4.2.117: nosloppyhfuzz()

By default, LaTeX output contains commands that cause it to shut up about hboxes that are less than 4pt overfull. When nosloppyhfuzz() appears before stating the document type, LaTeX complaints are vanilla'.

### 4.2.118: notableofcontents()

Prevents the generation of a table of contents. This is default in, e.g., manpage and plainhtml documents. When present, this option must appear before stating the document type with article, report etc..

### 4.2.119: notitleclearpage()

Prevents the generation of a clearpage() instruction after the typesetting of title information. This instruction is default in all non article documents. When present, must appear before stating the document type with article, book or report.

### 4.2.120: notocclearpage()

With the LaTeX convertor, no clearpage() instruction is inserted immediately beyond the document's table of contents. The clearpage() instruction is default in all but the article document type. When present, must appear before stating the document type with article, book or report. With other convertors than the LaTeX convertor, it is ignored.)

### 4.2.121: notransinclude(filename)

Reads filename and inserts it literally in the text not subject to macro expansion or character translation. No information is written either before or after the file's contents, not even a newline.

NOTE: Starting with Yodl version 3.00.0 Yodl's default file inclusion behavior has changed. The current working directory no longer remains fixed at the directory in which Yodl is called, but is volatile, changing to the directory in which a yodl-file is located. This has the advantage that Yodl's file inclusion behavior now matches the way C's #include directive operates; it has the disadvantage that it may break some current documents. Conversion, however is simple but can be avoided altogether if Yodl's -L (--legacy-include) option is used.

### 4.2.122: noxlatin()

When used in the preamble, the LaTeX converter disables the inclusion of the file xlatin1.tex. Normally this file gets included in the LateX output files to ensure the conversion of high ASCII characters (like é) to LaTeX-understandable codes. (The file xlatin1.tex comes with the Yodl distribution.)

### 4.2.123: nparagraph(title)

Starts a non-numbered paragraph (duh, corresponds to subparagraph in latex).

### 4.2.124: npart(title)

Starts a part in a book document, but without numbering it and without entering the title of the part in the table of contents.

### 4.2.125: nsect(title)

Starts a section, but does not generate a number before the title nor an entry in the table of contents. Further sectioning commands are nsubsect, nsubsubsect and nsubsubsubsect.

### 4.2.126: nsubsect(title)

Starts a non-numbered subsection.

### 4.2.127: nsubsubsect(title)

Starts a non-numbered sub-sub section.

### 4.2.128: nsubsubsect(title)

Starts a non-numbered sub-subsection.

### 4.2.129: paragraph(title)

Starts a parapgraph. This level of sectioning is not numbered, in contrast to higher' sectionings (duh, corresponds to subparagraph in latex).

### 4.2.130: part(title)

Starts a new part in a book document.

### 4.2.131: pindex()

Generate an index entry for index p.

### 4.2.132: plainhtml(title)

Starts a document for only a plain HTML conversion. Not available in other output formats. Similar to article, except that an author- and date field are not needed.

### 4.2.133: printindex()

Make index for texinfo (?).

### 4.2.134: quote(text)

Sets the text as a quotation. Usually, the text is indented, depending on the output format.

### 4.2.135: rangle()

Inserts the right angle character (>).

### 4.2.136: redef(nrofargs)(redefinition)

Defines macro macro to expand to redefinition. Similar to def, but any pre-existing definition is overruled. Use ARGx in the redefinition part to indicate where the arguments should be pasted. E.g., ARG1 places the first argument, ARG2 the second argument, etc...

### 4.2.137: redefinemacro(nrofargs)(redefinition)

Defines macro macro to expand to redefinition. Similar to def, but any pre-existing definition is overruled. Use ARGx in the redefinition part to indicate where the arguments should be pasted. E.g., ARG1 places the first argument, ARG2 the second argument, etc... This commands is actually calling redef().

### 4.2.138: ref(labelname)

Sets the reference for labelname. Use label to define a label.

### 4.2.139: report(title)(author)(date)

Starts a report type document. The top-level sectioning command in a report is chapter.

### 4.2.140: roffcmd(dotcmd)(sameline)(secondline)(thirdline)

Sets a t/nroff command that starts with a dot, on its own line. The arguments are: dotcmd - the command itself, e.g., .IP; sameline - when not empty, set following the dotcmd on the same line; secondline - when not empty, set on the next line; thirdline - when not empty, set on the third line. Note that dotcmd and thirdline are not further expanded by Yodl, the other arguments are.

### 4.2.141: row(contents)

The argument contents may contain a man-page alignment specification (only one specification can be entered per row), using setmanalign(). If omitted, the standard alignment is used. Furthermore it contains the contents of the elements of the row, using cell() or cells() macros. If cells() is used, setmanalign() should have been used too. In this macro call only the cell(), cells() and setmanalign() macros should be called. Any other macro call may produce unexpected results.

The row macro defines a counter XXcellnr that can be inspected and is incremented by predefined macros adding columns to a row. The counter is initially 0. Predefined macros adding columns to a row add the number of columns they add to the row inserting the contents of those columns. These macros rely on the correct value of this counter and any user-defined macros adding columns to table rows should correctly update XXcellnr.

### 4.2.142: rowline()

Sets a horizontal line over the full width of the table. See also columnline(). Use rowline() instead of a row() macro call to obtain a horizontal line-separator.

### 4.2.143: sc(text)

Set text in small caps (or tt).

### 4.2.144: sect(title)

Starts a new section.

### 4.2.145: setaffilstring(name)

Defines name as the affiliation information' string, by default AFFILIATION INFORMATION. E.g., after setaffilstring(AFILIACION), Yodl outputs this Spanish string to describe the affiliation information. Currently, it is relevant only for txt.

### 4.2.146: setauthorstring(name)

Defines name as the Author information' string, by default AUTHOR INFORMATION. E.g., after setauthorstring(AUTOR), Yodl outputs this portuguese string to describe the author information. Currently, it is relevant only for txt.

### 4.2.147: setchapterstring(name)

Defines name as the chapter' string, by default Chapter. E.g., after setchapterstring(Hoofdstuk), Yodl gains some measure of national language support for Dutch. Note that LaTeX support has its own NLS, this macro doesn't affect the way LaTeX output looks.

### 4.2.148: setdatestring(name)

Defines name as the date information' string, by default DATE INFORMATION. E.g., after setdatestring(DATA), Yodl outputs this portuguese string to describe the date information. Currently, it is relevant only for txt.

### 4.2.149: setfigureext(name)

Defines the name as the figure' extension. The extension should include the period, if used. E.g., use setfigureext(.ps) if the extensions of the figure-images should end in .ps

### 4.2.150: setfigurestring(name)

Defines the name as the figure' text, used e.g. in figure captions. E.g., after setfigurestring(Figuur), Yodl uses Dutch names for figures.

### 4.2.151: sethtmlfigureext(ext)

Defines the filename extension for HTML figures, defaults to .jpg. Note that a leading dot must be included in ext. The new extension takes effect starting with the following usage of the figure macro. It is only active in html, but otherwise acts identically as setfigureext().

### 4.2.152: setincludepath(name)

Sets a new value of the include-path specification used when opening .yo files. A warning is issued when the path specification does not include a .: element. Note that the local directory may still be an element of the new include path, as the local directory may be the only or the last element of the specification. For these eventualities the new path specification is not checked.

### 4.2.153: setlanguage(name)

Installs the headers specific to a language. The argument must be the name of a language, whose headers have been set by a corresponding languageXXX() call. For example: languagedutch(). The language macros should set the names of the headers of the following elements: table of contents, affiliation, author, chapter, date, figure, part and title

### 4.2.154: setlatexalign(alignment)

This macro defines the table alignment used when setting tables in LaTeX. Use as many l (for left-alignment), r (for right alignment), and c (for centered-alignment) characters as there are columns in the table. See also table()

### 4.2.155: setlatexfigureext(ext)

Defines the filename extension for encapsulated PostScript figures in LaTeX, defaults to .ps. The dot must be included in t new extension ext. The new extension takes effect starting with a following usage of the figure macro. It is only active in LaTeX, but otherwise acts identically as setfigureext().

### 4.2.156: setlatexverbchar(char)

Set the char used to quote LaTeX \verb sequences

### 4.2.157: setmanalign(alignment)

This macro defines the table alignment used when setting tables used in man-pages (see tbl(1)). Use as many l (for left-alignment), r (for right alignment), and c (for centered-alignment) characters as there are columns in the table. Furthermore, s can be used to indicate that the column to its left is combined (spans into) the current column. Use this specification when cells spanning multiple columns are defined. Each row in a table which must be convertable to a manpage may contain a separate setmanalign() call. Note that neither rowline nor columnline requires setmanalign() specifications, as these macros define rows by themselves. It is the responsibility of the author to ensure that the number of alignment characters is equal to the number of columns of the table.

### 4.2.158: setpartstring(name)

Defines name as the part' string, by default Part. E.g., after setpartstring(Teil), Yodl identifies parts in the German way. Note that LaTeX output does its own national language support; this macro doesn't affect the way LaTeX output looks.

### 4.2.159: setrofftab(x)

Sets the character separating items in a line of input data of a roff (manpage) table. By default it is set to ~. This separator is used internally, and needs only be changed (into some unique character) if the table elements themselves contain ~ characters.

### 4.2.160: setrofftableoptions(optionlist)

Set the options for tbl table, default: none. Multiple options should be separated by blanks, by default no option is used. From the tbl(1) manpage, the following options are selected for consideration:

• center Centers the table (default is left-justified)
• expand Makes the table as wide as the current line length
• box Encloses the table in a box
• allbox Encloses each item of the table in a box
Note that starting with Yodl V 2.00 no default option is used anymore. See also setrofftab() which is used to set the character separating items in a line of input data.

### 4.2.161: settitlestring(name)

Defines name as the title information' string, by default TITLE INFORMATION. E.g., after settitlestring(TITEL), Yodl outputs this Dutch string to describe the title information. Currently, it is relevant only for txt.

### 4.2.162: settocstring(name)

Defines name as the table of contents' string, by default Table of Contents. E.g., after settocstring(Inhalt), Yodl identifies the table of contents in the German way. Note that LaTeX output does its own national language support; this macro doesn't affect the way LaTeX output looks.

### 4.2.163: sgmlcommand(cmd)

Writes cmd to the output when converting to sgml. The cmd is not further expanded by Yodl.

### 4.2.164: sgmltag(tag)(onoff)

Similar to htmltag, but used in the SGML converter.

### 4.2.165: sloppyhfuzz(points)

By default, LaTeX output contains commands that cause it to shut up about hboxes that are less than 4pt overfull. When sloppyhfuzz() appears before stating the document type, LaTeX complaints occur only if hboxes are overfull by more than points.

### 4.2.166: standardlayout()

Enables the default LaTeX layout. When this macro is absent, then the first lines of paragraphs are not indented and the space between paragraphs is somewhat larger. The standardlayout() directive must appear before stating the document type as article, report, etc..

### 4.2.167: startcenter()

DEPRECATED. center() should be used.

### 4.2.168: startdit()

DEPRECATED. Use description().

### 4.2.169: starteit()

DEPRECATED. Use enumeration().

### 4.2.170: startit()

DEPRECATED. Use itemization().

### 4.2.172: starttable()

DEPRECATED. Use table().

### 4.2.173: subs(text)

Sets text in subscript in supporting formats

### 4.2.174: subsect(title)

Starts a new subsection. Other sectioning commands are subsubsect and subsubsubsect.

### 4.2.175: subsubsect(title)

Starts a sub-subsection.

### 4.2.176: subsubsubsect(title)

Starts a sub-sub-sub-subsection. This level of sectioning is not numbered, in contrast to higher' sectionings.

### 4.2.177: sups(text)

Sets text in superscript in supporting formats

### 4.2.178: table(nColumns)(alignment)(Contents)

The table()-macro defines a table. Its first argument specifies the number of columns in the table. Its second argument specifies the (standard) alignment of the information within the cells as used by LaTeX or man/ms. Use l for left-alignment, c for centered-alignment and r for right alignment. Its third argument defines the contents of the table which are the rows, each containing column-specifications and optionally man/ms alignment definitions for this row.

### 4.2.179: tcell(text)

Roff helper to set a table textcell, i.e., a paragraph. For LaTeX special table formatting p{} should be used.

### 4.2.180: telycommand(cmd)

Writes cmd to the output when converting to tely. The cmd is not further expanded by Yodl.

The TeX symbol.

### 4.2.182: texinfocommand(cmd)

Writes cmd to the output when converting to texinfo. The cmd is not further expanded by Yodl.

### 4.2.183: tindex()

Generate an index entry for index t.

### 4.2.184: titleclearpage()

Forces the generation of a clearpage() directive following the title of a document. This is already the default in books and reports, but can be overruled with notitleclearpage(). When present, must appear in the preamble; i.e., before the document type is stated with article, book or report.

### 4.2.185: tocclearpage()

With the LaTeX convertor, a clearpage() directive if inserted, immediately following the document's table of contents. This is already the default in all but the article document type, but it can be overruled by notocclearpage(). When present, it must appear in the preamble; i.e., before the document type is stated with article, book or report. With other convertors than the LaTeX convertor, it is ignored.

### 4.2.186: tt(text)

Sets text in teletype font, and prevents it from being expanded. For unbalanced parameter lists, use CHAR(40) to get ( and CHAR(41) to get ).

### 4.2.187: txtcommand(cmd)

Writes cmd to the output when converting to txt. The cmd is not further expanded by Yodl.

### 4.2.188: url(description)(locator)

In LaTeX documents the description is sent to the output. For HTML, a link is created with the descriptive text description and pointing to locator. The locator should be the full URL, including service; e.g, http://www.icce.rug.nl, but excluding the double quotes that are necessary in plain HTML. Use the macro link to create links within the same document. For other formats, something like description [locator] will appear.

### 4.2.189: verb(text)

Sets text in verbatim mode: not subject to macro expansion or character table expansion. The text appears literally on the output, usually in a teletype font (that depends on the output format). This macro is for larger chunks, e.g., listings. For unbalanced parameter lists, use CHAR(40) to get ( and CHAR(41) to get ).

### 4.2.190: verbinclude(filename)

Reads filename and inserts it literally in the text, set in verbatim mode. not subject to macro expansion.The text appears literally on the output, usually in a teletype font (that depends on the output format). This macro is an alternative to verb(...), when the text to set in verbatim mode is better kept in a separate file.

NOTE: Starting with Yodl version 3.00.0 Yodl's default file inclusion behavior has changed. The current working directory no longer remains fixed at the directory in which Yodl is called, but is volatile, changing to the directory in which a yodl-file is located. This has the advantage that Yodl's file inclusion behavior now matches the way C's #include directive operates; it has the disadvantage that it may break some current documents. Conversion, however is simple but can be avoided altogether if Yodl's -L (--legacy-include) option is used.

### 4.2.191: verbpipe(command)(text)

Pipe text through command, but don't expand the output.

### 4.2.192: vindex()

Generate an index entry for index v.

### 4.2.193: whenhtml(text)

Sends text to the output when in HTML conversion mode. The text is further expanded if necessary.

### 4.2.194: whenlatex(text)

Sends text to the output when in LATEX conversion mode. The text is further expanded if necessary.

### 4.2.195: whenman(text)

Sends text to the output when in MAN conversion mode. The text is further expanded if necessary.

### 4.2.196: whenms(text)

Sends text to the output when in MS conversion mode. The text is further expanded if necessary.

### 4.2.197: whensgml(text)

Sends text to the output when in SGML conversion mode. The text is further expanded if necessary.

### 4.2.198: whentely(text)

Sends text to the output when in TELY conversion mode. The text is further expanded if necessary.

### 4.2.199: whentexinfo(text)

Sends text to the output when in TEXINFO conversion mode. The text is further expanded if necessary.

### 4.2.200: whentxt(text)

Sends text to the output when in TXT conversion mode. The text is further expanded if necessary.

### 4.2.201: whenxml(text)

Sends text to the output when in XML conversion mode. The text is further expanded if necessary.

### 4.2.202: xit(itemname)

Starts an xml menu item where the file to which the menu refers to is the argument of the xit() macro. It should be used as argument to xmlmenu(), which has a 3rd argument: the default path prefixed to the xit() elements.

This macro is only available within the xml-conversion mode. The argument must be a full filename, including .xml extension, if applicable.

No .xml extension indicates a subdirectory, containing another sub-menu.

### 4.2.203: xmlcommand(cmd)

Writes cmd to the output when converting to xml. The cmd is not further expanded by Yodl.

Starts an xmlmenu. Use itemization() to define the items. Only available in xml conversion. The menutitle appears in the menu as the heading of the menu. The menulist is a series of xit() elements, containing the name of the file to which the menu refers as their argument (including a final /). Prefixed to evert every xit()-element is the value of XXdocumentbase.

Order is the the order' of the menu. If omitted, no order is defined.

### 4.2.205: xmlnewfile()

In XML output, starts a new file. All other formats are not affected. Note that you must take your own provisions to access the new file; say via links. Also, it's safe to start a new file just befoore opening a new section, since sections are accessible from the clickable table of contents. The XML converter normally only starts new files prior to a chapter definition.

### 4.2.206: xmlsetdocumentbase(name)

Defines name as the XML document base. No default. Only interpreted with xml conversions. It is used with the figure and xmlmenu macros.

### 4.2.207: xmltag(tag)(onoff)

Similar to htmltag, but used in the XML converter.

## 4.3: Conversion-related topics

### 4.3.2: Conversion-type specific literal commands

According to the format of the output file, the macro package defines a given symbol:
• latex when the output format is LaTeX,
• html when the output format is HTML,
• man when the output format is groff in conjunction with the man macro package,
• ms when the output format is groff with the ms package,
• sgml when the output format is SGML,
• txt when the output format is plain ASCII.
• xml when the output format is XML.
The defined symbol can be tested in a document to determine the conversion type.

Furthermore, the package defines the following macros to send literal text (commands in the output format) to the output file:

• latexcommand(cmd): sends the LaTeX command cmd when in LaTeX conversion mode. The cmd is not further expanded.
• htmlcommand(cmd): sends the HTML command cmd when in HTML conversion mode. The cmd is not further expanded.
• htmltag(tag)(onoff): sends <tag> to the output when onoff is nonzero, or sends </tag> when onoff is zero. Only active in HTML conversions.
• mancommand(cmd): sends cmd to the output when in man conversion mode. The cmd is not further expanded.
• mscommand(cmd): sends cmd to the output when in ms conversion mode. The cmd is not further expanded.
• roffcmd(dotcmd)(trailer)(secondline)(thirdline): sends a command to the output when in man or ms conversion mode. The dotcmd is the typical groff command that starts with a dot. All other arguments may be empty, but when given are interpreted as follows. The trailer follows the dotcmd on the same line. The secondline is sent on a separate line following the dotcmd and trailer. The thirdline is sent after that. Of the four arguments, dotcmd and thirdline are not subject to further expansion. All other arguments are further expanded if necessary.

The roffcmd macro illustrates the complexity of dot-commands for the divers groff macro packages. E.g., a section title for the man package should look as

.SH "Section Title"

while the same command for the ms macro package must be sent as
.SH
Section Title
.PP

The roffcmd macro can be used to send these commands to the output file as follows:
COMMENT(For the man output format:)
roffcmd(.SH)("Section Title")()()

COMMENT(For the ms output format:)
roffcmd(.SH)()(Section Title)(.PP)()

• sgmlcommand(cmd): sends the SGML command cmd when in SGML conversion mode. The cmd is not further expanded.
• sgmltag(tag)(onoff): sends <tag> when onoff is nonzero, or sends </tag> when onoff is zero. Only active in SGML conversions.
• txtcommand(cmd): implemented for compatibility reasons, though a command' in plain ASCII output doesn't make much sense. The usefulness of this macro is rather in the fact that it only produces output when in ASCII conversion mode.
The above commands can be used to quickly implement a macro. E.g., the macro package implements the it macro (which starts an item in a list) as:

DEFINEMACRO(it)(0)(
latexcommand(\item )
htmlcommand(<li> )
....
)

Depending on the output format, it() will lead to one of the above expansions.

The above described formatcommand() macros are implemented to send not further expanded strings (i.e., commands) to the output. The macro package also implements whenformat() macros to send any text, which is then subject to further expansion. These when...() macros are:

• whenlatex(text): sends text when in LaTeX conversion mode,
• whenhtml(text): sends text when in HTML conversion mode,
• whenman(text): sends text when in man conversion mode,
• whenms(text): sends text when in ms conversion mode,
• whentxt(text): sends text when in ASCII conversion mode,
• whensgml(text): sends text when in SGML conversion mode.
Once again, note that the difference between the whenformat() macros and the formatcommand() macros is, that the former will expand their argument while the latter will not. As an example, consider the following code fragment:

whenlatex(a LaTeX-generated
footnote(LaTeX is a great
document language!)
document)
whenhtml(a HTML document via your
favorite browser)

The whenformat() macros are used here to make sure that the arguments to the macros are further expanded; this makes sure that the footnote macro in the whenlatex block gets treated as a footnote.

### 4.3.3: Figures

Figures in format-independent documents are a problem. You cannot avoid contact with the final format (HTML, LaTeX or whatever) if you want to include figures in a text.

Yodl approaches figures as follows:

• Figures can only be included in LaTeX, HTML and XML documents.
• For LaTeX, you must prepare a picture in an external file that is included in the document as en encapsulated PostScript file. Incidentally, that means that epsf must be stated as one of the LaTeX styles using the latexoptions macro. The default, however, can be modified using the setlatexfigureext() macro.
The file in question is stated in Yodl without an extension. Yodl provides a default extension, .ps.
• For HTML and XML, you must prepare a picture in an external file that is placed in the document using the <img src=...> tag. The file must have the default extension (.jpg) or the extension specified with the sethtmlfigureext() macro.
• All other output formats do not include pictures in the document, but typeset something like insert figure .. here.
The macro to include a figure is called, appropriately, figure. It takes three arguments:
• The first argument is the filename. This name may include directories, but may not include the filename extension. The reason for this is, that Yodl supplies the correct extension once the output format is known.
• The second argument is the figure title, or the caption. Yodl prefixes this caption with the text Figure xx:, where xx is a number.
• The last argument is a label, which Yodl defines as a placeholder for the figure number.
For example, you might draw a picture or scan a photo and put it in a .jpg file, for usage with HTML documents. The conversion to PostScript could be automated, e.g., using a Yodl macro:

SYSTEM(xpmtoppm picture.xpm | pnmtops > picture.ps)

See section 3.1.67 for details about using the SYSTEM macro.

After this, you would be reasonably safe that the picture is available for both HTML and LaTeX output. The picture would be typeset in a figure using:

figure(picture)
(A photo of me.)
(photo)

Note how the first argument, the filename, does not contain an extension. The third argument, which is a label, can be used in, e.g.,

See figure ref(photo) for a photograph showing me.

Yodl has a several auxiliary macros, which are:
• fig(label): This macro is a shorthand for getfigurestring() ref(label). It just makes typing shorter, and is used as e.g.: See fig(photo) for a photograph. Note that the string figure that is generated by this macro can be (re)defined, see below.
• setfigurestring(name): This macro is similar to setchapterstring etc.. It defines the string that is used to identify a figure, and is (appropriately) figure by default. The macro getfigurestring() expands to the string in question. See also section 4.3.6.1 for a discussion of national language support.
• sethtmlfigureext(.new): This macro redefines the filename extension for HTML conversions from .gif to .new. Note that you must include a leading dot in the redefinition.
The new extension is used in the first following figure statement.
• sethtmlfigurealign(align): This redefines the alignment of figures in HTML, which is default bottom. Check your HTML handbook for possible options; top and center should be fairly standard.
• setlatexfigureext(.new): Redefines the extension from .ps to .new.

### 4.3.4: Fonts and sizes

Yodl's standard macro package supports the following macros to change fonts:
• bf(text): sets text in boldface.
• em(text): sets text emphasized, usually in italics.
• tt(text): sets text in teletype.
Furthermore, the tt() macro will not expand macros occurring inside its argument. That means that you can safely write:

In Yodl, you can use tt(includefile(somefile)) to include a file

The tt() macro should not be used for long listings of verbatim text; use verb() to set code samples etc..

Yodl's standard macro package has no commands to change font sizes, as the size is changed internally when appropriate (e.g., in section titles), nor is there a default macro to define other font-families.

### 4.3.5: Labels, links, references and URLs

References such as see ... for more information are very common in documents. Yodl supports three mechanisms to accomplish such references:

Labels and references:
Labels can be defined in a document as a placeholder for the last number used in a sectioning command. At other points in the document, references to those labels are used. The reference expands to the number, as in see section 1.3.

This mechanism is available in all output formats. Furthermore, the numeric reference (1.3 in the example of the previous paragraph) is in HTML a clickable reference that leads to the mentioned section.

This mechanism can be used to set links in a document without using the number of a sectioning command, as in see the introduction for more information, with the introduction being a clickable link to some label.

This mechanism of course only leads to a clickable link in HTML: in other formats the text see the etc. is just typeset as is.

URLs:
Universal Resource Locators (URLs) are used to create links to other HTML documents or services, like HTML's <a href=..> method. The URLs of course only result in clickable links in HTML output; in other output formats only some descriptive text appears.
The above mechanism is implemented by the following macros:
• The macro label(name) defines a label named name. The name of the label can be used in a ref or link macro.
• The macro ref(name) sets a reference to the label named name. The text of the reference is the number of the last sectioning command that was active during the creation of the label. When using references it is therefore important to define the corresponding labels right after a sectioning command, as in
section(How to install my program) label(howtoinstall)
This section describes...
...
See section ref(howtoinstall) for installation instructions.

The macro ref(howtoinstall) expands to the number of the section named How to install my program.
• The macro link(description)(name) always expands to the description. In HTML output, a clickable link is created pointing to a label called name. For example:
label(megahard)
COMMENT(sigh...)
The Jodel package isn't shareware, it isn't
beggarware, it isn't freeware, it's
bf(megahard-ware).
...

This code fragment would always set the text picosoft, but under HTML a clickable link would appear pointing to link(the text)(megahard).
• The macro url(description)(location) always expands to the description, but creates a hyperlink pointing to location in HTML. For example,
Take a look at my
url(homepage)(http://www.somwhere.nl/karel/karel.html).

The text homepage always appears, but only in HTML it is a link. (Note that the double quotes, which are necessary in HTML around the location, are not required by Yodl.) To use a different font in the description part, surrond it inside the url parameter list, as in:
The Yodl package can be obtained at the site tt(ftp.rug.nl) in the
directory url(tt(/contrib/frank/software/yodl))
(ftp://ftp.rug.nl/contrib/frank/software/yodl).

• The macro email(address) is a special case of url: under HTML, the address appears as a clickable link in slanted font to mail address. For example:
I can be reached at
email(f.b.brokken@rug.nl).

I can be reached at f.b.brokken@rug.nl.

Always keep in mind that the name of a label must be exactly identical in both the label macro and in the ref or link macro. Other than that, the name is irrelevant.

Furthermore, note that lincludefile is yet another macro defining a label: it includes a file and automatically creates a label just before the included file's text. That means that a Yodl file like:

chapter(Introduction)
sect(Welcome)
lincludefile(WELCOME)(welcome)

chapter(Technical information)
lincludefile(TECHINFO)(techinfo)

creates two labels: WELCOME and TECHINFO.
Here are some final thoughts about using labels and references:
• Don't put weird' characters in label names. Generally, don't use spaces and tabs.
• The name of the label is always only an internal symbol; it does not appear in the output. Therefore, constructions such as the following are not correct:
ref(em(labelname))

The reason for the incorrectness is, what internal name should em(labelname) generate? Here probably an attempt is made to set a reference in italics. The right construction is of course to set whatever ref() returns in italics, as in:
em(ref(labelname))

• The label macro should not appear nested inside another macro. There is no strict reason for this as far as Yodl is concerned; however, the processors of Yodl's output might go haywire. E.g., beware of the construction
section(Introduction label(intro))

The right form being
section(Introduction)label(intro)

(linking to intro will usually not show Introduction), or:
label(intro)section(Introduction)

(linking to intro will usually show Introduction), or:

### 4.3.6: Lists and environments

Yodl's default macros support the following lists and environments:

By default, the following lists are available:

Description lists:
A description list consists of a list of elements, where each element starts with a short (usually bold faced) description. The description list is generated by the description() macro. The elements of the list start with dit(). The dit() macro expects a short description of the item.

Example:

A description list:
description(
dit(First this:) One item.
dit(Then this:) Another item.
)

Enumeraton lists:
An enumeration list consist of sequentially numbered elements. The list is generated by the enumeration() macro. Its elements start with the eit() macro.

Example:

An enumerated list:
enumeration(
eit() One item.
eit() Another item.
)

Itemized lists:
An itemized lists consists of indented items, usually preceded by a bullet.

An itemized list is produced by the itemization() macro, which has one argument: the items themselves. These items must start with it().

Example:

An itemized list:
itemization(
it() One item.
it() Another item.
)

Specialized environments are:

Centered text:
Centering text may not be available in all output formats. When unavailable, the text is typeset left-flushed.

Centered text is generated by the center() macro. Line brakes within centered text may be obtained using the nl() macro.

Example:

center(
Centered text. nl()
Another line of centered text.
)

Verbatim text:
Verbatim text appears on the output exactly in the same layout as it is in the input file. Typesetting text in verbatim mode is useful for, e.g., source files. Depending on the output format, the font of the verbatim text is changed to a teletype font.

The text must either be inside the verb() macro. For example:

verb(
This is totally verbatim text.
It is not further processed by Yodl.
)

The verbatim text is of course not subject to macro expansion by Yodl. Note, however, that SUBST transformations will take place, as these substitutions take place during the lexical scanning phase of Yodl's input, and are not part of the macro-expansion process. See also section 3.1.65.

Furthermore, if a character translation table has been defined, the argument of the verb() macro will also be subject to character table transformations. By temporarily suppressing the active character table (see section PUSHCHARTABLE 3.1.56) this can be prevented.

Quotations:
Quotations are usually indented with respect to their surrounding text. It is for the author to decided whether the quoted text should be typeset normally, or that it should be bold-faced or emphasized. To insert a quotation use the quote() macro:

Shakespeare once wrote:
quote(
To be or not to be, that's the question''
)

#### 4.3.6.1: National language support

Yodl includes rudimentary national language support (NLS), in the sense that it allows you to redefine the strings identifying chapters or parts, or the strings identifying figures. E.g., a command chapter(Introduction) will by default result in the text Chapter 1: Introduction.

Using the setchapterstring(text) macro, the Chapter text can be redefined. E.g., in a Dutch text you might put

setchapterstring(Hoofdstuk)

somewhere near the beginning of your document. Similar to setchapterstring, a macro getchapterstring exists returning the text identifying chapters. (Internally, getchapterstring is of course used to actually set the text). To redefine the text to identify a part, use setpartstring(text); to redefine the text to identify a figure, use setfigurestring(text).

The set....string macros only influence how Yodl names chapters or parts in HTML, man, ms or txt output. LaTeX output is not affected, since LaTeX does its own NLS. Usually, NLS is present for LaTeX as a style file' named, e.g., dutch.sty. Therefore, if you want a Dutch document, you need to:

• put latexpackage(dutch)(babel)in the preamble of the document. This ensures that LaTeX uses Dutch abbreviation rules.
• redefine the chapter and part names for non-LaTeX output, using:
setlanguage(dutch)

• Finally, you should probably type your text in Dutch.
The setlanguage() macro expects one argument: the name of the language that is used. See section 4.2 for details about this macro. The setlanguage() macro redefines the language-dependent section (and other) headers, and depends on the availability of the corresponding language<name>() macro, where <name> is the name of the language (by convention <name> states the english name of the language). Currently, languagedutch(), languageenglish() (the default), and languageportugese() are available. It's easy to expand this little set with macros for other languages. The setlanguage() macro merely requires the specification of the language. For example:

setlanguage(english)

This macro installs the following defaults (corresponding translations should be defined for other languages):

setaffilstring(Affiliation)
setauthorstring(Author)
setchapterstring(Chapter)
setdatestring(Date)
setfigurestring(Figure)
setpartstring(Part)
settitlestring(Title)

Yodl inserts page-breaks in a limited number of cases:
• A pagebreak is generated after the title information in book and report documents.
So, when a document has both title information and a table of contents then whatever follows next will normally be starting on a separate page. Furthermore, if the document is a book or a report, the title and table of contents will also be separated by a pagebreak.

This behavior can be modified using the (no)titleclearpage() and (no)tocclearpage() directives, further described in section 4.3.8.

### 4.3.7: Sectioning

This section describes the sectioning commands for articles, reports, books and for plainhtml. The document type manpage defines its own sectioning commands (cf. section 4.1.2:
• part(title): Starts a new part. Only available in book documents.
• chapter(title): Starts a new chapter. Only available in book or report documents.
• sect(title): Starts a section.
• subsect(title): A subsection.
• subsubsect(title): A sub-subsection.
• subsubsubsect(title): An even smaller sectioning command.
These macros generate entries in the table of contents and use numbering, which means that each section is prefixed with a number (1, 1.1, 1.2, and so on). The macros are also available with an n prefix (npart, nchapter, nsect etc.) which generate neither entries in the table of contents nor numbers. The n-versions can be used in, e.g., an article where the sectioning commands should show their captions, but not any numbers generated by default.

Sectioning should always start at the top level sections of the available document: chapter for reports, sect for articles, etc.. If you start a document with a lower sectioning command (e.g., when you start an article with a subsect), the numbering of sections may go haywire. The only exception to this rule is the part of a book document: parts are optional, in books, chapters may be the top sectioning commands. Summarizing, books or reports should start with chapter. Articles should start with sections.

The sectioning commands have a further function: when label statements appear after the sectioning command, then a label name is used as a placeholder for the last generated number. This is further described in section 4.3.5.

### 4.3.8: Typesetting modifiers

This section lists various macros that can be used to modify the looks of your document. When used, these macros must appear before stating the document type with article, report, book, manpage or plainhtml.
• abstract(text): This macro is relevant for all output formats. The text is added to the document after the title, author and date information, but before the table of contents. The abstract is usually set as a quote, in italics font (though this depends on the output format). Abstracts are supported in articles and reports, but not in other document types. I.e., if you need introductory text in a book, you should start with a non-numbered chapter that holds this text.
• affiliation(site): This macro is relevant for article, report and book documents. It defines the affiliation of the author. The site information appears in the title, below the author's name.
• htmlbodyopt(option)(value): This macro adds option="value" to the <body> tag that will be generated for HTML output. The HTML converter generates <body> tags each time that a new file is started; i.e., at the top of the document and at each chapter-file. Different HTML browsers support different <body> tag options, but useful ones may be e.g.:
htmlbodyopt(fgcolor)(#000000)
htmlbodyopt(bgcolor)(#FFFFFF)

This defines the foreground color as pure white (red/green/blue all 0) and the background color as black (red/green/blue all hexadecimal FF, or 255). Another useful option may be htmlbodyopt(background) (some.gif), defining some.gif as the page background.

Note that value is automatically surrounded by double quotes when this macro is used. They should not be used by authors using this macro.

• latexdocumentclass(class): This macro forces the \documentclass{...} setting in LaTeX output to class.
• latexlayoutcmds(commands): This macro can be used to specify your own LaTeX layout commands. When present, the commands are placed in LaTeX output following the \documentclass definition.
• latexoptions(options): This macro is only relevant for LaTeX output formats, it is not expanded in other formats. The options are used in LaTeX's \documentclass definition; e.g., a useful option might be dina4. Multiple options should be separate by commas, according to the LaTeX convention.
• latexpackage(options)(name): This macro is only relevant for LaTeX output formats, it is not expanded in other formats. Each package should have its own latexpackage() statement. If there are no options, the options argument should remain empty. Here is an example using this macro:
latexpackage(dutch)(babel)

• mailto(email): The mailto macro is only expanded in HTML documents, it is ignored in other formats. It defines where mail about the document should be sent to.
• nosloppyhfuzz(): By default, the LaTeX output contains the text
\hfuzz=4pt

which is placed there by the macro package. This suppresses overfull hbox warnings of LaTeX when the overfull-ness is less than 4pt. Use nosloppyhfuzz() to get the standard LaTeX warnings about overfull hboxes.
• notableofcontents(): As the name suggests, this macro suppresses the generation of the table of contents. For HTML that means that no clickable index of sections appears after the document title.

• notitleclearpage(): Normally, Yodl inserts a clearpage() directive after typesetting title information in book or report documents, but not in article documents. Use notitleclearpage to suppress this directive.
• notocclearpage() (no table-of-contents clear-page): In all document types, Yodl inserts a clearpage() directive following the table of contents. Use notocclearpage() to suppress that.
• noxlatin(): The LaTeX output contains by default the command to include the file xlatin1.tex, distributed with Yodl. This file maps Latin-1 characters to LaTeX-understandable codes and makes sure that you can type characters such as ü, and still make them processable by LaTeX. If you don't want this, put noxlatin() in the preamble.
• standardlayout(): This is another LaTeX option. Use standardlayout() to get vanilla' LaTeX layout, possibly indenting paragraphs and using fairly limited vertical spacing between paragraphs. This macro is ignored for other conversion types.
• titleclearpage(): Forces the insertion of a clearpage() directive after the title information has been typeset. This behavior is the default in book and report documents. See also notitleclearpage().
• tocclearpage(): Forces the insertion of a clearpage() directive following the table of contents. This behavior is default in all document types; the macro is provided for consistency reasons with (no)titleclearpage().
Note again: these modifiers must appear before the document type definition.

### 4.3.9: Miscellaneous commands

The following is a list of commands that don't fall in one of the above categories.
• clearpage(): This macro starts a new page in LaTeX. For HTML, a horizontal rule is shown. (Note that the macro package sometimes inserts new pages by itself; e.g., following a table of contents. See also section 4.3.8 for a discussion of (no)titleclearpage() and (no)tocclearpage().)
• def(macro)(nrofarguments)(definition): This defines a new macro macro having nrofarguments arguments, and expanding to definition. The markers ARGx, where x is 1, 2, etc., can be used in the definition part to indicate where arguments should be pasted in. This macro is a shorthand for DEFINEMACRO, see section 3.1.11.
• footnote(text): This macro sets text as a footnote when the output format allows it. When not, the text is set in parentheses.
• gagmacrowarning(name name ...): This macro suppresses yodl's warnings cannot expand possible user macro name, where name is a candidate macro name. gagmacrowarning is a synonym for NOUSERMACRO, described in section 3.1.45.
E.g., if your document contains "as for manpages, see sed(1), tr(1) and awk(1)", and if you get tired of warnings about possible user macros sed, tr and awk, try the following:
gagmacrowarning(sed tr awk)
...
As for manpages, see sed(1), tr(1) and awk(1).

• htmlnewfile(): Starts a new subfile in HTML output. This stanza is also automatically generated when the HTML converter encounters a chapter directive. Using htmlnewfile, the output can be split at any point. However make sure that the subfile is still reachable; e.g., by creating a clickable link with label and ref, or label and link.
• includefile(file): Includes file and defines a label (see the label macro) with the same name. Furthermore, a message about the inclusion is shown on the screen. The file is searched for relative to the directory of the file in which the includefile macro was used (or relative to the directory where the yodl run was started when the --legacy-include or -L option was provided) and also in the system-wide include directory. The default extension .yo is supplied if necessary.
The lincludefile macro is handy in the following situation:
chapter(Introduction)
lincludefile(INTRO)(intro)

This fragment starts a chapter and includes a file. Here the label name (INTRO) can also be used to refer to the chapter as the lincludefile stanza appears immediately following the corresponding sectioning command.
• nl(): Forces a new line. Some output formats may produce an error upon the usage of nl() in unexpected' places; e.g., LaTeX won't allow new lines in the footnote text (as defined in the footnote macro). Using nl() in running text should however be ok. Example:
This line is nl()
broken in two.

• redefinemacro(macro)(nrofargs)(redef): This command (re)defines a macro, expecting nrofargs arguments, to redef. If a previous definition of the macro existed, it is overruled. Example:
redefinemacro(clearpage)(0)(\
em(---New page starts here---))

Use ARGx in the redef part to indicate where all arguments should occur, as in the following imaginary macro to typeset a literature reference:
redefinemacro(litref)(3)(
Title: bf(ARG1) nl()
Author(s): em(ARG2) nl()
)
...
litref(Java in a Nutshell)
(David Flanagan)
(O'Reilly & Associates, Inc.)

The redefinemacro statement also has a shorthand called redef.

## 4.4: Locations of the macros

The files defining the macros are by default installed to the directory /usr/local/share/yodl during Yodl's installation process (Note that this diverts from an earlier default: /usr/local/lib/yodl; furthermore, some systems or some distributions may use other locations).

The files in this directory are organized as follows:

• The files that should be read for a particular conversion are named after their conversion, e.g., latex.yo and html.yo. These files must be processed by Yodl before your document can be converted accordingly. The provided yodl2... scripts take care of that automatically.
• All support counters, symbols and macros are defined in files named std.<conversion>.yo, e.g., std.html.yo, std.latex.yo. These files may be modified without notice, and are an essential part of the Yodl macros. They should not be modified by hand, as they are created by the macro generating process.
• The predefined character tables are found in files names chartables/<conversion>.yo.
The (binary) Yodl package contains the following programs and support files:
• The yodl program itself, which generates converted document(s);
• The yodlpost postprocessor, which performs fixups for conversion formats. Using yodlpost is required for formats whose documents cannot be created in one pass by yodl itself;
• Auxiliary scripts such as yodl2tex, yodl2html;
• The macros and character tables for the various conversion types;
• The raw macros and the macro-generating scripts;
• The documentation (html and manual pages)
The source Yodl package contains all the sources files, installation guides, change-logs etc., that are required to compile the binary programs. Those who want to compile Yodl themselves, must have a C compiler (preferably the Gnu C compiler) available, and preferably the icmake program maintenance utility. Basic support for make is provided as well.