latex2e
included) and HTML 2 (some features of the HTML
converter may use HTML 3.0), the groff
`man' format which is used for man
pages and the groff
`ms' format which is more expressive. More formats may
be made available as the need arises.
Two primitive output formats are also available. First, the output format SGML is included in the package, though the converter is not very stable nor complete: I wrote the converter for backward-compatibility for our existing Linuxdoc-SGML programs. The SGML converter is not really for public consumption. Second, the plain ASCII output converter creates a `bare' text file, stripping the YODL input files of its commands. The ASCII converter is the most rudimentary of the set; a `last-resort' option.
The macro files may not be yet perfect, but I'm working on it as I'm using it. If you find errors or omissions in the macro package, don't hesitate to contact me.
/usr/local/lib/yodl
during YODL's installation
process (your system administrator may have chosen another location,
though). The files in this directory are, e.g., tex.yo
and html.yo
,
and by their name define the output format: tex
for LaTeX and html
for
HTML. The names are also expected by the conversion shell scripts; e.g,,
yodl2tex
will expect the file tex.yo
, yodl2html
will expect the file
html.yo
, etc.. This directory furthermore holds several post-processors
(described later) and a subdirectory chartables
, where character
conversion tables are located.
The programs of the YODL package are the yodl
program itself and
auxiliary scripts such as yodl2tex
, yodl2html
. All programs are
normally installed to /usr/local/bin
.
yodl2tex
, yodl2html
and
other yodl2...
drivers. Basically, an invocation like
starts the yodl
program to process file.yo
and to write output to
file.tex
. The extension of the input file, .yo
, is the default YODL
extension; the extension of the output file, .tex
, is given by the name of
the shell script. The script yodl2html
hence writes to a file with the
extension .html
.
Furthermore, the conversion scripts auto-load the right macro file: tex.yo
for LaTeX conversions, html.yo
for HTML conversions, etc.. The macro files
are of course found in the system-wide include directory.
When the conversion scripts are started without arguments, usage information is shown.
The output files are, depending on the conversion:
.tex
is
written.
The `main' output file always has the name of the input file but with
extension .html
. This file holds the document title and the table of
contents. When more than one output files are created, then they are named
name01.html
, name02.html
etc., where name
is the original name
of the input file. E.g., a document prog.yo
might lead to
prog.html
, prog01.html
etc..
groff
conversions two output formats are supported: the
man
format (invoked by yodl2man
and resulting in a file .man
),
and the ms
format (invoked by yodl2ms
and resulting in a file
.ms
). The differences between the man
and ms
macro sets of
groff
make different converters and output files necessary.
.sgml
is
written.
yodl2txt
and one
output file with the extension .txt
is created.
The YODL package furthermore holds `second-step' scripts, which are:
yodl2dvi
is one more step on top of
yodl2tex
: it also runs LaTeX on the resulting .tex
file. This
script tries to be smart about it; when LaTeX' logfile indicates warnings
about unresolved labels, the LaTeX process is started once again. This
process is repeated up to three times.
yodl2manless
is an extra step to yodl2man
: it
converts a .yo
file to .man
format, and runs groff
on it,
piping the output to a less-like pager for viewing.
yodl2manless
, the script yodl2msless
starts the
ms
converter and pipes the groff
output through a pager.
yodl2msps
is an extra step on top of the ms
converter; it converts the ms
output file into PostScript format.
The scripts yodl2manless
and yodl2msless
start groff
with the
instruction to produce plain ASCII text. The groff
program then (usually)
outputs boldface as overstrike, and italics as underlined. This convention is
most often used, and is meant to provide some degree of font alternation for
printed ASCII documents. If you want to convert a YODL document to true
ASCII, without overstrikes or underlines, take a look at the C program
striproff
which is included in the YODL distribution as
misc/striproff.c
. This program is not compiled and installed by the
default YODL installation process, but is only distributed as an example. If
you choose to compile and install it, you can use it as follows, assuming that
you have a manpage document mymanpage.yo
and an article myarticle.yo
:
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.
The defined symbol can be tested in a document to determine the conversion type.
Furthermore, the package defines the following macros to send litteral 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
while the same command for the ms
macro package must be sent as
The roffcmd
macro can be used to send these commands to the output
file as follows:
sgmlcommand(cmd)
: sends the SGML command cmd
when in SGML
conversion mode. The cmd
is not further expanded.
sgmltag(tag)(onoff)
: sends <tag>
when onoff
is nonzero,
or sends </tag>
when onoff
is zero. Only active in SGML
conversions.
txtcommand(cmd)
: implemented for compatibility reasons, though
a `command' in plain ASCII output doesn't make much sense. The usefulness
of this macro is rather in the fact that it only produces output when in
ASCII conversion mode.
The above commands can be used to quickly implement a macro. E.g., the macro
package implements the it
macro (which starts an item in a list) as:
Depending on the output format, it()
will lead to one of the above
expansions.
The above described formatcommand()
macros are implemented to send not
further expanded strings (i.e., commands) to the output. The macro package
also implements 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.
Note again that the difference between the when
format()
macros
and the formatcommand()
macros is, that the former will expand their
argument while the latter will not. As an example, consider the following code
fragment:
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.
.dvi
file. Nevertheless, some formats are more
useful for some document types. A book that is converted to the man
output
format to be later processed with groff
won't look too good; a better
conversion to ASCII would be via the ms
output format.
Each document must be started by specifying the document type. The relevant macros are:
article(title)(author)(date)
: The article
document type is
meant for short documents. The macro arguments specify the title of the
document, the author and the 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 its own page, and the sectioning command
chapter
. A report
is meant for larger documents.
book(title)(author)(date)
: The book
type is for still larger
documents. It supports the sectioning command part
.
manpage(title)(section)(date)(source)(manual)
: The manpage
document type is specifically meant to write manual pages, as found on
Unix systems. It uses its own sectioning commands to reflect the necessary
sections in a manual page. This document format is described separately
in 3.3.
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 the YODL package to help you with handy macros.
Except for the fact that no author
and date
arguments are
necessary, this document type is similar to article
. (In fact, you can
emulate plainhtml
by using an article
, but without author and date
information for the title.)
plainhtml
is available for other output formats, though it doesn't
really make sense to use it. If you want the most `portable' document
type, use one of article
, report
or book
.
The function of these macros is, globally, threefold. First, the macros must
send any commands that need to appear before `real' text to the output file.
E.g., the LaTeX output needs the right \documentstyle
preamble, HTML
output needs <html>
and <body>
tags.
Second, the macros define appropriate document-dependent settings. E.g., this
means that the LaTeX converter defines the title, author and date using
\title
etc..
Third, the actual document is started. In 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 which define the document type perform many functions, means that once the macro is started, nothing `extra' can be put say between the generated title and the table of contents. Sometimes however this is what you'd like; as is the case with an abstract. The YODL package therefore implements modifiers, that appear before the document type macros.
3.2.2.1: Pagebreaks after the title and table of contents
In respect to the occurrence of pagebreaks in documents, YODL has the following
default behavior:
That means, that when a document has both title information and a table of
contents whatever follows next will normally be starting on a separate page.
Furthermore, if the document is a This behavior can be modified using the 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 See the documentation on HTML for more information.
Note that the will start an article as far as Yodl is concerned, but will use Backward compatibility note: At the ICCE, we've used Linuxdoc-SGML for
some time. The modifier
approximates the LaTeX output that this SGML variant produces. The style
files which is placed there by the macro package. This suppresses overfull
hbox warnings of LaTeX when the overfull-ness is less than 4pt. I find
this useful.
This macro has no consequences for non-LaTeX formats.
Use The table of contents is by default suppressed in This macro has no consequences for non-LaTeX formats.
Note again that when present, the modifiers must appear before the
document type definition.
The macros generate entries in the table of contents and use numbering, which
means that each section is prefixed with a number (1, 1.1, 1.2, and so on).
The macros are also available with an The sectioning should start at the top level sections of the available
document: The sectioning commands have a further function: when There are two ways to indicate an itemized list: one is to start the list
with The items in the list are indicated with Example:
The items in the list are marked with Example:
The elements in the list must be indicated with Example:
Centered text is either either inside Example:
The text must either be inside The text in question is of course not subject to macro expansion by YODL.
However, global string substitution as defined by The The Currently the macro package has no commands to change font sizes, as the size
is changed internally when appropriate (e.g., in section titles). I'll
implement such commands when the need arises.
book
and
report
documents.
book
or a report
, the title and table
of contents will also be separated by a pagebreak.
(no)titleclearpage()
and
(no)tocclearpage()
directives. This is further described in section
3.2.3.
3.2.3: Typesetting modifiers
This section lists a number of macros that can be used to modify the looks of
your document. When used, these macros must appear before stating the
document type with article
, report
, book
, manpage
or
plainhtml
.
abstract(text)
: This macro is relevant for all output formats.
The text
is added to the document after the title, author and date
information, but before the table of contents. The abstract is usually set
as a quote, in italics font (though this depends on the output format).
Abstracts are supported in 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 will be generated for HTML output. The HTML
converter generates <body>
tags each time that a new file is started;
i.e., at the top of the document and at each chapter-file. Different HTML
browsers support different <body>
tag options, but useful ones may be
e.g.:
htmlbodyopt(background) (some.gif)
,
defining some.gif
as the page background.
value
is automatically surrounded by double quotes when
this macro is used. There is no need to type them.
latexdocumentstyle(style)
: This macro forces the
\documentstyle{...}
setting in LaTeX output to style
. E.g., at the ICCE
we have a local article
-derivate called artikel1
. Using
artikel1
in
the LaTeX output.
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 \documentstyle
stanza. (Thanks,
Bernhard Reiter <breiter@mathematik.Uni-Osnabrueck.DE>
).
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 \documentstyle
preamble; e.g., useful options may be
dina4
or epsf
. To specify several options, separate them by a
comma (this is a LaTeX convention).
linuxdoc-sgml.sty
and qwertz.sty
must of course be in one of
the TEXINPUTS
directories.
mailto(email)
: The mailto
macro is only expanded in HTML
documents. It defines where mail about the document should go to.
nosloppyhfuzz()
: By default, the LaTeX output contains the text
nosloppyhfuzz()
to get `plain' 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.
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()
(Read as: no-toc-clearpage, read
toc
as table of contents.): 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 stanza 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 ++NOTRANS(ü)
, and still make them processable by
LaTeX. If you don't want this, put noxlatin()
in the preamble.
standardlayout()
: This is another LaTeX option. I like my
paragraph starts not to be indented, and I like more space between
paragraphs. Use standardlayout()
to get `vanilla' LaTeX layout.
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()
.
3.2.4: Sectioning
This section describes the sectioning commands for article
s, report
s,
book
s and for plainhtml
. The document type manpage
defines its own
sectioning commands which are described in section 3.3.
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 you only
want to use the sectioning commands to set captions, but aren't interested in
numbering.
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.
Summarized, in a book
or report
you should start at least with a
chapter
. In an article
you should start with a section
.
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 3.2.8.
3.2.5: Lists and environments
The macro package supports the following lists and environments:
itemize
and an open parenthesis and to close it with a closing
parenthesis. The other way is to start the list with startit()
and to
end it with endit()
.
it()
.
description()
or
is started with startdit()
and ended with enddit()
.
dit()
, this macro expects the
short description of the item.
enumerate()
, or
it must start with starteit()
and end with endeit()
.
eit()
.
center()
, or starts with
startcenter()
and ends with endcenter()
. Separate lines in a
centered block must be terminated by nl()
, otherwise they are merged
with subsequent lines.
verb()
:
SUBST
always occurs,
see section 2.3.30.
quote
macro. It has one
argument, the quote to set, as in:
3.2.6: Fonts and sizes
The macro package supports the following macros to change fonts:
bf(text)
: sets text
in boldface.
em(text)
: sets text
emphasized, usually in italics.
tt(text)
: sets text
in teletype.
tt()
macro furthermore causes YODL not to expand macros which are
within the parentheses. That means that you can safely type:
tt()
macro is not suited for long listings; use verb()
to set code
samples etc..
3.2.7: Accents
The macro converters offer two ways of putting characters with accents in the
output file. First, Latin-1 characters may appear as they are in the input.
E.g., when a YODL input file contains the character +ü, then that character
will appear on the output in such a way that the final document will show a +ü.
YODL handles this via the character translation tables (see section
2.4): e.g, a +ü might lead to \
"
{u}
in LaTeX output or
to ü
in HTML output. The YODL macro package supports most vowels with
the following accents: `
'
"
^
(e.g., +à+ä+â). Exceptions
are the characters that I couldn't generate with my editor (umm ;-), for a
full list see e.g., the file html.tables.yo
that is distributed with the
YODL package. Ergo, if you need such characters, and if your editor can
generate them, you can just go ahead and type them in (as in, Meine Frau
mag +überhaupt kein Bier).
You can also create all these characters and other accent characters using multi-character sequences. This method is implemented because many editors (or tty-lines) cannot handle 8-bits characters. The sequence that defines a character with an accent consists of three characters:
'
"
`
~
^
or o
,
followed by
E.g., the sequence \
"
u
leads to +ü, and \
o
A
leads to
+Å. The one exception to this rule is the German `scharfes Ess', the +ß
character. This character is produced by the sequence \
ss
.
Such multi-character sequences are handled by YODL via the SUBST mechanism (see
section 2.3.30). Therefore, such substitutions are `global' in the sense
that wherever they occur in the input file, they are recognized and
substituted. If you need to set \
"u
literally, use e.g., the CHAR
macro (see section 2.3.3) to `protect' the backspace; as in:
In the same vein, you could protect any other characters of a multi-character sequence to protect from the substitution mechanism.
The multi-character accents are supported in all output formats but txt
(plain ASCII) and in groff output, which send un-accented characters
to the output. These ASCII and groff converers map accent characters `back',
i.e., \
"
u
appears as u
. However, Latin-1 characters when
present in the input go to the output unaffected.
This mechanism is available in all but the most primitive output formats (e.g, the ASCII converter will ignore the requests). 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 lead to clickable links in HTML output; in other
output formats only some descriptive text appears.
The following macros implement the above mechanisms:
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
The macro ref(howtoinstall)
would then expand 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:
This code fragment would always set the text picosoft, but under HTML a clickable link would appear pointing to the text.
url(description)(location)
always expands to the
description
, but creates a hyperlink pointing to location
in HTML.
For example,
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 needed in
YODL.) To use a different font in the description
part, surrond it
inside the url paramater list, as in:
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 as karel@icce.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.
Note also the macro package also implements a macro includefile
, that
includes a file and automatically creates a label. That means that a YODL file
like:
implicitly creates two labels, named welcome
and techinfo
.
Below are some randoms dont's about labels and references:
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:
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
The right stanza is of course
The way YODL approaches figures, is currently the folloowing.
epsf
must be stated as one of the LaTeX
styles using latexoptions
macro.
The file in question is stated in YODL without an extension. YODL provides a
default extension, being .ps
.
<img src=...>
stanza. The file must be a GIF
file. The file is -again- stated without the filename extension; YODL
supplies .gif
.
The macro to include a figure is called, appropriately, figure
. It takes
three arguments:
For example, you might draw a picture or scan a photo and put it in a .gif
file, for usage with HTML documents. The conversion to PostScript could be
automated, e.g., using a YODL macro:
See the discussion of the SYSTEM
macro (section 2.3.32) for the danger
of live data and how YODL handles them.
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:
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.,
YODL has a few 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
3.2.10.1 for a discussion of national language support.
sethtmlfigureext(.new)
: This macro redefines the filename extension
for HTML conversions from .gif
to .new
. Note that you must include a
leading dot in the redefinition.
The new extension is used in the first following figure
statement.
sethtmlfigurealign(align)
: This redefines the alignment of figures
in HTML, which is default bottom
. Check your HTML handbook for possible
options; top
and center
should be fairly standard.
setlatexfigureext(.new)
: Redefines the extension from .ps
to
.new
.
Finally, an example of a picture is shown in figure 1. The picture is
also distributed with the YODL package as doc/world.gif
.
E.g., if your document contains This macro is handy in the following situation:
This fragment starts a chapter and includes a file. The label name
Example:
This line is Example:
Use The
3.2.10.1: National language support
YODL includes rudimentary national support, in the sense that it allows you to
redefine the strings that are used to identify a sections of the level chapter
or part, or the strings that are used to identify a figure. E.g., a command
Using the somewhere near the beginning of your document. Similar to The YODL may not be totally complete in respect to NLS; e.g., you might see
Contents instead of Inhoudsopgave. But I'm working on it.
where the arguments are:
The arguments to the The after which an abbreviated usage information is presented. This
information should show, e.g., the possible program flags and required
arguments; but no more.
followed by some descriptive text. The descriptive text can e.g. show what
the program is supposed to do.
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 followed by a list of related manual pages.
Diagnostics can state, e.g., what error messages are produced by the
program and what the cure is.
This section is optional.
The As an example, the manual page for the
The following list shows all macros of the package in alphabetical
order.
First of all, a document in the YODL language needs a preamble. This part
of the document must be at the top, and must define the modifiers and the
document type The modifiers, when present, must appear first.
The modifiers may be, e.g., Following the modifiers, you need to define the document type. This type is
either You should decide on the document type by counting the top-level sectioning
commands that you need. E.g., if you write an The document type also affects the way YODL formats the output. An If your document uses special macros, then these must be defined before
they are used. I myself usually define such macros following the preamble.
E.g., see the file To answer yes-but-what-if oriented minds, here are two results of the
wrong order of text, preamble and modifiers:
I tried to limit these pecularities to a minimum for obvious reasons. Normal
usage of the YODL language and of its converters should have no problems with
these pecularities, but they are listed in this section for completeness.
3.6.1.1: Direct commands to LaTeX
To send LaTeX commands directly to the output, use the The following two code fragments both output
3.6.1.2: Verbatim text
The YODL macro packages offer two ways of putting verbatim text (e.g., source
code listings) in the output. These ways are also described in the following
sections.
The verb macro
The first way is the The The tt macro
The second way to put verbatim text in LaTeX is the
3.6.2.1: Direct commands to HTML
Similar to the LaTeX converter, you can use either Furthermore, the HTML converter defines the macro E.g., the following code sends a HTML command
3.6.2.2: Numbering of sections
The HTML converter numbers its own sections. This is handled internally.
However, the current converter only can number sections as starting at 1, and
outputs the numbers in arabic numerals (you can't number with A, B, etc..).
3.6.2.3: The htmlbodyopt macro
The macro
3.6.2.4: The yodl2html-post postprocessor
The HTML converter necessarily uses a post-processor, which re-parses the
output of the The post-processor is a program The usage of the post-processor has one important drawback. The The tags start with In respect to the output, the following applies. You can start lines with a
single dot, since all dots are converted by the active character conversion
table to
3.6.3.1: The groff postprocessors
The post-processors for The labels and references are resolved via a post-processor which is
similar to the HTML postprocessor: the An in-depth description of the post-processor would be beyond this document.
The post-processor is a C program For these reasons, the SGML converter only supports the The SGML converter adds two macros to the set: The layout of the input file is very important in the ASCII converter, since
the output is basically the same as the input. The only exception to this rule
are multiple empty lines, which are eaten up by a post-processor
For example, you should format your sections in the following way to make sure
that the titles start at the leftmost column:
This ensures that the chapter and section titles appear `left-flushed'.
Optionally you might want to try the following layout:
Similarly, you should choose a `good-looking' way to format your lists, as in:
This makes sure that (a) the itemized list is `indented' relative to the other
text, and (b) that the lines within one item of the list are indented to the
same level.
Don't blame YODL as a package for the ugliness of the ASCII converter. Rather,
blame me: I wrote the ASCII converter when I was too lazy to dig into the
groff format. Now that there's a
figure 1: Sample picture in a figure.
3.2.10: Miscellaneous commands
The following is a list of commands that don't fall in one of the above
categories.
clearpage()
: This macro starts a new page in LaTeX. For HTML, a
horizontal rule is shown. (Note that the macro package sometimes inserts
new pages by itself; e.g., following a table of contents. See also section
3.2.3 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
2.3.8.
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 2.3.23.
"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:
htmlnewfile()
: Starts a new subfile in HTML output. This stanza as
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 where the yodl
run was started and in the system-wide
include directory. The default extension .yo
is supplied if necessary.
intro
can also be used to refer to the chapter. The includefile
stanza should therefore appear 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.
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.
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
statement also has a shorthand called redef
.
chapter(Introduction)
will yield for example the text Chapter 1:
Introduction.
setchapterstring(text)
macro, the Chapter text can be
redefined. E.g., in a Dutch text you might put
setchapterstring
,
a macro getchapterstring
exists that returns the text to identify a chapter.
(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)
.
set....string
macros only affect 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:
dutch
in the latexoptions
macro in the preamble of the
document. This makes sure that LaTeX uses Dutch names.
3.3: The manpage document type
The document type manpage
is implemented for the creation of Unix-style
manual pages. A manpage
document must be organized as follows:
manpage
macro define, e.g., the headers and
footers of the manual page. The date
, source
and manual
arguments can be empty.
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.
manpageoptions()
section is
optional.
manpage
document type requires you to strictly follow the above
order of commands and to state all the necessary sections (and optionally, to
state the not required sections but in their right order).
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'.
yodl
program follows (the actual
manual page may differ):
3.4: Alphabetical list of the macros
abstract(text)
:
Defines an abstract for an article
or report
document. Abstracts are
not implemented for book
s or manpage
s. Must appear before
starting the document with the article
or report
+macro.
affiliation(site)
:
Defines an affiliation, to appear in the document titlepage below the
author field. Must appear before starting the document with
article
, report
or book
. The affiliation is only printed when the
author field is not empty.
article(title)(author)(date)
:
Starts an article. The top-level sectioning command is (n)sect
. In HTML
conversions only one output file is written.
bf(text)
:
Sets text
in boldface.
book(title)(author)(date)
:
Starts a book document. The top-level sectioning command is (n)chapter
,
(n)part
being optional. In HTML output files are created for each
chapter.
center(text)
:
Sets text
centered, when the output format permits. Use nl()
in the
text to break lines.
chapter(title)
:
Starts a new chapter in book
s or report
s.
clearpage()
:
Starts a new page, when the output format permits. Under HTML a horizontal
line is drawn.
def(macroname)(nrofargs)(redefinition)
:
Defines macroname
as a macro, having nrofargs
arguments, and
expanding to redefinition
. This macro is a shorthand for
DEFINEMACRO
.
An error occurs when the macro is already defined. Use
redef()
to unconditionally define or redefine a macro.
description(list)
:
Sets list
as a description list. Use dit(item)
to
indicate items in the list.
dit(itemname)
:
Starts an item named itemname
in a descriptive list. The list is either
enclosed by startdit()
and enddit()
, or is an argument to
description()
.
eit()
:
Indicates an item in an enumerated list. The list is either enclosed by
starteit()
and endeit()
, or is an argument to enumerate()
.
em(text)
:
Sets text
as emphasized, usually italics.
email(address)
:
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
.
endcenter()
:
Ends centered text that is started with startcenter()
.
enddit()
:
Ends a descriptive list that is started with startdit()
.
endeit()
:
Ends an enumerated list that is started with starteit()
.
endit()
:
Ends an itemized list that is started with startit()
.
enumerate(list)
:
Sets list
as an enumerated list. Use eit()
to indicate items in
the list.
fig(label)
:
This macro is a shorthand for figure ref(label)
and just makes the typing
shorter, as in see fig(schematic) for ..
See getfigurestring()
and
setfigurestring()
for the figure
text.
figure(file)(caption)(label)
:
Sets the picture in file
as a figure in the current document, using the
descriptive text caption
. The label
is defined as a placeholder for the
figure number and can be used in a corresponding ref
statement. Note that
the file
must be the filename without extension: YODL will supply .gif
when in HTML mode, or .ps
when in LaTeX mode. Figures in other modes are
not (yet) implemented.
footnote(text)
:
Sets text
as a footnote, or in parentheses when the output format
does not allow footnotes.
gagmacrowarning(name name ...)
:
Prevents the yodl
program from printing cannot expand possible user
macro. E.g., if you have in your document the file(s) are ..
then you
might want to put before that: gagmacrowarning(file)
. Synonym for
NOUSERMACRO
.
getchapterstring()
:
Expands to the string that defines a `chapter' entry, by default Chapter.
Can be redefined for national language support by setchapterstring()
.
getfigurestring()
:
Returns the string that defines a `figure' text, in captions or in the
fig()
+macro. The string can be redefined using the setfiguretext()
+macro.
getpartstring()
:
Expands to the string that defines a `part' entry, by default Part. Can
be redefined for national language support by setpartstring()
.
htmlbodyopt(option)(value)
:
Adds option="value"
to the options of the <body ...>
tag in HTML
files. Useful options are, e.g., fgcolor
and bgcolor
, whose values
are expressed as #rrggbb
, where rr
are two hexadecimal digits of
the red component, gg
two hexadecimal digits of the green component,
and bb
two hexadecimal digits of the blue component.
htmlcommand(cmd)
:
Sets cmd
when converting to HTML. The cmd
is not further parsed
by YODL.
htmlnewfile()
:
In HTML output, starts a new file. All other formats are not affected. Note
that you must take your own provisions to access the new file; say via links.
Also, it's safe to start a new file just befoore opening a new section, since
sections are accessible from the clickable table of contents. The HTML
converter normally only starts new files prior to a chapter
definition.
htmltag(tagname)(start)
:
Sets tagname
as a HTML tag, enclosed by <
and >
. When
start
is zero, the tagname
is prefixed with /
.
includefile(file)
:
Includes file
and defines a label with the same name. The default
extension .yo
is supplied if necessary.
it()
:
Indicates an item in an itemized list. The list is either surrounded by
startit()
and endit()
, or it is an argument to itemize()
.
itemize(list)
:
Sets list
as an itemized list. Use it()
to indicate items in the
list.
label(labelname)
:
Defines labelname
as an anchor for a link
command, or to stand for the last numbering of a section or figure in a
ref
command.
latexcommand(cmd)
:
Writes cmd
to the output when converting to LaTeX. The cmd
is not
further expanded by YODL.
latexdocumentstyle(style)
:
Forces the LaTeX
\documentstyle{...}
setting to style
. Normally the style is
defined by the macros article
, report
or book
. This macro
is an escape route incase you need to specify your own document style
for LaTeX. This option is a modifier and must
appear before the article
, report
or book
macros.
latexoptions(options)
:
Sets the LaTeX processing options, a useful option is, e.g.,
dina4,epsf
. This command must appear before the document type is
stated by article
, report
, etc..
latexlayoutcmds(latexcommands)
:
This macro is provided incase you want to put your own LaTeX layout commands
into LaTeX output. The latexcommands
are pasted right after the
\documentstyle
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.
link(description)(labelname)
:
In HTML output a clickable link with the text description
is created that
points to the place where labelname
is defined using the label
+macro.
Using link
is similar to url
, except that a hyperlink
is set pointing to a location in the same document. For output formats other
than HTML, only the description
appears.
mailto(address)
:
Defines the default mailto
address for HTML output. Must appear
before the document type is stated by article
, report
, etc..
mancommand(cmd)
:
Writes cmd
to the output when converting to man. The cmd
is not
further expanded by YODL.
manpage(title)(section)(date)(source)(manual)
:
Starts a manual page document. The section
argument must be a number,
stating to which section the manpage belongs to. Most often used are commands
(1), file formats (5) and macro packages (7). The sectioning commands in a
manpage are not (n)sect
etc., but manpage...()
. The order of the
sections in a manpage must be: manpagename
, manpagesynopsis
,
manpagedescription
, manpageoptions
, manpagefiles
,
manpageseealso
, manpagediagnostics
, manpagebugs
,
manpageauthor
. Optional extra sections can be added with
manpagesection
.
manpageauthor()
:
Starts the AUTHOR entry in a manpage
document. Must be the last section
of a manpage
.
manpagebugs()
:
Starts the BUGS entry in a manpage
document.
manpagedescription()
:
Starts the DESCRIPTION entry in a manpage
document.
manpagediagnostics()
:
Starts the DIAGNOSTICS entry in a manpage
document.
manpagefiles()
:
Starts the FILES entry in a manpage
document.
manpagename(name)(short description)
:
Starts the NAME entry in a manpage
document. The short description is
used by, e.g., the whatis
database.
manpageoptions()
:
Starts the OPTIONS entry in a manpage
document.
manpagesection(SECTIONNAME)
:
Inserts a non-required section named SECTIONNAME
in a manpage
document. This macro can be used to augment `standard' manual pages with extra
sections, e.g., EXAMPLES. Note that the name of the extra section should
appear in upper case, which is consistent with the normal typesetting of
manual pages.
manpageseealso()
:
Starts the SEE ALSO entry in a manpage
document.
manpagesynopsis()
:
Starts the SYNOPSIS entry in a manpage
document.
mscommand(cmd)
:
Writes cmd
to the output when converting to ms. The cmd
is not
further expanded by YODL.
nchapter(title)
:
Starts a chapter (in a book
or report
) without generating a
number before the title and without placing an entry for the chapter in
the table of contents.
nl()
:
Forces a newline; i.e., breaks the current line in two.
nosloppyhfuzz()
:
By default, LaTeX output contains commands that cause it to shut up about
hboxes that are less than 4pt overfull. When nosloppyhfuzz()
appears
before stating the document type, LaTeX complaints are `vanilla'.
notableofcontents()
:
Prevents the generation of a table of contents. This is default in, e.g.,
manpage
and plainhtml
documents. When present, this option must
appear before stating the document type with article
, report
etc..
notitleclearpage()
:
Prevents the generation of a clearpage()
instruction after the typesetting
of title information. This instruction is default in all non article
documents. When present, must appear before stating the document type with
article
, book
or report
.
notocclearpage()
:
Prevents the generation of a clearpage()
instruction after the typesetting
of a table of contents. This instruction is default in all
documents. When present, must appear before stating the document type with
article
, book
or report
.
noxlatin()
:
When used in the preamble, the LaTeX converter disables the inclusion of the
file xlatin1.tex
. Normally this file gets included in the LateX output
files to ensure the conversion of high ASCII characters (like +é) to
LaTeX-understandable codes. (The file xlatin1.tex
comes with the YODL
distribution.)
npart(title)
:
Starts a part in a book
document, but without numbering it and without
entering the title of the part in the table of contents.
nsect(title)
:
Starts a section, but does not generate a number before the title
nor
an entry in the table of contents. Further sectioning commands are
nsubsect
, nsubsubsect
and nsubsubsubsect
.
nsubsect(title)
:
Starts a non-numbered subsection.
nsubsubsect(title)
:
Starts a non-numbered sub-subsection.
nsubsubsect(title)
:
Starts a non-numbered sub-sub-subsection.
part(title)
:
Starts a new part in a book
document.
plainhtml(title)
:
Starts a document for only a plain HTML conversion. Not available in
other output formats. Similar to article
, except that an author- and
date field are not needed.
quote(text)
:
Sets the text as a quotation. Usually, the text is indented, depending on the
output format.
redef(macro)(nrofarguments)(redefinition)
:
Defines macro macro
to expand to redefinition
.
Similar to def
, but any pre-existing definition is overruled. This command
is a shorthand for redefinemacro
.
redefinemacro(nrofargs)(redefinition)
:
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..
ref(labelname)
:
Sets the reference for labelname
. Use label
to define a label.
report(title)(author)(date)
:
Starts a report type document. The top-level sectioning command in a report
is chapter
.
roffcmd(dotcmd)(sameline)(secondline)(thirdline)
:
Sets a t/nroff command that starts with a dot, on its own line. The arguments
are: dotcmd
- the command itself, e.g., .IP
; sameline
- when not
empty, set following the dotcmd
on the same line; secondline
- when
not empty, set on the next line; thirdline
- when not empty, set on the
third line. Note that dotcmd
and thirdline
are not further expanded by
YODL, the other arguments are.
sect(title)
:
Starts a new section.
setchapterstring(name)
:
Defines name
as the `chapter' string, by default Chapter. E.g., after
setchapterstring(Hoofdstuk)
, YODL gains some measure of national language
support for Dutch. Note that LaTeX support has its own NLS, this macro doesn't
affect the way LaTeX output looks.
setfigurestring(name)
:
Defines the name
as the `figure' text, used e.g. in figure captions. E.g.,
after setfigurestring(Figuur)
, YODL uses Dutch names for figures.
sethtmlfigureext(ext)
:
Defines the filename extension for HTML figures, defaults to .gif
. Note
that a leading dot must be included in ext
. The new extension takes effect
starting with the following usage of the figure
+macro.
sethtmlfigurealign(alignment)
:
Redefines the alignment for figures in HTML. The default is bottom
. Other
options depend on the client browser, but top
and center
should be
universal.
setlatexfigureext(ext)
:
Defines the filename extension for encapsulated PostScript figures in LaTeX,
defaults to .ps
. The dot must be included in t new extension ext
. The
new extension takes effect starting with a following usage of the figure
+macro.
setpartstring(name)
:
Defines name
as the `part' string, by default Part. E.g., after
setpartstring(Teil)
, YODL identifies parts in the German way. Note that
LaTeX output does its own national language support; this macro doesn't affect
the way LaTeX output looks.
sgmlcommand(cmd)
:
Writes cmd
to the output when converting to SGML. The cmd
is not
further expanded by YODL.
sgmltag(tag)(onoff)
:
Similar to htmltag
, but used in the SGML converter.
standardlayout()
:
Enables the default LaTeX layout. When this macro is absent, then the
first lines of paragraphs are not indented and the space between
paragraphs is somewhat larger. The standardlayout()
directive must appear
before stating the document type as article
, report
, etc..
startcenter()
:
Starts centered text. Use endcenter()
to stop centering text.
startdit()
:
Starts a descriptive list. Use dit(item)
to set items in the list, and
use enddit()
to end the list.
starteit()
:
Starts an enumerated list. Use eit()
in the list to indicate items, and
use endeit()
to end the list.
startit()
:
Starts an itemized list. Use it()
in the list to indicate items, and use
endit()
to end the list.
subsect(title)
:
Starts a new subsection. Other sectioning commands are
subsubsect
and subsubsubsect
.
subsubsect(title)
:
Starts a sub-subsection.
subsubsubsect(title)
:
Starts a sub-sub-subsection.
titleclearpage()
:
Forces the generation of a clearpage()
directive following the title of a
document. This is already the default in book
s and report
s, but can be
overruled with notitleclearpage()
. When present, must appear in the
preamble; i.e., before the document type is stated with article
,
book
or report
.
tocclearpage()
:
Forces the generation of a clearpage()
directive following the table of
contents in a
document. This is already the default in all document types, but can be
overruled with notocclearpage()
. When present, must appear in the
preamble; i.e., before the document type is stated with article
,
book
or report
.
tt(text)
:
Sets text
in teletype font, and prevents it from being expanded.
For unbalanced parameter lists, use CHAR(40)
to get
(
and CHAR(41)
to get )
.
txtcommand(cmd)
:
Writes cmd
to the output when converting to ASCII. The cmd
is not further expanded by YODL.
url(description)(locator)
:
In LaTeX documents the description
is sent to the output. For HTML,
a link is created with the descriptive text description
and pointing
to locator
. The locator
should be the full URL, including
service; e.g, http://www.icce.rug.nl
, but excluding the double
quotes that are necessary in plain HTML. Use the macro link
to create
links within the same document. For other formats, something like
++description [locator] will appear.
verb(text)
:
Sets text
in verbatim mode: not subject to macro expansion or
character table expansion. The text appears literally on the output,
usually in a teletype font (that depends on the output format). This
macro is for larger chunks, e.g., listings. For unbalanced parameter
lists, use CHAR(40)
to get (
and CHAR(41)
to get )
.
verbinclude(filename)
:
Reads filename and inserts it literally in the text, set in verbatim mode.
not subject to macro expansion or character table expansion.
The text appears literally on the output,
usually in a teletype font (that depends on the output format).
The filename is not changed in any way.
whenhtml(text)
:
Sends text
to the output when in HTML conversion mode. The text is
further expanded if necessary.
whenlatex(text)
:
Sends text
to the output when in LaTeX conversion mode. The text is
further expanded if necessary.
whenman(text)
:
Sends text
to the output when in man conversion mode. The text is
further expanded if necessary.
whenms(text)
:
Sends text
to the output when in ms conversion mode. The text is further
expanded if necessary.
whensgml(text)
:
Sends text
to the output when in SGML conversion mode. The text is
further expanded if necessary.
whentxt(text)
:
Sends text
to the output when in ASCII conversion mode. The text is
further expanded if necessary.
3.5: General structure of a YODL document
This section describes the general format of a YODL document.
latexoptions
, mailto
, affiliation
,
etc.. A very useful modifier is abstract
. All modifiers are listed in
section 3.2.3. 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.
article
, report
, book
, plainhtml
or manpage
.
Except for the manpage
document type, which is described in section
3.3, the following rules apply:
article
with 20 sections, it
might be a good idea to switch to a report
and group some of the sections
into chapters. Similarly, a report with 30 chapters might be better off as a
book
with parts. As a rule of thumb, a document should have no more than
10 top-level sectionings, and each top-level sectioning should have no more
than 10 subsectionings, etc..
article
(or plainhtml
) leads to one output file; which means under HTML one final
document. If your article is way too long, then the loading of the HTML
document will be long too. In HTML output, YODL splits report
s and
books
into files that hold the separate chapters. These can then be
reached via the table of contents. Ergo, the document length can also be
relevant when you contemplate switching to a report
or book
.
doc/yodl.yo
that is distributed with the YODL package.
This is the main file of this manual and follows the syntax described herein.
<html>
tag would come
too late in a HTML conversion, causing the HTML viewer to become confused.
Or, the \documentstyle
definition would be seen too late by the LaTeX
typesetter.
latexoptions
, after the
document type, then the modifiers will have no effect; though YODL won't
complain either. The reason for this is the definition of such modifiers
will be seen following the stage where they are needed..
3.6: Pecularities of conversions
Each macro package that handles a conversion from YODL to a given output format
has its pecularities. I tried to make the different conversion packages as
uniform as possible, but given the characteristics of output formats,
differences still exist.
3.6.1: Notes on the LaTeX converter
The LaTeX converter is, in YODL's viewpoint, the easiest one: since LaTeX has a
wide functionality, a YODL document is basically just re-mapped to LaTeX
commands.
latexcommand
macro
(see section 3.2.1), or use NOTRANS
(see section
2.3.22). The advantage of the latexcommand
macro is that it only
outputs its argument when in LaTeX mode.
\pagestyle{plain}
when in
LaTeX mode:
verb
macro and is meant for longer listings (whole
files); as in:
verb
command in LaTeX leads to \begin{verbatim}
and
\end{verbatim}
. That means that the verb
macro has only one caveat:
you cannot put \end{verbatim}
in it.
tt
macro, used for
short in-line strings (e.g, **argv
). The LaTeX converter doesn't actually
use a verbatim mode, but sets the characters in teletype font. I just hope
that the character conversion tables are complete..
3.6.2: Notes on the HTML converter
The HTML converter is, from YODL's point of view, somewhat harder. HTML doesn't
support automatic section numbering or resolving of label/reference pairs. The
converter must take care of this.
NOTRANS
or
htmlcommand
to send HTML commands to the output. Or, since the only
`difficult' characters are probably only <
and >
, you can also resort
to CHAR
for these two characters.
htmltag
, expecting two
arguments: the tag to set, and an `on/off' switch. E.g., htmltag(b)(1)
sets <b>
while htmltag(b)(0)
sets </b>
.
<hr>
to the output file when
in HTML mode:
htmlbodyopt(option)(value)
, which is described earlier, can be
repeated up to six times: the HTML converter currently supports up to 6
option/value settings. When the need arises, I'll implement more.
yodl
program. The post-processor is necessary for a variety
of reasons: the HTML output is split into several files, a table of contents
is created, labels and references to labels are resolved.
yodl2html-post
and is automatically
activated when the shellscript yodl2html
is used. I therefore strongly urge
you to convert YODL documents to HTML using this script.
yodl
program sec places tags for the post-processor in its output. The
post-processor takes actions according to the tags.
.yodltagstart.
and end with .yodltagend.
(though
in upper case, guess why I typed them here in lowercase?). Therefore, you
cannot put these strings in a YODL document that should be converted to
HTML. The tags would however be harmless in other output formats. (If this
setup that uses tags proves to be a problem, I'll implement a way around it.
Besides, the tags can be configured in the top-level Makefile
when
installiong the YODL package.)
3.6.3: Notes on the groff converter
The two converters that write groff
output are the man
and ms
converters.
\&.
. However that also means that you cannot easily paste
groff
commands into an output file. If you want to send commands, use the
macro roffcmd()
.
groff
output are quite complex. Similar to the
HTML postprocessor, labels and references need to be fixed and a table of
contents must be created. Furthermore, groff
and its macros require an
unusually strict and unreadable input (well, in my opinion they do). The
complexity of the groff
conversions lies therefore in the post-processor.
.yodltagstart.
and
.yodltagend.
strings, though in uppercase, are reserved. The
converters also introduce an extra internal label for usage in the
table of contents generation: .yoldtoccommand.
.
yodlfixlabels
.
3.6.4: Notes on the SGML converter
I implemented the definition of the SGML converter for reasons of backward
compatibility at our site (the ICCE). The SGML converter is by no means
complete, or indeed usable unless you're using the SGML system at the ICCE. It
outputs an SGML file which is suitable for our SGML implementation, which
is a hacked Linuxdoc-SGML mutant.
article
document
type. Therefore, the top-level sectioning command can only be sect
.
sgmltag(tag)(onoff)
and
sgmlcommand(cmd)
, which work similarly to the htmltag
and
htmlcommand
macros.
3.6.5: Notes on the ASCII converter
As stated before, the ASCII converter basically only strips macronames in its
input. This converter is so rudimentary, that the groff
converters are a
better path to generate plain ASCII output. As it is, the ASCII converter is
now only usable as a last resort, when neither LaTeX, nor a HTML browser, nor
groff
is available.
yodl2txt-post
and replaced by one empty line each.
man
and a ms
output format, you're
probably better off using that.