.TH "yodl" "1" "1996\-2017" "yodl_4\&.01\&.00\&.tar\&.gz" "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 \fBNOTE:\fP Starting with Yodl version 3\&.00\&.0 Yodl\(cq\&s default file inclusion behavior has changed\&. The current working directory no longer remains fixed at the directory in which Yodl is called, but is volatile, changing to the directory in which a yodl\-file is located\&. This has the advantage that Yodl\(cq\&s file inclusion behavior now matches the way \fBC\fP\(cq\&s \f(CW#include\fP directive operates; it has the disadvantage that it may break some current documents\&. Conversion, however is simple but can be avoided altogether if the \f(CW\-L\fP (\f(CW\-\-legacy\-include\fP) option is used (see below)\&. .PP .SH "OPTIONS" .PP .IP o \f(CW\-D, \-\-define=NAME[=VALUE]\fP: Defines \fIname\fP as a symbol\&. This option is acts like \f(CWDEFINESYMBOL(NAME)()\fP\&. If \f(CW=VALUE\fP is added, \f(CWNAME\fP is initialized to \f(CWVALUE\fP (identically to \f(CWDEFINESYMBOL(NAME)(VALUE)\fP)\&. .IP o \f(CW\-d, \-\-definemacro=NAME=EXPANSION\fP: Defines \f(CWNAME\fP as macro expanding to \f(CWEXPANSION\fP .IP o \f(CW\-h, \-\-help\fP: usage information is written to the standard error stream, describing all of Yodl\(cq\&s options\&. .IP o \f(CW\-i, \-\-index[=file]\fP: `file\(cq\& is the name of the index file\&. By default \f(CW\&.idx\fP is used\&. No default when output is written to stdout\&. The index file is processed by Yodl\(cq\&s post\-processor, \f(CWyodlpost\fP\&. .IP o \f(CW\-I, \-\-include=DIR\fP: 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 \f(CWlatex\fP 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 (\f(CWlatex\fP in the above example) is the bare name, YODL supplies a default extension (\f(CW\&.yo\fP), if necessary\&. .IP The \f(CW\-I\fP 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\&., \f(CW/usr/share/yodl\fP\&. 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 \f(CW\-I\fP or the \f(CWYODL_INCLUDE_PATH\fP environment variable\&. By default, the current directory is added to the standard include path\&. Hewver, when \f(CW\-I\fP or \f(CWYODL_INCLUDE_PATH\fP is used, the current directory must be mentioned explicitly\&. The individual directories need not be terminated by a /\-character\&. In distributed \f(CW\&.deb\fP archives, the standard directory is defined as \f(CW/usr/share/yodl\fP (prefixed by the current working directory)\&. .IP o \f(CW\-k, \-\-keep\-ws\fP: 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 \f(CW\-k\fP flag\&. Note that white space are always kept when using verbatim copying, and when the white\-space level is zero\&. .IP o \f(CW\-m, \-\-messages=SET\fP: Set the so\-called `message level\(cq\& to a combination of the SET \f(CWacdeinw\fP\&. The letters of this set have the following meanings: .IP o \f(CWa\fP: alert\&. When an alert\-error occurs, Yodl terminates\&. Here Yodl requests something of the system (like a \f(CWget_cwd()\fP), but the system fails\&. .IP o \f(CWc\fP: 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 parameter list should appear, or a non\-existing file in an \f(CWINCLUDEFILE\fP specification (as this file should be parsed)\&. A non\-existing file with a \f(CWNOEXPANDINCLUDE\fP specification is a plain (non\-critical) error\&. .IP o \f(CWd\fP: debug\&. Probably too much info, like getting information about each character that was read by Yodl\&. .IP o \f(CWe\fP: 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 \f(CWi\fP: info\&. Not as detailed as `debug\(cq\&, but still very much info, like information about media switches\&. .IP o \f(CWn\fP: notice\&. Information about, e\&.g\&., calls to the builtin function calls\&. .IP o \f(CWw\fP: 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 \f(CW\-n, \-\-max\-nested\-files=NR\fP: This option causes Yodl to abort when the number of nested input files exceeds \f(CWNR\fP, which is 20 by default\&. Exceeding this number usually means a circular definition somewhere in the document\&. This is the case when, a file \f(CWa\&.yo\fP includes \f(CWb\&.yo\fP, while \f(CWb\&.yo\fP includes \f(CWa\&.yo\fP etc\&.\&. It does not prevent recursive macro\- or subst\-replacements\&. For that the \f(CW\-r\fP (\f(CW\-\-max\-replacements\fP) option is available\&. .IP o \f(CW\-o, \-\-output=FILE\fP: This option causes Yodl to write its output to \f(CWFILE\fP\&. By default, the output goes to the standard output stream\&. E\&.g\&., you can use YODL to read a file \f(CWinput\fP and to write to \f(CWoutput\fP 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 \f(CW\-\-index\fP option is specified\&. .IP o \f(CW\-p, \-\-preload=CMD\fP: This option `pre\-loads\(cq\& the string \f(CWcmd\fP\&. It acts as though \f(CWcmd\fP was the first command in the first input file that is processed by YODL\&. .IP More than one \f(CW\-\-preload=CMD\fP options may be present on the command line\&. Each of the commands is then processed in turn, before reading any file\&. .IP o \f(CW\-r, \-\-max\-replacements=NR\fP: This option causes Yodl to abort when the number of macro calls or subst\-replacements exceeds \f(CWNR * 10,000\fP\&. By default, \f(CWNR\fP equals 1\&. Setting \f(CW\-\-max\-replacements=0\fP implies that no macro\- or subst\-replacement checks are performed\&. .IP o \f(CW\-t, \-\-trace\fP: This option enables tracing: while parsing, Yodl writes its output to the standard error stream\&. As is the case with the \f(CW\-k\fP option, this option is defined for debugging purposes only\&. .IP o \f(CW\-V, \-\-version\fP\&. This option shows YODL\(cq\&s actual version\&. .IP o \f(CW\-v, \-\-verbose\fP: 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 \f(CW\-\-verbose\fP 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 \f(CWVERBOSITY\fP builtin can be used for that\&. .IP o \f(CW\-W, \-\-warranty\fP\&. This option shows a warranty disclaimer and a copyright notice\&. .IP o \f(CW\-w, \-\-warn\fP: 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 \f(CWtmp/wip/macros\fP\&. The files in this directory are included by the converters \fByodl2txt\fP(1) etc\&.\&. .PP .SH "SEE ALSO" .PP \fByodlstriproff\fP(1), \fByodl\fP(1), \fByodlbuiltins\fP(7), \fByodlconverters\fP(1), \fByodlletter\fP(7), \fByodlmacros\fP(7), \fByodlmanpage\fP(7), \fByodlpost\fP(1), \fByodlverbinsert\fP(1)\&. .PP .SH "BUGS" .PP \- .PP .SH "AUTHOR" .PP Frank B\&. Brokken (f\&.b\&.brokken@rug\&.nl),