Yodl
is described in
this chapter. The macro package consists of a number of definition files,
which convert a Yodl document that follows a certain syntax to an output
format. The main output formats, currently supported, are:
latex2e
);
groff
`man' format which is used for man pages;
groff
`ms' format which is more expressive;
The following conversion format is in an experimental stage:
Currently discontinued conversion formats are:
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.
First of all, a Yodl document needs a preamble. This part of the document must be at the top, and must define the modifiers and the document type. Modifiers, when present, must appear first.
Modifiers are often specific for a particular target document type
(e.g., latexoptions
or mailto
), but may also have a general nature
(e.g., affiliation
or abstract
). All modifiers are used to modify
parameters of document types. Therefore, they must be specified before the
document type is defined.
All modifiers are listed in section 4.3.7. In general, you should use
as many modifiers as appropriate. E.g., you should define a mailto
even
when you're not planning to convert your document to HTML. The reason is
twofold: first, you might later decide that a HTML version isn't a bad idea
after all. Second, later versions of the converters might use mailto
even
for non-HTML output formats.
Following the modifiers, the document type is defined. The document type
is either article
, report
, book
, plainhtml
or manpage
.
Except for the manpage
document type, which is a highly specialized
document type, described in section 4.1.2, the following rules apply:
A decision about the document type to use should be based on its complexity. If the document's organization becomes too complex, it is probably a good idea to use a document type supporting a more complex organization. E.g., a complex article might be written as an accessible report, combining related sections into chapters. Similarly, the structure of a report having 30 chapters might improve when it's re-organized as a book having parts. To offer a rule of thumb: a document should have no more than approximately ten top-level sections, and each top-level sectioning should have no more than approximately ten subsections, etc..
The document type influences the way Yodl formats the output. An article
(or plainhtml
) results in one output file. E.g., one final document when
converting to HTML. If your article is way too long, then the loading of the
HTML document also requires much time. When converting to HTML, Yodl splits
report
s and books
into files each holding a chapter. These can be
accessed through the table of contents. So, the document length can also be
relevant when you contemplate switching to a report
or book
.
Documents using special macros, must have defined these macros before they
are used. An appropriate location for these macros is immediately beyond the
preamble. E.g., see the file Documentation/manual/manual.yo
distributed
with the Yodl package. This is the main file of this manual, showing the
preferred organization of Yodl files.
To answer yes-but-what-if oriented minds, here are two results of the wrong order of text, preamble and modifiers:
<html>
tag would come too
late in a HTML conversion, causing the HTML browser to become confused. Or,
the \documentstyle
definition would be seen too late by the LaTeX
typesetter.
latexoptions
, beyond the
document type, then these modifiers have no effect; though Yodl won't complain
either. The reason for this being that the definitions of such modifiers are
encountered only after the stage where they were needed....
.html
file. Nevertheless,
some formats are particularly usefule for some document types. A book
converted to the man
output format to be processed later with groff
won't look too good. Its looks would greatly improve when the document would
be converted to ASCII using the ms
output format.
Following the preamble and the definition of specialized macros symbols and counters, documents start by specifying the document type. The available macros are:
article(title)(author)(date)
: The article
document type
should be used for short documents. Its arguments specify the document's
title, author and date.
In articles, the title page is numbered and the table of contents is on
the title page. The sectioning commands sect
, subsect
etc. are
available.
report(title)(author)(date)
: The report
document type differs
from an article
in that it has a separate unnumbered title page, a table
of contents on a page of its own, and it supports the sectioning command
chapter
in addition to the ones supported by article
s. A report
should be used fir larger documents.
book(title)(author)(date)
: The book
type is for even larger
documents. In addition to the sectioning commands supported by report
it
supports the sectioning command part
.
plainhtml(title)
: This document type is typically used in HTML
output. It's implemented for situations where you only need to create a HTML
file, but want to use Yodl to help you by providing useful macros. This
document type is similar to article
, but does not require you to specify
author
and date
arguments (In fact, you can emulate plainhtml
by
using an article
, using empty author and date arguments).
manpage(title)(section)(date)(source)(manual)
: The manpage
document type should only be used to write Unix-style manual pages. It uses
its own sectioning commands to reflect the necessary sections in a manual
page. This document format is described separately in 4.1.2.
\documentstyle
preamble, HTML output needs <html>
and <body>
tags.
Second, the macros define appropriate document-dependent settings. E.g., the
LaTeX converter defines the title, author and date using \title
etc..
Third, the actual document is started. E.g., for LaTeX this means a
\begin{
type}
, followed by the appropriate commands to generate a
the document title and the table of contents. The title
setting in the
above macros defines the document title which always appears on the front page
of the document. For HTML output, this is also the title of the HTML file (or
files), as appearing in the HTML <title>
tag.
The fact that the macros defining the document type perform many functions means that once the macro is started, nothing `extra' can be inserted between, e.g., the generated title and the table of contents. Sometimes this is not what you'd like; as is the case with an abstract. Yodl therefore uses modifiers, appearing before the document type macros, to insert information between the various elements of a document definition.
Yodl
mapage documents can be converted to groff
documents (using yodl2man
), to html
documents (using yodl2html
), or
to plain ascii text documents (using yodl2txt
).
A manpage document must be organized as follows:
manpage(short title) (section) (date) (source) (manual)Its arguments are:
ls
;
fork()
;
strdup()
;
syslog.conf
);
date
, source
and manual
arguments
can be empty.
manpagename(name)(short description)The
name
argument should be a short name (e.g., the program name), and
the short description
should state the function. The descriptive argument
is used by, e.g., the whatis
database.
manpagesynopsis()Following this, an abbreviated usage information is presented. This information should show, e.g., the possible program flags and required arguments; but no more.
manpagedescription()This is followed by some descriptive text. The descriptive text can e.g. show what the program (function, file, game, etc.) is supposed to do.
manpageoptions()The options are typically a descriptive list of possible flags and their meaning. This section lists the information of the synopsis, but also gives an in-depth description. The
manpageoptions()
section is optional.
manpagefiles()
manpageseealso()This is then followed by a list of related manual pages. Here, use the format
bf(topic)(sectionnr)
, e.g., Yodl
(1).
manpagediagnostics()Diagnostics can state, e.g., what error messages are produced by the program and what the cure is.
manpagebugs()This section is optional.
manpageauthor()
manpage
document type requires you to follow the
above order of commands strictly and to state all the necessary sections (and
optionally, to state the not required sections but in their proper sequence).
Furthermore, sectioning commands that are available in other document types
(sect
, subsect
etc.) are not allowed in a manpage
. You can
however insert other sections in the manual page with the macro
manpagesection
. This macro takes one argument: the title of the extra
section. It is suggested that you type the section name in upper case, to
conform to the standard.
As an example, the manual page for the yodl
program follows (the
actual manual page may differ):
manpage(yodl) (1) (1996) (The Yodl Package) (Yet oneOther Document Language) manpagename(yodl)(main Yodl converter) manpagesynopsis() YODL [-DNAME] [-IDIR] [-oFILE] [-PCMD] [-pPASS] [-t] [-v] [-w] [-h] [-?] inputfile [inputfile...] manpagedescription() This manual page describes the 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, 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, YODL warns when it encounters inconsistencies. dit(-h, -?) Shows usage information. dit(inputfile) File to process, use em(-) to instruct YODL to read from stdin. ) manpagefiles() The 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 YODL are too many to enumerate, but all errors are printed to em(stderr) after which YODL exits with a non-zero status. manpagebugs() There may be bugs in the YODL program, but that's not very likely. More likely you'll encounter bugs or omissions in the macro package itself. manpageauthor() Karel Kubat
Yodl
documents to
other formats. Furthermore, these macros often depend on macros or other
symbols defined for internal use.
Many predefined macros depend on symbols start with XX
. Therefore, it is
strongly advised not to start any locally defined symbol with XX
as doing
so, or undefining existing symbols starting with XX
, may also produce
unexpected results.
Here are the default macros, alphabetically ordered:
Defines an abstract for an article or report type of document. Abstracts are
not implemented for books or manpages. Must appear before starting the
document using the article
or report
macro.
Adds text
n
times to symbol
. The value n
may also be the name
of a defined counter (which is not modified).
Defines an affiliation, to appear in the document titlepage below the author
field. Must appear before starting the document with article
,
report
or book
. The affiliation is only printed when the author field
is not empty. When converting to html the way the affiliation is displayed can
be tuned using CSS id selector specifications. The affiliation has
id="affiliation"
.
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.
Starts appendices
Starts an article. The top-level sectioning command is (n)sect
. 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
id="title"
, the author id="author"
, and the date id="date"
.
)
In html, pushes text
as an attribute for the next html tag supporting
attrib
. E.g, to set a blue color and 30 pixel left-hand side margin for a
section use
attrib(style="color:blue;margin-left:30px;")\ sect(Section name)This results in the html markup
<h1 style="color:blue;margin-left:30px;">Section name</h1>This macro is only effective with html conversions. It is applied in a stack-wise fasion: when multiple
attrib
calls are used, then the topmost
attrib-string is added to the first macro calling the
attribinsert
macro, with subsequent macros using subsequent elements on
the attrib-stack.
Commonly used attributes are id="idname"
, expecting a #idname
CSS
label in either internal or external CSS specifications, or style="spec"
(as shown in the example).
Example: when using
attrib(width = "100" height = "100") attrib(id = "#fig") figure(imgfile)(Caption)(IMG)then the
#id
attribute is applied to <figure>
, and the width
and height
attributes are applied to <img>
, which html markup is
inserted by the figure
macro.
The attrib
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):
bf 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 tbl tac tc tnac tnc tr tt ttbegin url
verb verborg verbinclude
.
Removes any existing contents from the attrib-stack. This macro is only active when converting to html
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.
Sets text
in boldface.
Generate a binding character (non-breaking space) after text.
Starts a book document. The top-level sectioning command is (n)chapter
,
(n)part
being optional. In HTML output files are created for each
chapter, while the way the headings are displayed can be tuned using
CSS id selector specifications: the title has id="title"
, the author
id="author"
, and the date id="date"
.
)
Sets a table cell, i.e., one element in a row. With the man/ms converters
multiple blanks between cell()
macro calls are merged into a single blank
character.
Instead of using cell
in table
, consider using tc
in tbl
.
Set a table cell over nColumns
columns. With LaTeX and xml the
information in the combined cells is centered.
With man/ms conversions the cells()
macro simply calls the cell()
macro, but here the setmanalign()
macro can be used to determine the
alignment of multiple cells.
With html the macro attrib
can be used, but when it contains a style
specification the macro's default style="text-align: center"
is ignored
(but it can optionally be specified using the attrib
macro).
Instead of using cells
in table
, consider using tnc
in tbl
.
Sets a horizontal line starting at column number from
over count
columns in a row. If from
is less then the number of columns already added
to a row then it is ignored. This macro must be embedded in a row
macro
defining a table row. To put a line across the table's full width use
rowline
. To set horizontal lines across columns 1
until 2 and columns 4 until 5 table of a table use:
row(cellsline(1)(2)cellsline(4)(2))Combining
cellsline
and cell
or cells
calls in one row produces
undefined results.
Instead of using cellsline
in table
, consider using tline
in
tbl
.
Centers text
. Use nl()
in the text to break lines. In html the
attrib
macro is not supported, but a division (div
) with style
definition text-align: center
is used. To center a table in html use
the tableatt
macro. If a table
or tableatt
macro is used inside a
center
macro then the contents of columns are column-wise centered.
Inside a center(...)
context the counter XXcenter
is unequal 0.
Starts a new chapter in books or reports.
Generate an index entry for LaTex() or texinfo
c-indices. Its argument is the
index entry. See also the [fptv]index
macro.
Sets text
as a citation or quotation
Starts a new page, when the output format permits. Under HTML a horizontal line is drawn.
Sets text
in code font, and prevents it from being expanded.
For unbalanced parameter lists, use CHAR(40)
to get
(
and CHAR(41)
to get )
.
Sets a horizontal line over some columns in a row. Note that columnline
defines a row by itself, consisting of just a horizontal line spanning some of
its columns, rather than the table's full width, like rowline
. The two
arguments represent column numbers. It is the responsibility of the author to
make sure that the from
and through
values are sensible. I.e.,
1 <= from <= through <= ncolumnsTo set a horizontal line in just one column select
through
equal to
from
.
Note: this macro cannot be used if multiple lines must be set in one
row. In those cases the macros tline, tskip
, and tendline
should be
used.
Instead of using columnline
in table
, consider using tline
in
tbl
.
Inserts two dashes in teletype font, and prevents them from being expanded.
In html the attrib
macro is recognized by the <code>
tag that is used
to embed the two dashes.
Defines macroname
as a macro, having nrofargs
arguments, and
expanding to redefinition
. This macro is a shorthand for
DEFINEMACRO
.
An error occurs when the macro is already defined. Use
redef()
to unconditionally define or redefine a macro.
Sets list
as a description list. Use dit(item)
to
indicate items in the list.
Starts an item named itemname
in a description list. The list should be
used in description
macros. With html
conversions the
contents of a description item is separated from the item itself. The dit
macro only defines the item, and not the description itself. This macro sets
the item in bold-face (`strong' font). The macro itdesc
, available since
Yodl 3.05, can be used to defines an item and its description, using its
suggested format (i.e., indenting the description relative to the item).
Indicates an item in an enumerated list. The eit
macro should be used as
an argument in enumeration
macros.
Sets ellipsis (...).
Sets text
as emphasized, usually italics.
In HTML, this macro sets the address
in a <a href="mailto=..">
locator. In other output formats, the address
is sent to the output. The
email
macro is a special case of url
.
enumeration()
starts an enumerated list. Use eit()
in the list to
indicate items in the list.
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).
Symbol symbol receives the value resulting from evaluating
expression. E.g., if sym
is a defined symbol, then
evalsymbol(sym)(SUBSTR(hello world)(3)(2))assigns the value
lo
to sym
.
This macro is a shorthand for figure ref(label)
and just makes the typing
shorter, as in see fig(schematic) for ..
See getfigurestring()
and
setfigurestring()
for the figure
text.
Sets the picture in file
as a figure in the current document, using the
descriptive text caption
. The label
is defined as a placeholder for
the figure number and can be used in a corresponding ref
statement. Note
that the file
must be the filename without extension: By default, Yodl
will supply .gif
when in HTML mode, or .ps
when in LaTeX mode. Figures
in other modes may not (yet) haven been implemented.
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 <figcaption>
html-markup; the string pushed next defines
the attributes for its <img>
html-markup; the string pushed last defines
the attributes for its <figure>
html-markup. The figure
macro's html
output is organized like this:
<figure -attrib-string pushed last (if any)> <img ... -attrib-string pushed last but one> <figcaption -attrib-string pushed 2nd to last> ... </figcaption> </figure>Starting with Yodl 3.07.00 no
alt="Figure # is shown here..."
attribute is
defined anymore for the img
markup: an alt
-attribute can easily be
defined at the last attrib-call, using getfigurestring()
to obtain
Figure
or its language-specific translation, and
COUNTERVALUE(XXfigurecounter)
to obtain the order-number of the figure
shown in the next figure
-macro call.
Sets text
as filename, usually boldface.
In html attrib
macro applies to the <strong>
tag.
Generate an index entry for LaTex() or texinfo
f-indices. Its argument is the
index entry. See also the [cptv]index
macro.
Sets text
as a footnote, or between parentheses when the output format
does not allow footnotes.
Prevents the yodl
program from printing cannot expand possible user
macro. E.g., if you have in your document the file(s) are ..
then you
might want to put before that: gagmacrowarning(file)
. Calls
NOUSERMACRO
.
Expands to the string that defines the name of Affiliation Information, by
default AFFILIATION INFORMATION. Can be redefined for national language
support by setaffilstring()
. Currently, it is relevant only for txt.
Expands to the string that defines the name of Author Information, by
default AUTHOR INFORMATION. Can be redefined for national language
support by setauthorstring()
. Currently, it is relevant only for txt.
Expands to the string that defines a `chapter' entry, by default Chapter.
Can be redefined for national language support by setchapterstring()
.
Expands to the string that defines the name of Date Information, by
default DATE INFORMATION. Can be redefined for national language
support by setdatestring()
. Currently, it is relevant only for txt.
Returns the string that defines a `figure' text, in captions or in the
fig()
macro. The string can be redefined using the setfiguretext()
macro.
Expands to the string that defines a `part' entry, by default Part. Can
be redefined for national language support by setpartstring()
.
Expands to the string that defines the name of Title Information, by
default TITLE INFORMATION. Can be redefined for national language
support by settitlestring()
. Currently, it is relevant only for txt.
Expands to the string that defines the name of the table of contents, by
default Table of Contents. Can be redefined for national language
support by settocstring()
.
Writes cmd
to the output when converting to html. The cmd
is not
further expanded by Yodl.
Adds the contents of file
to the head
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 <script>
sections, must be included into the head section of
html documents. This macro is only active in the preamble, should only
specified once, and is only interpreted for html conversions.
Adds the literal text option
to the current information in the head
section of an HTML document. Option
may (or: should) contain plain html
text. A commonly occurring head option is link
, defining, e.g., a style
sheet. Since that option is frequently used, it has received a dedicated
macro: htmlstylesheet
. When large bodies of html-text must be added to
html documents the macro htmlheadfile
should be used. This macro is only
active in the preamble and is only interpreted for html conversions.
In HTML output, starts a new file. All other formats are not affected. Note
that you must take your own provisions to access the new file; say via links.
Also, it's safe to start a new file just befoore opening a new section, since
sections are accessible from the clickable table of contents. The HTML
converter normally only starts new files prior to a chapter
definition.
Adds a <style type="text/css"> ... </style>
element to the head section
of an HTML document.
Use htmlstyle
to specify one or more CSS definitions which are eventually
inserted at the ellipsis (...
) in the generic style
definition shown
above. E.g., (using #rrggbb
to specify a color, where rr
are two
hexadecimal digits specifying the color's red component, gg
two
hexadecimal digits specifying the color's green component, and bb
two
hexadecimal digits specifying the color's blue component) specifying
htmlstyle(body)(color: #rrggbb; background-color: #rrggbb) htmlstyle(h1)(color: blue; text-align: center) htmlstyle(h2)(color: green)results in the element
<style type="text/css"> body {color: #rrggbb; background-color: #rrggbb;} h1 {color: blue; text-align: center;} h2 {color: green;} </style>The macros
htmlheadopt
and htmlstylesheet
could also be used to put
information into the head-section of an HTML document, but htmlheadopt
is
of a much more general nature, while htmlstylesheet
refers to CSS elements
stored in an external file. The macro attrib
can be used to define
inline styles.
The htmlstyle
macro is only active in the preamble and is only
interpreted for html conversions.
Refer to available CSS specifications (cf.,
http://www.w3schools.com/cssref/ for an overview of how CSS
specifications are used, and which CSS specifications are available).
By default the internal style specification
figure {text-align: center;} img {vertical-align: center;}
is used. If this is not appropriate, specify nohtmlimgstyle()
in the
preamble.
Adds a <link rel="stylesheet" type="text/css" ...>
element to the head
section of an HTML document, using url
in its href
field. The argument
url
is not expanded, and should be plain HTML text, without surrounding
quotes. The macro htmlheadopt
can also be used to put information in the
head-section of an HTML document, but htmlheadopt
is of a much more
general nature. This macro is only active in the preamble and is only
interpreted for html conversions.
Sets tagname
as a HTML tag, enclosed by <
and >
. When start
is zero, the tagname
is prefixed with /
. As not all html tags are
available through predefined Yodl-macros (there are too many of them, some are
used very infrequently, and you can easily define macros for the tags for
which Yodl doesn't offer predefined ones), the htmltag
macro can be used
to handle your own set of macros. In html the attrib
macro is
supported. E.g.,
attrib(title="World Health Organization")\ htmltag(abbr)()WHO+htmltag(abbr)(0)
The macro ifnewparagraph
should be called from the PARAGRAPH
macro,
if defined. It will insert truelist
if a new paragraph is inserted,
otherwise falselist
is inserted (e.g., following two consecutive calls of
PARAGRAPH). This macro can be used to prevent outputting multiple blank lines.
Includes file
. The default
extension .yo
is supplied if necessary.
Since Yodl version 3.00.0 Yodl's default file inclusion behavior has
changed. The current working directory no longer remains fixed at the
directory in which Yodl is called, but is volatile, changing to the directory
in which a yodl-file is located. This has the advantage that Yodl's file
inclusion behavior now matches the way C's #include
directive
operates. The originally implemented file inclusion behavior is used when
Yodl's -L
(--legacy-include
) option is used.
Include file
into the output. No processing is done, file
should
be in preformatted form, e.g.:
whenhtml(includeverbatim(foo.html))
Indicates an item in an itemized list. Items in it
macros are
arguments of itemization
macros.
Starts an item and its description in a description list. Its name is
itemname
, the contents of the item is defined by contents
. The
itemname
is defined by using the dit
macro.
With html
conversions the contents are surrounded by <dd>
and
</dd>
tags, resulting in contents which are indented relative to the
itemname. When the attrib
macro is used it is applied to the itemname
(dt
-tags).
With other conversions the contents
are quoted (as if using
quote(contents)
).
Sets list
as an itemizationd list. Use it()
to indicate items in the
list.
Generate an index entry for LaTex() or texinfo k-indices. Its argument is the
index entry. See also the [cfptv]vindex
macro.
Defines labelname
as an anchor for a link
command, or to stand for the last numbering of a section or figure in a
ref
command.
Character <
Defines the Dutch-language specific headers. Active this macro via setlanguage(dutch).
Defines the English-language specific headers. Active this macro via setlanguage(english).
Defines the Portugese-language specific headers. Active this macro via setlanguage(portugese).
The LaTeX symbol.
This macro is provided to add Yodl-interpreted text to your own LaTeX layout
commands. The command is terminated with an end-of-line.
See also the macro latexlayoutcmds()
Writes cmd
plus a white space to the output when converting to LaTeX. The
cmd
is not further expanded by Yodl.
Forces the LaTeX
\documentclass{...}
setting to class
. Normally the class is
defined by the macros article
, report
or book
. This macro
is an escape route in case you need to specify your own document class
for LaTeX. This option is a modifier and must
appear before the article
, report
or book
macros.
This macro is provided in case you want to put your own LaTeX layout commands
into LaTeX output. The NOTRANSs
are pasted right after the
\documentclass
stanza. The default is, of course, no local LaTeX
commands. Note that this macro does not overrule my favorite LaTeX
layout. Use nosloppyhfuzz()
and standardlayout()
to disable my favorite
LaTeX layout.
Set latex options: documentclass[options]
.
This command must appear before the document type is
stated by article
, report
, etc..
Include latex package(s), a useful package is, e.g.,
epsf
. This command must appear before the document type is
stated by article
, report
, etc..
Starts a new chapter in books or reports, setting a label at the beginning of the chapter.
Starts a letter written in the indicated language. The date of the letter is set to `date', the subject of the letter will be `subject'. The letter starts with `opening'. It is based on the `letter.cls' document class definition. The macro is available for LaTeX only. Preamble command suggestions:
latexoptions(11pt)
a4enlarged()
letterreplyto(name)(address)(postalcode/city)
letterfootitem(phone)(number)
, maybe e-mail too.
letteradmin(yourdate)(yourref)
letterto(addressitem)
. Use a separate letterto()
macro call
for each new line of the address.
Adds an addendum at the end of a letter. `type' should be `bijlagen', `cc' or `ps'.
Puts `yourletterfrom' and `yourreference' elements in the letter. If left empty, two dashes are inserted.
Puts a footer at the bottom of letter-pages. Up to three will usually fit. LaTeX only.
Defines the `reply to' address in LaTeX or txt-letters.
Adds `element' as an additional line to the address in LaTeX letters.
In HTML output a clickable link with the text description
is created
that points to the place where labelname
is defined using the label
macro, and attrib
macro applies to the <a>
tag. Using
link
is similar to url
, except that a hyperlink is set pointing to a
location in the same document. For output formats other than HTML, only the
description
appears.
This macro is a combination of the ref
and link
macros. In HTML
output a clickable link with the text description
and the label value is
created that points to the place where labelname
is defined using the
label
macro, and attrib
macro applies to the <a>
tag. For output formats other than HTML, only the description
and the
label value appears.
Starts a new section, setting a label at the beginning of the section.
In html attrib
macro applies to the <h2>
tag.
Starts a new subsection. Other sectioning commands are
subsubsect
and subsubsubsect
. A label is added just before the
subsection.
In html attrib
macro applies to the <h3>
tag.
Starts a sub-subsection, a label is added just before the section
In html attrib
macro applies to the <h4>
tag.
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.
An url described by its Locator. For small urls with readable addresses.
Defines the default mailto
address for HTML output. Must appear
before the document type is stated by article
, report
, etc..
Make index for latex.
Writes cmd
to the output when converting to man. The cmd
is not
further expanded by Yodl.
Starts a manual page document. The section
argument must be a number,
stating to which section the manpage belongs to. Most often used are commands
(1), file formats (5) and macro packages (7). The sectioning commands in a
manpage are not (n)sect
etc., but manpage...()
. The first section
must be the manpagename
, the last section must be the
manpageauthor
. The standard manpage for section 1 contains the following
sections (in the given order): manpagename
, manpagesynopsis
,
manpagedescription
, manpageoptions
, manpagefiles
,
manpageseealso
, manpagediagnostics
, manpagebugs
,
manpageauthor
. Optional extra sections can be added with
manpagesection
. Standard manpageframes for several manpagesections
are provided in /usr/local/share/yodl/manframes
. Yodl
manual pages can be
converted to groff, html
, or plain ascii text formats.
Starts the AUTHOR entry in a manpage
document. Must be the last section
of a manpage
.
Starts the BUGS entry in a manpage
document.
Starts the DESCRIPTION entry in a manpage
document.
Starts the DIAGNOSTICS entry in a manpage
document.
Starts the FILES entry in a manpage
document.
Starts the NAME entry in a manpage
document. The short description is
used by, e.g., the whatis
database.
Starts the OPTIONS entry in a manpage
document.
Inserts a non-required section named SECTIONNAME
in a manpage
document. This macro can be used to augment `standard' manual pages with extra
sections, e.g., EXAMPLES. Note that the name of the extra section should
appear in upper case, which is consistent with the normal typesetting of
manual pages.
Starts the SEE ALSO entry in a manpage
document.
Starts the SYNOPSIS entry in a manpage
document.
With man-conversions arguments of tt macros are displayed as normal text. To
enhance their visibility arguments of tt macros may be quoted, in which case
they are surrounded by backtics and normal quotes. By default arguments of tt
macros are not quoted. Quotation is used after calling manttquoted(1)
, and
is suppressed after calling manttquoted(0)
. The macro is only active when
converting to man.
Unbreakable box in LaTeX. Other formats may have different opitions on our unbreakable boxex.
Put a line comment in the output.
Write format-specific comment to the output.
Writes cmd
to the output when converting to ms. The cmd
is not
further expanded by Yodl.
Inserts count
`non-breaking space' characters into the generated output;
i.e., the space character is not optimized away. If the argument list is empty
one non-breaking space is inserted.
Starts a chapter (in a book
or report
) without generating a
number before the title and without placing an entry for the chapter in
the table of contents.
In html attrib
macro applies to the <h1>
tag.
Named email. A more consistent naming for url, lurl, email and nemail would be nice.
Forces a newline; i.e., breaks the current line in two.
Prepend text to node names, e.g.
nodeprefix(LilyPond) sect(Overview)Currently used in texinfo descriptions only.
Prepend text to node names, e.g.
nodeprefix(LilyPond) sect(Overview)Currently used in texinfo descriptions only.
Use text as description for the next node, e.g.
nodetext(The GNU Music Typesetter)chapter(LilyPond)Currently used in texinfo descriptions only.
Starting yodl 3.05 html-conversions by default use html5. This can be
suppressed (in favor of using html4) by calling this macro. This macro merely
suppresses writing the initial <!DOCTYPE html>
to generated html
files; it is only active in the preamble and is only interpreted for
html conversions.
By default html-pages specify
(<style type="text/css" img {vertical-align: bottom;}></style>)
This macro suppresses this img
CSS style specification. This macro is
only active in the preamble and is only interpreted for html conversions.
Expand to text, to avoid spaces before macros e.g.: a2. Although a+sups(2) should have the same effect.
By default, LaTeX output contains commands that cause it to shut up about
hboxes that are less than 4pt overfull. When nosloppyhfuzz()
appears
before stating the document type, LaTeX complaints are `vanilla'.
Prevents the generation of a table of contents. This is default in, e.g.,
manpage
and plainhtml
documents. When present, this option must
appear before stating the document type with article
, report
etc..
Prevents the generation of a clearpage()
instruction after the typesetting
of title information. This instruction is default in all non article
documents. When present, must appear before stating the document type with
article
, book
or report
.
With the LaTeX converter, no clearpage()
instruction is inserted
immediately beyond the document's table of contents. The clearpage()
instruction is default in all but the article
document type. When present,
must appear before stating the document type with article
, book
or
report
. With other converters than the LaTeX converter, it is ignored.
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.
When used in the preamble, the LaTeX converter disables the inclusion of the
file xlatin1.tex
. Normally this file gets included in the LateX output
files to ensure the conversion of high ASCII characters (like é) to
LaTeX-understandable codes. (The file xlatin1.tex
comes with the Yodl
distribution.)
Starts a non-numbered paragraph (duh, corresponds to subparagraph in latex).
Starts a part in a book
document, but without numbering it and without
entering the title of the part in the table of contents.
In html attrib
macro applies to the <h1>
tag.
Starts a section, but does not generate a number before the title
nor
an entry in the table of contents. Further sectioning commands are
nsubsect
, nsubsubsect
and nsubsubsubsect
.
In html attrib
macro applies to the <h2>
tag.
Starts a non-numbered subsection. In html the attrib
macro applies to
the <h3>
tag.
Starts a non-numbered sub-sub section.
In html attrib
macro applies to the <p>
tag.
Starts a non-numbered sub-subsection.
Starts a paragraph. This level of sectioning is not numbered, in
contrast to `higher' sectionings (duh, corresponds to subparagraph in latex).
In html attrib
macro applies to the <p>
tag.
Starts a new part in a book
document.
In html attrib
macro applies to the <h1>
tag.
Generate an index entry for LaTex() or texinfo
p-indices. Its argument is the
index entry. See also the [cftv]index
macro.
Starts a document for only a plain HTML conversion. Not available in
other output formats. Similar to article
, except that an author- and
date field are not needed.
Make index for texinfo (?).
Sets the text as a quotation. Usually, the text is indented, depending on
the output format. In html the attrib
macro is recognized by the
<blockquote>
tag.
Inserts the right angle character (>).
Defines macro macro
to expand to redefinition
.
Similar to def
, but any pre-existing definition is overruled. Use
ARG
x in the redefinition part to indicate where the arguments should
be pasted. E.g., ARG1
places the first argument, ARG2
the second
argument, etc...
Defines macro macro
to expand to redefinition
.
Similar to def
, but any pre-existing definition is overruled. Use
ARG
x in the redefinition part to indicate where the arguments should
be pasted. E.g., ARG1
places the first argument, ARG2
the second
argument, etc... This commands is actually calling redef().
Sets the reference for labelname
. Use label
to define a label.
Starts a report type document. The top-level sectioning command in a report
is chapter
. In html the way the headings are displayed can be tuned using
CSS id selector specifications: the title has id="title"
, the author
id="author"
, and the date id="date"
.
Sets a t/nroff command that starts with a dot, on its own line. The
arguments are: dotcmd
- the command itself, e.g., .IP
; sameline
-
when not empty, sameline
is set on the same line, following the
dotcmd
; secondline
- when not empty, is set on the next line;
thirdline
- when not empty, is set on the third line. Note: dotcmd
and
thirdline
are not further expanded by Yodl
, the other arguments are.
The argument contents
may contain a man-page alignment specification
(only one specification can be entered per row), using setmanalign()
. If
omitted, the standard alignment is used. Furthermore it contains the contents
of the elements of the row, using cell()
or cells()
macros. If
cells()
is used, setmanalign()
should have been used too. In this
macro call only the cell()
, cells()
and setmanalign()
macros
should be called. Any other macro call may produce unexpected results.
The row
macro defines a counter XXcol
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 XXcol
.
In html attrib
macro applies to the <tr>
tag.
Instead of using row
in table
, consider using tr
in tbl
.
Sets a horizontal line over the full width of the table. See also
the columnline
macro. Use rowline
instead of a row
macro call to
provide a table with a horizontal line-separator.
Instead of using rowline
consider using tline
in a tbl
argument.
Set text
in the tt (code) font, using small caps.
In html the attrib
macro is not supported, while the code
section is embedded in a <div style="font-size: 90%">
section.
Starts a new section. In html the attrib
macro is recognized by the
<h2>
tag.
Defines name
as the `affiliation information' string, by default
AFFILIATION INFORMATION. E.g., after setaffilstring(AFILIACION)
,
Yodl
outputs this Spanish string to describe the affiliation information.
Currently, it is relevant only for txt.
Defines name
as the `Author information' string, by default
AUTHOR INFORMATION. E.g., after setauthorstring(AUTOR)
,
Yodl
outputs this portuguese string to describe the author information.
Currently, it is relevant only for txt.
Defines name
as the `chapter' string, by default Chapter. E.g., after
setchapterstring(Hoofdstuk)
, Yodl
gains some measure of national language
support for Dutch. Note that LaTeX support has its own NLS, this macro doesn't
affect the way LaTeX output looks.
Defines name
as the `date information' string, by default
DATE INFORMATION. E.g., after setdatestring(DATA)
,
Yodl
outputs this portuguese string to describe the date information.
Currently, it is relevant only for txt.
Defines the name
as the `figure' extension. The extension should include
the period, if used. E.g., use setfigureext(.ps) if the extensions
of the figure-images should end in .ps
Defines the name
as the `figure' text, used e.g. in figure captions. E.g.,
after setfigurestring(Figuur)
, Yodl uses Dutch names for figures.
Defines the filename extension for HTML figures, defaults to .jpg
. Note
that a leading dot must be included in ext
. The new extension takes effect
starting with the following usage of the figure
macro. It is only active
in html, but otherwise acts identically as setfigureext().
See also the setlatexfigureext
macro.
Adds <meta charset="meta-charset">
to the head of html documents. By
default <meta charset="UTF-8">
is used. This macro is only active in the
preamble and is only interpreted for html conversions.
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.
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
This macro defines the table alignment used when setting tables in LaTeX.
Use as many l
(for left-alignment), r
(for right alignment), and c
(for centered-alignment) characters as there are columns in the table. See
also table()
.
Instead of using the table
macro consider using the tbl
macro.
Defines the filename extension for encapsulated PostScript figures in LaTeX,
defaults to .ps
. The dot must be included in t new extension ext
. The
new extension takes effect starting with a following usage of the figure
macro. It is only active in LaTeX, but otherwise acts identically as
setfigureext().
See also the sethtmlfigureext
macro.
Set the char used to quote LaTeX
\verb
sequences
This macro defines the table alignment in the context of the table
macro, and is used when setting tables in man-pages (see tbl(1)).
Use as many l
(for left-alignment), r
(for right alignment), and c
(for centered-alignment) characters as there are columns in the
table.
Use s
to indicate that the column to its left is combined (spans into) the
current column. Use this specification when cells spanning multiple columns
must be defined.
Each row in a table which must be convertible to a manpage may be preceded by
its own setmanalign
call.
Note that neither rowline
nor columnline
requires setmanalign
specifications, as these macros define rows by themselves. It is the
responsibility of the author to ensure that the number of alignment characters
is equal to the number of columns of the table.
Instead of using the table
macro consider using the tbl
macro.
Defines name
as the `part' string, by default Part. E.g., after
setpartstring(Teil)
, Yodl identifies parts in the German way. Note that
LaTeX output does its own national language support; this macro doesn't affect
the way LaTeX output looks.
Sets the character separating items in a line of input data of a roff
(manpage) table. By default it is set to ~
. This separator is used
internally, and needs only be changed (into some unique character) if the
table elements themselves contain ~
characters.
This macro can be used in the context of the table
and tbl
macros.
Set options used for man-conversion, as used by the tbl
and table
macros. By default no options are used. Multiple options should be separated
by blanks. From the tbl(1) manpage, the following options are available:
center
Centers the table; default is left-justified. In the
context of the tbl
macro this is implied when the tbl
macro is
specified as argument of the center
macro.
expand
Makes the table as wide as the current line length
box
Encloses the table in a box
allbox
Encloses each item of the table in a box
See also setrofftab
which is used to set the character separating
items in a line of input data.
Defines name
as the `title information' string, by default
TITLE INFORMATION. E.g., after settitlestring(TITEL)
,
Yodl
outputs this Dutch string to describe the title information.
Currently, it is relevant only for txt.
Defines name
as the `table of contents' string, by default Table of
Contents. E.g., after settocstring(Inhalt)
, Yodl
identifies the table
of contents in the German way. Note that LaTeX output does its own national
language support; this macro doesn't affect the way LaTeX output looks.
Writes cmd
to the output when converting to sgml. The cmd
is not
further expanded by Yodl.
Similar to htmltag
, but used in the SGML converter.
By default, LaTeX output contains commands that cause it to shut up about
hboxes that are less than 4pt overfull. When sloppyhfuzz()
appears
before stating the document type, LaTeX complaints occur only if hboxes are
overfull by more than points
.
Enables the default LaTeX layout. When this macro is absent, then the
first lines of paragraphs are not indented and the space between
paragraphs is somewhat larger. The standardlayout()
directive must appear
before stating the document type as article
, report
, etc..
In html and xml the contents
are set between <strong>
and
</strong>
tags.
In html attrib
macro applies to the <strong>
tag.
Sets text in subscript in supporting formats.
In html the attrib
macro is recognized by the <sub>
tag.
For superscripting, the sups
macro can be used.
Starts a new subsection. Other sectioning commands are
subsubsect
and subsubsubsect
.
In html attrib
macro applies to the <h3>
tag.
Starts a sub-subsection.
In html attrib
macro applies to the <h4>
tag.
Starts a sub-sub-sub-subsection. This level of sectioning is not numbered, in contrast to `higher' sectionings.
Sets text in superscript in supporting formats
In html the attrib
macro is recognized by the <sup>
tag.
For subscripting, the subs
macro can be used.
Instead of using the table
macro, consider using the tbl
macro.
The table()
-macro defines a table. Its first argument specifies the number
of columns in the table.
Its second argument specifies the (standard) alignment of the information
within the cells as used by LaTeX or man/ms. Use l
for left-alignment,
c
for centered-alignment and r
for right alignment.
Its third argument defines the contents of the table which are the rows, each containing column-specifications and optionally man/ms alignment definitions for this row.
See also the tableatt
macro and the specialized setmanalign()
macro.
Instead of using the tableatt
macro, consider using the tbl
macro.
The tableatt()
-macro defines a table. The last attrib
call that was
specified before using the tableatt()
-macro is used to specify html
attributes for the table. E.g., to center a table in html use
attrib(style="margin-left:auto;margin-right:auto;") tableatt(...)The macro's first argument specifies the number of columns in the table. Its second argument specifies the (standard) alignment of the information within the cells as used by LaTeX or man/ms. Use
l
for left-alignment,
c
for centered-alignment and r
for right alignment. Its third argument
defines the contents of the table which are the rows, each containing
column-specifications and optionally man/ms alignment definitions for this
row.
See also the table
macro and the specialized setmanalign()
macro.
This macro is one of the four macros that can be used to define column
contents of rows of tables defined by the tbl
macro. Alternatively, tc,
tnc
, and tnac
can be used.
The tac
macro is used as argument of the tr
macro. The cell's
alignment is defined by the alignment
specification, containing at most
two alignment specifications: a horizontal alignment (one of c, l, r
(centered, left-aligned, right-aligned)) and a vertical alignment (one of t, b
(vertical top- and bottom-alignment)) (not all conversion types may support
all alignment types, e.g., man-conversion does not support vertical bottom
alignment). Specifications other than c, l, r, b, and t and specifications
beyond the second one are ignored. The result of specifying conflicting
alignment types (e.g., lr
or tb
) is not defined.
When converting to man
, if the table's contents should span multiple rows,
then a groff/troff(1) text block must be used. Since most tables do
not use this, a text block is not generated by default. To actually wrap the
contents of column elements in a text block while converting to man
prefix
the first text block requiring a text-block wrapping by twrap(1)
, and end
the last text block requiring a text-block wrapping by wrap(0)
.
The tao
macro can be used to overrule the specified alignment for a
specific conversion type.
The macro tac
recognizes attrib
.
This macro is used inside the tbl
macro to override the alignment
specification that would otherwise be used for the next table element. It is
only active for the next tc, tnc, tac,
or tnac
call. Its first
argument defines the conversion type for which the override should be used,
its second argument defines the alignment specification to use.
Here are some examples:
tbl(lr)( tr( tc(left aligned) tc(right aligned) ) tr( tao(html)(c) tc(left aligned, centered with html) tao(latex)(l) tao(man)(l) tac(c)(centered, latex and man: left aligned) ) )
Further details about the tao
macro are provided in the yodltables(7)
man-page.
The tbl
macro refines the more basic table
macro. It was named after
the tbl(1) table formatting program used with troff(1) documents.
The tbl
macro currently is available for html, man/ms, latex
and
txt
conversions.
Its first argument defines the alignment of the information in the table's
columns, and is used by all conversions except txt
. Use l
for
left-alignment, c
for centered-alignment and r
for
right-alignment. Individual cells of the table may override these default
settings using the macros tac
and tnac
.
Its second argument defines the contents of the table consisting of rows
(using tr
), and horizontal lines (using tline
), which may extend over
the full table width or may cover one or more individual columns. With txt
conversion rough approximations of horizontal lines are used.
Tables defined by the tbl
macro are centered (pseudo centering (8 space
characters) is used for txt
conversion) when used as argument of the
center
macro.
See also the tao
macro for information about how to realize specific
alignments for specific conversion types.
When defining tbl
tables it is advised to clearly layout the table
specification. To avoid inadvertently introducing new lines lines should end
in a backslash (or
The macro tbl
recognizes attrib
.
This macro is one of the four macros that can be used to define column
contents of rows of tables defined by the tbl
macro. Alternatively,
tnc, tac
, and tnac
can be used.
The tc
macro is used as argument of the tr
macro. Its order within a
row defines its type attribute, using the alignment specification defined by
the first argument of the tbl
call. E.g., if tbl(clr)(...)
was used,
then the contents of the first tc
call in a tr
is centered in the
table's first column; the contents of the second tc
call is left-aligned
in the table's second column; and the contents of the third tc
call is
right-aligned in the table's third column.
When converting to man
, if the table's contents should span multiple rows,
then a groff/troff(1) text block must be used. Since most tables do
not use this, a text block is not generated by default. To actually wrap the
contents of column elements in a text block while converting to man
prefix
the first text block requiring a text-block wrapping by twrap(1)
, and end
the last text block requiring a text-block wrapping by wrap(0)
.
The tao
macro can be used to overrule the default alignment specification
for a specific conversion type.
The macro tc
recognizes attrib
.
Roff helper to set a table text-cell, i.e., a paragraph. For LaTeX special table formatting p{} should be used.
When using the tbl
macro for defining tables the twrap
macro can be
used to set table elements in text-blocks (i.e., enclosing text, possibly
containing newlines in T{
and T}
sequences).
Writes cmd
to the output when converting to tely. The cmd
is not
further expanded by Yodl.
The TeX symbol.
Writes cmd
to the output when converting to texinfo. The cmd
is not
further expanded by Yodl.
Generate an index entry for LaTex() or texinfo
t-indices. Its argument is the
index entry. See also the [cfpv]index
macro.
Forces a new page (using clearpage
) following the title of a
document. This is already the default in books and reports, but can be
overruled using notitleclearpage
. When present, it must appear in the
preamble, i.e., before the document type is stated as article, book or
report.
This macro is used to insert a horizontal line spanning one or more columns
of a table defined by the tbl
macro.
If endNr
is not specified, and the tline
call does not follow a
previous line
call in which endNr
was specified, then a horizontal
line spanning the full width of the table is defined (except when converting
to plain text in which case a line of beginNr
- (minus) characters is
written; if beginNr
is not specified then a line of 60 - characters is
written).
If endNr
is not specified, but the tline
call follows previous tline
calls that did specify endNr
then the current row is ended.
If endNr
is specified, then a horizontal line is set, starting at column
number beginNr
continuing through column number endNr
. Note that these
are numbers, not offsets: beginNr
should be at least 1, endNr
must at least be equal to beginNr
and should be at most equal to the
number of columns in the table. The beginNr
values of subsequent tline
calls refer to the same row as the first tline
call, and must exceed
endNr
of the previous tline
call.
Examples:
tline()() sets a line spanning the full table width tline(1)(1) sets a line in column 1 tline(3)(4) sets another line in column 3 and 4 tline()() ends the previous line tline()() sets a line spanning the full table width
This macro is one of the four macros that can be used to define column
contents of rows of tables defined by the tbl
macro. Alternatively, tc,
tac
, and tnc
can be used.
The tnac
macro is used as argument of the tr
macro. Its first argument
defines the number of columns spanned by the contents (2nd argument)
of the tnc
macro.
The cell's alignment is defined by the macro's second (alignment
)
specification, containing at most two alignment specifications: a horizontal
alignment (one of c, l, r (centered, left-aligned, right-aligned)) and a
vertical alignment (one of t, b (vertical top- and bottom-alignment)) (not all
conversion types may support all alignment types). Specifications other than
c, l, r, b, and t and specifications beyond the second one are ignored. The
result of specifying conflicting alignment types (e.g., lr
or tb
) is
not defined.
When converting to man
, if the table's contents should span multiple rows,
then a groff/troff(1) text block must be used. Since most tables do
not use this, a text block is not generated by default. To actually wrap the
contents of column elements in a text block while converting to man
prefix
the first text block requiring a text-block wrapping by twrap(1)
, and end
the last text block requiring a text-block wrapping by wrap(0)
. Multiple
rows in a text block are top-aligned with left and righ neighboring cells.
The tao
macro can be used to overrule the default alignment specification
for a specific conversion type.
The macro tnac
recognizes attrib
.
This macro is one of the four macros that can be used to define the column
contents of rows of tables that are defined by the tbl
macro. Alternatively, tc, tac
, and tnac
can be used.
The tnc
macro is used as argument to the tr
macro. Its first argument
defines the number of columns spanned by the contents (2nd argument)
of the tnc
macro. The contents are centered in the nCells
columns.
When converting to man
, if the table's contents should span multiple rows,
then a groff/troff(1) text block must be used. Since most tables do
not use this, a text block is not generated by default. To actually wrap the
contents of column elements in a text block while converting to man
prefix
the first text block requiring a text-block wrapping by twrap(1)
, and end
the last text block requiring a text-block wrapping by wrap(0)
. Multiple
rows in a text block are top-aligned with left and righ neighboring cells.
The tao
macro can be used to overrule the default alignment specification
for a specific conversion type.
The macro tc
recognizes attrib
.
With the LaTeX converter, a clearpage()
directive if inserted,
immediately following the document's table of contents. This is already the
default in all but the article
document type, but it can be overruled by
notocclearpage()
. When present, it must appear in the preamble; i.e.,
before the document type is stated with article
, book
or
report
. With other converters than the LaTeX converter, it is ignored.
This macro defines the rows of a table that is defined by the tbl
macro.
The macro tr
expects one argument: the contents of the row, defining the
row's column elements. It is not used for defining a (partial) horizontal
line: to set horizontal lines in a table defined by the tbl
macro use the
macro tline
.
Normally the contents of the columns in a (tr
) row is defined by
of one or more calls to the macros tc, tac, tnc,
and/or tnac
.
The macro tr
recognizes attrib
.
Sets text
in teletype font, and prevents it from being expanded.
When converting to man, text
is surrounded by a backtick and a single
quote character.
For unbalanced parameter lists, use CHAR(40)
to get
(
and CHAR(41)
to get )
.
The tt
macro does interpret character tables as well as any SUBST
definitions. This is usually what is intended. In situations where this is
unwelcome the ttbegin
and ttend
pair of macros can be used, between
which the builtin commands PUSHSUBST, POPSUBST, NOEXPAND
and/or
NOTRANS
can be used. E.g., to clearly show two hyphens in LaTeX
teletype font use
ttbegin()--ttend()rather than
tt(--)Likewise, use
ttbegin
and ttend
if the teletype text contains
accented letters like ë. To set this in teletype font use
ttbegin()\"
e+ttend()
.
With html conversions the attrib
macro applies to the <code>
tag.
With man conversions the arguments of tt macros can be quoted. See the
manttquoted
macro for details.
Initiates text set in teletype font. Following the text to set in
teletype font a ttend()
macro should be called.
Usually the tt
macro can be used instead of the ttbegin
--
ttend
combination. However, tt
interprets character tables as well as
SUBST
definitions. In situations where this is unwelcome the ttbegin
and ttend
pair of macros can be used, between which builtin commands like
PUSHSUBST, POPSUBST, NOEXPAND
and/or NOTRANS
can be used.
In html the attrib
macro applies to the <code>
tag.
Ends text set in teletype font following ttbegin
. Refer to the
ttbegin
macro's description for details.
Used for man/ms conversions only: when called with a non-zero argument
before using the tc, tnc, tac
, and tnac
macros then their contents are
wrapped in text blocks (T{ ... T}
blocks). To end the wrapping
twrap(0)
must be called. E.g., in the following row-definition the
contents of columns three and four are set in T-blocks when converting to
man/ms:
tr(tc(one)tc(two)twrap(1)tc(one)tc(two)twrap(0))
Writes cmd
to the output when converting to txt. The cmd
is not
further expanded by Yodl.
In LaTeX documents the description
is sent to the output. For HTML,
a link is created with the descriptive text description
and pointing
to locator
. The locator
should be the full URL, including
service; e.g, http://www.icce.rug.nl
, but excluding the double
quotes that are necessary in plain HTML. Use the macro link
to create
links within the same document. For other formats, something like
description [locator] will appear.
In html attrib
macro applies to the <a>
tag.
Sets text
in verbatim mode: not subject to macro expansion or character
table expansion, and starting with Yodl version 4.00.00: not using SUBST
definitions. See also verborg
, which does not provide the protection
against SUBST
definitions.
While converting Yodl-documents to target document types Yodl frequently uses
the (not further documented) builtin function XXSUBST
. In the
unlikely event that the text XXSUBST(...)
must be written
in a document, the sequence
XXSUBST+CHAR(40)...CHAR(41)can be used.
The text that is passed as argument to the verb
-macro 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.
When unbalanced parameter lists are required, use CHAR(40)
to get
(
and CHAR(41)
to get )
.
Reads filename and inserts it literally in the text, set in verbatim mode.
not subject to macro expansion. The text appears literally on the output,
usually in a teletype font (that depends on the output format). This macro is
an alternative to verb(...)
, when the text to set in verbatim mode is
better kept in a separate file.
Passes args
to yodlverbinsert(1), inserting its output into the
converted file. This macro can be used to insert, e.g., a line-numbered
indented file, or a labeled subsection of a file, into the file that's
currently being written by yodl
. E.g,
verbinsert(-ans4 file) -- inserts file, showing line numbers, using a 4 blank-space character wide indentation. verbinsert(-ns4 //SECT file) -- inserts the section of file, labeled //SECT file, showing line numbers, using a 4 blank-space character wide indentation.
Sets text
in verbatim mode: not subject to macro expansion or character
table expansion, and starting with Yodl version 4.00.00: this macro replaces
the previosly defined verb
macro. The current verb
macro surrounds
this macro by PUSHSUBST
and POPSUBST
.
The text that is passed as argument to the verborg
-macro appears
literally on the output, albeit that SUBST
definitions are processed,
usually in a teletype font (that depends on the
output format). This macro is for larger chunks, e.g., listings.
When unbalanced parameter lists are required, use CHAR(40)
to get
(
and CHAR(41)
to get )
.
Pipe text through command, but don't expand the output.
Generate an index entry for LaTex() or texinfo v-indices.
Its argument is the index entry.
See also the [cfkpt]index
macro.
Sends text
to the output when in HTML conversion mode. The text is
further expanded if necessary.
Sends text
to the output when in LATEX conversion mode. The text is
further expanded if necessary.
Sends text
to the output when in MAN conversion mode. The text is
further expanded if necessary.
Sends text
to the output when in MS conversion mode. The text is
further expanded if necessary.
Sends text
to the output when in SGML conversion mode. The text is
further expanded if necessary.
Sends text
to the output when in TELY conversion mode. The text is
further expanded if necessary.
Sends text
to the output when in TEXINFO conversion mode. The text is
further expanded if necessary.
Sends text
to the output when in TXT conversion mode. The text is
further expanded if necessary.
Sends text
to the output when in XML conversion mode. The text is
further expanded if necessary.
Starts an xml menu item where the file to which the menu refers to is the argument of the xit() macro. It should be used as argument to xmlmenu(), which has a 3rd argument: the default path prefixed to the xit() elements.
This macro is only available within the xml-conversion mode. The argument must be a full filename, including .xml extension, if applicable.
No .xml extension indicates a subdirectory, containing another sub-menu.
Writes cmd
to the output when converting to xml. The cmd
is not
further expanded by Yodl.
Starts an xmlmenu. Use itemization() to define the items. Only available in xml conversion. The menutitle appears in the menu as the heading of the menu. The menulist is a series of xit() elements, containing the name of the file to which the menu refers as their argument (including a final /). Prefixed to evert every xit()-element is the value of XXdocumentbase.
Order is the the `order' of the menu. If omitted, no order is defined.
In XML output, starts a new file. All other formats are not affected. Note
that you must take your own provisions to access the new file; say via links.
Also, it's safe to start a new file just befoore opening a new section, since
sections are accessible from the clickable table of contents. The XML
converter normally only starts new files prior to a chapter
definition.
Defines name
as the XML document base. No default.
Only interpreted with xml conversions. It is used with the figure and xmlmenu
macros.
Similar to htmltag
, but used in the XML converter.
latex
when the output format is LaTeX,
html
when the output format is HTML,
man
when the output format is groff in conjunction with the
man macro package,
ms
when the output format is groff with the ms package,
sgml
when the output format is SGML,
txt
when the output format is plain ASCII.
xml
when the output format is XML.
Furthermore, the package defines the following macros to send literal text (commands in the output format) to the output file:
latexcommand(cmd)
: sends the LaTeX command cmd
when in LaTeX
conversion mode. The cmd
is not further expanded.
htmlcommand(cmd)
: sends the HTML command cmd
when in HTML
conversion mode. The cmd
is not further expanded.
htmltag(tag)(onoff)
: sends <tag>
to the output when onoff
is nonzero, or sends </tag>
when onoff
is zero. Only active in
HTML conversions.
mancommand(cmd)
: sends cmd
to the output when in man
conversion mode. The cmd
is not further expanded.
mscommand(cmd)
: sends cmd
to the output when in ms
conversion mode. The cmd
is not further expanded.
roffcmd(dotcmd)(trailer)(secondline)(thirdline)
: sends a command
to the output when in man
or ms
conversion mode. The dotcmd
is the
typical groff
command that starts with a dot. All other arguments may be
empty, but when given are interpreted as follows. The trailer
follows the
dotcmd
on the same line. The secondline
is sent on a separate line
following the dotcmd
and trailer
. The thirdline
is sent after
that. Of the four arguments, dotcmd
and thirdline
are not subject
to further expansion. All other arguments are further expanded if necessary.
The roffcmd
macro illustrates the complexity of dot-commands for the
divers groff
macro packages. E.g., a section title for the man
package should look as
.SH "Section Title"while the same command for the
ms
macro package must be sent as
.SH Section Title .PPThe
roffcmd
macro can be used to send these commands to the output
file as follows:
COMMENT(For the man output format:) roffcmd(.SH)("Section Title")()() COMMENT(For the ms output format:) roffcmd(.SH)()(Section Title)(.PP)()
sgmlcommand(cmd)
: sends the SGML command cmd
when in SGML
conversion mode. The cmd
is not further expanded.
sgmltag(tag)(onoff)
: sends <tag>
when onoff
is nonzero,
or sends </tag>
when onoff
is zero. Only active in SGML conversions.
txtcommand(cmd)
: implemented for compatibility reasons, though a
`command' in plain ASCII output doesn't make much sense. The usefulness of
this macro is rather in the fact that it only produces output when in ASCII
conversion mode.
it
macro (which starts an item in a list) as:
DEFINEMACRO(it)(0)( latexcommand(\item ) htmlcommand(<li> ) .... )Depending on the output format,
it()
applies one of the above
expansions.
The above described formatcommand()
macros are implemented to send not
further expanded strings (i.e., commands) to the output. The macro package
also implements when
format()
macros to send any text, which is
then subject to further expansion. These when...()
macros are:
whenlatex(text)
: sends text
when in LaTeX conversion mode,
whenhtml(text)
: sends text
when in HTML conversion mode,
whenman(text)
: sends text
when in man conversion mode,
whenms(text)
: sends text
when in ms conversion mode,
whentxt(text)
: sends text
when in ASCII conversion mode,
whensgml(text)
: sends text
when in SGML conversion mode.
when
format()
macros and the formatcommand()
macros is,
that the former expands their argument while the latter does not. As an
example, consider the following code fragment:
You are now reading whenlatex(a LaTeX-generated footnote(LaTeX is a great document language!) document) whenhtml(a HTML document via your favorite browser)The
when
format()
macros are used here to make sure that the
arguments to the macros are further expanded; this makes sure that the
footnote
macro in the whenlatex
block gets treated as a footnote.
Yodl approaches figures as follows:
epsf
must be stated as one of the LaTeX
styles using the latexoptions
macro. The default, however, can be
modified using the setlatexfigureext()
macro.
.ps
.
<img src=...>
tag. The file must
have the default extension (.jpg
) or the extension specified with the
sethtmlfigureext()
macro.
figure
. It
takes three arguments:
.jpg
file, for usage with HTML documents. The conversion to PostScript
could be automated, e.g., using a Yodl macro:
SYSTEM(xpmtoppm picture.xpm | pnmtops > picture.ps)See section 3.1.64 for details about using the
SYSTEM
macro.
After this, you would be reasonably safe that the picture is available for both HTML and LaTeX output. The picture would be typeset in a figure using:
figure(picture) (A photo of me.) (photo)Note how the first argument, the filename, does not contain an extension. The third argument, which is a label, can be used in, e.g.,
See figure ref(photo) for a photograph showing me.Yodl has a several auxiliary macros, which are:
fig(label)
: This macro is a shorthand for getfigurestring()
ref(label)
. It just makes typing shorter, and is used as e.g.: See
fig(photo) for a photograph.
Note that the string figure
that is
generated by this macro can be (re)defined, see below.
setfigurestring(name)
: This macro is similar to
setchapterstring
etc.. It defines the string that is used to identify a
figure, and is (appropriately) figure
by default. The macro
getfigurestring()
expands to the string in question. See also section
4.3.5.1 for a discussion of national language support.
sethtmlfigureext(.new)
: This macro redefines the filename
extension for HTML conversions from .gif
to .new
. Note that you must
include a leading dot in the redefinition.
figure
statement.
sethtmlfigurealign(align)
: This redefines the alignment of
figures in HTML, which is default bottom
. Check your HTML handbook for
possible options; top
and center
should be fairly standard.
setlatexfigureext(.new)
: Redefines the extension from .ps
to
.new
.
bf(text)
: sets text
in boldface.
em(text)
: sets text
emphasized, usually in italics.
tt(text)
: sets text
in teletype.
tt()
macro does not expand macros occurring
inside its argument. That means that you can safely write:
In Yodl, you can use tt(includefile(somefile)) to include a file in your document.The
tt()
macro should not be used for long listings of verbatim text;
use verb()
to set code samples etc..
Yodl's standard macro package has no commands to change font sizes, as the size is changed internally when appropriate (e.g., in section titles), nor is there a default macro to define other font-families.
This mechanism is available in all output formats. Furthermore, the numeric reference (1.3 in the example of the previous paragraph) is in HTML a clickable reference that leads to the mentioned section.
This mechanism of course only leads to a clickable link in HTML: in other formats the text see the etc. is just typeset as is.
<a href=..>
method. The
URLs of course only result in clickable links in HTML output; in other output
formats only some descriptive text appears.
label(name)
defines a label named name
. The
name of the label can be used in a ref
or link
macro.
ref(name)
sets a reference to the label named
name
. The text of the reference is the number of the last sectioning
command that was active during the creation of the label. When using
references it is therefore important to define the corresponding labels right
after a sectioning command, as in
section(How to install my program) label(howtoinstall) This section describes... ... See section ref(howtoinstall) for installation instructions.The macro
ref(howtoinstall)
expands to the number of the
section named How to install my program.
link(description)(name)
always expands to the
description
. In HTML output, a clickable link is created pointing to a
label called name
. For example:
label(megahard) COMMENT(sigh...) The Jodel package isn't shareware, it isn't beggarware, it isn't freeware, it's bf(megahard-ware). ... Who wants a link(picosoft)(megahard)?This code fragment would always set the text picosoft, but under HTML a clickable link would appear pointing to
link(the text)(megahard)
.
url(description)(location)
always expands to the
description
, but creates a hyperlink pointing to location
in HTML.
For example,
Take a look at my url(homepage)(http://www.somwhere.nl/karel/karel.html).The text homepage always appears, but only in HTML it is a link. (Note that the double quotes, which are necessary in HTML around the location, are not required by Yodl.) To use a different font in the
description
part, surrond it inside the url
parameter list, as in:
The Yodl package can be obtained at the site tt(ftp.rug.nl) in the directory url(tt(/contrib/frank/software/yodl)) (ftp://ftp.rug.nl/contrib/frank/software/yodl).
email(address)
is a special case of url
: under
HTML, the address
appears as a clickable link in slanted font to mail
address
. For example:
I can be reached at email(f.b.brokken@rug.nl).I can be reached at f.b.brokken@rug.nl.
Always keep in mind that the name of a label must be exactly identical in
both the label
macro and in the ref
or link
macro. Other than
that, the name is irrelevant.
Furthermore, note that lincludefile
is yet another macro defining a
label: it includes a file and automatically creates a label just before the
included file's text. That means that a Yodl file like:
chapter(Introduction) sect(Welcome) lincludefile(WELCOME)(welcome) chapter(Technical information) lincludefile(TECHINFO)(techinfo)creates two labels:
WELCOME
and TECHINFO
.
ref(em(labelname))The reason for the incorrectness is, what internal name should
em(labelname)
generate? Here probably an attempt is made to set a
reference in italics. The right construction is of course to set whatever
ref()
returns in italics, as in:
em(ref(labelname))
label
macro should not appear nested inside another
macro. There is no strict reason for this as far as Yodl is concerned;
however, the processors of Yodl's output might go haywire. E.g., beware of the
construction
section(Introduction label(intro))The right form being
section(Introduction)label(intro)(linking to
intro
usually does not show Introduction
), or:
label(intro)section(Introduction)(linking to
intro
usually does show Introduction
).
By default, the following lists are available:
description()
macro. The
elements of the list start with dit()
. The dit()
macro expects a short description of the item.
Example:
A description list: description( dit(First this:) One item. dit(Then this:) Another item. )
enumeration()
macro. Its elements start with the eit()
macro.
Example:
An enumerated list: enumeration( eit() One item. eit() Another item. )
An itemized list is produced by the itemization()
macro, which has one
argument: the items themselves. These items must start with it()
.
Example:
An itemized list: itemization( it() One item. it() Another item. )
Centered text is generated by the center()
macro. Line brakes within
centered text may be obtained using the nl()
macro.
Example:
center( Centered text. nl() Another line of centered text. )
The text must either be inside the verb()
macro. For example:
verb( This is totally verbatim text. It is not further processed by Yodl. )The verbatim text is of course not subject to macro expansion by Yodl. Note, however, that
SUBST
transformations will take place, as these
substitutions take place during the lexical scanning phase of Yodl
's input,
and are not part of the macro-expansion process. See also section 3.1.62.
Furthermore, if a character translation table has been defined, the
argument of the verb()
macro will also be subject to character
table transformations. By temporarily suppressing the active character table
(see section PUSHCHARTABLE 3.1.53) this can be prevented.
quote()
macro:
Shakespeare once wrote: quote( ``To be or not to be, that's the question'' )
chapter(Introduction)
by default results in the text Chapter 1: Introduction.
Using the setchapterstring(text)
macro, the Chapter text can be
redefined. E.g., in a Dutch text you might put
setchapterstring(Hoofdstuk)somewhere near the beginning of your document. Similar to
setchapterstring
, a macro getchapterstring
exists returning the
text identifying chapters. (Internally, getchapterstring
is of course
used to actually set the text). To redefine the text to identify a part, use
setpartstring(text)
; to redefine the text to identify a figure, use
setfigurestring(text)
.
The set....string
macros only influence how Yodl names chapters or
parts in HTML, man
, ms
or txt
output. LaTeX output is not
affected, since LaTeX does its own NLS. Usually, NLS is present for LaTeX as a
`style file' named, e.g., dutch.sty
. Therefore, if you want a Dutch
document, you need to:
latexpackage(dutch)(babel)
in the preamble of
the document. This ensures that LaTeX uses Dutch abbreviation rules.
setlanguage(dutch)
setlanguage()
macro expects one argument: the name of the language
that is used. See section 4.2 for details about this macro. The
setlanguage()
macro redefines the language-dependent section (and other)
headers, and depends on the availability of the corresponding
language<name>()
macro, where <name>
is the name of the language (by
convention <name>
states the english name of the language).
Currently, languagedutch()
, languageenglish()
(the default),
and languageportugese()
are available. It's easy to expand this little set
with macros for other languages. The setlanguage()
macro merely requires
the specification of the language. For example:
setlanguage(english)This macro installs the following defaults (corresponding translations should be defined for other languages):
settocstring(Table of Contents) setaffilstring(Affiliation) setauthorstring(Author) setchapterstring(Chapter) setdatestring(Date) setfigurestring(Figure) setpartstring(Part) settitlestring(Title)
book
and
report
documents.
book
or a report
, the title and table of contents
will also be separated by pagebreaks.
This behavior can be modified using the (no)titleclearpage()
and
(no)tocclearpage()
directives, further described in section
4.3.7.
article
s, report
s,
book
s and for plainhtml
. The document type manpage
defines its own
sectioning commands (cf. section 4.1.2:
part(title)
: Starts a new part. Only available in book
documents.
chapter(title)
: Starts a new chapter. Only available in book
or report
documents.
sect(title)
: Starts a section.
subsect(title)
: A subsection.
subsubsect(title)
: A sub-subsection.
subsubsubsect(title)
: An even smaller sectioning command.
n
prefix (npart
,
nchapter
, nsect
etc.) which generate neither entries in the table of
contents nor numbers. The n
-versions can be used in, e.g., an article
where the sectioning commands should show their captions, but not any numbers
generated by default.
Sectioning should always start at the top level sections of the available
document: chapter
for reports, sect
for articles, etc.. If you start a
document with a lower sectioning command (e.g., when you start an article with
a subsect
), the numbering of sections may go haywire. The only exception
to this rule is the part
of a book
document: parts are optional, in
books, chapter
s may be the top sectioning commands. Summarizing, books or
reports should start with chapter
. Articles should start with
sections
.
The sectioning commands have a further function: when label
statements
appear after the sectioning command, then a label name is used as a
placeholder for the last generated number. This is further described in
section 4.3.4.
article
, report
, book
, manpage
or plainhtml
.
abstract(text)
: This macro is relevant for all output formats.
The text
is added to the document after the title, author and date
information, but before the table of contents. The abstract is usually set as
a quote, in italics font (though this depends on the output format).
Abstracts are supported in article
s and report
s, but not in other
document types. I.e., if you need introductory text in a book
, you should
start with a non-numbered chapter that holds this text.
affiliation(site)
: This macro is relevant for article
,
report
and book
documents. It defines the affiliation of the
author. The site
information appears in the title, below the author's
name.
htmlbodyopt(option)(value)
: This macro adds option="value"
to
the <body>
tag that is generated for HTML output. The HTML converter
generates <body>
tags each time that a new file is started; i.e., at the
top of the document and at each chapter-file. Different HTML browsers support
different <body>
tag options, but useful ones may be e.g.:
htmlbodyopt(fgcolor)(#000000) htmlbodyopt(bgcolor)(#FFFFFF)This defines the foreground color as pure white (red/green/blue all 0) and the background color as black (red/green/blue all hexadecimal FF, or 255). Another useful option may be
htmlbodyopt(background) (some.gif)
, defining
some.gif
as the page background.
See the documentation on HTML for more information.
Note that value
is automatically surrounded by double quotes when
this macro is used. They should not be used by authors using this macro.
latexdocumentclass(class)
: This macro forces the
\documentclass{...}
setting in LaTeX output to class
.
latexlayoutcmds(commands)
: This macro can be used to specify your
own LaTeX layout commands. When present, the commands
are placed in LaTeX
output following the \documentclass
definition.
latexoptions(options)
: This macro is only relevant for LaTeX
output formats, it is not expanded in other formats. The options
are used
in LaTeX's \documentclass
definition; e.g., a useful option might be
dina4
. Multiple options should be separate by commas, according to the
LaTeX convention.
latexpackage(options)(name)
: This macro is only relevant for
LaTeX output formats, it is not expanded in other formats. Each package
should have its own latexpackage()
statement. If there are no options, the
options
argument should remain empty. Here is an example using this macro:
latexpackage(dutch)(babel)
mailto(email)
: The mailto
macro is only expanded in HTML
documents, it is ignored in other formats. It defines where mail about the
document should be sent to.
nosloppyhfuzz()
: By default, the LaTeX output contains the text
\hfuzz=4ptwhich is placed there by the macro package. This suppresses overfull hbox warnings of LaTeX when the overfull-ness is less than 4pt. Use
nosloppyhfuzz()
to get the standard LaTeX warnings about overfull hboxes.
notableofcontents()
: As the name suggests, this macro suppresses
the generation of the table of contents. For HTML that means that no
clickable index of sections appears after the document title.
The table of contents is by default suppressed in plainhtml
and
manpage
documents.
notitleclearpage()
: Normally, Yodl inserts a clearpage()
directive after typesetting title information in book
or report
documents, but not in article
documents. Use notitleclearpage
to
suppress this directive.
notocclearpage()
(no table-of-contents clear-page): In all
document types, Yodl inserts a clearpage()
directive following the table
of contents. Use notocclearpage()
to suppress that.
noxlatin()
: The LaTeX output contains by default the command to
include the file xlatin1.tex
, distributed with Yodl. This file maps
Latin-1 characters to LaTeX-understandable codes and makes sure that you can
type characters such as ü
, and still make them processable by LaTeX. If
you don't want this, put noxlatin()
in the preamble.
standardlayout()
: This is another LaTeX option. Use
standardlayout()
to get `vanilla' LaTeX layout, possibly indenting
paragraphs and using fairly limited vertical spacing between paragraphs.
This macro is ignored for other conversion types.
titleclearpage()
: Forces the insertion of a clearpage()
directive after the title information has been typeset. This behavior is the
default in book
and report
documents. See also notitleclearpage()
.
tocclearpage()
: Forces the insertion of a clearpage()
directive following the table of contents. This behavior is default in all
document types; the macro is provided for consistency reasons with
(no)titleclearpage()
.
clearpage()
: This macro starts a new page in LaTeX. For HTML, a
horizontal rule is shown. (Note that the macro package sometimes inserts new
pages by itself; e.g., following a table of contents. See also section
4.3.7 for a discussion of (no)titleclearpage()
and
(no)tocclearpage()
.)
def(macro)(nrofarguments)(definition)
: This defines a new macro
macro
having nrofarguments
arguments, and expanding to
definition
. The markers ARG
x, where x is 1, 2, etc., can be
used in the definition
part to indicate where arguments should be pasted
in. This macro is a shorthand for DEFINEMACRO
, see section
3.1.11.
footnote(text)
: This macro sets text
as a footnote when the
output format allows it. When not, the text is set in parentheses.
gagmacrowarning(name name ...)
: This macro suppresses yodl
's
warnings cannot expand possible user macro name, where name
is a
candidate macro name. gagmacrowarning
is a synonym for NOUSERMACRO
,
described in section 3.1.41.
"as for manpages, see sed(1), tr(1) and
awk(1)"
, and if you get tired of warnings about possible user macros sed, tr
and awk, try the following:
gagmacrowarning(sed tr awk) ... As for manpages, see sed(1), tr(1) and awk(1).
htmlnewfile()
: Starts a new subfile in HTML output. This stanza
is also automatically generated when the HTML converter encounters a
chapter
directive. Using htmlnewfile
, the output can be split at
any point. However make sure that the subfile is still reachable; e.g., by
creating a clickable link with label
and ref
, or label
and
link
.
includefile(file)
: Includes file
and defines a label (see the
label
macro) with the same name. Furthermore, a message about the
inclusion is shown on the screen. The file
is searched for relative to the
directory of the file in which the includefile
macro was used (or relative
to the directory where the yodl
run was started when the
--legacy-include
or -L
option was provided) and also in the
system-wide include directory. The default extension .yo
is supplied if
necessary.
lincludefile
macro is handy in the following situation:
chapter(Introduction) lincludefile(INTRO)(intro)This fragment starts a chapter and includes a file. Here the label name (
INTRO
) can also be used to refer to the chapter as the lincludefile
stanza appears immediately following the corresponding
sectioning command.
nl()
: Forces a new line. Some output formats may produce an error
upon the usage of nl()
in `unexpected' places; e.g., LaTeX won't allow new
lines in the footnote text (as defined in the footnote
macro). Using
nl()
in running text should however be ok. Example:
This line is nl() broken in two.
redefinemacro(macro)(nrofargs)(redef)
: This command (re)defines a
macro, expecting nrofargs
arguments, to redef
. If a previous
definition of the macro existed, it is overruled. Example:
redefinemacro(clearpage)(0)(\ em(---New page starts here---))Use
ARG
x in the redef
part to indicate where all arguments
should occur, as in the following imaginary macro to typeset a literature
reference:
redefinemacro(litref)(3)( Title: bf(ARG1) nl() Author(s): em(ARG2) nl() Published by: ARG3 ) ... litref(Java in a Nutshell) (David Flanagan) (O'Reilly & Associates, Inc.)The
redefinemacro
statement also has a shorthand called redef
.
/usr/local/share/yodl
during Yodl's installation process (Note that this
diverts from an earlier default: /usr/local/lib/yodl
; furthermore,
some systems or some distributions may use other locations).
The files in this directory are organized as follows:
latex.yo
and html.yo
. These files must
be processed by Yodl before your document can be converted accordingly. The
provided yodl2...
scripts take care of that automatically.
std.<conversion>.yo
, e.g., std.html.yo, std.latex.yo
. These files may
be modified without notice, and are an essential part of the Yodl macros. They
should not be modified by hand, as they are created by the macro generating
process.
chartables/<conversion>.yo
.
yodl
program itself, which generates converted document(s);
yodlpost
postprocessor, which performs fixups for conversion
formats. Using yodlpost
is required for formats whose documents
cannot be created in one pass by yodl
itself;
yodl2tex
, yodl2html
;
C
compiler (preferably the Gnu
C compiler) available, and preferably the
icmake
program maintenance utility. Basic support for make
is provided
as well.