Chapter 5: Conversions and convertors

Each macro package handling a conversion from Yodl to a given output format has its pecularities. Although the various macro packages are very similar, they do show some differences, due to the unique characteristics of the output formats. Normally, these differences should not cause difficulties in performing the conversion(s). In this chapter the conversion of a Yodl document is covered. The currently supported document types are discussed. Furthermore, in this chapter the new post processor yodlpost is described as well as a little support program: yodlverbinsert.

5.1: Conversion script invocations

Yodl is distributed with scripts named yodl2latex, yodl2html and other yodl2... drivers. Invocations like

    yodl2latex file
        
causes Yodl to process file.yo and to write output to file.latex. The extension of the input file, .yo, is the default Yodl extension; the extension of the output file, .latex, is given by the name of the shell script. Analogously, yodl2html writes to a file having the extension .html.

The conversion scripts auto-load the macro file appropriate for the conversion: latex.yo for LaTeX conversions, html.yo for HTML conversions, etc.. The macro files are in Yodl's standard include directory (which is mentioned in Yodl's usage information when Yodl is started without arguments). If the include directory is altered in such a way that it doesn't contain a path to the default directory anymore, then Yodl won't be able to auto-load the conversion specific macro files, producing unexpected results. This can be prevented by specifying the literal text $STD_INCLUDE in a user-defined path setting.

When the conversion scripts themselves are started without arguments, usage information is shown about the conversion scripts.

Depending on the conversion type, the following output is produced:

The `second-phase' scripts, distributed with earlier versions of Yodl, are no longer part of Yodl's distribution, as they do not relate directly to Yodl's actions. They may remain useful, though, as leftovers from earlier distributions.

5.2: The HTML converter

HTML doesn't support automatic section numbering or resolving of label/reference pairs. The converter takes care of this. Other target languages (e.g., XML, text) suffer from the same problems.

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

5.2.0.2: Section numbering

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

5.3: The LaTeX converter

The LaTeX converter is, from Yodl's viewpoint, an easy one: since LaTeX supports wide functionality, a Yodl document is basically just re-mapped to LaTeX commands. No post-processing by yodlpost is required.

5.3.0.1: Direct commands to LaTeX

To send LaTeX commands directly to the output, use the latexcommand() macro (see section 4.3.2), or use NOTRANS (see section 3.1.44). 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})
    )()
        

5.3.0.2: Verbatim text

The Yodl macro package defines two macros that generate verbatim text (e.g., source code listings). These macros are verb() and tt().
verb
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() macro will generate \begin{verbatim} and \end{verbatim} when used in LaTeX conversion mode. That means that (in that situation) the verb macro has only one caveat: you cannot put \end{verbatim} into it.
tt
The tt() macro also inserts verbatim text. It is 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.

5.4: The man converter

Manual pages can be constructed using the special yodl2man converter. This converter assumes that the manual page has been designed using the manpage() macro. Yodl (and thus the yodl2man converter, when conerting man-pages, will skip all leading white space on lines. Paragraphs are supported, though. An empty line separates paragraphs.

5.4.0.1: Direct commands to man

Either NOTRANS or mancommand can be used to send man commands to the output.

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

COMMENT(-- alternative 1, using mancommand --)
    mancommand(<hr>)
    
    COMMENT(-- alternative 2, using NOTRANS --)
    IFDEF(man)(
        NOTRANS(<hr>)
    )()
        

5.5: The txt converter

Plain text documents can be constructed using the yodl2txt converter. This converter will resolve all references into the document itself, so postprocessing is required.

5.5.0.1: Direct commands to txt

Either NOTRANS or txtcommand can be used to send txt commands to the output.

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

COMMENT(-- alternative 1, using txtcommand --)
    txtcommand(<hr>)
    
    COMMENT(-- alternative 2, using NOTRANS --)
    IFDEF(txt)(
        NOTRANS(<hr>)
    )()
        

5.6: The experimental XML converter

The XML converter is experimental. It was added to Yodl to allow me to write documents for the horrible `webplatform' of the university of Groningen. The XML support files (located in the xml directory in the standard macro's directory) clearly reflect this target. Although experimental, they were kept because the XML macros support interesting constructions allowing Yodl to handle closing tags somewhat more strict than required for HTML.

5.7: The Yodl Post-processor `yodlpost'

Following the conversion of a Yodl text, most target-languages require an additional operation, called `post-processing'. Post-processing is required for various reasons: to split the output in separate files (HTML, XML); to fixup the locations of labels, that are referred to earlier than the labels are defined (virtually all target language except LaTeX); tables of contents are available only after the conversion, but will have to be inserted at the beginning of the document; etc. etc..

Starting with Yodl V. 2.00 there is only one post-processor, handling all the conversions for all target languages. Program maintenance of just one program is certainly easier than maintenance of as many programs as there are target-languages, at the expense of only a slightly larger program: after all, the one post-processor contains the conversion procedures for all target languages. It turns out that this is a very minimal drawback. See section 6.7 for the technical details of post-processor program maintenance.

The post-processor that is distributed since Yodl V. 2.00 does not use the .tt(Yodl)TAGSTART. and .tt(Yodl)TAGEND. tags anymore. Instead, the conversion process produces a index file in which comparable information is written. The advantage of using an index file is that the postprocessor doesn't have to parse the output file generated by Yodl twice (once to determine the tags, once to process the tags), which by itself accelerates the conversion process; and (albeit of a somewhat limited practical importance) that the tags are no longer reserved words: authors may put .tt(Yodl)TAGSTART. and .tt(Yodl)TAGEND. into their texts as often as they want.

Authors should be aware of some caveats with respect to some target languages:

man- and ms- conversions
all dots are converted by the active character conversion table to \&.. Commands in these languages always start with a dot as the first character on a line. In order to insert these commands the roffcmd() (see section MACROLIST) should be used.
plain text conversions
As stated before, the ASCII converter basically only strips macronames from its input. This converter is so basic, that it should only be used as a last resort, when no other target language is available for the job.
With the plain text converer, the layout of the input file is very important, as the output is basically the same as the input. The only exception to this rule are multiple empty lines, which normally are consumed by the post-processor, to be replaced by one single empty line.
sgml conversions
the SGML converter was implemented for historic reasons. It is by no means complete, and can at best be considered an `initial starting point'. Currently, the SGML converter only supports the article document type, having sect as its top-level sectioning command.
xml conversions
The XML converter was implemented to allow me (Frank) to produce XML text as defined by the so-called `webplatform' of the University of Groningen. A completely pathological implementation of XML, crippling its users to the level of the `double click brigade'. Well, so be it. The net result of this is that Yodl now offers some sort of XML conversion, which will surely require modifications in the near future. Much XML handling is based on frame-files which are literally inserted into the converted text. Hopefully that will be useful when constructing XML conversions for other environments than the `webplatform'.

5.8: The support program `yodlverbinsert'

The program yodlverbinsert is a simple C support program that can be used to generate verb()-sections in Yodl files from sections of existing files. The files from which sections are included are usually C or Cpp source files, accepting either // or /*-style comment.

Yodlverbinsert offers the possibility to indent both the initial verb-statement and the inserted file contents. Furthermore, an additional empty line may be inserted before the first line that is actually inserted. The program is invoked according to the following synopsis:

yodlverbinsert [OPTIONS] marker file

The arguments have the following meanings;

The default values of options are listed below, with each of the options between square brackets. The defaults were chosen so that yodlverbinsert performs the behavior of an earlier version of this program, which was not distributed with Yodl.

Yodlverbinsert writes its selected section to its standard output stream.

5.8.1: Example

Assume the file demo contains the following text:


preceding text

//one
one 1

//=

/*two*/

    two

/**/

trailing text
    

Then the following commands write the shown output to the program's standard output:

To call yodlverbinsert from a Yodl document, use PIPETHROUGH. E.g.,


    PIPETHROUGH(yodlverbinsert //one demo)
        

Alternatively, define a simple macro like the macro verbinsert:


DEFINEMACRO(verbinsert)(2)(PIPETHROUGH(yodlverbinsert //ARG1 ARG2)()\ 
)
    
which may be a useful macro if all or most of your labeled sections start with //, and if yodlverbinsert's arguments don't vary much. Variants to this macro can easily be conceived of.

Note, however, that by default the PIPETHROUGH built-in will not be executed. Be sure to call yodl using the --live-data option, e.g., yodl -l3 ....