yodlconverters(1)

NAME
yodl2... - miscellaneous Yodl converters

SYNOPSIS

yodl2... [-DNAME] [-IDIR] [-oFILE] [-PCMD] [-pPASS] [-t] [-v] [-w] [-h] [-?] inputfile[.yo]

DESCRIPTION

This manual page describes the various shell scripts that convert documents in the Yodl language to other formats. The basic converters are:

yodl2html:
    converts to HTML, writes a file with the extension .html.

yodl2man:
    converts to nroff `man' format, writes .man. Can be further processed with e.g. nroff -Tascii -man file.man.

yodl2ms:
    converts to nroff `ms' format, writes .ms. Can be further processed with e.g. nroff -Tformat -mgs file.ms; format being e.g., ascii or ps.

yodl2sgml:
    converts to SGML, writes .sgml. Implemented for backward compatibility at our site, producing output for our `hacked Linuxdoc-SGML mutant'.

yodl2tex:
    converts to LaTeX output, writes .tex. Can be further processed with, e.g., latex file.tex and xdvi file.dvi. This is the most complete Yodl converter.

yodl2txt:
    converts to plain ASCII, writes .txt. This is a very rudimentary converter, a last-resort.

The following second-stage converters are also implemented:

yodl2dvi:
    runs yodl2tex, and LaTeX-es the output file. When appropriate, re-runs LaTeX to solve labels; the LaTeX job is run up to three times.

yodl2manless:
    runs yodl2man, and nroff's the output, piping into a `less'-like pager.

yodl2msless:
    runs yodl2ms, and nroff's the output into a `less'-like pager.

Appropriate converters for given output formats, with examples, are:

For plain ASCII output:
    For manual pages: yodl2manless file >outfile,
    or gzipped: yodl2manless file | gzip -c >outfile.gz.
    For other document types: yodl2msless file >outfile.
    Optionally, you can pipe the yodl2..less output through striproff to strip ASCII control characters such as underline or boldface.

For LaTeX and .dvi output:
    yodl2tex file to write file.tex, or
    yodl2dvi file to write file.tex and file.dvi.

For PostScript output:
    yodl2msps file, or
    yodl2dvi file followed by dvips -ofile.ps file.dvi.)

OPTIONS

The options are identical to those of the yodl program, which is the first-phase converter. Options may be:

-DNAME
    Defines symbol NAME. In the document IFDEF clauses can be used to test for the definition.

-IDIR
    Overrules the standard include directory (default /usr/local/lib/yodl) with DIR. It's not very wise to use this option, since the converters must be able to access their macro files in /usr/local/lib/yodl.

-oFILE
    Specifies FILE as the output file (default is stdout). This option is auto-supplied by the converters to generate an output file with an appropriate extension; so, don't use it.

-PCMD
    `Preloads' command CMD, as if CMD was the first line of the input. An example is -PSUBST(VERSION)(0.12b)' to substitute 0.12b for each occurrence of VERSION in the input.

-pPASS
    Defines PASS as the maximum number of `passes'; when this number is exceeded, yodl aborts.

-t  Enables tracing mode. Useful for debugging.

-v  Raises the verbosity mode. Useful for debugging.

-w  Enables warning. When enabled, yodl will warn when it sees inconsistencies. This option already gets enabled by default when the yodl2... scripts are used.

-h, -?
    Shows usage information.

inputfile
    File to process, yodl supplies an extension .yo if necessary. Depending on the output format, the converters write a file with the same basename but with a corresponding extension.

FILES

Each yodl2format converter requires a file format.yo in the standard include directory /usr/local/lib/yodl. This file is auto-loaded to make the conversion to format possible.

Each format.yo file in the standard include directory expects other files; e.g., shared.yo, aux-macros.yo.

The output then goes to a file with an extension .format.

Some converters require post-processors, which are located in the standard include directory and named yodl2format-post.

SEE ALSO

o   yodl(1): the first step converter.

o   yodlmacros(7): short description of the macros of the converters.

o   yodlmanpage(1): description of the manpage document type.

o   striproff(1): description of the striproff program.

DIAGNOSTICS

Warnings and errors are too many to enumerate, but all errors are printed to stderr after which the converters exit with a non-zero status.

BUGS

There may be bugs in the yodl program, but that's not very likely. More likely you'll encounter bugs or omissions in the macro package itself.

AUTHOR

Karel Kubat (karel@icce.rug.nl)