- Table of Contents
- Previous Chapter
- Next Chapter

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

- For LaTeX conversions, one output file with the extension `.latex` is written.
- For HTML conversions, several files may be written; one file per chapter of the original document. When the document is not sectioned by chapters, only one output file is produced.

  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 man conversions, one output file with the extension `.man` is written.
- For text conversions, the converter is named `yodl2txt` and one output file with the extension `.txt` is created.
- For XML conversions, the converter is named `yodl2xml` and output files are produced comparably to the way they are produced with the `html` conversion: one file per chapter if chapters are used, otherwise one single output file, having the extension(s) `.xml`.

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;

- `marker`
  The argument `marker` must start in `file`'s first column en must either start as a standard C or C++ comment: `//` or `/*` must be used. Following that, the remainder of the argument is used as a label, e.g., `//label`, `/*LABEL*/`. The label may contain non-alpha characters as well. Except for the first two characters and their locations no special restrictions imposed upon the label texts. A labeled section ends at the next `//=` (when the label started with `//`) or at the next `/**/` (when the label started with `/*`). Like the labels, the end-markers must also start in the file's first column.
- `file`
  The argument `file` must be an existing file. `Yodlverbinsert` was designed with C or C++ sources in minde, from which labeled sections must be inserted into a `Yodl` document, but `file` could also refer to another type of (text) file.

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

- -N
  Do not write a newline immediately following `verb`-statement's open-parenthesis. By default it is written, causing an additional line to be inserted before the first line that's actually inserted from a file.
- -s `spaces` [0]
  start each line that is written into the `verb`-section with `spaces` additional blanks.
- -S `spaces` [8]
  prefix the `verb` of the `verb`-section by `spaces` additional blanks.
- -t `tabs` [0]
  start each line that is written into the `verb`-section with `tabs` additional tab characters. If both `-s` and `-t` are specified, the tabs are inserted first.
- -T `tabs` [0]
  prefix the `verb` of the `verb`-section by `tabs` additional tab characters. If both `-S` and `-T` are specified, the tabs are inserted first.

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

- `verbinclude //one demo`

              verb(
      one 1

      )

- `verbinclude -N //one demo`

              verb(one 1

      )

- `verbinclude -s4 '/*two*/' demo`

              verb(

              two

      )

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

- Table of Contents
- Previous Chapter
- Next Chapter