<html>
<head>
<title> Yodl 3.00.0 </title>
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<ul>
<li> <a href="yodl.html">Table of Contents</a>
<li> <a href="yodl03.html">Previous Chapter</a>
<li> <a href="yodl05.html">Next Chapter</a>
</ul>
<hr>
<a name="MACROPACKAGE"></a><a name="l106"></a>
<h1>Chapter 4: Macros and Document types</h1>
The macro package distributed with <code>Yodl</code> 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:
<ul>
<li> HTML;
<li> LaTeX (plain LaTeX, no <code>latex2e</code>);
<li> The <code>groff</code> `man' format which is used for man pages;
<li> The <code>groff</code> `ms' format which is more expressive;
<li> Basic, plain text
</ul>
<p>
The following conversion format is in an experimental stage:
<ul>
<li> XML, as used by the University of Groningen's so-called
`webplatform'.
</ul>
<p>
Currently discontinued conversion formats are:
<ul>
<li> SGML, although the basic macros are available. SGML can probably be
reactivated fairly quickly. Contact the maintainer if support for SGML should
be reinstated
<li> texinfo, mainly due to the fact that the current maintainer doesn't
know what the required <em>post-processing</em> actions are.
<li> tely, since this conversion format is unknown to the current
maintainer.
</ul>
<p>
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.
<p>
<a name="l107"></a>
<h2>4.1: General structure of a Yodl document</h2>
This section describes the general format of a Yodl document.
<p>
First of all, a Yodl document needs a <em>preamble</em>. 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.
<p>
Modifiers are often specific for a particular target document type
(e.g., <code>latexoptions</code> or <code>mailto</code>), but may also have a general nature
(e.g., <code>affiliation</code> or <code>abstract</code>). All modifiers are used to modify
parameters of document types. Therefore, they must be specified before the
document type is defined.
<p>
All modifiers are listed in section <a href="yodl04.html#MODIFIERS">4.3.8</a>. In general, you should use
as many modifiers as appropriate. E.g., you should define a <code>mailto</code> 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 <code>mailto</code> even
for non-HTML output formats.
<p>
Following the modifiers, the <em>document type</em> is defined. The document type
is either <code>article</code>, <code>report</code>, <code>book</code>, <code>plainhtml</code> or <code>manpage</code>.
Except for the <code>manpage</code> document type, which is a highly specialized
document type, described in section <a href="yodl04.html#MANPAGE">4.1.2</a>, the following rules apply:
<p>
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 <em>article</em> might be written as an accessible
<em>report</em>, combining related sections into chapters. Similarly, the structure
of a report having 30 chapters might improve when it's re-organized as a
<em>book</em> 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..
<p>
The document type influences the way Yodl formats the output. An <code>article</code>
(or <code>plainhtml</code>) 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
<code>report</code>s and <code>books</code> 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 <code>report</code> or <code>book</code>.
<p>
Documents using special macros, must have defined these macros <em>before</em> they
are used. An appropriate location for these macros is immediately beyond the
preamble. E.g., see the file <code>Documentation/manual/manual.yo</code> distributed
with the Yodl package. This is the main file of this manual, showing the
preferred organization of Yodl files.
<p>
To answer <em>yes-but-what-if</em> oriented minds, here are two results of the
wrong order of text, preamble and modifiers:
<ul>
<li> 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 <code><html></code> tag would come too
late in a HTML conversion, causing the HTML browser to become confused. Or,
the <code>\documentstyle</code> definition would be seen too late by the LaTeX
typesetter.
<li> If you put modifiers, such as <code>latexoptions</code>, <em>beyond</em> 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 <strong>following</strong> the stage where they are needed..
</ul>
<p>
<a name="l108"></a>
<h3>4.1.1: Document types</h3>
As distributed, Yodl supports four document types: <em>article, report,
book</em> and the <em>manual</em> 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 <code>.dvi</code> file. Nevertheless, some
formats are particularly usefule for some document types. A book converted to
the <code>man</code> output format to be processed later with <code>groff</code> won't look too
good. Its looks would greatly improve when the document would be converted to
ASCII using the <code>ms</code> output format.
<p>
Following the preamble and the definition of specialized macros symbols and
counters, documents start by specifying the document type. The available
macros are:
<ul>
<li> <code>article(title)(author)(date)</code>: The <code>article</code> document type
should be used for short documents. Its arguments specify the document's
title, author and date.
<p>
In articles, the title page is numbered and the table of contents is on
the title page. The sectioning commands <code>sect</code>, <code>subsect</code> etc. are
available.
<li> <code>report(title)(author)(date)</code>: The <code>report</code> document type differs
from an <code>article</code> 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
<code>chapter</code> in addition to the ones supported by <code>article</code>s. A <code>report</code>
should be used fir larger documents.
<li> <code>book(title)(author)(date)</code>: The <code>book</code> type is for even larger
documents. In addition to the sectioning commands supported by <code>report</code> it
supports the sectioning command <code>part</code>.
<li> <code>plainhtml(title)</code>: 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 <code>article</code>, but does not require you to specify
<code>author</code> and <code>date</code> arguments (In fact, you can emulate <code>plainhtml</code> by
using an <code>article</code>, using empty author and date arguments).
<li> <code>manpage(title)(section)(date)(source)(manual)</code>: The <code>manpage</code>
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 <a href="yodl04.html#MANPAGE">4.1.2</a>.
</ul>
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 <code>\documentstyle</code>
preamble, HTML output needs <code><html></code> and <code><body></code> tags.
<p>
Second, the macros define appropriate document-dependent settings. E.g., the
LaTeX converter defines the title, author and date using <code>\title</code> etc..
<p>
Third, the actual document is started. E.g., for LaTeX this means a
<code>\begin{</code><em>type</em><code>}</code>, followed by the appropriate commands to generate a
the document title and the table of contents. The <code>title</code> 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 <code><title></code> tag.
<p>
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
<em>modifiers</em>, appearing <em>before</em> the document type macros, to insert
information between the various elements of a document definition.
<p>
<a name="MANPAGE"></a><a name="l109"></a>
<h3>4.1.2: The manpage document type</h3>
The <em>manpage</em> document type was implemented to simplify the construction of
Unix-style manual pages. A <em>manpage</em> document <strong>must</strong> be organized as
follows:
<ol>
<li> The manual page itself is defined, using the macro
<pre>
manpage(short title)
(section)
(date)
(source)
(manual)
</pre>
Its arguments are:
<dl>
<p><dt><strong>Short title:</strong><dd> This should be the program name or something
similar; i.e., whatever the manpage is describing.
<p><dt><strong>Section:</strong><dd> A number, stating the manpage section. The Linux man (7)
page recognizes the following manpage sections:
<ul>
<li> Section 1 is for commands, like <code>ls</code>;
<li> Section 2 is for system calls, like <code>fork()</code>;
<li> Section 3 is for library calls, like <code>strdup()</code>;
<li> Section 4 is for special files (like <em>devices</em>);
<li> Section 5 is for file formats, (like <code>syslog.conf</code>);
<li> Section 6 is for games;
<li> Section 7 is for macro packages and conventions;
<li> Section 8 is for system management commands;
<li> Section 9 is for other types of manpages, such as kernel
commands.
</ul>
<p><dt><strong>Date:</strong><dd> The date of release.
<p><dt><strong>Source:</strong><dd> The package where the manpage belongs to.
<p><dt><strong>Manual:</strong><dd> The manual to which the package belongs.
</dl>
The arguments of the <em>manpage</em> macro define, e.g., the headers and
footers of the manual page. The <code>date</code>, <code>source</code> and <code>manual</code> arguments
can be empty.
<li> The subject of the manpage is defined using
<pre>
manpagename(name)(short description)
</pre>
The <code>name</code> argument should be a short name (e.g., the program name), and
the <code>short description</code> should state the function. The descriptive argument
is used by, e.g., the <code>whatis</code> database.
<li> The synopsis starts after:
<pre>
manpagesynopsis()
</pre>
Following this, an abbreviated usage information is presented. This
information should show, e.g., the possible program flags and required
arguments; but no more.
<li> The description is given after:
<pre>
manpagedescription()
</pre>
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.
<li> Options are expected after:
<pre>
manpageoptions()
</pre>
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 <code>manpageoptions()</code> section is optional.
<li> Necessary files are listed after:
<pre>
manpagefiles()
</pre>
<li> The `see also' entry is defined by:
<pre>
manpageseealso()
</pre>
This is then followed by a list of related manual pages. Here, use the
format <code>bf(topic)(sectionnr)</code>, e.g., <code>Yodl</code>(1).
<li> Diagnostics are described after:
<pre>
manpagediagnostics()
</pre>
Diagnostics can state, e.g., what error messages are produced by the
program and what the cure is.
<li> Known bugs should be mentioned after:
<pre>
manpagebugs()
</pre>
This section is optional.
<li> Finally, the author is stated after:
<pre>
manpageauthor()
</pre>
</ol>
The <code>manpage</code> document type <strong>requires</strong> 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
(<code>sect</code>, <code>subsect</code> etc.) are not allowed in a <code>manpage</code>. You <em>can</em>
however insert other sections in the manual page with the macro
<code>manpagesection</code>. 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.
<p>
As an example, the manual page for the <code>yodl</code> program follows (the
actual manual page may differ):
<pre>
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
</pre>
<p>
<a name="MACROLIST"></a><a name="l110"></a>
<h2>4.2: Predefined macros</h2>
This section describes all macros defined by default. Altering or removing
these macros may produce unexpected results when converting <code>Yodl</code> documents to
other formats. Furthermore, these macros often depend on macros or other
symbols defined for internal use.
<p>
Many predefined macros depend on symbols start with <code>XX</code>. Therefore, it is
strongly advised not to start any locally defined symbol with <code>XX</code> as doing
so, or undefining existing symbols starting with <code>XX</code>, may also produce
unexpected results.
<p>
Here are the default macros, alphabetically ordered:
<p>
<a name="l111"></a>
<h3>4.2.1: abstract(text)</h3>
<p>
Defines an abstract for an <code>article</code> or <code>report</code> document. Abstracts are
not implemented for <code>book</code>s or <code>manpage</code>s. Must appear <strong>before</strong>
starting the document with the <code>article</code> or <code>report</code> macro.
<p>
<a name="l112"></a>
<h3>4.2.2: addntosymbol(symbol)(n)(text)</h3>
<p>
Adds <code>text</code> <code>n</code> times to <code>symbol</code>. The value <code>n</code> may also be the name
of a defined counter (which itself will not be modified).
<p>
<a name="l113"></a>
<h3>4.2.3: affiliation(site)</h3>
<p>
Defines an affiliation, to appear in the document titlepage below the
author field. Must appear <strong>before</strong> starting the document with
<code>article</code>, <code>report</code> or <code>book</code>. The affiliation is only printed when the
author field is not empty.
<p>
<a name="l114"></a>
<h3>4.2.4: AfourEnlarged()</h3>
<p>
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.
<p>
<a name="l115"></a>
<h3>4.2.5: appendix()</h3>
<p>
Starts appendices
<p>
<a name="l116"></a>
<h3>4.2.6: article(title)(author)(date)</h3>
<p>
Starts an article. The top-level sectioning command is <code>(n)sect</code>. In HTML
conversions only one output file is written.
<p>
<a name="l117"></a>
<h3>4.2.7: bf(text)</h3>
<p>
Sets <code>text</code> in boldface.
<p>
<a name="l118"></a>
<h3>4.2.8: bind(text)</h3>
<p>
Generate a binding character after text.
<p>
<a name="l119"></a>
<h3>4.2.9: book(title)(author)(date)</h3>
<p>
Starts a book document. The top-level sectioning command is <code>(n)chapter</code>,
<code>(n)part</code> being optional. In HTML output files are created for each
chapter.
<p>
<a name="l120"></a>
<h3>4.2.10: cell(contents)</h3>
<p>
Sets a table cell, i.e., one element in a row. With the man/ms converters
multiple blanks between <code>cell()</code> macro calls are merged into a single blank
character.
<p>
<a name="l121"></a>
<h3>4.2.11: cells(nColumns)(contents)</h3>
<p>
Set a table cell over <code>nColumns</code> columns. In html, LaTeX and xml formats
the information in the combined cells will be centered. With man/ms
conversions the <code>cells()</code> macro simply calls the <code>cell()</code> macro, but here
the <code>setmanalign()</code> macro can be used to determine the alignment
of multiple cells.
<p>
<a name="l122"></a>
<h3>4.2.12: cellsline(from)(count)</h3>
<p>
Sets a horizontal line starting at column number <code>from</code> over <code>count</code>
columns in a row. If <code>from</code> is less then the number of columns already added
to a row then it is ignored. This macro must be embedded in a <code>row</code> macro
defining a table row. To put a line across the table's full width use
<code>rowline</code>. To set horizontal lines across columns 1
until 2 and columns 4 until 5 table of a table use:
<pre>
row(cellsline(1)(2)cellsline(4)(2))
</pre>
Combining <code>cellsline</code> and <code>cell</code> or <code>cells</code> calls in one row produces
undefined results.
<p>
<a name="l123"></a>
<h3>4.2.13: center(text)</h3>
<p>
Sets <code>text</code> centered, when the output format permits. Use <code>nl()</code> in the
text to break lines.
<p>
<a name="l124"></a>
<h3>4.2.14: chapter(title)</h3>
<p>
Starts a new chapter in <code>book</code>s or <code>report</code>s.
<p>
<a name="l125"></a>
<h3>4.2.15: cindex()</h3>
<p>
Generate an index entry for index c.
<p>
<a name="l126"></a>
<h3>4.2.16: cite(1)</h3>
<p>
Sets a citation or quotation
<p>
<a name="l127"></a>
<h3>4.2.17: clearpage()</h3>
<p>
Starts a new page, when the output format permits. Under HTML a horizontal
line is drawn.
<p>
<a name="l128"></a>
<h3>4.2.18: code(text)</h3>
<p>
Sets <code>text</code> in code font, and prevents it from being expanded.
For unbalanced parameter lists, use <code>CHAR(40)</code> to get
<code>(</code> and <code>CHAR(41)</code> to get <code>)</code>.
<p>
<a name="l129"></a>
<h3>4.2.19: columnline(from)(to)</h3>
<p>
Sets a horizontal line over some columns in a row. Note that <code>columnline</code>
defines a row by itself, consisting of just a horizontal line spanning some of
its columns, rather than the table's full width, like <code>rowline</code>. The two
arguments represent column numbers. It is the responsibility of the author to
make sure that the <code>from</code> and <code>to</code> values are sensible. I.e.,
<pre>
1 <= from <= to <= ncolumns
</pre>
<strong>Note</strong>: this macro cannot be used if multiple lines must be set in one
row. In those cases the macro <code>colsline</code> should be used.
<p>
<a name="l130"></a>
<h3>4.2.20: def(macroname)(nrofargs)(redefinition)</h3>
<p>
Defines <code>macroname</code> as a macro, having <code>nrofargs</code> arguments, and
expanding to <code>redefinition</code>. This macro is a shorthand for
<code>DEFINEMACRO</code>.
An error occurs when the macro is already defined. Use
<code>redef()</code> to unconditionally define or redefine a macro.
<p>
<a name="l131"></a>
<h3>4.2.21: description(list)</h3>
<p>
Sets <code>list</code> as a description list. Use <code>dit(item)</code> to
indicate items in the list.
<p>
<a name="l132"></a>
<h3>4.2.22: dit(itemname)</h3>
<p>
Starts an item named <code>itemname</code> in a descriptive list. The list is either
enclosed by <code>startdit()</code> and <code>enddit()</code>, or is an argument to
<code>description()</code>.
<p>
<a name="l133"></a>
<h3>4.2.23: eit()</h3>
<p>
Indicates an item in an enumerated list. The <code>eit()</code> macro should be
an argument in <code>enumerate()</code>.
<p>
<a name="l134"></a>
<h3>4.2.24: ellipsis()</h3>
<p>
Sets ellipsis (...).
<p>
<a name="l135"></a>
<h3>4.2.25: em(text)</h3>
<p>
Sets <code>text</code> as emphasized, usually italics.
<p>
<a name="l136"></a>
<h3>4.2.26: email(address)</h3>
<p>
In HTML, this macro sets the <code>address</code> in a <code><a href="mailto=.."></code>
locator. In other output formats, the <code>address</code> is sent to the output. The
<code>email</code> macro is a special case of <code>url</code>.
<p>
<a name="l137"></a>
<h3>4.2.27: endcenter()</h3>
<p>
DEPRECATED. Use center().
<p>
<a name="l138"></a>
<h3>4.2.28: enddit()</h3>
<p>
DEPRECATED. Use description().
<p>
<a name="l139"></a>
<h3>4.2.29: endeit()</h3>
<p>
DEPRECATED. Use enumeration().
<p>
<a name="l140"></a>
<h3>4.2.30: endit()</h3>
<p>
DEPRECATED. Use itemization().
<p>
<a name="l141"></a>
<h3>4.2.31: endmenu()</h3>
<p>
DEPRECATED. Use menu().
<p>
<a name="l142"></a>
<h3>4.2.32: endtable()</h3>
<p>
DEPRECATED. Use table().
<p>
<a name="l143"></a>
<h3>4.2.33: enumerate(list)</h3>
<p>
DEPRECATED. Use enumeration().
<p>
<a name="l144"></a>
<h3>4.2.34: enumeration(list)</h3>
<p>
<code>enumeration()</code> starts an enumerated list. Use <code>eit()</code> in the list to
indicate items in the list.
<p>
<a name="l145"></a>
<h3>4.2.35: euro()</h3>
<p>
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. <a href="http://ec.europa.eu/euro/entry.html">http://ec.europa.eu/euro/entry.html</a>) is written. Note that LaTeX
may require latexpackage()(eurosym).
<p>
<a name="l146"></a>
<h3>4.2.36: fig(label)</h3>
<p>
This macro is a shorthand for <code>figure ref(label)</code> and just makes the typing
shorter, as in <code>see fig(schematic) for ..</code> See <code>getfigurestring()</code> and
<code>setfigurestring()</code> for the <code>figure</code> text.
<p>
<a name="l147"></a>
<h3>4.2.37: figure(file)(caption)(label)</h3>
<p>
Sets the picture in <code>file</code> as a figure in the current document, using the
descriptive text <code>caption</code>. The <code>label</code> is defined as a placeholder for the
figure number and can be used in a corresponding <code>ref</code> statement. Note that
the <code>file</code> must be the filename without extension: By default,
Yodl will supply <code>.gif</code>
when in HTML mode, or <code>.ps</code> when in LaTeX mode. Figures in other modes may
not (yet) haven been implemented.
<p>
<a name="l148"></a>
<h3>4.2.38: file(text)</h3>
<p>
Sets <code>text</code> as filename, usually boldface.
<p>
<a name="l149"></a>
<h3>4.2.39: findex()</h3>
<p>
Generate an index entry for index f.
<p>
<a name="l150"></a>
<h3>4.2.40: footnote(text)</h3>
<p>
Sets <code>text</code> as a footnote, or in parentheses when the output format
does not allow footnotes.
<p>
<a name="l151"></a>
<h3>4.2.41: gagmacrowarning(name name ...)</h3>
<p>
Prevents the <code>yodl</code> program from printing <em>cannot expand possible user
macro</em>. E.g., if you have in your document <code>the file(s) are ..</code> then you
might want to put before that: <code>gagmacrowarning(file)</code>. Calls
<code>NOUSERMACRO</code>.
<p>
<a name="l152"></a>
<h3>4.2.42: getaffilstring()</h3>
<p>
Expands to the string that defines the name of <em>Affiliation Information</em>, by
default <em>AFFILIATION INFORMATION</em>. Can be redefined for national language
support by <code>setaffilstring()</code>. Currently, it is relevant only for txt.
<p>
<a name="l153"></a>
<h3>4.2.43: getauthorstring()</h3>
<p>
Expands to the string that defines the name of <em>Author Information</em>, by
default <em>AUTHOR INFORMATION</em>. Can be redefined for national language
support by <code>setauthorstring()</code>. Currently, it is relevant only for txt.
<p>
<a name="l154"></a>
<h3>4.2.44: getchapterstring()</h3>
<p>
Expands to the string that defines a `chapter' entry, by default <em>Chapter</em>.
Can be redefined for national language support by <code>setchapterstring()</code>.
<p>
<a name="l155"></a>
<h3>4.2.45: getdatestring()</h3>
<p>
Expands to the string that defines the name of <em>Date Information</em>, by
default <em>DATE INFORMATION</em>. Can be redefined for national language
support by <code>setdatestring()</code>. Currently, it is relevant only for txt.
<p>
<a name="l156"></a>
<h3>4.2.46: getfigurestring()</h3>
<p>
Returns the string that defines a `figure' text, in captions or in the
<code>fig()</code> macro. The string can be redefined using the <code>setfiguretext()</code>
macro.
<p>
<a name="l157"></a>
<h3>4.2.47: getpartstring()</h3>
<p>
Expands to the string that defines a `part' entry, by default <em>Part</em>. Can
be redefined for national language support by <code>setpartstring()</code>.
<p>
<a name="l158"></a>
<h3>4.2.48: gettitlestring()</h3>
<p>
Expands to the string that defines the name of <em>Title Information</em>, by
default <em>TITLE INFORMATION</em>. Can be redefined for national language
support by <code>settitlestring()</code>. Currently, it is relevant only for txt.
<p>
<a name="l159"></a>
<h3>4.2.49: gettocstring()</h3>
<p>
Expands to the string that defines the name of the table of contents, by
default <em>Table of Contents</em>. Can be redefined for national language
support by <code>settocstring()</code>.
<p>
<a name="l160"></a>
<h3>4.2.50: htmlbodyopt(option)(value)</h3>
<p>
Adds <code>option="value"</code> to the options of the <code><body ...></code> tag in HTML
files. Useful options are, e.g., <code>fgcolor</code> and <code>bgcolor</code>, whose values
are expressed as <code>#rrggbb</code>, where <code>rr</code> are two hexadecimal digits of
the red component, <code>gg</code> two hexadecimal digits of the green component,
and <code>bb</code> two hexadecimal digits of the blue component.
<p>
<a name="l161"></a>
<h3>4.2.51: htmlcommand(cmd)</h3>
<p>
Writes <code>cmd</code> to the output when converting to html. The <code>cmd</code> is not
further expanded by Yodl.
<p>
<a name="l162"></a>
<h3>4.2.52: htmlheadopt(option)</h3>
<p>
Adds the literal text <code>option</code> to the current information in the <code>head</code>
section of an HTML document. <code>Option</code> may (or: should) contain plain html
text. A commonly occurring head option is <code>link</code>, defining, e.g., a style
sheet. Since that option is frequently used, it has received a dedicated
macro: <code>htmlstylesheet</code>. Like <code>htmlbodyopt</code> this macro should be placed in
the document's preamble.
<p>
<a name="l163"></a>
<h3>4.2.53: htmlnewfile()</h3>
<p>
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 <code>chapter</code> definition.
<p>
<a name="l164"></a>
<h3>4.2.54: htmlstylesheet(url)</h3>
<p>
Adds a <code><link rel="stylesheet" type="text/css" ...></code> element to the head
section of an HTML document, using <code>url</code> in its <code>href</code> field. The argument
<code>url</code> is not expanded, and should be plain HTML text, without
surrounding quotes. The macro <code>htmlheadopt</code> can also be used to put
information in the head-section of an HTML document, but <code>htmlheadopt</code> is of
a much more general nature. Like <code>htmlbodyopt</code> this macro should be placed
in the document's preamble.
<p>
<a name="l165"></a>
<h3>4.2.55: htmltag(tagname)(start)</h3>
<p>
Sets <code>tagname</code> as a HTML tag, enclosed by <code><</code> and <code>></code>. When
<code>start</code> is zero, the <code>tagname</code> is prefixed with <code>/</code>.
<p>
<a name="l166"></a>
<h3>4.2.56: ifnewparagraph(truelist)(falselist)</h3>
<p>
The macro <code>ifnewparagraph</code> should be called from the <code>PARAGRAPH</code> macro, if
defined. It will insert <code>truelist</code> if a new paragraph is inserted,
otherwise <code>falselist</code> is inserted (e.g., following two consecutive calls of
PARAGRAPH). This macro can be used to prevent the output of multiple blank
lines.
<p>
<a name="l167"></a>
<h3>4.2.57: includefile(file)</h3>
<p>
Includes <code>file</code>. The default
extension <code>.yo</code> is supplied if necessary.
<p>
<strong>NOTE:</strong> 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 <strong>C</strong>'s <code>#include</code> 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 <code>-L</code> (<code>--legacy-include</code>) option is used.
<p>
Furthermore, the <code>includefile</code> macro no longer defines a label. To define a
label just before the file's inclusion use <code>lincludefile</code>.
<p>
<a name="l168"></a>
<h3>4.2.58: includeverbatim(file)</h3>
<p>
Include <code>file</code> into the output. No processing is done, <code>file</code> should
be in preformatted form, e.g.: <pre>
whenhtml(includeverbatim(foo.html))
</pre>
<p>
<strong>NOTE:</strong> 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 <strong>C</strong>'s <code>#include</code> 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 <code>-L</code> (<code>--legacy-include</code>) option is used.
<p>
<a name="l169"></a>
<h3>4.2.59: it()</h3>
<p>
Indicates an item in an itemized list. The list is either surrounded by
<code>startit()</code> and <code>endit()</code>, or it is an argument to <code>itemize()</code>.
<p>
<a name="l170"></a>
<h3>4.2.60: itemization(list)</h3>
<p>
Sets <code>list</code> as an itemizationd list. Use <code>it()</code> to indicate items in the
list.
<p>
<a name="l171"></a>
<h3>4.2.61: itemize(list)</h3>
<p>
DEPRECATED. Use itemization().
<p>
<a name="l172"></a>
<h3>4.2.62: kindex()</h3>
<p>
Generate an index entry for index k.
<p>
<a name="l173"></a>
<h3>4.2.63: label(labelname)</h3>
<p>
Defines <code>labelname</code> as an anchor for a <code>link</code>
command, or to stand for the last numbering of a section or figure in a
<code>ref</code> command.
<p>
<a name="l174"></a>
<h3>4.2.64: langle()</h3>
<p>
Character <
<p>
<a name="l175"></a>
<h3>4.2.65: languagedutch()</h3>
<p>
Defines the Dutch-language specific headers. Active this macro via
setlanguage(dutch).
<p>
<a name="l176"></a>
<h3>4.2.66: languageenglish()</h3>
<p>
Defines the English-language specific headers. Active this macro via
setlanguage(english).
<p>
<a name="l177"></a>
<h3>4.2.67: languageportugese()</h3>
<p>
Defines the Portugese-language specific headers. Active this macro via
setlanguage(portugese).
<p>
<a name="l178"></a>
<h3>4.2.68: LaTeX()</h3>
<p>
The LaTeX symbol.
<p>
<a name="l179"></a>
<h3>4.2.69: latexaddlayout(arg)</h3>
<p>
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 <code>latexlayoutcmds()</code>
<p>
<a name="l180"></a>
<h3>4.2.70: latexcommand(cmd)</h3>
<p>
Writes <code>cmd</code> plus a white space to the output when converting to LaTeX. The
<code>cmd</code> is not further expanded by Yodl.
<p>
<a name="l181"></a>
<h3>4.2.71: latexdocumentclass(class)</h3>
<p>
Forces the LaTeX
<code>\documentclass{...}</code> setting to <code>class</code>. Normally the class is
defined by the macros <code>article</code>, <code>report</code> or <code>book</code>. This macro
is an escape route incase you need to specify your own document class
for LaTeX. This option is a <em>modifier</em> and must
appear <em>before</em> the <code>article</code>, <code>report</code> or <code>book</code> macros.
<p>
<a name="l182"></a>
<h3>4.2.72: latexlayoutcmds(NOTRANSs)</h3>
<p>
This macro is provided in case you want to put your own LaTeX layout commands
into LaTeX output. The <code>NOTRANSs</code> are pasted right after the
<code>\documentclass</code> stanza. The default is, of course, no local LaTeX
commands. Note that this macro <strong>does not</strong> overrule my favorite LaTeX
layout. Use <code>nosloppyhfuzz()</code> and <code>standardlayout()</code> to disable my favorite
LaTeX layout.
<p>
<a name="l183"></a>
<h3>4.2.73: latexoptions(options)</h3>
<p>
Set latex options: <code>documentclass[options]</code>.
This command <strong>must</strong> appear before the document type is
stated by <code>article</code>, <code>report</code>, etc..
<p>
<a name="l184"></a>
<h3>4.2.74: latexpackage(options)(name)</h3>
<p>
Include latex package(s), a useful package is, e.g.,
<code>epsf</code>. This command <strong>must</strong> appear before the document type is
stated by <code>article</code>, <code>report</code>, etc..
<p>
<a name="l185"></a>
<h3>4.2.75: lchapter(label)(title)</h3>
<p>
Starts a new chapter in <code>book</code>s or <code>report</code>s, setting a label at
the beginning of the chapter.
<p>
<a name="l186"></a>
<h3>4.2.76: letter(language)(date)(subject)(opening)(salutation)(author)</h3>
<p>
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:
<ul>
<li> <code>latexoptions(11pt)</code>
<li> <code>a4enlarged()</code>
<li> <code>letterreplyto(name)(address)(postalcode/city)</code>
<li> <code>letterfootitem(phone)(number)</code>, maybe e-mail too.
<li> <code>letteradmin(yourdate)(yourref)</code>
<li> <code>letterto(addressitem)</code>. Use a separate <code>letterto()</code> macro call
for each new line of the address.
</ul>
<p>
<a name="l187"></a>
<h3>4.2.77: letteraddenda(type)(value)</h3>
<p>
Adds an addendum at the end of a letter. `type' should be `bijlagen',
`cc' or `ps'.
<p>
<a name="l188"></a>
<h3>4.2.78: letteradmin(yourdate)(yourref)</h3>
<p>
Puts `yourletterfrom' and `yourreference' elements in the letter. If left
empty, two dashes are inserted.
<p>
<a name="l189"></a>
<h3>4.2.79: letterfootitem(name)(value)</h3>
<p>
Puts a footer at the bottom of letter-pages. Up to three will usually fit.
LaTeX only.
<p>
<a name="l190"></a>
<h3>4.2.80: letterreplyto(name)(address)(zip city)</h3>
<p>
Defines the `reply to' address in LaTeX or txt-letters.
<p>
<a name="l191"></a>
<h3>4.2.81: letterto(element)</h3>
<p>
Adds `element' as an additional line to the address in LaTeX letters.
<p>
<a name="l192"></a>
<h3>4.2.82: link(description)(labelname)</h3>
<p>
In HTML output a clickable link with the text <code>description</code> is created that
points to the place where <code>labelname</code> is defined using the <code>label</code> macro.
Using <code>link</code> is similar to <code>url</code>, except that a hyperlink
is set pointing to a location in the same document. For output formats other
than HTML, only the <code>description</code> appears.
<p>
<a name="l193"></a>
<h3>4.2.83: lref(description)(labelname)</h3>
<p>
This macro is a combination of the <code>ref</code> and <code>link</code> macros. In HTML
output a clickable link with the text <code>description</code> and the label value
is created that points to the place where <code>labelname</code> is defined using
the <code>label</code> macro. For output formats other than HTML, only the
<code>description</code> and the label value appears.
<p>
<a name="l194"></a>
<h3>4.2.84: lsect(label)(title)</h3>
<p>
Starts a new section, setting a label at the beginning of the section.
<p>
<a name="l195"></a>
<h3>4.2.85: lsubsect(label)(title)</h3>
<p>
Starts a new subsection. Other sectioning commands are
<code>subsubsect</code> and <code>subsubsubsect</code>. A label is added just before the
subsection.
<p>
<a name="l196"></a>
<h3>4.2.86: lsubsubsect(label)(title)</h3>
<p>
Starts a sub-subsection, a label is added just before the section
<p>
<a name="l197"></a>
<h3>4.2.87: lsubsubsubsect(label)(title)</h3>
<p>
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.
<p>
<a name="l198"></a>
<h3>4.2.88: lurl(locator)</h3>
<p>
An url described by its Locator. For small urls with readable addresses.
<p>
<a name="l199"></a>
<h3>4.2.89: mailto(address)</h3>
<p>
Defines the default <code>mailto</code> address for HTML output. Must appear
<strong>before</strong> the document type is stated by <code>article</code>, <code>report</code>, etc..
<p>
<a name="l200"></a>
<h3>4.2.90: makeindex()</h3>
<p>
Make index for latex.
<p>
<a name="l201"></a>
<h3>4.2.91: mancommand(cmd)</h3>
<p>
Writes <code>cmd</code> to the output when converting to man. The <code>cmd</code> is not
further expanded by Yodl.
<p>
<a name="l202"></a>
<h3>4.2.92: manpage(title)(section)(date)(source)(manual)</h3>
<p>
Starts a manual page document. The <code>section</code> 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 <strong>not</strong> <code>(n)sect</code> etc., but <code>manpage...()</code>. The first section
<strong>must</strong> be the <code>manpagename</code>, the last section <strong>must</strong> be the
<code>manpageauthor</code>. The standard manpage for section 1 contains the following
sections (in the given order): <code>manpagename</code>, <code>manpagesynopsis</code>,
<code>manpagedescription</code>, <code>manpageoptions</code>, <code>manpagefiles</code>,
<code>manpageseealso</code>, <code>manpagediagnostics</code>, <code>manpagebugs</code>,
<code>manpageauthor</code>. Optional extra sections can be added with
<code>manpagesection</code>. Standard manpageframes for several manpagesections
are provided in <code>/usr/local/share/yodl/manframes</code>.
<p>
<a name="l203"></a>
<h3>4.2.93: manpageauthor()</h3>
<p>
Starts the AUTHOR entry in a <code>manpage</code> document. Must be the last section
of a <code>manpage</code>.
<p>
<a name="l204"></a>
<h3>4.2.94: manpagebugs()</h3>
<p>
Starts the BUGS entry in a <code>manpage</code> document.
<p>
<a name="l205"></a>
<h3>4.2.95: manpagedescription()</h3>
<p>
Starts the DESCRIPTION entry in a <code>manpage</code> document.
<p>
<a name="l206"></a>
<h3>4.2.96: manpagediagnostics()</h3>
<p>
Starts the DIAGNOSTICS entry in a <code>manpage</code> document.
<p>
<a name="l207"></a>
<h3>4.2.97: manpagefiles()</h3>
<p>
Starts the FILES entry in a <code>manpage</code> document.
<p>
<a name="l208"></a>
<h3>4.2.98: manpagename(name)(short description)</h3>
<p>
Starts the NAME entry in a <code>manpage</code> document. The short description is
used by, e.g., the <code>whatis</code> database.
<p>
<a name="l209"></a>
<h3>4.2.99: manpageoptions()</h3>
<p>
Starts the OPTIONS entry in a <code>manpage</code> document.
<p>
<a name="l210"></a>
<h3>4.2.100: manpagesection(SECTIONNAME)</h3>
<p>
Inserts a non-required section named <code>SECTIONNAME</code> in a <code>manpage</code>
document. This macro can be used to augment `standard' manual pages with extra
sections, e.g., EXAMPLES. <strong>Note that</strong> the name of the extra section should
appear in upper case, which is consistent with the normal typesetting of
manual pages.
<p>
<a name="l211"></a>
<h3>4.2.101: manpageseealso()</h3>
<p>
Starts the SEE ALSO entry in a <code>manpage</code> document.
<p>
<a name="l212"></a>
<h3>4.2.102: manpagesynopsis()</h3>
<p>
Starts the SYNOPSIS entry in a <code>manpage</code> document.
<p>
<a name="l213"></a>
<h3>4.2.103: mbox()</h3>
<p>
Unbreakable box in LaTeX. Other formats may have different opitions on
our unbreakable boxex.
<p>
<a name="l214"></a>
<h3>4.2.104: menu(list)</h3>
<p>
DEPRECATED.
<p>
<a name="l215"></a>
<h3>4.2.105: metaC(text)</h3>
<p>
Put a line comment in the output.
<p>
<a name="l216"></a>
<h3>4.2.106: metaCOMMENT(text)</h3>
<p>
Write format-specific comment to the output.
<p>
<a name="l217"></a>
<h3>4.2.107: mit()</h3>
<p>
DEPRECATED.
<p>
<a name="l218"></a>
<h3>4.2.108: mscommand(cmd)</h3>
<p>
Writes <code>cmd</code> to the output when converting to ms. The <code>cmd</code> is not
further expanded by Yodl.
<p>
<a name="l219"></a>
<h3>4.2.109: nchapter(title)</h3>
<p>
Starts a chapter (in a <code>book</code> or <code>report</code>) without generating a
number before the title and without placing an entry for the chapter in
the table of contents.
<p>
<a name="l220"></a>
<h3>4.2.110: nemail(name)(address)</h3>
<p>
Named email.
A more consistent naming for url, lurl, email and nemail would be
nice.
<p>
<a name="l221"></a>
<h3>4.2.111: nl()</h3>
<p>
Forces a newline; i.e., breaks the current line in two.
<p>
<a name="l222"></a>
<h3>4.2.112: node(previous)(this)(next)(up)</h3>
<p>
<strong>DEPRECATED</strong> Defines a node with name <code>this</code>, and links to nodes <code>previous</code>, <code>next</code>
and (up), for the <code>node</code> command.
<p>
<a name="l223"></a>
<h3>4.2.113: nodeprefix(text)</h3>
<p>
Prepend text to node names, e.g. <pre>
nodeprefix(LilyPond) sect(Overview)
</pre>
Currently used in texinfo descriptions only.
<p>
<a name="l224"></a>
<h3>4.2.114: nodeprefix(text)</h3>
<p>
Prepend text to node names, e.g. <pre>
nodeprefix(LilyPond) sect(Overview)
</pre>
Currently used in texinfo descriptions only.
<p>
<a name="l225"></a>
<h3>4.2.115: nodetext(text)</h3>
<p>
Use text as description for the next node, e.g. <pre>
nodetext(The GNU Music Typesetter)chapter(LilyPond)
</pre>
Currently used in texinfo descriptions only.
<p>
<a name="l226"></a>
<h3>4.2.116: nop(text)</h3>
<p>
Expand to text, to avoid spaces before macros e.g.: a<sup>2</sup>. Although
a+sups(2) should have the same effect.
<p>
<a name="l227"></a>
<h3>4.2.117: nosloppyhfuzz()</h3>
<p>
By default, LaTeX output contains commands that cause it to shut up about
hboxes that are less than 4pt overfull. When <code>nosloppyhfuzz()</code> appears
before stating the document type, LaTeX complaints are `vanilla'.
<p>
<a name="l228"></a>
<h3>4.2.118: notableofcontents()</h3>
<p>
Prevents the generation of a table of contents. This is default in, e.g.,
<code>manpage</code> and <code>plainhtml</code> documents. When present, this option <strong>must</strong>
appear before stating the document type with <code>article</code>, <code>report</code>
etc..
<p>
<a name="l229"></a>
<h3>4.2.119: notitleclearpage()</h3>
<p>
Prevents the generation of a <code>clearpage()</code> instruction after the typesetting
of title information. This instruction is default in all non <code>article</code>
documents. When present, must appear <strong>before</strong> stating the document type with
<code>article</code>, <code>book</code> or <code>report</code>.
<p>
<a name="l230"></a>
<h3>4.2.120: notocclearpage()</h3>
<p>
With the LaTeX convertor, no <code>clearpage()</code> instruction is inserted
immediately beyond the document's table of contents. The <code>clearpage()</code>
instruction is default in all but the <code>article</code> document type. When present,
must appear <strong>before</strong> stating the document type with <code>article</code>, <code>book</code> or
<code>report</code>.
With other convertors than the LaTeX convertor, it is ignored.)
<p>
<a name="l231"></a>
<h3>4.2.121: notransinclude(filename)</h3>
<p>
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.
<p>
<strong>NOTE:</strong> 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 <strong>C</strong>'s <code>#include</code> 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 <code>-L</code> (<code>--legacy-include</code>) option is used.
<p>
<a name="l232"></a>
<h3>4.2.122: noxlatin()</h3>
<p>
When used in the preamble, the LaTeX converter disables the inclusion of the
file <code>xlatin1.tex</code>. 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 <code>xlatin1.tex</code> comes with the <code>Yodl</code>
distribution.)
<p>
<a name="l233"></a>
<h3>4.2.123: nparagraph(title)</h3>
<p>
Starts a non-numbered paragraph (duh, corresponds to subparagraph in latex).
<p>
<a name="l234"></a>
<h3>4.2.124: npart(title)</h3>
<p>
Starts a part in a <code>book</code> document, but without numbering it and without
entering the title of the part in the table of contents.
<p>
<a name="l235"></a>
<h3>4.2.125: nsect(title)</h3>
<p>
Starts a section, but does not generate a number before the <code>title</code> nor
an entry in the table of contents. Further sectioning commands are
<code>nsubsect</code>, <code>nsubsubsect</code> and <code>nsubsubsubsect</code>.
<p>
<a name="l236"></a>
<h3>4.2.126: nsubsect(title)</h3>
<p>
Starts a non-numbered subsection.
<p>
<a name="l237"></a>
<h3>4.2.127: nsubsubsect(title)</h3>
<p>
Starts a non-numbered sub-sub section.
<p>
<a name="l238"></a>
<h3>4.2.128: nsubsubsect(title)</h3>
<p>
Starts a non-numbered sub-subsection.
<p>
<a name="l239"></a>
<h3>4.2.129: paragraph(title)</h3>
<p>
Starts a parapgraph. This level of sectioning is not numbered, in
contrast to `higher' sectionings (duh, corresponds to subparagraph in latex).
<p>
<a name="l240"></a>
<h3>4.2.130: part(title)</h3>
<p>
Starts a new part in a <code>book</code> document.
<p>
<a name="l241"></a>
<h3>4.2.131: pindex()</h3>
<p>
Generate an index entry for index p.
<p>
<a name="l242"></a>
<h3>4.2.132: plainhtml(title)</h3>
<p>
Starts a document for only a plain HTML conversion. Not available in
other output formats. Similar to <code>article</code>, except that an author- and
date field are not needed.
<p>
<a name="l243"></a>
<h3>4.2.133: printindex()</h3>
<p>
Make index for texinfo (?).
<p>
<a name="l244"></a>
<h3>4.2.134: quote(text)</h3>
<p>
Sets the text as a quotation. Usually, the text is indented, depending on the
output format.
<p>
<a name="l245"></a>
<h3>4.2.135: rangle()</h3>
<p>
Inserts the right angle character (>).
<p>
<a name="l246"></a>
<h3>4.2.136: redef(nrofargs)(redefinition)</h3>
<p>
Defines macro <code>macro</code> to expand to <code>redefinition</code>.
Similar to <code>def</code>, but any pre-existing definition is overruled. Use
<code>ARG</code><em>x</em> in the redefinition part to indicate where the arguments should
be pasted. E.g., <code>ARG1</code> places the first argument, <code>ARG2</code> the second
argument, etc...
<p>
<a name="l247"></a>
<h3>4.2.137: redefinemacro(nrofargs)(redefinition)</h3>
<p>
Defines macro <code>macro</code> to expand to <code>redefinition</code>.
Similar to <code>def</code>, but any pre-existing definition is overruled. Use
<code>ARG</code><em>x</em> in the redefinition part to indicate where the arguments should
be pasted. E.g., <code>ARG1</code> places the first argument, <code>ARG2</code> the second
argument, etc... This commands is actually calling redef().
<p>
<a name="l248"></a>
<h3>4.2.138: ref(labelname)</h3>
<p>
Sets the reference for <code>labelname</code>. Use <code>label</code> to define a label.
<p>
<a name="l249"></a>
<h3>4.2.139: report(title)(author)(date)</h3>
<p>
Starts a report type document. The top-level sectioning command in a report
is <code>chapter</code>.
<p>
<a name="l250"></a>
<h3>4.2.140: roffcmd(dotcmd)(sameline)(secondline)(thirdline)</h3>
<p>
Sets a t/nroff command that starts with a dot, on its own line. The arguments
are: <code>dotcmd</code> - the command itself, e.g., <code>.IP</code>; <code>sameline</code> - when not
empty, set following the <code>dotcmd</code> on the same line; <code>secondline</code> - when
not empty, set on the next line; <code>thirdline</code> - when not empty, set on the
third line. Note that <code>dotcmd</code> and <code>thirdline</code> are not further expanded by
<code>Yodl</code>, the other arguments are.
<p>
<a name="l251"></a>
<h3>4.2.141: row(contents)</h3>
<p>
The argument <code>contents</code> may contain a man-page alignment specification
(only one specification can be entered per row), using <code>setmanalign()</code>. If
omitted, the standard alignment is used. Furthermore it contains the contents
of the elements of the row, using <code>cell()</code> or <code>cells()</code> macros. If
<code>cells()</code> is used, <code>setmanalign()</code> should have been used too. In this
macro call only the <code>cell()</code>, <code>cells()</code> and <code>setmanalign()</code> macros
should be called. Any other macro call may produce unexpected results.
<p>
The <code>row</code> macro defines a counter <code>XXcellnr</code> 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 <code>XXcellnr</code>.
<p>
<a name="l252"></a>
<h3>4.2.142: rowline()</h3>
<p>
Sets a horizontal line over the full width of the table. See also
<code>columnline()</code>. Use <code>rowline()</code> instead of a <code>row()</code> macro call to
obtain a horizontal line-separator.
<p>
<a name="l253"></a>
<h3>4.2.143: sc(text)</h3>
<p>
Set <code>text</code> in small caps (or tt).
<p>
<a name="l254"></a>
<h3>4.2.144: sect(title)</h3>
<p>
Starts a new section.
<p>
<a name="l255"></a>
<h3>4.2.145: setaffilstring(name)</h3>
<p>
Defines <code>name</code> as the `affiliation information' string, by default
<em>AFFILIATION INFORMATION</em>. E.g., after <code>setaffilstring(AFILIACION)</code>,
<code>Yodl</code> outputs this Spanish string to describe the affiliation information.
Currently, it is relevant only for txt.
<p>
<a name="l256"></a>
<h3>4.2.146: setauthorstring(name)</h3>
<p>
Defines <code>name</code> as the `Author information' string, by default
<em>AUTHOR INFORMATION</em>. E.g., after <code>setauthorstring(AUTOR)</code>,
<code>Yodl</code> outputs this portuguese string to describe the author information.
Currently, it is relevant only for txt.
<p>
<a name="l257"></a>
<h3>4.2.147: setchapterstring(name)</h3>
<p>
Defines <code>name</code> as the `chapter' string, by default <em>Chapter</em>. E.g., after
<code>setchapterstring(Hoofdstuk)</code>, <code>Yodl</code> 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.
<p>
<a name="l258"></a>
<h3>4.2.148: setdatestring(name)</h3>
<p>
Defines <code>name</code> as the `date information' string, by default
<em>DATE INFORMATION</em>. E.g., after <code>setdatestring(DATA)</code>,
<code>Yodl</code> outputs this portuguese string to describe the date information.
Currently, it is relevant only for txt.
<p>
<a name="l259"></a>
<h3>4.2.149: setfigureext(name)</h3>
<p>
Defines the <code>name</code> 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 <code>.ps</code>
<p>
<a name="l260"></a>
<h3>4.2.150: setfigurestring(name)</h3>
<p>
Defines the <code>name</code> as the `figure' text, used e.g. in figure captions. E.g.,
after <code>setfigurestring(Figuur)</code>, Yodl uses Dutch names for figures.
<p>
<a name="l261"></a>
<h3>4.2.151: sethtmlfigureext(ext)</h3>
<p>
Defines the filename extension for HTML figures, defaults to <code>.jpg</code>. Note
that a leading dot must be included in <code>ext</code>. The new extension takes effect
starting with the following usage of the <code>figure</code> macro. It is only active
in html, but otherwise acts identically as setfigureext().
<p>
<a name="l262"></a>
<h3>4.2.152: setincludepath(name)</h3>
<p>
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.
<p>
<a name="l263"></a>
<h3>4.2.153: setlanguage(name)</h3>
<p>
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
<p>
<a name="l264"></a>
<h3>4.2.154: setlatexalign(alignment)</h3>
<p>
This macro defines the table alignment used when setting tables in LaTeX.
Use as many <code>l</code> (for left-alignment), <code>r</code>
(for right alignment), and <code>c</code> (for centered-alignment) characters as there
are columns in the table. See also <code>table()</code>
<p>
<a name="l265"></a>
<h3>4.2.155: setlatexfigureext(ext)</h3>
<p>
Defines the filename extension for encapsulated PostScript figures in LaTeX,
defaults to <code>.ps</code>. The dot must be included in t new extension <code>ext</code>. The
new extension takes effect starting with a following usage of the <code>figure</code>
macro. It is only active in LaTeX, but otherwise acts identically as
setfigureext().
<p>
<a name="l266"></a>
<h3>4.2.156: setlatexverbchar(char)</h3>
<p>
Set the char used to quote LaTeX
<code>\verb</code>
sequences
<p>
<a name="l267"></a>
<h3>4.2.157: setmanalign(alignment)</h3>
<p>
This macro defines the table alignment used when setting tables used in
man-pages (see <strong>tbl</strong>(1)). Use as many <code>l</code> (for left-alignment), <code>r</code>
(for right alignment), and <code>c</code> (for centered-alignment) characters as there
are columns in the table. Furthermore, <code>s</code> 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
<code>setmanalign()</code> call. Note that neither <code>rowline</code> nor <code>columnline</code>
requires <code>setmanalign()</code> 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.
<p>
<a name="l268"></a>
<h3>4.2.158: setpartstring(name)</h3>
<p>
Defines <code>name</code> as the `part' string, by default <em>Part</em>. E.g., after
<code>setpartstring(Teil)</code>, 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.
<p>
<a name="l269"></a>
<h3>4.2.159: setrofftab(x)</h3>
<p>
Sets the character separating items in a line of input data of a <code>roff</code>
(manpage) table. By default it is set to <code>~</code>. This separator is used
internally, and needs only be changed (into some unique character) if the
table elements themselves contain <code>~</code> characters.
<p>
<a name="l270"></a>
<h3>4.2.160: setrofftableoptions(optionlist)</h3>
<p>
Set the options for tbl table, default: none. Multiple options should be
separated by blanks, by default no option is used. From the <strong>tbl</strong>(1) manpage,
the following options are selected for consideration:
<ul>
<li> <code>center</code> Centers the table (default is left-justified)
<li> <code>expand</code> Makes the table as wide as the current line length
<li> <code>box</code> Encloses the table in a box
<li> <code>allbox</code> Encloses each item of the table in a box
</ul>
Note that starting with Yodl V 2.00 no default option is used anymore.
See also <code>setrofftab()</code> which is used to set the character separating
items in a line of input data.
<p>
<a name="l271"></a>
<h3>4.2.161: settitlestring(name)</h3>
<p>
Defines <code>name</code> as the `title information' string, by default
<em>TITLE INFORMATION</em>. E.g., after <code>settitlestring(TITEL)</code>,
<code>Yodl</code> outputs this Dutch string to describe the title information.
Currently, it is relevant only for txt.
<p>
<a name="l272"></a>
<h3>4.2.162: settocstring(name)</h3>
<p>
Defines <code>name</code> as the `table of contents' string, by default <em>Table of
Contents</em>. E.g., after <code>settocstring(Inhalt)</code>, <code>Yodl</code> 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.
<p>
<a name="l273"></a>
<h3>4.2.163: sgmlcommand(cmd)</h3>
<p>
Writes <code>cmd</code> to the output when converting to sgml. The <code>cmd</code> is not
further expanded by Yodl.
<p>
<a name="l274"></a>
<h3>4.2.164: sgmltag(tag)(onoff)</h3>
<p>
Similar to <code>htmltag</code>, but used in the SGML converter.
<p>
<a name="l275"></a>
<h3>4.2.165: sloppyhfuzz(points)</h3>
<p>
By default, LaTeX output contains commands that cause it to shut up about
hboxes that are less than 4pt overfull. When <code>sloppyhfuzz()</code> appears
before stating the document type, LaTeX complaints occur only if hboxes are
overfull by more than <code>points</code>.
<p>
<a name="l276"></a>
<h3>4.2.166: standardlayout()</h3>
<p>
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 <code>standardlayout()</code> directive must appear
<strong>before</strong> stating the document type as <code>article</code>, <code>report</code>, etc..
<p>
<a name="l277"></a>
<h3>4.2.167: startcenter()</h3>
<p>
DEPRECATED. center() should be used.
<p>
<a name="l278"></a>
<h3>4.2.168: startdit()</h3>
<p>
DEPRECATED. Use description().
<p>
<a name="l279"></a>
<h3>4.2.169: starteit()</h3>
<p>
DEPRECATED. Use enumeration().
<p>
<a name="l280"></a>
<h3>4.2.170: startit()</h3>
<p>
DEPRECATED. Use itemization().
<p>
<a name="l281"></a>
<h3>4.2.171: startmenu()</h3>
<p>
DEPRECATED. Use menu().
<p>
<a name="l282"></a>
<h3>4.2.172: starttable()</h3>
<p>
DEPRECATED. Use table().
<p>
<a name="l283"></a>
<h3>4.2.173: subs(text)</h3>
<p>
Sets text in subscript in supporting formats
<p>
<a name="l284"></a>
<h3>4.2.174: subsect(title)</h3>
<p>
Starts a new subsection. Other sectioning commands are
<code>subsubsect</code> and <code>subsubsubsect</code>.
<p>
<a name="l285"></a>
<h3>4.2.175: subsubsect(title)</h3>
<p>
Starts a sub-subsection.
<p>
<a name="l286"></a>
<h3>4.2.176: subsubsubsect(title)</h3>
<p>
Starts a sub-sub-sub-subsection. This level of sectioning is not numbered, in
contrast to `higher' sectionings.
<p>
<a name="l287"></a>
<h3>4.2.177: sups(text)</h3>
<p>
Sets text in superscript in supporting formats
<p>
<a name="l288"></a>
<h3>4.2.178: table(nColumns)(alignment)(Contents)</h3>
<p>
The <code>table()</code>-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 <code>l</code> for left-alignment, <code>c</code> for centered-alignment and <code>r</code>
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.
<p>
See also the specialized <code>setmanalign()</code> macro.
<p>
<a name="l289"></a>
<h3>4.2.179: tcell(text)</h3>
<p>
Roff helper to set a table textcell, i.e., a paragraph. For LaTeX
special table formatting p{} should be used.
<p>
<a name="l290"></a>
<h3>4.2.180: telycommand(cmd)</h3>
<p>
Writes <code>cmd</code> to the output when converting to tely. The <code>cmd</code> is not
further expanded by Yodl.
<p>
<a name="l291"></a>
<h3>4.2.181: TeX()</h3>
<p>
The TeX symbol.
<p>
<a name="l292"></a>
<h3>4.2.182: texinfocommand(cmd)</h3>
<p>
Writes <code>cmd</code> to the output when converting to texinfo. The <code>cmd</code> is not
further expanded by Yodl.
<p>
<a name="l293"></a>
<h3>4.2.183: tindex()</h3>
<p>
Generate an index entry for index t.
<p>
<a name="l294"></a>
<h3>4.2.184: titleclearpage()</h3>
<p>
Forces the generation of a <code>clearpage()</code> directive following the title of a
document. This is already the default in <code>book</code>s and <code>report</code>s, but can be
overruled with <code>notitleclearpage()</code>. When present, must appear in the
<em>preamble</em>; i.e., before the document type is stated with <code>article</code>,
<code>book</code> or <code>report</code>.
<p>
<a name="l295"></a>
<h3>4.2.185: tocclearpage()</h3>
<p>
With the LaTeX convertor, a <code>clearpage()</code> directive if inserted,
immediately following the document's table of contents. This is already the
default in all but the <code>article</code> document type, but it can be overruled by
<code>notocclearpage()</code>. When present, it must appear in the <em>preamble</em>; i.e.,
before the document type is stated with <code>article</code>, <code>book</code> or
<code>report</code>. With other convertors than the LaTeX convertor, it is ignored.
<p>
<a name="l296"></a>
<h3>4.2.186: tt(text)</h3>
<p>
Sets <code>text</code> in teletype font, and prevents it from being expanded.
For unbalanced parameter lists, use <code>CHAR(40)</code> to get
<code>(</code> and <code>CHAR(41)</code> to get <code>)</code>.
<p>
<a name="l297"></a>
<h3>4.2.187: txtcommand(cmd)</h3>
<p>
Writes <code>cmd</code> to the output when converting to txt. The <code>cmd</code> is not
further expanded by Yodl.
<p>
<a name="l298"></a>
<h3>4.2.188: url(description)(locator)</h3>
<p>
In LaTeX documents the <code>description</code> is sent to the output. For HTML,
a link is created with the descriptive text <code>description</code> and pointing
to <code>locator</code>. The <code>locator</code> should be the full URL, including
service; e.g, <code>http://www.icce.rug.nl</code>, but excluding the double
quotes that are necessary in plain HTML. Use the macro <code>link</code> to create
links within the same document. For other formats, something like
<em>description [locator]</em> will appear.
<p>
<a name="l299"></a>
<h3>4.2.189: verb(text)</h3>
<p>
Sets <code>text</code> 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 <code>CHAR(40)</code> to get <code>(</code> and <code>CHAR(41)</code>
to get <code>)</code>.
<p>
<a name="l300"></a>
<h3>4.2.190: verbinclude(filename)</h3>
<p>
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 <code>verb(...)</code>, when the text to set in verbatim mode is
better kept in a separate file.
<p>
<strong>NOTE:</strong> 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 <strong>C</strong>'s <code>#include</code> 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 <code>-L</code> (<code>--legacy-include</code>) option is used.
<p>
<a name="l301"></a>
<h3>4.2.191: verbpipe(command)(text)</h3>
<p>
Pipe text through command, but don't expand the output.
<p>
<a name="l302"></a>
<h3>4.2.192: vindex()</h3>
<p>
Generate an index entry for index v.
<p>
<a name="l303"></a>
<h3>4.2.193: whenhtml(text)</h3>
<p>
Sends <code>text</code> to the output when in HTML conversion mode. The text is
further expanded if necessary.
<p>
<a name="l304"></a>
<h3>4.2.194: whenlatex(text)</h3>
<p>
Sends <code>text</code> to the output when in LATEX conversion mode. The text is
further expanded if necessary.
<p>
<a name="l305"></a>
<h3>4.2.195: whenman(text)</h3>
<p>
Sends <code>text</code> to the output when in MAN conversion mode. The text is
further expanded if necessary.
<p>
<a name="l306"></a>
<h3>4.2.196: whenms(text)</h3>
<p>
Sends <code>text</code> to the output when in MS conversion mode. The text is
further expanded if necessary.
<p>
<a name="l307"></a>
<h3>4.2.197: whensgml(text)</h3>
<p>
Sends <code>text</code> to the output when in SGML conversion mode. The text is
further expanded if necessary.
<p>
<a name="l308"></a>
<h3>4.2.198: whentely(text)</h3>
<p>
Sends <code>text</code> to the output when in TELY conversion mode. The text is
further expanded if necessary.
<p>
<a name="l309"></a>
<h3>4.2.199: whentexinfo(text)</h3>
<p>
Sends <code>text</code> to the output when in TEXINFO conversion mode. The text is
further expanded if necessary.
<p>
<a name="l310"></a>
<h3>4.2.200: whentxt(text)</h3>
<p>
Sends <code>text</code> to the output when in TXT conversion mode. The text is
further expanded if necessary.
<p>
<a name="l311"></a>
<h3>4.2.201: whenxml(text)</h3>
<p>
Sends <code>text</code> to the output when in XML conversion mode. The text is
further expanded if necessary.
<p>
<a name="l312"></a>
<h3>4.2.202: xit(itemname)</h3>
<p>
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.
<p>
This macro is only available
within the xml-conversion mode. The argument must be a full filename,
including .xml extension, if applicable.
<p>
No .xml extension indicates a subdirectory, containing another sub-menu.
<p>
<a name="l313"></a>
<h3>4.2.203: xmlcommand(cmd)</h3>
<p>
Writes <code>cmd</code> to the output when converting to xml. The <code>cmd</code> is not
further expanded by Yodl.
<p>
<a name="l314"></a>
<h3>4.2.204: xmlmenu(order)(title)(menulist)</h3>
<p>
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.
<p>
Order is the the `order' of the menu. If omitted, no order is defined.
<p>
<a name="l315"></a>
<h3>4.2.205: xmlnewfile()</h3>
<p>
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 <code>chapter</code> definition.
<p>
<a name="l316"></a>
<h3>4.2.206: xmlsetdocumentbase(name)</h3>
<p>
Defines <code>name</code> as the XML document base. No default.
Only interpreted with xml conversions. It is used with the figure and xmlmenu
macros.
<p>
<a name="l317"></a>
<h3>4.2.207: xmltag(tag)(onoff)</h3>
<p>
Similar to <code>htmltag</code>, but used in the XML converter.
<p>
<a name="l318"></a>
<h2>4.3: Conversion-related topics</h2>
<p>
<a name="l319"></a>
<h3>4.3.1: Accents</h3>
<p>
<a name="FORMATDEFINES"></a><a name="l320"></a>
<h3>4.3.2: Conversion-type specific literal commands</h3>
According to the format of the output file, the macro package defines a given
symbol:
<ul>
<li> <code>latex</code> when the output format is LaTeX,
<li> <code>html</code> when the output format is HTML,
<li> <code>man</code> when the output format is groff in conjunction with the
man macro package,
<li> <code>ms</code> when the output format is groff with the ms package,
<li> <code>sgml</code> when the output format is SGML,
<li> <code>txt</code> when the output format is plain ASCII.
<li> <code>xml</code> when the output format is XML.
</ul>
The defined symbol can be tested in a document to determine the conversion
type.
<p>
Furthermore, the package defines the following macros to send literal text
(commands in the output format) to the output file:
<ul>
<li> <code>latexcommand(cmd)</code>: sends the LaTeX command <code>cmd</code> when in LaTeX
conversion mode. The <code>cmd</code> is not further expanded.
<li> <code>htmlcommand(cmd)</code>: sends the HTML command <code>cmd</code> when in HTML
conversion mode. The <code>cmd</code> is not further expanded.
<li> <code>htmltag(tag)(onoff)</code>: sends <code><tag></code> to the output when <code>onoff</code>
is nonzero, or sends <code></tag></code> when <code>onoff</code> is zero. Only active in
HTML conversions.
<li> <code>mancommand(cmd)</code>: sends <code>cmd</code> to the output when in man
conversion mode. The <code>cmd</code> is not further expanded.
<li> <code>mscommand(cmd)</code>: sends <code>cmd</code> to the output when in ms
conversion mode. The <code>cmd</code> is not further expanded.
<li> <code>roffcmd(dotcmd)(trailer)(secondline)(thirdline)</code>: sends a command
to the output when in <code>man</code> or <code>ms</code> conversion mode. The <code>dotcmd</code> is the
typical <code>groff</code> command that starts with a dot. All other arguments may be
empty, but when given are interpreted as follows. The <code>trailer</code> follows the
<code>dotcmd</code> on the same line. The <code>secondline</code> is sent on a separate line
following the <code>dotcmd</code> and <code>trailer</code>. The <code>thirdline</code> is sent after
that. Of the four arguments, <code>dotcmd</code> and <code>thirdline</code> are <strong>not</strong> subject
to further expansion. All other arguments are further expanded if necessary.
<p>
The <code>roffcmd</code> macro illustrates the complexity of dot-commands for the
divers <code>groff</code> macro packages. E.g., a section title for the <code>man</code>
package should look as
<pre>
.SH "Section Title"
</pre>
while the same command for the <code>ms</code> macro package must be sent as
<pre>
.SH
Section Title
.PP
</pre>
The <code>roffcmd</code> macro can be used to send these commands to the output
file as follows:
<pre>
COMMENT(For the man output format:)
roffcmd(.SH)("Section Title")()()
COMMENT(For the ms output format:)
roffcmd(.SH)()(Section Title)(.PP)()
</pre>
<li> <code>sgmlcommand(cmd)</code>: sends the SGML command <code>cmd</code> when in SGML
conversion mode. The <code>cmd</code> is not further expanded.
<li> <code>sgmltag(tag)(onoff)</code>: sends <code><tag></code> when <code>onoff</code> is nonzero,
or sends <code></tag></code> when <code>onoff</code> is zero. Only active in SGML conversions.
<li> <code>txtcommand(cmd)</code>: 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.
</ul>
The above commands can be used to quickly implement a macro. E.g., the
macro package implements the <code>it</code> macro (which starts an item in a list) as:
<pre>
DEFINEMACRO(it)(0)(
latexcommand(\item )
htmlcommand(<li> )
....
)
</pre>
Depending on the output format, <code>it()</code> will lead to one of the above
expansions.
<p>
The above described <em>format</em><code>command()</code> macros are implemented to send not
further expanded strings (i.e., commands) to the output. The macro package
also implements <code>when</code><em>format</em><code>()</code> macros to send any text, which is
then subject to further expansion. These <code>when...()</code> macros are:
<ul>
<li> <code>whenlatex(text)</code>: sends <code>text</code> when in LaTeX conversion mode,
<li> <code>whenhtml(text)</code>: sends <code>text</code> when in HTML conversion mode,
<li> <code>whenman(text)</code>: sends <code>text</code> when in man conversion mode,
<li> <code>whenms(text)</code>: sends <code>text</code> when in ms conversion mode,
<li> <code>whentxt(text)</code>: sends <code>text</code> when in ASCII conversion mode,
<li> <code>whensgml(text)</code>: sends <code>text</code> when in SGML conversion mode.
</ul>
Once again, <strong>note</strong> that the difference between the
<code>when</code><em>format</em><code>()</code> macros and the <em>format</em><code>command()</code> macros is,
that the former will expand their argument while the latter will not. As an
example, consider the following code fragment:
<pre>
You are now reading
whenlatex(a LaTeX-generated
footnote(LaTeX is a great
document language!)
document)
whenhtml(a HTML document via your
favorite browser)
</pre>
The <code>when</code><em>format</em><code>()</code> macros are used here to make sure that the
arguments to the macros are further expanded; this makes sure that the
<code>footnote</code> macro in the <code>whenlatex</code> block gets treated as a footnote.
<p>
<a name="l321"></a>
<h3>4.3.3: Figures</h3>
Figures in format-independent documents are a problem. You <em>cannot</em> avoid
contact with the final format (HTML, LaTeX or whatever) if you want to include
figures in a text.
<p>
Yodl approaches figures as follows:
<ul>
<li> Figures can only be included in LaTeX, HTML and XML documents.
<li> For LaTeX, you must prepare a picture in an external file that is
included in the document as en <em>encapsulated PostScript</em> file.
Incidentally, that means that <code>epsf</code> must be stated as one of the LaTeX
styles using the <code>latexoptions</code> macro. The default, however, can be
modified using the <code>setlatexfigureext()</code> macro.
<br>
The file in question is stated in Yodl without an extension. Yodl provides
a default extension, <code>.ps</code>.
<li> For HTML and XML, you must prepare a picture in an external file that
is placed in the document using the <code><img src=...></code> tag. The file must
have the default extension (<code>.jpg</code>) or the extension specified with the
<code>sethtmlfigureext()</code> macro.
<li> All other output formats do not include pictures in the document, but
typeset something like <em>insert figure .. here</em>.
</ul>
The macro to include a figure is called, appropriately, <code>figure</code>. It
takes three arguments:
<ul>
<li> 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.
<li> The second argument is the figure title, or the caption. Yodl prefixes
this caption with the text <em>Figure xx:</em>, where <em>xx</em> is a number.
<li> The last argument is a label, which Yodl defines as a placeholder for
the figure number.
</ul>
For example, you might draw a picture or scan a photo and put it in a
<code>.jpg</code> file, for usage with HTML documents. The conversion to PostScript
could be automated, e.g., using a Yodl macro:
<pre>
SYSTEM(xpmtoppm picture.xpm | pnmtops > picture.ps)
</pre>
See section <a href="yodl03.html#SYSTEM">3.1.67</a> for details about using the <code>SYSTEM</code> macro.
<p>
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:
<pre>
figure(picture)
(A photo of me.)
(photo)
</pre>
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.,
<pre>
See figure ref(photo) for a photograph showing me.
</pre>
Yodl has a several auxiliary macros, which are:
<ul>
<li> <code>fig(label)</code>: This macro is a shorthand for <code>getfigurestring()
ref(label)</code>. It just makes typing shorter, and is used as e.g.: <code>See
fig(photo) for a photograph.</code> Note that the string <code>figure</code> that is
generated by this macro can be (re)defined, see below.
<li> <code>setfigurestring(name)</code>: This macro is similar to
<code>setchapterstring</code> etc.. It defines the string that is used to identify a
figure, and is (appropriately) <code>figure</code> by default. The macro
<code>getfigurestring()</code> expands to the string in question. See also section
<a href="yodl04.html#NATIONAL">4.3.6.1</a> for a discussion of national language support.
<li> <code>sethtmlfigureext(.new)</code>: This macro redefines the filename
extension for HTML conversions from <code>.gif</code> to <code>.new</code>. Note that you must
include a leading dot in the redefinition.
<br>
The new extension is used in the first following <code>figure</code> statement.
<li> <code>sethtmlfigurealign(align)</code>: This redefines the alignment of
figures in HTML, which is default <code>bottom</code>. Check your HTML handbook for
possible options; <code>top</code> and <code>center</code> should be fairly standard.
<li> <code>setlatexfigureext(.new)</code>: Redefines the extension from <code>.ps</code> to
<code>.new</code>.
</ul>
<p>
<a name="l322"></a>
<h3>4.3.4: Fonts and sizes</h3>
Yodl's standard macro package supports the following macros to change fonts:
<ul>
<li> <code>bf(text)</code>: sets <code>text</code> in boldface.
<li> <code>em(text)</code>: sets <code>text</code> emphasized, usually in italics.
<li> <code>tt(text)</code>: sets <code>text</code> in teletype.
</ul>
Furthermore, the <code>tt()</code> macro will <em>not</em> expand macros occurring
inside its argument. That means that you can safely write:
<pre>
In Yodl, you can use tt(includefile(somefile)) to include a file
in your document.
</pre>
The <code>tt()</code> macro should not be used for long listings of verbatim text;
use <code>verb()</code> to set code samples etc..
<p>
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.
<p>
<a name="LABELS"></a><a name="l323"></a>
<h3>4.3.5: Labels, links, references and URLs</h3>
References such as <em>see ... for more information</em> are very common in
documents. Yodl supports three mechanisms to accomplish such references:
<dl>
<p><dt><strong>Labels and references:</strong><dd> 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 <em>see section 1.3</em>.
<p>
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.
<p><dt><strong>Labels and links:</strong><dd> This mechanism can be used to set links in a
document without using the number of a sectioning command, as in <em>see the
introduction for more information</em>, with the <em>introduction</em> being a
clickable link to some label.
<p>
This mechanism of course only leads to a clickable link in HTML: in other
formats the text <em>see the</em> etc. is just typeset as is.
<p><dt><strong>URLs:</strong><dd> Universal Resource Locators (URLs) are used to create links to
other HTML documents or services, like HTML's <code><a href=..></code> method. The
URLs of course only result in clickable links in HTML output; in other output
formats only some descriptive text appears.
</dl>
The above mechanism is implemented by the following macros:
<ul>
<li> The macro <code>label(name)</code> defines a label named <code>name</code>. The
name of the label can be used in a <code>ref</code> or <code>link</code> macro.
<li> The macro <code>ref(name)</code> sets a reference to the label named
<code>name</code>. 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
<pre>
section(How to install my program) label(howtoinstall)
This section describes...
...
See section ref(howtoinstall) for installation instructions.
</pre>
The macro <code>ref(howtoinstall)</code> expands to the number of the
section named <em>How to install my program</em>.
<li> The macro <code>link(description)(name)</code> always expands to the
<code>description</code>. In HTML output, a clickable link is created pointing to a
label called <code>name</code>. For example:
<pre>
label(megahard)
COMMENT(sigh...)
The Jodel package isn't shareware, it isn't
beggarware, it isn't freeware, it's
bf(megahard-ware).
...
Who wants a link(picosoft)(megahard)?
</pre>
This code fragment would always set the text <em>picosoft</em>, but under HTML
a clickable link would appear pointing to <code>link(the text)(megahard)</code>.
<li> The macro <code>url(description)(location)</code> always expands to the
<code>description</code>, but creates a hyperlink pointing to <code>location</code> in HTML.
For example,
<pre>
Take a look at my
url(homepage)(http://www.somwhere.nl/karel/karel.html).
</pre>
The text <a href="http://www.somwhere.nl/karel/karel.html">homepage</a> 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 <code>description</code> part, surrond it <em>inside the url
parameter list</em>, as in:
<pre>
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).
</pre>
<li> The macro <code>email(address)</code> is a special case of <code>url</code>: under
HTML, the <code>address</code> appears as a clickable link in slanted font to mail
<code>address</code>. For example:
<pre>
I can be reached at
email(f.b.brokken@rug.nl).
</pre>
I can be reached at <a href="mailto:f.b.brokken@rug.nl"><em>f.b.brokken@rug.nl</em></a>.
<p>
Always keep in mind that the name of a label must be exactly identical in
both the <code>label</code> macro and in the <code>ref</code> or <code>link</code> macro. Other than
that, the name is irrelevant.
<p>
Furthermore, note that <code>lincludefile</code> 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:
<pre>
chapter(Introduction)
sect(Welcome)
lincludefile(WELCOME)(welcome)
chapter(Technical information)
lincludefile(TECHINFO)(techinfo)
</pre>
creates two labels: <code>WELCOME</code> and <code>TECHINFO</code>.
</ul>
Here are some final thoughts about using labels and references:
<ul>
<li> Don't put `weird' characters in label names. Generally, don't use
spaces and tabs.
<li> 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:
<pre>
ref(em(labelname))
</pre>
The reason for the incorrectness is, what internal name should
<code>em(labelname)</code> generate? Here probably an attempt is made to set a
reference in italics. The right construction is of course to set <em>whatever
<code>ref()</code> returns</em> in italics, as in:
<pre>
em(ref(labelname))
</pre>
<li> The <code>label</code> 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
<pre>
section(Introduction label(intro))
</pre>
The right form being
<pre>
section(Introduction)label(intro)
</pre>
(linking to <code>intro</code> will usually <em>not</em> show <code>Introduction</code>), or:
<pre>
label(intro)section(Introduction)
</pre>
(linking to <code>intro</code> <em>will</em> usually show <code>Introduction</code>), or:
</ul>
<p>
<a name="l324"></a>
<h3>4.3.6: Lists and environments</h3>
Yodl's default macros support the following lists and environments:
<p>
By default, the following lists are available:
<dl>
<p><dt><strong>Description lists:</strong><dd> 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 <code>description()</code> macro. The
elements of the list start with <code>dit()</code>. The <code>dit()</code>
macro expects a short description of the item.
<p>
Example:
<pre>
A description list:
description(
dit(First this:) One item.
dit(Then this:) Another item.
)
</pre>
<p><dt><strong>Enumeraton lists:</strong><dd> An enumeration list consist of sequentially
numbered elements. The list is generated by the <code>enumeration()</code>
macro. Its elements start with the <code>eit()</code> macro.
<p>
Example:
<pre>
An enumerated list:
enumeration(
eit() One item.
eit() Another item.
)
</pre>
<p><dt><strong>Itemized lists:</strong><dd> An itemized lists consists of indented items, usually
preceded by a bullet.
<p>
An itemized list is produced by the <code>itemization()</code> macro, which has one
argument: the items themselves. These items must start with <code>it()</code>.
<p>
Example:
<pre>
An itemized list:
itemization(
it() One item.
it() Another item.
)
</pre>
</dl>
Specialized environments are:
<dl>
<p><dt><strong>Centered text:</strong><dd> Centering text may not be available in all output
formats. When unavailable, the text is typeset left-flushed.
<p>
Centered text is generated by the <code>center()</code> macro. Line brakes within
centered text may be obtained using the <code>nl()</code> macro.
<p>
Example:
<pre>
center(
Centered text. nl()
Another line of centered text.
)
</pre>
<p><dt><strong>Verbatim text:</strong><dd> <em>Verbatim</em> 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.
<p>
The text must either be inside the <code>verb()</code> macro. For example:
<pre>
verb(
This is totally verbatim text.
It is not further processed by Yodl.
)
</pre>
The verbatim text is of course not subject to macro expansion by Yodl.
Note, however, that <code>SUBST</code> transformations <em>will</em> take place, as these
substitutions take place during the lexical scanning phase of <code>Yodl</code>'s input,
and are not part of the macro-expansion process. See also section <a href="yodl03.html#SUBST">3.1.65</a>.
<p>
Furthermore, if a character translation table has been defined, the
argument of the <code>verb()</code> macro will also be subject to character
table transformations. By temporarily suppressing the active character table
(see section <a href="yodl03.html#PUSHCHARTABLE">PUSHCHARTABLE 3.1.56</a>) this can be prevented.
<p><dt><strong>Quotations:</strong><dd> 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 <code>quote()</code> macro:
<pre>
Shakespeare once wrote:
quote(
``To be or not to be, that's the question''
)
</pre>
</dl>
<p>
<a name="NATIONAL"></a><a name="l325"></a>
<h4>4.3.6.1: National language support</h4>
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 <code>chapter(Introduction)</code> will
by default result in the text <em>Chapter 1: Introduction</em>.
<p>
Using the <code>setchapterstring(text)</code> macro, the <em>Chapter</em> text can be
redefined. E.g., in a Dutch text you might put
<pre>
setchapterstring(Hoofdstuk)
</pre>
somewhere near the beginning of your document. Similar to
<code>setchapterstring</code>, a macro <code>getchapterstring</code> exists returning the
text identifying chapters. (Internally, <code>getchapterstring</code> is of course
used to actually set the text). To redefine the text to identify a part, use
<code>setpartstring(text)</code>; to redefine the text to identify a figure, use
<code>setfigurestring(text)</code>.
<p>
The <code>set....string</code> macros only influence how Yodl names chapters or
parts in HTML, <code>man</code>, <code>ms</code> or <code>txt</code> 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., <code>dutch.sty</code>. Therefore, if you want a Dutch
document, you need to:
<ul>
<li> put <code>latexpackage(dutch)(babel)</code>in the preamble of
the document. This ensures that LaTeX uses Dutch abbreviation rules.
<li> redefine the chapter and part names for non-LaTeX output, using:
<pre>
setlanguage(dutch)
</pre>
<li> Finally, you should probably type your text in Dutch.
</ul>
The <code>setlanguage()</code> macro expects one argument: the name of the language
that is used. See section <a href="yodl04.html#MACROLIST">4.2</a> for details about this macro. The
<code>setlanguage()</code> macro redefines the language-dependent section (and other)
headers, and depends on the availability of the corresponding
<code>language<name>()</code> macro, where <code><name></code> is the name of the language (by
convention <code><name></code> states the english name of the language).
Currently, <code>languagedutch()</code>, <code>languageenglish()</code> (the default),
and <code>languageportugese()</code> are available. It's easy to expand this little set
with macros for other languages. The <code>setlanguage()</code> macro merely requires
the specification of the language. For example:
<pre>
setlanguage(english)
</pre>
This macro installs the following defaults (corresponding translations
should be defined for other languages):
<pre>
settocstring(Table of Contents)
setaffilstring(Affiliation)
setauthorstring(Author)
setchapterstring(Chapter)
setdatestring(Date)
setfigurestring(Figure)
setpartstring(Part)
settitlestring(Title)
</pre>
<p>
<a name="l326"></a>
<h4>4.3.6.2: Pagebreaks after the title and table of contents</h4>
Yodl inserts page-breaks in a limited number of cases:
<ul>
<li> A pagebreak is generated after the title information in <code>book</code> and
<code>report</code> documents.
<li> A pagebreak is generated after a table of contents in all documents.
</ul>
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 <code>book</code> or a <code>report</code>, the title and
table of contents will also be separated by a pagebreak.
<p>
This behavior can be modified using the <code>(no)titleclearpage()</code> and
<code>(no)tocclearpage()</code> directives, further described in section
<a href="yodl04.html#MODIFIERS">4.3.8</a>.
<p>
<a name="l327"></a>
<h3>4.3.7: Sectioning</h3>
This section describes the sectioning commands for <code>article</code>s, <code>report</code>s,
<code>book</code>s and for <code>plainhtml</code>. The document type <code>manpage</code> defines its own
sectioning commands (cf. section <a href="yodl04.html#MANPAGE">4.1.2</a>:
<ul>
<li> <code>part(title)</code>: Starts a new part. Only available in <code>book</code>
documents.
<li> <code>chapter(title)</code>: Starts a new chapter. Only available in <code>book</code>
or <code>report</code> documents.
<li> <code>sect(title)</code>: Starts a section.
<li> <code>subsect(title)</code>: A subsection.
<li> <code>subsubsect(title)</code>: A sub-subsection.
<li> <code>subsubsubsect(title)</code>: An even smaller sectioning command.
</ul>
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 <code>n</code> prefix (<code>npart</code>,
<code>nchapter</code>, <code>nsect</code> etc.) which generate neither entries in the table of
contents nor numbers. The <code>n</code>-versions can be used in, e.g., an article
where the sectioning commands should show their captions, but not any numbers
generated by default.
<p>
Sectioning should always start at the top level sections of the available
document: <code>chapter</code> for reports, <code>sect</code> for articles, etc.. If you start a
document with a lower sectioning command (e.g., when you start an article with
a <code>subsect</code>), the numbering of sections may go haywire. The only exception
to this rule is the <code>part</code> of a <code>book</code> document: parts are optional, in
books, <code>chapter</code>s may be the top sectioning commands. Summarizing, books or
reports should start with <code>chapter</code>. Articles should start with
<code>sections</code>.
<p>
The sectioning commands have a further function: when <code>label</code> 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 <a href="yodl04.html#LABELS">4.3.5</a>.
<p>
<a name="MODIFIERS"></a><a name="l328"></a>
<h3>4.3.8: Typesetting modifiers</h3>
This section lists various macros that can be used to modify the looks of your
document. When used, these macros must appear <em>before</em> stating the document
type with <code>article</code>, <code>report</code>, <code>book</code>, <code>manpage</code> or <code>plainhtml</code>.
<ul>
<li> <code>abstract(text)</code>: This macro is relevant for all output formats.
The <code>text</code> 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 <code>article</code>s and <code>report</code>s, but not in other
document types. I.e., if you need introductory text in a <code>book</code>, you should
start with a non-numbered chapter that holds this text.
<li> <code>affiliation(site)</code>: This macro is relevant for <code>article</code>,
<code>report</code> and <code>book</code> documents. It defines the affiliation of the
author. The <code>site</code> information appears in the title, below the author's
name.
<li> <code>htmlbodyopt(option)(value)</code>: This macro adds <code>option="value"</code> to
the <code><body></code> tag that will be generated for HTML output. The HTML converter
generates <code><body></code> 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 <code><body></code> tag options, but useful ones may be e.g.:
<pre>
htmlbodyopt(fgcolor)(#000000)
htmlbodyopt(bgcolor)(#FFFFFF)
</pre>
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 <code>htmlbodyopt(background) (some.gif)</code>, defining
<code>some.gif</code> as the page background.
<p>
See the documentation on HTML for more information.
<p>
Note that <code>value</code> is automatically surrounded by double quotes when
this macro is used. They should not be used by authors using this macro.
<li> <code>latexdocumentclass(class)</code>: This macro forces the
<code>\documentclass{...}</code> setting in LaTeX output to <code>class</code>.
<li> <code>latexlayoutcmds(commands)</code>: This macro can be used to specify your
own LaTeX layout commands. When present, the <code>commands</code> are placed in LaTeX
output following the <code>\documentclass</code> definition.
<li> <code>latexoptions(options)</code>: This macro is only relevant for LaTeX
output formats, it is not expanded in other formats. The <code>options</code> are used
in LaTeX's <code>\documentclass</code> definition; e.g., a useful option might be
<code>dina4</code>. Multiple options should be separate by commas, according to the
LaTeX convention.
<li> <code>latexpackage(options)(name)</code>: This macro is only relevant for
LaTeX output formats, it is not expanded in other formats. Each <em>package</em>
should have its own <code>latexpackage()</code> statement. If there are no options, the
<code>options</code> argument should remain empty. Here is an example using this macro:
<pre>
latexpackage(dutch)(babel)
</pre>
<li> <code>mailto(email)</code>: The <code>mailto</code> macro is only expanded in HTML
documents, it is ignored in other formats. It defines where mail about the
document should be sent to.
<li> <code>nosloppyhfuzz()</code>: By default, the LaTeX output contains the text
<pre>
\hfuzz=4pt
</pre>
which is placed there by the macro package. This suppresses <em>overfull
hbox</em> warnings of LaTeX when the overfull-ness is less than 4pt. Use
<code>nosloppyhfuzz()</code> to get the standard LaTeX warnings about overfull hboxes.
<li> <code>notableofcontents()</code>: 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.
<p>
The table of contents is by default suppressed in <code>plainhtml</code> and
<code>manpage</code> documents.
<li> <code>notitleclearpage()</code>: Normally, Yodl inserts a <code>clearpage()</code>
directive after typesetting title information in <code>book</code> or <code>report</code>
documents, but not in <code>article</code> documents. Use <code>notitleclearpage</code> to
suppress this directive.
<li> <code>notocclearpage()</code> (no table-of-contents clear-page): In all
document types, Yodl inserts a <code>clearpage()</code> directive following the table
of contents. Use <code>notocclearpage()</code> to suppress that.
<li> <code>noxlatin()</code>: The LaTeX output contains by default the command to
include the file <code>xlatin1.tex</code>, distributed with Yodl. This file maps
Latin-1 characters to LaTeX-understandable codes and makes sure that you can
type characters such as <code>ü</code>, and still make them processable by LaTeX. If
you don't want this, put <code>noxlatin()</code> in the preamble.
<li> <code>standardlayout()</code>: This is another LaTeX option. Use
<code>standardlayout()</code> to get `vanilla' LaTeX layout, possibly indenting
paragraphs and using fairly limited vertical spacing between paragraphs.
This macro is ignored for other conversion types.
<li> <code>titleclearpage()</code>: Forces the insertion of a <code>clearpage()</code>
directive after the title information has been typeset. This behavior is the
default in <code>book</code> and <code>report</code> documents. See also <code>notitleclearpage()</code>.
<li> <code>tocclearpage()</code>: Forces the insertion of a <code>clearpage()</code>
directive following the table of contents. This behavior is default in all
document types; the macro is provided for consistency reasons with
<code>(no)titleclearpage()</code>.
</ul>
<em>Note again</em>: these modifiers must appear <em>before</em> the document type
definition.
<p>
<a name="l329"></a>
<h3>4.3.9: Miscellaneous commands</h3>
The following is a list of commands that don't fall in one of the above
categories.
<ul>
<li> <code>clearpage()</code>: 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
<a href="yodl04.html#MODIFIERS">4.3.8</a> for a discussion of <code>(no)titleclearpage()</code> and
<code>(no)tocclearpage()</code>.)
<li> <code>def(macro)(nrofarguments)(definition)</code>: This defines a new macro
<code>macro</code> having <code>nrofarguments</code> arguments, and expanding to
<code>definition</code>. The markers <code>ARG</code><em>x</em>, where <em>x</em> is 1, 2, etc., can be
used in the <code>definition</code> part to indicate where arguments should be pasted
in. This macro is a shorthand for <code>DEFINEMACRO</code>, see section
<a href="yodl03.html#DEFINEMACRO">3.1.11</a>.
<li> <code>footnote(text)</code>: This macro sets <code>text</code> as a footnote when the
output format allows it. When not, the text is set in parentheses.
<li> <code>gagmacrowarning(name name ...)</code>: This macro suppresses <code>yodl</code>'s
warnings <em>cannot expand possible user macro name</em>, where <code>name</code> is a
candidate macro name. <code>gagmacrowarning</code> is a synonym for <code>NOUSERMACRO</code>,
described in section <a href="yodl03.html#NOUSERMACRO">3.1.45</a>.
<br>
E.g., if your document contains <code>"as for manpages, see sed(1), tr(1) and
awk(1)"</code>, and if you get tired of warnings about possible user macros sed, tr
and awk, try the following:
<pre>
gagmacrowarning(sed tr awk)
...
As for manpages, see sed(1), tr(1) and awk(1).
</pre>
<li> <code>htmlnewfile()</code>: Starts a new subfile in HTML output. This stanza
is also automatically generated when the HTML converter encounters a
<code>chapter</code> directive. Using <code>htmlnewfile</code>, 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 <code>label</code> and <code>ref</code>, or <code>label</code> and
<code>link</code>.
<li> <code>includefile(file)</code>: Includes <code>file</code> and defines a label (see the
<code>label</code> macro) with the same name. Furthermore, a message about the
inclusion is shown on the screen. The <code>file</code> is searched for relative to the
directory of the file in which the <code>includefile</code> macro was used (or relative
to the directory where the <code>yodl</code> run was started when the
<code>--legacy-include</code> or <code>-L</code> option was provided) and also in the
system-wide include directory. The default extension <code>.yo</code> is supplied if
necessary.
<br>
The <code>lincludefile</code> macro is handy in the following situation:
<pre>
chapter(Introduction)
lincludefile(INTRO)(intro)
</pre>
This fragment starts a chapter and includes a file. Here the label name
(<code>INTRO</code>) can also be used to refer to the chapter as the <code>lincludefile</code>
stanza appears <em>immediately</em> following the corresponding
sectioning command.
<li> <code>nl()</code>: Forces a new line. Some output formats may produce an error
upon the usage of <code>nl()</code> in `unexpected' places; e.g., LaTeX won't allow new
lines in the footnote text (as defined in the <code>footnote</code> macro). Using
<code>nl()</code> in running text should however be ok. Example:
<pre>
This line is nl()
broken in two.
</pre>
<li> <code>redefinemacro(macro)(nrofargs)(redef)</code>: This command (re)defines a
macro, expecting <code>nrofargs</code> arguments, to <code>redef</code>. If a previous
definition of the macro existed, it is overruled. Example:
<pre>
redefinemacro(clearpage)(0)(\
em(---New page starts here---))
</pre>
Use <code>ARG</code><em>x</em> in the <code>redef</code> part to indicate where all arguments
should occur, as in the following imaginary macro to typeset a literature
reference:
<pre>
redefinemacro(litref)(3)(
Title: bf(ARG1) nl()
Author(s): em(ARG2) nl()
Published by: ARG3
)
...
litref(Java in a Nutshell)
(David Flanagan)
(O'Reilly & Associates, Inc.)
</pre>
The <code>redefinemacro</code> statement also has a shorthand called <code>redef</code>.
</ul>
<p>
<a name="l330"></a>
<h2>4.4: Locations of the macros</h2>
The files defining the macros are by default installed to the directory
<code>/usr/local/share/yodl</code> during Yodl's installation process (Note that this
diverts from an earlier default: <code>/usr/local/lib/yodl</code>; furthermore,
some systems or some distributions may use other locations).
<p>
The files in this directory are organized as follows:
<ul>
<li> The files that should be read for a particular conversion are named
after their conversion, e.g., <code>latex.yo</code> and <code>html.yo</code>. These files must
be processed by Yodl before your document can be converted accordingly. The
provided <code>yodl2...</code> scripts take care of that automatically.
<li> All support counters, symbols and macros are defined in files named
<code>std.<conversion>.yo</code>, e.g., <code>std.html.yo, std.latex.yo</code>. 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.
<li> The predefined character tables are found in files names
<code>chartables/<conversion>.yo</code>.
</ul>
The (binary) Yodl package contains the following programs and support
files:
<ul>
<li> The <code>yodl</code> program itself, which generates converted document(s);
<li> The <code>yodlpost</code> postprocessor, which performs fixups for conversion
formats. Using <code>yodlpost</code> is required for formats whose documents
cannot be created in one pass by <code>yodl</code> itself;
<li> Auxiliary scripts such as <code>yodl2tex</code>, <code>yodl2html</code>;
<li> The macros and character tables for the various conversion types;
<li> The raw macros and the macro-generating scripts;
<li> The documentation (html and manual pages)
</ul>
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 <code>C</code>
compiler (preferably the <code>Gnu</code> <strong>C</strong> compiler) available, and preferably the
<code>icmake</code> program maintenance utility. Basic support for <code>make</code> is provided
as well.
<p>
<hr>
<ul>
<li> <a href="yodl.html">Table of Contents</a>
<li> <a href="yodl03.html">Previous Chapter</a>
<li> <a href="yodl05.html">Next Chapter</a>
</ul>
<hr>
</body>
</html>
distrib
>
Mageia
>
4
>
i586
>
media
>
core-release
>
by-pkgid
>
f9a3dabf4d0709484a9d2134094ee2a2
>
files
>
11
