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:

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

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:

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:

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:

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:

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

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.

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:

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:

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:

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:

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.

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:

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:

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.

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:

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.

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:

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)>, Tue Apr 15 19:40:40 2008 MSD.