.TH "yodl" "1" "1996\-2021" "yodl_4\&.03\&.03" "Your Own Document Language" .PP .SH "NAME" yodl \- main Yodl converter .PP .SH "SYNOPSIS" .PP \fByodl\fP [OPTION]\&.\&.\&. [FILE]\&.\&.\&. .PP .SH "DESCRIPTION" .PP Yodl is a package that implements a pre\-document language and tools to process it\&. The idea of Yodl is that you write up a document in a pre\-language, then use the tools (e\&.g\&. \fByodl2html\fP(1)) to convert it to some final document language\&. Current converters are for HTML, man, LaTeX, text and an experimental xml converter\&. Main document types are \(dq\&article\(dq\&, \(dq\&report\(dq\&, \(dq\&book\(dq\& \(dq\&manpage\(dq\& and \(dq\&letter\(dq\&\&. The Yodl document language is designed to be easy to use and extensible\&. .PP .SH "OPTIONS" .PP .IP o `\-D, \-\-define=NAME[=VALUE]\(cq\&: Defines \fIname\fP as a symbol\&. This option is acts like `DEFINESYMBOL(NAME)()\(cq\&\&. If `=VALUE\(cq\& is added, `NAME\(cq\& is initialized to `VALUE\(cq\& (identically to `DEFINESYMBOL(NAME)(VALUE)\(cq\&)\&. .IP o `\-d, \-\-definemacro=NAME=EXPANSION\(cq\&: Defines `NAME\(cq\& as macro expanding to `EXPANSION\(cq\& .IP o `\-h, \-\-help\(cq\&: usage information is written to the standard error stream, describing all of Yodl\(cq\&s options\&. .IP o `\-i, \-\-index[=file]\(cq\&: `file\(cq\& is the name of the index file\&. By default `\&.idx\(cq\& is used\&. No default when output is written to stdout\&. The index file is processed by Yodl\(cq\&s post\-processor, `yodlpost\(cq\&\&. .IP o `\-I, \-\-include=DIR\(cq\&: This defines the system\-wide include directory where YODL searches for its input files\&. E\&.g\&. a statement to include a given file, like: .nf INCLUDEFILE(latex) .fi Yodl now searches for the file `latex\(cq\& in the current directory, and when that fails, in the system\-wide include directory\&. The system\-wide include directory is typically the place where the maintainer of a system stores macro\-files for Yodl\&. This searching process applies to files that are included inside a document but also applies to filenames on the command line when invoking the YODL program\&. .IP The name of the included file (`latex\(cq\& in the above example) is the bare name, YODL supplies a default extension (`\&.yo\(cq\&), if necessary\&. .IP The `\-I\(cq\& option overrules Yodl\(cq\&s built\-in name for the system\-wide include directory\&. The built\-in name is defined when compiling Yodl, and is, e\&.g\&., `/usr/share/yodl\(cq\&\&. Furthermore, the definition may contain $HOME, which is replaced by the user\(cq\&s home directory if the `home\(cq\& or `HOME\(cq\& environment variable is defined\&. It may also contain $STD_INCLUDE, which is replaced by the compilation defined standard include path\&. The standard includepath may be overruled by either (in that order) the command line switch `\-I\(cq\& or the `YODL_INCLUDE_PATH\(cq\& environment variable\&. By default, the current directory is added to the standard include path\&. Hewver, when `\-I\(cq\& or `YODL_INCLUDE_PATH\(cq\& is used, the current directory must be mentioned explicitly\&. The individual directories need not be terminated by a /\-character\&. In distributed `\&.deb\(cq\& archives, the standard directory is defined as `/usr/share/yodl\(cq\& (prefixed by the current working directory)\&. .IP o `\-k, \-\-keep\-ws\(cq\&: Since YODL version 2\&.00 blanks at the begin and end of lines are ignored, even without a trailing \e, when the `white space level\(cq\& is non\-zero\&. Earlier versions kept these blanks\&. The legacy handling of white space at end of lines can by obtained using the `\-k\(cq\& flag\&. Note that white space are always kept when using verbatim copying, and when the white\-space level is zero\&. .IP o `\-m, \-\-messages=SET\(cq\&: Set the so\-called `message level\(cq\& to a combination of the SET `acdeinw\(cq\&\&. The letters of this set have the following meanings: .IP o `a\(cq\&: alert\&. When an alert\-error occurs, Yodl terminates\&. Here Yodl requests something of the system (like a `get_cwd()\(cq\&), but the system fails\&. .IP o `c\(cq\&: critical\&. When a critical error occurs, Yodl terminates\&. The message itself can be suppressed, but exiting can\(cq\&t\&. A critical condition is, e\&.g\&., the omission of an open parenthesis at a location where a parenthesized argument should appear, or a non\-existing file in an `INCLUDEFILE\(cq\& specification (as this file should be parsed)\&. A non\-existing file with a `NOEXPANDINCLUDE\(cq\& specification is a plain (non\-critical) error\&. .IP o `d\(cq\&: debug\&. Probably too much info, like getting information about each character that was read by Yodl\&. .IP o `e\(cq\&: error\&. An error (like doubly defined symbols)\&. Once an error has been encountered the remainder of the input is still parsed (up to a maximum number of errors), but no output is generated\&. .IP o `i\(cq\&: info\&. Not as detailed as `debug\(cq\&, but still very much info, like information about media switches\&. .IP o `n\(cq\&: notice\&. Information about, e\&.g\&., calls to the builtin function calls\&. .IP o `w\(cq\&: warning\&. Something you should know about, but probably not affecting Yodl\(cq\&s proper functioning Non\-configurable is the handling of an \fIemergency\fP message\&. These messages can\(cq\&t be suppressed, but shouldn\(cq\&t happen, as they point to some internal error\&. It would be appreciated to receive information about these messages if they ever occur\&. .IP o `\-n, \-\-max\-nested\-files=NR\(cq\&: This option causes Yodl to abort when the number of nested input files exceeds `NR\(cq\&, which is 20 by default\&. Exceeding this number usually means a circular definition somewhere in the document\&. This is the case when, a file `a\&.yo\(cq\& includes `b\&.yo\(cq\&, while `b\&.yo\(cq\& includes `a\&.yo\(cq\& etc\&.\&. It does not prevent recursive macro\- or subst\-replacements\&. For that the `\-r\(cq\& (`\-\-max\-replacements\(cq\&) option is available\&. .IP o `\-o, \-\-output=FILE\(cq\&: This option causes Yodl to write its output to `FILE\(cq\&\&. By default, the output goes to the standard output stream\&. E\&.g\&., you can use YODL to read a file `input\(cq\& and to write to `output\(cq\& with the following two commands: .nf yodl input > output yodl \-ooutput input .fi The difference being that in the latter case an index file is generated, but not in the former case\&. Notice that writing an index file can be forced when the `\-\-index\(cq\& option is specified\&. .IP o `\-p, \-\-preload=CMD\(cq\&: This option `pre\-loads\(cq\& the string `cmd\(cq\&\&. It acts as though `cmd\(cq\& was the first command in the first input file that is processed by YODL\&. .IP More than one `\-\-preload=CMD\(cq\& options may be present on the command line\&. Each of the commands is then processed in turn, before reading any file\&. .IP o `\-r, \-\-max\-replacements=NR\(cq\&: This option causes Yodl to abort when the number of macro calls or subst\-replacements exceeds `NR * 10,000\(cq\&\&. By default, `NR\(cq\& equals 1\&. Setting `\-\-max\-replacements=0\(cq\& implies that no macro\- or subst\-replacement checks are performed\&. .IP o `\-t, \-\-trace\(cq\&: This option enables tracing: while parsing, Yodl writes its output to the standard error stream\&. As is the case with the `\-k\(cq\& option, this option is defined for debugging purposes only\&. .IP o `\-V, \-\-version\(cq\&\&. This option shows YODL\(cq\&s actual version\&. .IP o `\-v, \-\-verbose\(cq\&: This option increases Yodl\(cq\&s `verbosity level\(cq\& and may occur more than once\&. By default yodl shows alerting, critical, emergency and error messages\&. Each `\-\-verbose\(cq\& option adds a next message level\&. In order, warning, notice, info and debug messages are added to this set\&. It is also possible to suppress messages\&. The `VERBOSITY\(cq\& builtin can be used for that\&. .IP o `\-W, \-\-warranty\(cq\&\&. This option shows a warranty disclaimer and a copyright notice\&. .IP o `\-w, \-\-warn\(cq\&: The presence of this option caused Yodl to warn when, e\&.g\&., symbols are redefined\&. .PP .SH "FILES" .PP The \fByodl\fP program requires no files, but `normal\(cq\& usage of the Yodl package requires macro files, by default installed in `tmp/wip/macros\(cq\&\&. The files in this directory are included by the converters \fByodl2txt\fP(1) etc\&.\&. .PP .SH "SEE ALSO" .PP \fByodlbuiltins\fP(7), \fByodlconverters\fP(1), \fByodlletter\fP(7), \fByodlmacros\fP(7), \fByodlmanpage\fP(7), \fByodlpost\fP(1), \fByodlstriproff\fP(1), \fByodltables\fP(7), \fByodlverbinsert\fP(1)\&. .PP .SH "BUGS" .PP \- .PP .SH "AUTHOR" .PP Frank B\&. Brokken (f\&.b\&.brokken@rug\&.nl),