Chapter 3: A macro package for Yodl

The macro package which is distributed with the Yodl package 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 supported output formats are LaTeX (just plain LaTeX, no 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.

3.1: Files of the macro package

The files of which the macro package consists are by default installed to the directory /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.

3.1.1: Conversion script invocations

The Yodl package is distributed with scripts yodl2tex, yodl2html and other yodl2... drivers. Basically, an invocation like

yodl2tex file

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:

  • For LaTeX conversions, one output file with the extension .tex is written.

  • For HTML conversions, several files may be written holding the separate chapters of the original document. When the document is not sectioned by chapters, only one output file is created.

    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..

  • For 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.

  • For SGML conversions, one output file with the extension .sgml is written.

  • For ASCII conversions, the converter is named yodl2txt and one output file with the extension .txt is created.

  • The Yodl package furthermore holds `second-step' scripts, which are:

  • The conversion script 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.

  • The script 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.

  • Similar to yodl2manless, the script yodl2msless starts the ms converter and pipes the groff output through a pager.

  • The script 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:

    % yodl2manless mymanpage | striproff > mymanpage.txt
    % yodl2msless myarticle  | striproff > myarticle.txt
    

    3.2: Macros of the package

    The following sections describe the macros that are defined in the macro package by groups. Following the description, the macros are listed in alphabetical order.

    3.2.1: Conversion defines and literal commands

    According to the format of the output file, the macro package defines a given symbol:

  • latex when the output format is LaTeX,

  • html when the output format is HTML,

  • man when the output format is groff in conjunction with the man macro package,

  • ms when the output format is groff with the ms package,

  • sgml when the output format is SGML,

  • txt when the output format is plain ASCII.

  • 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

    .SH "Section Title"
    

    while the same command for the ms macro package must be sent as

    .SH
    Section Title
    .PP
    

    The roffcmd macro can be used to send these commands to the output file as follows:

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

  • sgmlcommand(cmd): sends the SGML command cmd when in SGML conversion mode. The cmd is not further expanded.

  • sgmltag(tag)(onoff): sends <tag> when onoff is nonzero, or sends </tag> when onoff is zero. Only active in SGML conversions.

  • txtcommand(cmd): implemented for compatibility reasons, though a `command' in plain ASCII output doesn't make much sense. The usefulness of this macro is rather in the fact that it only produces output when in ASCII conversion mode.

  • The above commands can be used to quickly implement a macro. E.g., the macro package implements the it macro (which starts an item in a list) as:

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

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

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

  • whenlatex(text): sends text when in LaTeX conversion mode,

  • whenhtml(text): sends text when in HTML conversion mode,

  • whenman(text): sends text when in man conversion mode,

  • whenms(text): sends text when in ms conversion mode,

  • whentxt(text): sends text when in ASCII conversion mode,

  • whensgml(text): sends text when in SGML conversion mode.

  • Note again that the difference between the whenformat() macros and the formatcommand() macros is, that the former will expand their argument while the latter will not. As an example, consider the following code fragment:

    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 whenformat() macros are used here to make sure that the arguments to the macros are further expanded; this makes sure that the footnote macro in the whenlatex block gets treated as a footnote.

    3.2.2: Document types

    The macro package supports four document types: article, report, book and the manual page. Note that document types have nothing in common with output formats; a book can be converted to each of the output formats, and a manual page can be converted to a .dvi file. Nevertheless, some formats are 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:

  • A pagebreak is generated after the title information in book and report documents.

  • A pagebreak is generated after a table of contents in all documents.

  • 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 book or a report, the title and table of contents will also be separated by a pagebreak.

    This behavior can be modified using the (no)titleclearpage() and (no)tocclearpage() directives. 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 articles and reports, but not in other document types. I.e., if you need introductory text in a book, you should start with a non-numbered chapter that holds this text.

  • affiliation(site): This macro is relevant for article, report and book documents. It defines the affiliation of the author. The site information appears in the title, below the author's name.

  • htmlbodyopt(option)(value): This macro adds option="value" to the <body> tag that will be generated for HTML output. The HTML converter generates <body> tags each time that a new file is started; i.e., at the top of the document and at each chapter-file. Different HTML browsers support different <body> tag options, but useful ones may be e.g.:

    htmlbodyopt(fgcolor)(#000000)
    htmlbodyopt(bgcolor)(#FFFFFF)
    

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

    See the documentation on HTML for more information.

    Note that the 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

    latexdocumentstyle(artikel1)
    article(..title..)
           (..author..)
           (..date..)
    

    will start an article as far as Yodl is concerned, but will use 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).

    Backward compatibility note: At the ICCE, we've used Linuxdoc-SGML for some time. The modifier

    latexoptions(linuxdoc-sgml,qwertz)
    

    approximates the LaTeX output that this SGML variant produces. The style files 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

    \hfuzz=4pt
    

    which is placed there by the macro package. This suppresses overfull hbox warnings of LaTeX when the overfull-ness is less than 4pt. I find this useful.

    This macro has no consequences for non-LaTeX formats.

    Use 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.

    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() (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 ü, 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.

    This macro has no consequences for non-LaTeX formats.

  • titleclearpage(): Forces the insertion of a clearpage() directive after the title information has been typeset. This behavior is the default in book and report documents. See also notitleclearpage().

  • tocclearpage(): Forces the insertion of a clearpage() directive following the table of contents. This behavior is default in all document types; the macro is provided for consistency reasons with (no)titleclearpage().

  • Note again that when present, the modifiers must appear before the document type definition.

    3.2.4: Sectioning

    This section describes the sectioning commands for articles, reports, books 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.

  • 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 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.

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

    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 3.2.8.

    3.2.5: Lists and environments

    The macro package supports the following lists and environments:

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

    There are two ways to indicate an itemized list: one is to start the list with 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().

    The items in the list are indicated with it().

    Example:

    One version of itemized list:
    itemize(
        it() One item.
        it() Another item.
    )
        
    Second version:
    startit()
        it() One item.
        it() Another item.
    endit()
    
    

    Description lists:
    A description list is similar to an itemized list, except that the items in the list have a short description (as in this list). The description list is either inside a description() or is started with startdit() and ended with enddit().

    The items in the list are marked with dit(), this macro expects the short description of the item.

    Example:

    One version of a description list:
    description(
        dit(First this:) One item.
        dit(Then this:) Another item.
    )
        
    Second version:
    startdit()
        dit(First this:) One item.
        dit(Then this:) Another item.
    enddit()
    
    

    Enumerated lists:
    An enumerated list is like an itemized list, except that the items are numbered. The list must be inside a enumerate(), or it must start with starteit() and end with endeit().

    The elements in the list must be indicated with eit().

    Example:

    One version of an enumerated list:    
    enumerate(    
        eit() One item.    
        eit() Another item.    
    )    
        
    Second version:    
    starteit()    
        eit() One item.    
        eit() Another item.    
    endeit()    
    
    

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

    Centered text is either either inside 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.

    Example:

    center(\    
        Centered text. nl()    
        Another line of centered text.)    
        
    startcenter()    
        Centered text.    
    endcenter()    
    
    

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

    The text must either be inside verb():

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

    The text in question is of course not subject to macro expansion by Yodl. However, global string substitution as defined by SUBST always occurs, see section 2.3.30.

    Quotes:
    Long quotes can be set by the quote macro. It has one argument, the quote to set, as in:

    quote(DOS: n., A small annoying boot virus that causes random spontaneous 
    system crashes, usually just before saving a massive project. Easily 
    cured by UNIX. See also MS-DOS, IBM-DOS, DR-DOS.
        
    (from David Vicker's .plan))
    
    

    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.

  • The tt() macro furthermore causes Yodl not to expand macros which are within the parentheses. That means that you can safely type:

    In Yodl, you can use tt(includefile(somefile)) to include a file
    in your document.
    

    The tt() macro is not suited for long listings; use verb() to set code samples etc..

    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.

    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 &uuml; 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:

  • one backslash (\), followed by

  • the accent character, one of ' " ` ~ ^ or o, followed by

  • the character in question.

  • E.g., the sequence \"u leads to ü, and \oA 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:

    CHAR(\)"u
    

    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.

    3.2.8: Labels, links, references and URLs

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

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

    This mechanism is available in all 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.

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

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

    URLs:
    Universal Resource Locators (URLs) are used to create links to other HTML documents or services, à la the HTML <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:

  • The macro label(name) defines a label named name. The name of the label can be used in a ref or link macro.

  • The macro ref(name) sets a reference to the label named name. The text of the reference is the number of the last sectioning command that was active during the creation of the label. When using references it is therefore important to define the corresponding labels right after a sectioning command, as in

    section(How to install my program) label(howtoinstall)
    This section describes...
    .
    .
    See section ref(howtoinstall) for installation instructions.
    

    The macro ref(howtoinstall) would then expand to the number of the section named How to install my program.

  • The macro link(description)(name) always expands to the description. In HTML output, a clickable link is created pointing to a label called name. For example:

    label(megahard)
    COMMENT(zucht...)
    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 the text.

  • The macro url(description)(location) always expands to the description, but creates a hyperlink pointing to location in HTML. For example,

    If you have W3 access, take a look
    at my url(homepage)
    (http://www.icce.rug.nl/we/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 needed in Yodl.) To use a different font in the description part, surrond it inside the url paramater list, as in:

    The Yodl package can be obtained at
    the site tt(ftp.lilypond.org) in the directory
    url(tt(/pub/yodl))
       (ftp://ftp.lilypond.org/pub/yodl/development).
    

  • The macro email(address) is a special case of url: under HTML, the address appears as a clickable link in slanted font to mail address. For example:

    I can be reached as
    email(karel@icce.rug.nl).
    

    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:

    chapter(Introduction)
        sect(Welcome)
        includefile(welcome)
    
    chapter(Technical information)
    includefile(techinfo)
    

    implicitly creates two labels, named welcome and techinfo.

    Below are some randoms dont's about labels and references:

  • Don't put `weird' characters in label names. Generally, don't use spaces and tabs; though punctuation characters should work.

  • The name of the label is always only an internal symbol; it does not appear in the output. Therefore, constructions such as the following are not correct:

    ref(em(labelname))
    

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

    em(ref(labelname))
    

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

    section(Introduction label(intro))
    

    The right stanza is of course

    section(Introduction) label(intro)
    

  • undef(x)

    3.2.9: Figures

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

    The way Yodl approaches figures, is currently the folloowing.

  • Figures can only be included in LaTeX or in HTML documents.

  • For LaTeX, you must prepare a picture in an external file that is included in the document as en encapsulated PostScript file. Incidentally, that means that epsf must be stated as one of the LaTeX styles using latexoptions macro.

    The file in question is stated in Yodl without an extension. Yodl provides a default extension, being .ps.

  • For HTML, you must prepare a picture in an external file that is placed in the document using the <img src=...> stanza. The file must be a GIF file. The file is -again- stated without the filename extension; Yodl supplies .gif.

  • All other output formats do not include pictures in the document, but typeset something like insert figure .. here.

  • The macro to include a figure is called, appropriately, figure. It takes three arguments:

  • The first argument is the filename. This name may include directories, but may not include the filename extension. The reason for this is, that Yodl supplies the correct extension once the output format is known.

  • The second argument is the figure title, or the caption. Yodl prefixes this caption with the text Figure xx:, where xx is a number.

  • The last argument is a label, which Yodl defines as a placeholder for the figure number.

  • For example, you might draw a picture or scan a photo and put it in a .gif 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 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:

    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.
    

    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 ??. The picture is also distributed with the Yodl package as Documentation/pictures/world.xpm.

    figure 1 is shown here.
    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 ARGx, where x is 1, 2, etc., can be used in the definition part to indicate where arguments should be pasted in. This macro is a shorthand for DEFINEMACRO, see section 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.

    E.g., if your document contains "as for manpages, see sed(1), tr(1) and awk(1)", and if you get tired of warnings about possible user macros sed, tr and awk, try the following:

    gagmacrowarning(sed tr awk)
    .
    .
    As for manpages, see sed(1), tr(1) and awk(1).
    

  • htmlnewfile(): Starts a new subfile in HTML output. This stanza 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.

    This macro is handy in the following situation:

    chapter(Introduction)
    includefile(intro)
    

    This fragment starts a chapter and includes a file. The label name 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.

    Example:

    This line is nl()
    broken in two.
    

    This line is
    broken in two.

  • redefinemacro(macro)(nrofargs)(redef): This command (re)defines a macro, expecting nrofargs arguments, to redef. If a previous definition of the macro existed, it is overruled.

    Example:

    redefinemacro(clearpage)(0)(\ 
        em(---New page starts here---))
    

    Use ARGx in the redef part to indicate where all arguments should occur, as in the following imaginary macro to typeset a literature reference:

    redefinemacro(litref)(3)(\ 
        Title: bf(ARG1) nl()\ 
        Author(s): em(ARG2) nl()\ 
        Published by: ARG3)
    .
    .
    .
    litref(Java in a Nutshell)
          (David Flanagan)
          (O'Reilly & Associates, Inc.)
    

    The redefinemacro statement also has a shorthand called redef.

  • 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 chapter(Introduction) will yield for example 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 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).

    The 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:

  • put dutch in the latexoptions macro in the preamble of the document. This makes sure that LaTeX uses Dutch names.

  • redefine the chapter and part names for non-LaTeX output, as in:

    setpartstring(Deel)
    setchapterstring(Hoofdstuk)
    setfigurestring(figuur)
    

  • Finally, you should probably type your text in Dutch.

  • 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.

    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:

    1. The manual page itself is defined, using the macro

      manpage(short title)
                  (section)
                  (date)
                  (source)
                  (manual)
      

      where the arguments are:

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

      Section:
      A number, stating the manpage section. The Linux man (7) page states in respect to sections, that section 1 is for commands, 2 for system calls, 3 for library calls, 4 for special files (e.g., devices), 5 for file formats, 6 for games, 7 for macro packages and conventions, 8 for system management commands and 9 for other manpages, such as kernel commands.

      Date:
      The date of release.

      Source:
      The package where the manpage belongs to.

      Manual:
      The manual to which the package belongs.

      The arguments to the manpage macro define, e.g., the headers and footers of the manual page. The date, source and manual arguments can be empty.

    2. The subject of the manpage is stated using

      manpagename(name)(short description)
      

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

    3. The synopsis is started with

      manpagesynopsis()
      

      after which an abbreviated usage information is presented. This information should show, e.g., the possible program flags and required arguments; but no more.

    4. The description is presented using

      manpagedescription()
      

      followed by some descriptive text. The descriptive text can e.g. show what the program is supposed to do.

    5. The options may be listed following

      manpageoptions()
      

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

    6. Necessary files are listed following

      manpagefiles()
      

    7. The `see also' entry is started with

      manpageseealso()
      

      followed by a list of related manual pages.

    8. The diagnostics are described following

      manpagediagnostics()
      

      Diagnostics can state, e.g., what error messages are produced by the program and what the cure is.

    9. Next, known bugs can be described following

      manpagebugs()
      

      This section is optional.

    10. Finally the author is stated after

      manpageauthor()
      

    The 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'.

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

    manpage(yodl)
           (1)
           (1996)
           (The Yodl Package)
           (Yet oneOther Document Language)
    
    manpagename(yodl)(main Yodl convertor)
    
    manpagesynopsis()
        bf(yodl) [-DNAME] [-IDIR] [-oFILE] [-PCMD] [-pPASS] [-t] [-v] [-w] [-h]
        [-?]  inputfile [inputfile...]
    
    manpagedescription()
    
        This manual page describes the bf(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()
    
    startdit()
    
        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, bf(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, bf(yodl) will warn when it sees
        inconsistencies.
        
        dit(-h, -?) Shows usage information.
        
        dit(inputfile) File to process, use em(-) to instruct bf(yodl) to read 
        from stdin.
        
    enddit()
    
    manpagefiles()
    
        The bf(yodl) program requires no files, but `normal' usage of the Yodl
        package requires macro files installed in bf(/usr/local/lib/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 bf(yodl) are too many to enumerate, but all errors
        are printed to em(stderr) after which bf(yodl) exits with a non-zero
        status.
    
    manpagebugs()
    
        There may be bugs in the bf(yodl) program, but that's not very likely.
        More likely you'll encounter bugs or omissions in the macro package
        itself.
    
    manpageauthor()
    
        Karel Kubat (karel@icce.rug.nl)
    
    

    )

    3.4: Alphabetical list of the macros

    The following list shows all macros of the package in alphabetical order.

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

  • 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.

  • appendix():
    Start appendices

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

  • bind(text):
    Issue binding char after text.

  • 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 books or reports.

  • lchapter(label)(title):
    Starts a new chapter in books or reports, setting a label at the beginning of the chapter.

  • cite(1):
    Citation

  • clearpage():
    Starts a new page, when the output format permits. Under HTML a horizontal line is drawn.

  • setlatexverbchar(char):
    Set the char used to quote latex() \verb sequences

  • setrofftableoptions(optionlist):
    Set the options for tbl table, default: allbox

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

  • 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().

  • ellipsis():
    Set ellipsis.

  • 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.

  • nemail(name)(address):
    Named email (duh). A more consistent naming for url, lurl, email an nemail would be nice.

  • 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().

  • endmenu():
    DEPRECATED Ends a menu that is started with startmenu().

  • 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.

  • file(text):
    Sets text as filename, usually boldface.

  • 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.

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

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

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

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

  • 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().

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

  • gettocstring():
    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().

  • 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.

  • includeverbatim(file):
    Include file into the output. No processing is done, file should be in preformatted form, e.g.:
    whenhtml(includeverbatim(foo.html))
    
    .

  • cindex():
    Generate an index entry for index c.

  • findex():
    Generate an index entry for index f.

  • kindex():
    Generate an index entry for index k.

  • pindex():
    Generate an index entry for index p.

  • tindex():
    Generate an index entry for index t.

  • vindex():
    Generate an index entry for index v.

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

  • mit():
    DEPRECATED Indicates an item in a menu. The menu is surrounded by startmenu() and endmenu().

  • 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.

  • LaTeX():
    The LaTeX symbol.

  • latexcommand(cmd):
    Writes cmd to the output when converting to LaTeX. The cmd is not further expanded by YODL.

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

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

  • latexoptions(options):
    Set latex options: documentclass[options]. Junk this? 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 \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.

  • langle():
    Char langle

  • rangle():
    Char rangle

  • 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.

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

  • 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 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.

  • 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.

  • makeindex():
    Make index for latex (urg).

  • mbox():
    Inbreakable box. The roff command, anyone?

  • menu(list):
    DEPRICATED Sets list as a menu.

  • metaCOMMENT(text):
    Put a comment in the output.

  • metalC(text):
    Put a line comment in the output. FIXME: howto check if text has line breaks?

  • 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.

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

  • nodename(text):
    Use text as name for the next node, e.g.
    nodename(Options)manpagesynopsis()
    
    Currently used in texinfo descriptions only.

  • nodeprefix(text):
    Prepend text to node names, e.g.
    nodeprefix(LilyPond) sect(Overview)
    
    Currently used in texinfo descriptions only.

  • nodetext(text):
    Use text as description for the next node, e.g.
    nodetext(The GNU Music Typesetter)chapter(LilyPond)
    
    Currently used in texinfo descriptions only.

  • nop(text):
    Expand to text, to avoid spaces before macros e.g.: a2.

  • 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.)

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

  • 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.

  • nsubsubsubsect(title):
    Starts a non-numbered sub-sub-subsection.

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

  • 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.

  • printindex():
    Make index for texinfo (urg).

  • 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 ARGx in the redefinition part to indicate where the arguments should be pasted. E.g., ARG1 places the first argument, ARG2 the second argument, etc..

  • 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.

  • sc(text):
    Set text in small caps (or tt).

  • sect(title):
    Starts a new section.

  • lsect(label)(title):
    Starts a new section, setting a label at the beginning of the section.

  • setaffilstring(name):
    Defines name as the `affiliation information' string, by default AFFILIATION INFORMATION. E.g., after setaffilstring(AFILIAÇÃO), YODL outputs this portuguese string to describe the affiliation information. Currently, it is relevant only for txt.

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

  • 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.

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

  • 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.

  • setlanguage(language):
    Sets the language to language. Currentley supported languages english and portuguese.

  • 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.

  • settitlestring(name):
    Defines name as the `title information' string, by default TITLE INFORMATION. E.g., after settitlestring(TÍTULO), YODL outputs this portuguese string to describe the title information. Currently, it is relevant only for txt.

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

  • 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.

  • startmenu():
    DEPRECATED Starts a menu. Use mit() in the menu to indicate menu items, and use endmenu() to end the menu.

  • sups(text):
    Set superscript...

  • subs(text):
    Set subscript

  • subsect(title):
    Starts a new subsection. Other sectioning commands are subsubsect and subsubsubsect.

  • lsubsect(label)(title):
    Starts a new subsection. Other sectioning commands are subsubsect and subsubsubsect. A label is added just before the subsection.

  • subsubsect(title):
    Starts a sub-subsection.

  • lsubsubsect(label)(title):
    Starts a sub-subsection, a label is added just before the section

  • subsubsubsect(title):
    Starts a sub-sub-sub-subsection. This level of sectioning is not numbered, in contrast to `higher' sectionings.

  • lsubsubsubsect(label)(title):
    Starts a sub-sub-sub-subsection. This level of sectioning is not numbered, in contrast to `higher' sectionings. A label is added just before the subsubsubection.

  • texinfocommand(cmd):
    Writes cmd to the output when converting to Texinfo. The cmd is not further expanded by YODL.

  • TeX():
    The TeX symbol.

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

  • 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.

  • lurl(locator):
    An url described by its Locator. For small urls with readable addresses.

  • 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.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.

  • verbpipe(command)(text):
    Pipe text through command, but don't expand the output.

  • 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.

  • whentexinfo(text):
    Sends text to the output when in Texinfo 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.

  • starttable(nColumns)(LaTexAllignment):
    The arguments are the number of columns in the table, and the alignment specifications for LaTeX, which should consist of nColumns characters (l, r, or c). It is used internally by table()

  • endtable():
    This macro ends the definition of a table. It is used internally by table()

  • table(nColumns)(LaTeXallignment)(Contents):
    The table()-macro defines a table. Its first argument specifies the number of columns in the table. Its second argument specifies the LaTeX-alignment specifications: use l for left-alignment, r for right alignment, c for centered-alignment. The third argument defines the contents of the table which are the rows, each containing column-specifications.

  • row(Cells):
    The argument Cells contains the cells of one row of the table

  • cell(element):
    Set a table cell, i.e., one element in a row.

  • tcell(text):
    Roff helper to set a table textcell, i.e., a paragraph. For LaTeX special table formatting p{} should be used.

  • cells(nColumns)(element):
    Set a table cell centered over nColumns columns. See also leftcells() and rightcells().

  • columnline(from)(to):
    Sets a horizontal line over a column in a row. See also rowline().

  • rowline():
    Sets a horizontal line over the width of the table. See also cellsline().

  • 3.5: General structure of a Yodl document

    This section describes the general format of a Yodl document.

    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., 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.

    Following the modifiers, you need to define the document type. This type is either article, report, book, plainhtml or manpage. Except for the manpage document type, which is described in section 3.3, the following rules apply:

    You should decide on the document type by counting the top-level sectioning commands that you need. E.g., if you write an 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..

    The document type also affects the way Yodl formats the output. An 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 reports 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.

    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 doc/yodl.yo that is distributed with the Yodl package. This is the main file of this manual and follows the syntax described herein.

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

  • If you put text before the preamble, i.e., before stating the document type, chances are that Yodl will happily translate the file, but that the following stages will fail. E.g., the <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.

  • If you put modifiers, such as 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.

    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: 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.

    3.6.1.1: Direct commands to LaTeX

    To send LaTeX commands directly to the output, use the 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.

    The following two code fragments both output \pagestyle{plain} when in LaTeX mode:

    COMMENT(-- First alternative: --)
    latexcommand(\pagestyle{plain})
    
    COMMENT(-- Second alternative: --)
    IFDEF(latex)\ 
        (NOTRANS(\pagestyle{plain}))\ 
        ()
    

    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 verb macro and is meant for longer listings (whole files); as in:

    verb(\ 
    #include <stdio.h>
    
    int main (int argc, char **argv)
    {
        printf ("Hello World!\n");
        return (0);
    })
    

    The 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.

    The tt macro

    The second way to put verbatim text in LaTeX is the 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.

    3.6.2.1: Direct commands to HTML

    Similar to the LaTeX converter, you can use either 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.

    Furthermore, the HTML converter defines the macro 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>.

    E.g., the following code sends a HTML command <hr> to the output file when in HTML mode:

    COMMENT(-- alternative 1, using htmlcommand --)
    htmlcommand(<hr>)
    
    COMMENT(-- alternative 2, using NOTRANS --)
    IFDEF(html)\ 
        (NOTRANS(<hr>))\ 
        ()
    
    COMMENT(-- alternative 3, using CHAR --)
    IFDEF(html)\ 
        (CHAR(<)hrCHAR(>))\ 
        ()
        
    COMMENT(-- alternative 4, using htmltag --)
    htmltag(hr)(1)
    

    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 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.

    3.6.2.4: The yodl2html-post postprocessor

    The HTML converter necessarily uses a post-processor, which re-parses the output of the 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.

    The post-processor is a program 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.

    The usage of the post-processor has one important drawback. The yodl program sec places tags for the post-processor in its output. The post-processor takes actions according to the tags.

    The tags start with .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.

    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 \&.. 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().

    3.6.3.1: The groff postprocessors

    The post-processors for 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.

    The labels and references are resolved via a post-processor which is similar to the HTML postprocessor: the .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..

    An in-depth description of the post-processor would be beyond this document. The post-processor is a C program 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.

    For these reasons, the SGML converter only supports the article document type. Therefore, the top-level sectioning command can only be sect.

    The SGML converter adds two macros to the set: 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.

    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 yodl2txt-post and replaced by one empty line each.

    For example, you should format your sections in the following way to make sure that the titles start at the leftmost column:

    chapter(Some chapter)
    
    Text of the chapter. Text of the
    chapter. Text of the chapter. Text 
    of the chapter. Text of the chapter.
    Text of the chapter. 
    
    sect(A section within the chapter)
    
    Text of the section. Text of the 
    section. Text of the section. Text of 
    the section. Text of the section.
    
    sect(A second section)
    
    More text.
    

    This ensures that the chapter and section titles appear `left-flushed'. Optionally you might want to try the following layout:

    chapter(Some chapter)
    
        Text of the chapter. Text of the
        chapter. Text of the chapter. Text
        of the chapter. Text of the 
        chapter. Text of the chapter.
    
        sect(A section within the chapter)
    
            Text of the section. Text of
    	the section. Text of the section.
    
        sect(A second section)
        
            More text.
    

    Similarly, you should choose a `good-looking' way to format your lists, as in:

    Text before an itemized list.
    
    itemize(
    
        it() Some item. Some item. Some
        item. Some item. Some item.
    
        it() Another item. Another item.
        Another item. Another item. Another 
        item. 
        
    )
    
    Text following the list.
    

    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 man and a ms output format, you're probably better off using that.




    Go back to index of Yodl.

    Please send Yodl questions and comments to yodl@icce.rug.nl.

    Please send comments on these web pages to (address unknown)

    Copyright (c) 1997, 1998, 1999 Karel Kubat and Jan Nieuwenhuizen.

    Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.


    This page was built from Yodl-1.31.18 by

    <(address unknown)>, Fri Sep 17 13:36:43 2004 EDT.