<html>
<head>
<title> Yodl 3.00.0 </title>
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<ul>
<li> <a href="yodl.html">Table of Contents</a>
<li> <a href="yodl02.html">Next Chapter</a>
</ul>
<hr>
<a name="l1"></a>
<h1>Chapter 1: Introduction</h1>
<code>Yodl</code> stands for `Your Own Document Language' (originally: <code>Yet Oneother
Document Language</code>) and is basically a
pre-processor to convert document files in a special macro language (the <code>Yodl</code>
language) to any output format. The <code>Yodl</code> language is not a `final' language,
in the sense that it can be viewed or printed directly. Rather, a document in
the <code>Yodl</code> language is a `pre-document', that is converted with some macro
package to an output format, to be further processed.
<p>
<code>Yodl</code> was designed in 1996 by Karel Kubat when he needed a good document
preprocessor to convert output to either LaTeX (for printing) or to
HTML for publishing
via a WWW site. Although SGML does this too, he wanted something that is used
`intuitively' and with greater ease. This is reflected in the syntax of the
<code>Yodl</code> language, in the available macros of the <code>Yodl</code> macro package, and very
probably also in other aspects of <code>Yodl</code>. However, <code>Yodl</code> is designed to convert
to <em>any</em> output format; so it is possible to write a macro package that
converts <code>Yodl</code> documents to, say, the <code>man</code> format for manual pages.
<p>
Some highlights of <code>Yodl</code>:
<ul>
<li> <code>Yodl</code> allows the inclusion of files. This makes it easier to split up
a document into `logical' parts, each kept in a separate file. Thus, a `main
document' file can include all the sub-parts. (Imagine that you're the editor
of a journal. Authors are likely to send in their submissions in separate
files; inclusion can then be very handy!)
<li> Files which are included are searched for either `as-is', or in a
given `system-wide include' directory, similar to the workings of the <strong>C</strong>
preprocessor. Therefore, it is possible to create a set of include files
holding macros, and to place them into one macro directory. (See also chapter
<a href="yodl04.html#MACROPACKAGE">4</a>, where a macro package that is distributed with <code>Yodl</code> is
described.)
<li> For all the handled files (either stated on the commandline or
included), <code>Yodl</code> supplies an extension if none is present. The default
extension is <code>.yo</code>, but can be defined to anything in the compilation of the
<code>Yodl</code> program.
<li> <code>Yodl</code> supports conditional parsing of its input, controlled by defined
symbols. This resembles the <code>#ifdef</code> / <code>#else</code> / <code>#endif</code> preprocessor
macros of the <strong>C</strong> language. <code>Yodl</code> also supports other <code>if</code> clauses, e.g.,
to test for the presence of an argument to a macro.
<li> <code>Yodl</code> offers hooks to define counters, to modify them, and to use them
in a document. Thereby <code>Yodl</code> offers the possibility for automatic numbering of
e.g., sections. Of course, some document languages (e.g., LaTeX) offer this
too; but some don't. When converting a <code>Yodl</code> document to, say, HTML, this
feature is very handy.
<li> <code>Yodl</code> is designed to be easy to use: <code>Yodl</code> uses `normal' characters to
identify commands in the text, instead of insisting weird-looking tags or
escape characters. Editing a document in the <code>Yodl</code> macro language is designed
to be as easy as possible.
<li> Similar to other document languages, <code>Yodl</code> supports `character
conversion tables' which define how a character should appear in the output.
</ul>
This document first describes <code>Yodl</code> from the point of the user: how can
macros be defined, how is the program used etc.. Next, my own macro package is
presented and the macros therein described. Finally, this document holds
technical information about the installation and the inner workings of <code>Yodl</code>.
<p>
<a name="l2"></a>
<h2>1.1: From 1.xx to 2.00: what's new?</h2>
Compared to earlier versions, <code>Yodl</code> Version 2.00 is a complete rebuilt, and
offers many new features.
<p>
<ul>
<li> Changed Yodl's name expansion. From `Yet Oneother Document Language'
to:
<center><strong>Your Own Document Language</strong></center>
<li> The following commands are now obsolete and should/must be
avoided. Alternatives are always offered.
<dl>
<p><dt><strong>ENDDEF</strong><dd> DECWSLEVEL should be used;
<p><dt><strong>INCLUDELIT</strong><dd> NOEXPANDINCLUDE should be used;
<p><dt><strong>NEWCOUNTER</strong><dd> DEFINECOUNTER should be used;
<p><dt><strong>STARTDEF</strong><dd> INCWSLEVEL should be used;
<p><dt><strong>UNDEFINEMACRO</strong><dd> DELETEMACRO should be used;
<p><dt><strong>WRITEOUT</strong><dd> FPUTS should be used;
</dl>
<li> Several new commands were implemented:
<dl>
<p><dt><strong>ADDTOSYMBOL</strong><dd> adds text to a symbol's value;
<p><dt><strong>DEFINESYMBOLVALUE</strong><dd> defines a symbol and its initial value;
<p><dt><strong>DELETECOUNTER</strong><dd> opposite from NEWCOUNTER: removes an existing
counter;
<p><dt><strong>IFBUILTIN</strong><dd> checks whether the argument is a builtin macro;
<p><dt><strong>IFCOUNTER</strong><dd> checks whether the argument is a defined counter;
<p><dt><strong>IFEQUAL</strong><dd> checks whether two numerical values are equal;
<p><dt><strong>IFGREATER</strong><dd> checks whether the first numerical value exceeds the
second numerical value;
<p><dt><strong>IFMACRO</strong><dd> checks whether the argument is a defined macro;
<p><dt><strong>IFSMALLER</strong><dd> checks whether the first numerical value is smaller
than the second numerical value;
<p><dt><strong>IFSYMBOL</strong><dd> checks whether the argument is a defined symbol;
<p><dt><strong>PATHINCLUDELIT</strong><dd> includes literaly a file found in the
XXincludepath path;
<p><dt><strong>POPCOUNTER</strong><dd> pops a previously pushed countervalue;
<p><dt><strong>POPMACRO</strong><dd> pops a previously pushed macrodefinition;
<p><dt><strong>POPSYMBOL</strong><dd> pops a previously pushed symbolvalue;
<p><dt><strong>PUSHCOUNTER</strong><dd> pushes the current value of a counter, initilaizes
the active counter to 0;
<p><dt><strong>PUSHCOUNTERVALUE</strong><dd> pushes the current value of a counter,
initilaizes the active counter to any value;
<p><dt><strong>PUSHMACRO</strong><dd> pushes the current definition of a macro, activates a
local redefinition;
<p><dt><strong>PUSHSYMBOL</strong><dd> pushes the current value of a symbol, initializing the
active value to an empty string;
<p><dt><strong>SETSYMBOL</strong><dd> assigns a new value to a symbol;
<p><dt><strong>SYMBOLVALUE</strong><dd> returns the value of a symbol as text.
</dl>
<li> Several macros were deprecated. Alternatives are suggested in the
`man yodlmacros' manpage:
<ul>
<li> <code>enddit()</code>;
<li> <code>endeit()</code>;
<li> <code>endit()</code>;
<li> <code>endmenu()</code>;
<li> <code>endtable()</code>;
<li> <code>enumerate(list)</code>;
<li> <code>itemize(list)</code>;
<li> <code>menu(list)</code>;
<li> <code>mit()</code>;
<li> <code>node(previous)(this)(next)(up)</code>;
<li> <code>startcenter()</code>;
<li> <code>startdit()</code>;
<li> <code>starteit()</code>;
<li> <code>startit()</code>;
<li> <code>startmenu()</code>;
<li> <code>starttable(nColumns)(LaTexAllignment)</code>;
</ul>
<li> <code>XXincludePath</code>: Symbol installed by Yodl itself, but modifiable by
the user: It holds the value of the current :-separated list of
directories that are visited (sequentially) by the INCLUDEFILE
command. <code>XXincludePath</code> may contain <code>$HOME</code>, which will be
replaced by the user's home directory if the `home' or `HOME'
environment variable is defined. It may also contain
t($STD_INCLUDE), which will be replaced by the compilation defined
standard include path. The standard includepath may be overruled
by either (in that order) the command line switch -I or the
<code>tt(Yodl)_INCLUDE_PATH</code> environment variable. By default, the
current directory is added to the standard include path. When -I
or <code>tt(Yodl)_INCLUDE_PATH</code> is used, the current directory must be
mentioned explicitly. The individual directories need not be
terminated by a /-character. In the distributed .deb archive, the
standard directory is defined as the current working directory and
<code>/usr/share/yodl</code>, in that order.
<li> Initial blank lines in the generated document are suppressed by
default.
<li> Command line argument -D also allows the assignment of an initial
value to a symbol
<li> Command line argument -P is now -p, the previously defined -p
argument is now -n (--max-nested-files), defining the maximum
number of nested files yodl will process.
<li> Command line argument -r (--max-replacements) defines the maximum
number of macro and/or subst replacements accepted between
consecutive characters read from <strong>s</strong>.
<li> All assignents to counters (SETCOUNTER, ADDTOCOUNTER, etc.) not only
accept numerical arguments, but also counter names.
<li> Rewrote several awkwardly coded macros, using the new SYMBOL and
COUNTER facilities
<li> Added experimental, very limited, xml support to help me generating
xml for the horrible `webplatform' of the university of
Groningen. But at least Yodl now offers xml support as well.
<li> The default extension for figures in the HTML and XML conversions is
now <code>.jpg</code> rather than <code>.gif</code>. The <code>sethtmlfigureext()</code>
macro can be used the change the default figure extension.
<li> There is no limit to the number of conversion-options that can be
specified: macros like <code>htmlbodyopt()</code> and <code>latexoption()</code> can
be specified as often as required resulting in one concatenated
specification.
<li> Upgraded most of the documentation.
<li> Separated yodl-macro files for the various formats. While this might
not strictly be necessary, I feel this is better than using big
fat generic macro definition files which are bloated with
`, ' macros. I introduced a generic frame,
mentioning the macros that must at least be defined by the
individual formats.
<li> Internally, the software was VASTLY reorganized. I feel that
generally programs written in <strong>C</strong> don't benefit from approaches
that have become quite natural for C++ programmers. I had the
choice to either rewrite Yodl to a C++ program or to reprogram
Yodl in the line of C++, but still using C. I opted for the
latter. So, now the src section contains `object-like'
function families, like `countermap_...()' handling all
counte-related operations, `textvector_...()', handling all
text-vector like operations, and other. Other functions reveived
minor modifications. E.g., xrealloc() now requires you to specify
both the number of elements and the size of the elements. By doing
so, it is sheer impossible to overlook the fact that you have to
specify the size of the elements, thus preventing the allocation
of chars when, e.g., ints are required.
<li> An old inconvenience was removed: line number counting is now using
natural numbers, starting at 1, rather than line indices, starting
at 0.
<li> My old <code>@icce.rug.nl</code> e-mail address has been changed into my
current e-mail address:
<center>"Frank B. Brokken" <f.b.brokken@rug.nl></center>
<li> The post processing is now performed by the program `yodlpost'. This
program again used Design Patterns originally developed for object
oriented contexts, resulting in an program that is easy to
maintain. modify and expand.
<li> The post-processor doesn't use <code>.tt(Yodl)TAGSTART.</code> and <code>.YODTAGEND.</code>
anymore.
<li> The basic conversion formats now supported are html, latex, man, and
text. Xml support is experimental, other formats are no longer
supported, mainly because my personal unfamiliarity with the format
(texinfo), or because the format appears to be somewhat obsolete
(sgml).
<li> Added a Yodl document type `letter', indended to be used with the
`brief.cls' LaTeX documentclass
<li> Yodl 2.00 converts documents <em>much</em> faster than earlier versions.
</ul>
<p>
<a name="l3"></a>
<h2>1.2: Why use Yodl?</h2>
Yodl is not a word processor, not even an editor. At first glance you might
say, yeah, why should I learn Your Own Document Language? The answer is
exactly that: because it can be <em>Your</em> own document language!
<p>
First of all, Yodl may lower the threshold of new users to start writing
documents. An example of an excellent, though not very user-friendly document
language is LaTeX. Typing all the backslash and curly brace characters in
LaTeX and remembering that an asterisk must be typed as <code>$*$</code> may be hard
at first. In such situations, a properly configured Yodl macro set removes
these obstacles and thereby helps novices. Yodl is designed to be easy to
learn. As the Yodl package is growing, so is the manual. The ease of
`learning Yodl' may thus somewhat diminish, but just keep in mind: as long as
you need just plain texts, Yodl does OK. If you want more functionality, e.g.,
the composition of manual pages for Unix, dig into the documentation.
<p>
Second, Yodl permits to create more than one macro set, defining the same
commands, but leading to different output actions. Thereby, the same input
file can be converted to several output formats, depending on the loaded macro
set. In this, Yodl is a `general front' document language, which converts a
Yodl document to a specialized language for further processing. This was of
course one of my reasons to write Yodl: I needed a good converter for either
LaTeX or HTML.
<p>
Third, Yodl always allows an `escape route' to the output format. Most
situations can be handled with Yodl macros, but sure enough, some users will
want special actions for a given output format. A typical example for the
necessity of such an escape route is the typesetting of mathematical formulas.
Say you want to use Yodl for a document that is converted either to LaTeX
(being a very good mathematical typesetter) or to HTML (a very poor
mathematical typesetter). An approach might be to decide <em>inside the
document</em> how to typeset a mathematical formula. Yodl provides conditional
command processing to accomplish this. The decision would be based on the
output format: for LaTeX, you'd typeset the formula using all the facilities
that LaTeX offers, and for HTML you'd use poor-mans typesetting. Typically,
other pre-processors for documents don't allow such escape routes. Well, Yodl
does.
<p>
<a name="l4"></a>
<h2>1.3: Copying Yodl</h2>
Yodl is free software; it is distributed under the terms of the
GNU General Public Licence. For details, please refer to the file
COPYING.
<p>
The original author and brainfather of Yodl <a href="mailto:karel@e-tunity.nl"><em>Karel Kubat</em></a> would very much like to to hear from you,
if you use Yodl in a commercial setting (beats me why).
<p>
Also, he likes to receive postcards, preferably from far-away places
(i take it that's from outside, or near the edges of, Europe).
<p>
His snailmail address:
<p>
<blockquote>Karel Kubat <br>
... <br>
Zwolle <br>
The Netherlands</blockquote>
<p>
<hr>
<ul>
<li> <a href="yodl.html">Table of Contents</a>
<li> <a href="yodl02.html">Next Chapter</a>
</ul>
<hr>
</body>
</html>
distrib
>
Mageia
>
4
>
i586
>
media
>
core-release
>
by-pkgid
>
f9a3dabf4d0709484a9d2134094ee2a2
>
files
>
8
