.TH "Yodl macros" "7" "1996\-2017" "yodl_4\&.01\&.00\&.tar\&.gz" "Your Own Document Language"
.PP
.SH "NAME"
yodlmacros \- Macros for the Yodl converters
.PP
.SH "SYNOPSIS"
This manual page lists the standard macros of the Yodl package\&.
.PP
.SH "DESCRIPTION"
The following list shows the macros defined by the Yodl converters
define and which can be used in Yodl documents\&. Refer to the Yodl user
guide, distributed with the Yodl package, for a full description\&.
.PP
\fBNOTE:\fP Starting with Yodl version 3\&.00\&.0 Yodl\(cq\&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\(cq\&s
file inclusion behavior now matches the way \fBC\fP\(cq\&s \f(CW#include\fP directive
operates; it has the disadvantage that it may break some current
documents\&. Conversion, however is simple but can be avoided altogether if
Yodl\(cq\&s \f(CW\-L\fP (\f(CW\-\-legacy\-include\fP) option is used\&. This affects the
\f(CW(l)includefile, includeverbatim, notransinclude\fP and \f(CWverbinclude\fP macros
(see below)\&.
.PP
The following list shows all macros of the package in alphabetical
order\&.
.PP
.IP "\f(CWabstract(text)\fP"
Defines an abstract for an \f(CWarticle\fP or \f(CWreport\fP document\&. Abstracts are
not implemented for \f(CWbook\fPs or \f(CWmanpage\fPs\&. Must appear \fBbefore\fP
starting the document with the \f(CWarticle\fP or \f(CWreport\fP macro\&.
.IP
.IP "\f(CWaddntosymbol(symbol)(n)(text)\fP"
Adds \f(CWtext\fP \f(CWn\fP times to \f(CWsymbol\fP\&. The value \f(CWn\fP may also be the name
of a defined counter (which itself will not be modified)\&.
.IP
.IP "\f(CWaffiliation(site)\fP"
Defines an affiliation, to appear in the document titlepage below the author
field\&. Must appear \fBbefore\fP starting the document with \f(CWarticle\fP,
\f(CWreport\fP or \f(CWbook\fP\&. The affiliation is only printed when the author field
is not empty\&. When converting to html the way the affiliation is displayed can
be tuned using CSS id selector specifications\&. The affiliation has
\f(CWid=\(dq\&affiliation\(dq\&\fP\&.
.IP
.IP "\f(CWAfourEnlarged()\fP"
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\&.
.IP
.IP "\f(CWappendix()\fP"
Starts appendices
.IP
.IP "\f(CWarticle(title)(author)(date)\fP"
Starts an article\&. The top\-level sectioning command is \f(CW(n)sect\fP\&. In HTML
conversions only one output file is written, while the way the headings are
displayed can be tuned using CSS id selector specifications: the title has
\f(CWid=\(dq\&title\(dq\&\fP, the author \f(CWid=\(dq\&author\(dq\&\fP, and the date \f(CWid=\(dq\&date\(dq\&\fP\&.)
.IP
.IP "\f(CWattrib(text)\fP"
In html, pushes \f(CWtext\fP as an attribute for the next html tag supporting
\f(CWattrib\fP\&. E\&.g, to
set a blue color and 30 pixel left\-hand side margin for a section use
.nf
attrib(style=\(dq\&color:blue;margin\-left:30px;\(dq\&)\e
sect(Section name)
.fi
This results
in the html markup
.br
.nf
Section name
.fi
This macro is only effective with html conversions\&. It is applied in a
stack\-wise fasion: when multiple \f(CWattrib\fP calls are used, then the topmost
attrib\-string is added to the first macro calling the
\f(CWattribinsert\fP macro, with subsequent macros using subsequent elements on
the attrib\-stack\&.
.IP
Commonly used attributes are \f(CWid=\(dq\&idname\(dq\&\fP, expecting a \f(CW#idname\fP CSS
label in either internal or external CSS specifications, or \f(CWstyle=\(dq\&spec\(dq\&\fP
(as shown in the example)\&.
.IP
Example: when using
.nf
attrib(width = \(dq\&100\(dq\& height = \(dq\&100\(dq\&)
attrib(id = \(dq\fig\(dq\&)
figure(imgfile)(Caption)(IMG)
.fi
then the \f(CW#id\fP attribute is applied to \f(CW\fP, and the \f(CWwidth\fP
and \f(CWheight\fP attributes are applied to \f(CW \fP, which html markup is
inserted by the \f(CWfigure\fP macro\&.
.IP
The \f(CWattrib\fP macro is supported by the following predefined macros (between
parentheses the number of attribute strings that are inserted by these macros;
if only 1 attribute string is inserted no number is shown):
.IP
\f(CWbf cell cells center chapter code dashes dit em figure(3) file htmltag
itdesc lchapter link lref lsect lsubsect lsubsubsect nchapter npart nsect
nsubsect nsubsubsect paragraph part quote row sc sect strong subs subsect
subsubsect subsubsubsect sups tableatt tt ttbegin url verb verborg
verbinclude\fP\&.
.IP
.IP "\f(CWattribclear()\fP"
Removes any existing contents from the attrib\-stack\&. This macro is only
active when converting to html
.IP
.IP "\f(CWattribinsert()\fP"
In html, if the attrib\-stack is not empty,
inserts the value on top of the attrib\-stack and then pops the topmost value\&.
If the attrib\-stack is empty, nothing happens\&.
.IP
.IP "\f(CWbf(text)\fP"
Sets \f(CWtext\fP in boldface\&.
.IP
.IP "\f(CWbind(text)\fP"
Generate a binding character after text\&.
.IP
.IP "\f(CWbook(title)(author)(date)\fP"
Starts a book document\&. The top\-level sectioning command is \f(CW(n)chapter\fP,
\f(CW(n)part\fP being optional\&. In HTML output files are created for each
chapter, while the way the headings are displayed can be tuned using
CSS id selector specifications: the title has \f(CWid=\(dq\&title\(dq\&\fP, the author
\f(CWid=\(dq\&author\(dq\&\fP, and the date \f(CWid=\(dq\&date\(dq\&\fP\&.)
.IP
.IP "\f(CWcell(contents)\fP"
Sets a table cell, i\&.e\&., one element in a row\&. With the man/ms converters
multiple blanks between \f(CWcell()\fP macro calls are merged into a single blank
character\&.
.IP
.IP "\f(CWcells(nColumns)(contents)\fP"
Set a table cell over \f(CWnColumns\fP columns\&. With LaTeX and xml the
information in the combined cells is centered\&.
.IP
With man/ms conversions the \f(CWcells()\fP macro simply calls the \f(CWcell()\fP
macro, but here the \f(CWsetmanalign()\fP macro can be used to determine the
alignment of multiple cells\&.
.IP
With html the macro \f(CWattrib\fP can be used, but when it contains a \f(CWstyle\fP
specification the macro\(cq\&s default \f(CWstyle=\(dq\&text\-align: center\(dq\&\fP is ignored
(but it can optionally be specified using the \f(CWattrib\fP macro)\&.
.IP
.IP "\f(CWcellsline(from)(count)\fP"
Sets a horizontal line starting at column number \f(CWfrom\fP over \f(CWcount\fP
columns in a row\&. If \f(CWfrom\fP is less then the number of columns already added
to a row then it is ignored\&. This macro must be embedded in a \f(CWrow\fP macro
defining a table row\&. To put a line across the table\(cq\&s full width use
\f(CWrowline\fP\&. To set horizontal lines across columns 1
until 2 and columns 4 until 5 table of a table use:
.nf
row(cellsline(1)(2)cellsline(4)(2))
.fi
Combining \f(CWcellsline\fP and \f(CWcell\fP or \f(CWcells\fP calls in one row produces
undefined results\&.
.IP
.IP "\f(CWcenter(text)\fP"
Centers \f(CWtext\fP\&. Use \f(CWnl()\fP in the text to break lines\&. In html the
\f(CWattrib\fP macro is not supported, but a division (\f(CWdiv\fP) with style
definition \f(CWtext\-align: center\fP is used\&. To center a table in html use
the \f(CWtableatt\fP macro\&. If a \f(CWtable\fP or \f(CWtableatt\fP macro is used inside a
\f(CWcenter\fP macro then the contents of columns are column\-wise centered\&.
.IP
.IP "\f(CWchapter(title)\fP"
Starts a new chapter in \f(CWbook\fPs or \f(CWreport\fPs\&.
.IP
.IP "\f(CWcindex()\fP"
Generate an index entry for LaTex() or texinfo
c\-indices\&. Its argument is the
index entry\&. See also the \f(CW[fptv]index\fP macro\&.
.IP
.IP "\f(CWcite(1)\fP"
Sets a citation or quotation
.IP
.IP "\f(CWclearpage()\fP"
Starts a new page, when the output format permits\&. Under HTML a horizontal
line is drawn\&.
.IP
.IP "\f(CWcode(text)\fP"
Sets \f(CWtext\fP in code font, and prevents it from being expanded\&.
For unbalanced parameter lists, use \f(CWCHAR(40)\fP to get
\f(CW(\fP and \f(CWCHAR(41)\fP to get \f(CW)\fP\&.
.IP
.IP "\f(CWcolumnline(from)(to)\fP"
Sets a horizontal line over some columns in a row\&. Note that \f(CWcolumnline\fP
defines a row by itself, consisting of just a horizontal line spanning some of
its columns, rather than the table\(cq\&s full width, like \f(CWrowline\fP\&. The two
arguments represent column numbers\&. It is the responsibility of the author to
make sure that the \f(CWfrom\fP and \f(CWto\fP values are sensible\&. I\&.e\&.,
.nf
1 <= from <= to <= ncolumns
.fi
\fBNote\fP: this macro cannot be used if multiple lines must be set in one
row\&. In those cases the macro \f(CWcolsline\fP should be used\&.
.IP
.IP "\f(CWdashes()\fP"
Inserts two Sets \f(CWtext\fP in teletype font, and prevents it from being expanded\&.
For unbalanced parameter lists, use \f(CWCHAR(40)\fP to get
\f(CW(\fP and \f(CWCHAR(41)\fP to get \f(CW)\fP\&.
.IP
The \f(CWtt\fP macro interprets character tables as well as \f(CWSUBST\fP
definitions\&. This is usually what is intended\&. In situations where \f(CWtt\fP
performs unwelcome transformations, use the pair of \f(CWttbegin\fP and \f(CWttend\fP
macros\&.
.IP
In html the \f(CWattrib\fP macro applies to the \f(CW\fP tag\&.
.IP
.IP "\f(CWdef(macroname)(nrofargs)(redefinition)\fP"
Defines \f(CWmacroname\fP as a macro, having \f(CWnrofargs\fP arguments, and
expanding to \f(CWredefinition\fP\&. This macro is a shorthand for
\f(CWDEFINEMACRO\fP\&. An error occurs when the macro is already defined\&. Use
\f(CWredef()\fP to unconditionally define or redefine a macro\&.
.IP
.IP "\f(CWdescription(list)\fP"
Sets \f(CWlist\fP as a description list\&. Use \f(CWdit(item)\fP to
indicate items in the list\&.
.IP
.IP "\f(CWdit(itemname)\fP"
Starts an item named \f(CWitemname\fP in a description list\&. The list should be
used in \f(CWdescription\fP macros\&. With \f(CWhtml\fP conversions the
contents of a description item is separated from the item itself\&. The \f(CWdit\fP
macro only defines the item, and not the description itself\&. This macro sets
the item in bold\-face (`strong\(cq\& font)\&. The macro \f(CWitdesc\fP, available since
Yodl 3\&.05, can be used to defines an item \fIand\fP its description, using its
suggested format (i\&.e\&., indenting the description relative to the item)\&.
.IP
.IP "\f(CWeit()\fP"
Indicates an item in an enumerated list\&. The \f(CWeit\fP macro should be used as
an argument in \f(CWenumeration\fP macros\&.
.IP
.IP "\f(CWellipsis()\fP"
Sets ellipsis (\&.\&.\&.)\&.
.IP
.IP "\f(CWem(text)\fP"
Sets \f(CWtext\fP as emphasized, usually italics\&.
.IP
.IP "\f(CWemail(address)\fP"
In HTML, this macro sets the \f(CWaddress\fP in a \f(CW\fP
locator\&. In other output formats, the \f(CWaddress\fP is sent to the output\&. The
\f(CWemail\fP macro is a special case of \f(CWurl\fP\&.
.IP
.IP "\f(CWenumeration(list)\fP"
\f(CWenumeration()\fP starts an enumerated list\&. Use \f(CWeit()\fP in the list to
indicate items in the list\&.
.IP
.IP "\f(CWeuro()\fP"
Sets the euro currency symbol in latex, html, (and possibly sgml and xml)\&. In
all other conversions EUR which is the official textual abbreviation
(cf\&. http://ec\&.europa\&.eu/euro/entry\&.html) is written\&. Note that LaTeX
may require latexpackage()(eurosym)\&.
.IP
.IP "\f(CWfig(label)\fP"
This macro is a shorthand for \f(CWfigure ref(label)\fP and just makes the typing
shorter, as in \f(CWsee fig(schematic) for \&.\&.\fP See \f(CWgetfigurestring()\fP and
\f(CWsetfigurestring()\fP for the \f(CWfigure\fP text\&.
.IP
.IP "\f(CWfigure(file)(caption)(label)\fP"
Sets the picture in \f(CWfile\fP as a figure in the current document, using the
descriptive text \f(CWcaption\fP\&. The \f(CWlabel\fP is defined as a placeholder for
the figure number and can be used in a corresponding \f(CWref\fP statement\&. Note
that the \f(CWfile\fP must be the filename without extension: By default, Yodl
will supply \f(CW\&.gif\fP when in HTML mode, or \f(CW\&.ps\fP when in LaTeX mode\&. Figures
in other modes may not (yet) haven been implemented\&.
.IP
When converting to html, this macro uses three attribute\-strings (if
available)\&. The string pushed first using an attrib\-call defines the
attributes for its \f(CW\fP html\-markup; the string pushed next defines
the attributes for its \f(CW \fP html\-markup; the string pushed last defines
the attributes for its \f(CW\fP html\-markup\&. The \f(CWfigure\fP macro\(cq\&s html
output is organized like this:
.nf
\&.\&.\&.
.fi
Starting with Yodl 3\&.07\&.00 no \f(CWalt=\(dq\&Figure # is shown here\&.\&.\&.\(dq\&\fP attribute is
defined anymore for the \f(CWimg\fP markup: an \f(CWalt\fP\-attribute can easily be
defined at the last attrib\-call, using \f(CWgetfigurestring()\fP to obtain
\f(CWFigure\fP or its language\-specific translation, and
\f(CWCOUNTERVALUE(XXfigurecounter)\fP to obtain the order\-number of the figure
shown in the next \f(CWfigure\fP\-macro call\&.
.IP
.IP "\f(CWfile(text)\fP"
Sets \f(CWtext\fP as filename, usually boldface\&.
In html \f(CWattrib\fP macro applies to the \f(CW\fP tag\&.
.IP
.IP "\f(CWfindex()\fP"
Generate an index entry for LaTex() or texinfo
f\-indices\&. Its argument is the
index entry\&. See also the \f(CW[cptv]index\fP macro\&.
.IP
.IP "\f(CWfootnote(text)\fP"
Sets \f(CWtext\fP as a footnote, or between parentheses when the output format
does not allow footnotes\&.
.IP
.IP "\f(CWgagmacrowarning(name name \&.\&.\&.)\fP"
Prevents the \f(CWyodl\fP program from printing \fIcannot expand possible user
macro\fP\&. E\&.g\&., if you have in your document \f(CWthe file(s) are \&.\&.\fP then you
might want to put before that: \f(CWgagmacrowarning(file)\fP\&. Calls
\f(CWNOUSERMACRO\fP\&.
.IP
.IP "\f(CWgetaffilstring()\fP"
Expands to the string that defines the name of \fIAffiliation Information\fP, by
default \fIAFFILIATION INFORMATION\fP\&. Can be redefined for national language
support by \f(CWsetaffilstring()\fP\&. Currently, it is relevant only for txt\&.
.IP
.IP "\f(CWgetauthorstring()\fP"
Expands to the string that defines the name of \fIAuthor Information\fP, by
default \fIAUTHOR INFORMATION\fP\&. Can be redefined for national language
support by \f(CWsetauthorstring()\fP\&. Currently, it is relevant only for txt\&.
.IP
.IP "\f(CWgetchapterstring()\fP"
Expands to the string that defines a `chapter\(cq\& entry, by default \fIChapter\fP\&.
Can be redefined for national language support by \f(CWsetchapterstring()\fP\&.
.IP
.IP "\f(CWgetdatestring()\fP"
Expands to the string that defines the name of \fIDate Information\fP, by
default \fIDATE INFORMATION\fP\&. Can be redefined for national language
support by \f(CWsetdatestring()\fP\&. Currently, it is relevant only for txt\&.
.IP
.IP "\f(CWgetfigurestring()\fP"
Returns the string that defines a `figure\(cq\& text, in captions or in the
\f(CWfig()\fP macro\&. The string can be redefined using the \f(CWsetfiguretext()\fP
macro\&.
.IP
.IP "\f(CWgetpartstring()\fP"
Expands to the string that defines a `part\(cq\& entry, by default \fIPart\fP\&. Can
be redefined for national language support by \f(CWsetpartstring()\fP\&.
.IP
.IP "\f(CWgettitlestring()\fP"
Expands to the string that defines the name of \fITitle Information\fP, by
default \fITITLE INFORMATION\fP\&. Can be redefined for national language
support by \f(CWsettitlestring()\fP\&. Currently, it is relevant only for txt\&.
.IP
.IP "\f(CWgettocstring()\fP"
Expands to the string that defines the name of the table of contents, by
default \fITable of Contents\fP\&. Can be redefined for national language
support by \f(CWsettocstring()\fP\&.
.IP
.IP "\f(CWhtmlcommand(cmd)\fP"
Writes \f(CWcmd\fP to the output when converting to html\&. The \f(CWcmd\fP is not
further expanded by Yodl\&.
.IP
.IP "\f(CWhtmlheadfile(file)\fP"
Adds the contents of \f(CWfile\fP to the \f(CWhead\fP section of an HTML
document\&. The contents of file are not interpreted and should contain plain
html text\&. This option can be useful when large bodies of text, like the
contents of \f(CW