yodlpost
is
described as well as a little support program: yodlverbinsert
.
yodl2latex
, yodl2html
and
other yodl2...
drivers. Invocations like
yodl2latex filecauses
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:
.latex
is written.
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..
.man
is
written.
yodl2txt
and one
output file with the extension .txt
is created.
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
.
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.
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)
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.
latexcommand()
macro (see section 4.3.1), or use NOTRANS
(see section
3.1.40). 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}) )()
verb()
and tt()
.
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 generates \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()
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.
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, skips all leading white space on lines. Paragraphs are supported,
though. An empty line separates paragraphs.
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>) )()
yodl2txt
converter.
This converter resolves all references into the document itself, so
postprocessing is required.
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>) )()
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.
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 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:
\&.
. 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.
article
document type, having sect
as its top-level sectioning command.
Yodl
now offers some basic form of XML
conversion. After adding XML conversion, however, there was never any real
situation where it could profitably be used. Therefore, further develpment of
the XML conversion has, for the time being, been suspended.
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:
marker file
The arguments have the following meanings;
marker
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
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
.
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.
spaces
[0]verb
-section with
spaces
additional blanks.
spaces
[8]verb
of the verb
-section by
spaces
additional blanks.
tabs
[0]verb
-section with
tabs
additional tab characters. If both -s
and -t
are specified,
the tabs are inserted first.
tabs
[0]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.
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.