yodl(1)

📦
version 4.05.02 · 6 versions
, in ubuntu resolute, ubuntu stonking

💖 yodl — main Yodl converter 💖

okay bestie, gather round, because this is the main character of the whole Yodl package. This page is yodl(1) from section 1 (general commands) — iykyk 💅

✨ SYNOPSIS ✨

yodl [OPTION]... [FILE]...

🌸 DESCRIPTION 🌸

so like, Yodl is a package that implements a pre-document language plus the tools to process it 🦋 The whole idea? You write your document in a pre-language, and then you use the tools (hi, yodl2html(1) 👋) to convert it into some final document language. The converters we currently ship are for HTML, man, LaTeX, text, and an experimental xml converter ✨

The main document types are "article", "report", "book", "manpage" and "letter". And the Yodl document language is designed to be easy to use and extensible — like, it wants you to thrive 🫶

💅 OPTIONS 💅

  • -D, --define=NAME[=VALUE] — defines name as a symbol. It acts like DEFINESYMBOL(NAME)(). If you add =VALUE, then NAME gets initialized to VALUE (identically to DEFINESYMBOL(NAME)(VALUE)) ✨
  • -d, --definemacro=NAME=EXPANSION — defines NAME as a macro that expands to EXPANSION 🎀
  • -h, --help — usage information gets written to the standard error stream, describing all of Yodl's options. no gatekeeping, we love that 💖
  • -i, --index[=file] — file is the name of the index file. By default <outputbase>.idx is used. There's no default when output is written to stdout. The index file gets processed by Yodl's post-processor, yodlpost 👑
  • -I, --include=DIR — this defines the system-wide include directory where YODL searches for its input files. Like, say you write a statement to include a given file, something like:
INCLUDEFILE(latex)

Yodl now searches for the file latex in the current directory, and when that fails, it looks in the system-wide include directory. That system-wide include directory is typically where the maintainer of a system stores macro-files for Yodl. And this searching process applies to files included inside a document but also to filenames on the command line when you invoke the YODL program 🌈

The name of the included file (latex in the example above) is the bare name — YODL supplies a default extension (.yo) if necessary. 🦋

The -I option overrules Yodl's built-in name for the system-wide include directory. That built-in name is defined when compiling Yodl, and it's, e.g., /usr/share/yodl. On top of that, the definition may contain $HOME, which gets replaced by the user's home directory if the home or HOME environment variable is defined. It may also contain $STD_INCLUDE, which gets 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 YODL_INCLUDE_PATH environment variable. By default, the current directory is added to the standard include path. However, when -I or YODL_INCLUDE_PATH is used, the current directory must be mentioned explicitly 👀 The individual directories need not be terminated by a /-character. In distributed .deb archives, the standard directory is defined as /usr/share/yodl (prefixed by the current working directory). slay, distro packaging 💀

  • -k, --keep-ws — since YODL version 2.00, blanks at the begin and end of lines are ignored, even without a trailing \, when the 'white space level' is non-zero. Earlier versions kept these blanks. The legacy handling of white space at end of lines can be obtained using the -k flag. Note that white space is always kept when using verbatim copying, and when the white-space level is zero 🎀
  • -m, --messages=SET — sets the so-called 'message level' to a combination of the SET acdeinw. The letters of this set have the following meanings:
    • a — alert. When an alert-error occurs, Yodl terminates. This is where Yodl requests something of the system (like a get_cwd()), but the system fails 😭
    • c — critical. When a critical error occurs, Yodl terminates. The message itself can be suppressed, but exiting can't be. 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 specification (since this file should be parsed). A non-existing file with a NOEXPANDINCLUDE specification is a plain (non-critical) error 🫶
    • d — debug. Probably too much info, like getting information about each character that was read by Yodl 💀
    • e — 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 🙈
    • i — info. Not as detailed as debug, but still very much info, like information about media switches 👑
    • n — notice. Information about, e.g., calls to the builtin function calls ✨
    • w — warning. Something you should know about, but probably not affecting Yodl's proper functioning. Non-configurable is the handling of an emergency message. These messages can't be suppressed, but shouldn't happen, as they point to some internal error. It would be appreciated to receive information about these messages if they ever occur 🥺 (yes, they want your bug reports, bestie)
  • -n, --max-nested-files=NR — this option causes Yodl to abort when the number of nested input files exceeds NR, which is 20 by default. Exceeding this number usually means there's a circular definition somewhere in the document. That's the case when a file a.yo includes b.yo, while b.yo includes a.yo, etc. It does not prevent recursive macro- or subst-replacements — for that, the -r (--max-replacements) option is available 🔥
  • -o, --output=FILE — this option causes Yodl to write its output to FILE. By default, the output goes to the standard output stream. E.g., you can use YODL to read a file input and write to output with these two commands:
yodl input > output
yodl -ooutput input

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 option is specified 💅

  • -p, --preload=CMD — this option 'pre-loads' the string cmd. It acts as though cmd was the first command in the first input file that is processed by YODL. More than one --preload=CMD option may be present on the command line. Each of the commands is then processed in turn, before reading any file 🧚
  • -r, --max-replacements=NR — this option causes Yodl to abort when the number of macro calls or subst-replacements exceeds NR * 10,000. By default, NR equals 1. Setting --max-replacements=0 implies that no macro- or subst-replacement checks are performed 👀 (chaos mode, fr fr)
  • -t, --trace — this option enables tracing: while parsing, Yodl writes its output to the standard error stream. Just like the -k option, this one is defined for debugging purposes only 🐛
  • -V, --version — this option shows YODL's actual version ⭐
  • -v, --verbose — this option increases Yodl's 'verbosity level' and may occur more than once. By default yodl shows alerting, critical, emergency and error messages. Each --verbose option adds a next message level. In order, warning, notice, info and debug messages are added to this set. It's also possible to suppress messages — the VERBOSITY builtin can be used for that 🎀
  • -W, --warranty — this option shows a warranty disclaimer and a copyright notice 📜
  • -w, --warn — the presence of this option causes Yodl to warn when, e.g., symbols are redefined 👑

🗂️ FILES 🗂️

The yodl program requires no files, but 'normal' usage of the Yodl package requires macro files, by default installed in tmp/wip/macros. The files in this directory are included by the converters yodl2txt(1) etc. 🦋

👀 SEE ALSO 👀

yodlbuiltins(7), yodlconverters(1), yodlletter(7), yodlmacros(7), yodlmanpage(7), yodlpost(1), yodlstriproff(1), yodltables(7), yodlverbinsert(1).

like, the whole friend group, all linked up 💖

💀 BUGS 💀

-

that's it. that's the bug list. literally empty. we stay unbothered, periodt ✨

🌟 AUTHOR 🌟

Frank B. Brokken (f.b.brokken@rug.nl),

okay bestie, that's the whole vibe check 🫶 this page is from yodl_4.05.02, dated 1996-2025, and it lives in section yodl(1) of the manual. go forth and pre-document-language your little heart out, you're gonna ate 💅🌸💜

📦 where this page comes from