yodlmacros

title: yodlmacros(7)

summary: Macros for the Yodl converters

text:
# yodlmacros(7)

## NAME
yodlmacros - Macros for the Yodl converters

## SYNOPSIS
This manual page lists the standard macros of the Yodl package.

## DESCRIPTION
The following list shows the macros defined by the Yodl converters define and which can be used in Yodl documents. Refer to the Yodl user guide, distributed with the Yodl package, for a full description.

The following list shows all macros of the package in alphabetical order.

`abstract(text)’

Defines an abstract for an article or report type of document. Abstracts are not implemented for books or manpages. Must appear before starting the document using the `article’ or `report’ macro.

`addntosymbol(symbol)(n)(text)’

Adds `text’ `n’ times to `symbol’. The value `n’ may also be the name of a defined counter (which is not modified).

`affiliation(site)’

Defines an affiliation, to appear in the document titlepage below the author field. Must appear before starting the document with `article’, `report’ or `book’. The affiliation is only printed when the author field is not empty. When converting to html the way the affiliation is displayed can be tuned using CSS id selector specifications. The affiliation has `id="affiliation"’.

`AfourEnlarged()’

Enlarges the usable height of A4 paper by 2 cm.: the top margin is reduced by 2 cm. This macro should be called in the preamble. The macro is available only for LaTeX conversions.

`appendix()’

Starts appendices

`article(title)(author)(date)’

Starts an article. The top-level sectioning command is `(n)sect’. In HTML conversions only one output file is written, while the way the headings are displayed can be tuned using CSS id selector specifications: the title has `id="title"’, the author `id="author"’, and the date `id="date"’.)

`attrib(text)’

In html, pushes `text’ as an attribute for the next html tag supporting `attrib’. E.g, to set a blue color and 30 pixel left-hand side margin for a section use

```
    attrib(style="color:blue;margin-left:30px;")\

    sect(Section name)

```

This results in the html markup

```
    <h1 style="color:blue;margin-left:30px;">Section name</h1>

```

This macro is only effective with html conversions. It is applied in a stack-wise fasion: when multiple `attrib’ calls are used, then the topmost attrib-string is added to the first macro calling the `attribinsert’ macro, with subsequent macros using subsequent elements on the attrib-stack.

Commonly used attributes are `id="idname"’, expecting a `#idname’ CSS label in either internal or external CSS specifications, or `style="spec"’ (as shown in the example).

Example: when using

```
    attrib(width = "100" height = "100")

    attrib(id = "#fig")

    figure(imgfile)(Caption)(IMG)

```

then the `#id’ attribute is applied to `<figure>’, and the `width’ and `height’ attributes are applied to `<img>’, which html markup is inserted by the `figure’ macro.

The `attrib’ macro is supported by the following predefined macros (between parentheses the number of attribute strings that are inserted by these macros; if only 1 attribute string is inserted no number is shown):

`bf cell cells center chapter code dashes dit em figure(3) file htmltag itdesc lchapter link lref lsect lsubsect lsubsubsect nchapter npart nsect nsubsect nsubsubsect paragraph part quote row sc sect strong subs subsect subsubsect subsubsubsect sups tableatt tbl tac tc tnac tnc tr tt ttbegin url verb verborg verbinclude’.

`attribclear()’

Removes any existing contents from the attrib-stack. This macro is only active when converting to html

`attribinsert()’

In html, if the attrib-stack is not empty, inserts the value on top of the attrib-stack and then pops the topmost value. If the attrib-stack is empty, nothing happens.

`bf(text)’

Sets `text’ in boldface.

`bind(text)’

Generate a binding character (non-breaking space) after text.

`book(title)(author)(date)’

Starts a book document. The top-level sectioning command is `(n)chapter’, `(n)part’ being optional. In HTML output files are created for each chapter, while the way the headings are displayed can be tuned using CSS id selector specifications: the title has `id="title"’, the author `id="author"’, and the date `id="date"’.)

`cell(contents)’

Sets a table cell, i.e., one element in a row. With the man/ms converters multiple blanks between `cell()’ macro calls are merged into a single blank character.

Instead of using `cell’ in `table’, consider using `tc’ in `tbl’.

`cells(nColumns)(contents)’

Set a table cell over `nColumns’ columns. With LaTeX and xml the information in the combined cells is centered.

With man/ms conversions the `cells()’ macro simply calls the `cell()’ macro, but here the `setmanalign()’ macro can be used to determine the alignment of multiple cells.

With html the macro `attrib’ can be used, but when it contains a `style’ specification the macro’s default `style="text-align: center"’ is ignored (but it can optionally be specified using the `attrib’ macro).

Instead of using `cells’ in `table’, consider using `tnc’ in `tbl’.

`cellsline(from)(count)’

Sets a horizontal line starting at column number `from’ over `count’ columns in a row. If `from’ is less then the number of columns already added to a row then it is ignored. This macro must be embedded in a `row’ macro defining a table row. To put a line across the table’s full width use `rowline’. To set horizontal lines across columns 1 until 2 and columns 4 until 5 table of a table use:

```
    row(cellsline(1)(2)cellsline(4)(2))

```

Combining `cellsline’ and `cell’ or `cells’ calls in one row produces undefined results.

Instead of using `cellsline’ in `table’, consider using `tline’ in `tbl’.

`center(text)’

Centers `text’. Use `nl()’ in the text to break lines. In html the `attrib’ macro is not supported, but a division (`div’) with style definition `text-align: center’ is used. To center a table in html use the `tableatt’ macro. If a `table’ or `tableatt’ macro is used inside a `center’ macro then the contents of columns are column-wise centered.

Inside a `center(...)’ context the counter `XXcenter’ is unequal 0.

`chapter(title)’

Starts a new chapter in books or reports.

`cindex()’

Generate an index entry for LaTex() or texinfo c-indices. Its argument is the index entry. See also the `[fptv]index’ macro.

`cite(text)’

Sets `text’ as a citation or quotation

`clearpage()’

Starts a new page, when the output format permits. Under HTML a horizontal line is drawn.

`code(text)’

Sets `text’ in code font, and prevents it from being expanded. For unbalanced parameter lists, use `CHAR(40)’ to get `(’ and `CHAR(41)’ to get `)’.

`columnline(from)(through)’

Sets a horizontal line over some columns in a row. Note that `columnline’ defines a row by itself, consisting of just a horizontal line spanning some of its columns, rather than the table’s full width, like `rowline’. The two arguments represent column numbers. It is the responsibility of the author to make sure that the `from’ and `through’ values are sensible. I.e.,

```
    1 <= from <= through <= ncolumns

```

To set a horizontal line in just one column select `through’ equal to `from’.

Note: this macro cannot be used if multiple lines must be set in one row. In those cases the macros `tline, tskip’, and `tendline’ should be used.

Instead of using `columnline’ in `table’, consider using `tline’ in `tbl’.

`dashes()’

Inserts two dashes in teletype font, and prevents them from being expanded.

In html the `attrib’ macro is recognized by the `<code>’ tag that is used to embed the two dashes.

`def(macroname)(nrofargs)(redefinition)’

Defines `macroname’ as a macro, having `nrofargs’ arguments, and expanding to `redefinition’. This macro is a shorthand for `DEFINEMACRO’. An error occurs when the macro is already defined. Use `redef()’ to unconditionally define or redefine a macro.

`description(list)’

Sets `list’ as a description list. Use `dit(item)’ to indicate items in the list.

`dit(itemname)’

Starts an item named `itemname’ in a description list. The list should be used in `description’ macros. With `html’ conversions the contents of a description item is separated from the item itself. The `dit’ macro only defines the item, and not the description itself. This macro sets the item in bold-face (`strong’ font). The macro `itdesc’, available since Yodl 3.05, can be used to defines an item and its description, using its suggested format (i.e., indenting the description relative to the item).

`eit()’

Indicates an item in an enumerated list. The `eit’ macro should be used as an argument in `enumeration’ macros.

`ellipsis()’

Sets ellipsis (...).

`em(text)’

Sets `text’ as emphasized, usually italics.

`email(address)’

In HTML, this macro sets the `address’ in a `<a href="mailto=..">’ locator. In other output formats, the `address’ is sent to the output. The `email’ macro is a special case of `url’.

`enumeration(list)’

`enumeration()’ starts an enumerated list. Use `eit()’ in the list to indicate items in the list.

`euro()’

Sets the euro currency symbol in latex, html, (and possibly sgml and xml). In all other conversions EUR which is the official textual abbreviation (cf. http://ec.europa.eu/euro/entry.html) is written. Note that LaTeX may require latexpackage()(eurosym).

`evalsymbol(symbol)(expression)’

Symbol symbol receives the value resulting from evaluating expression. E.g., if `sym’ is a defined symbol, then

```
    evalsymbol(sym)(SUBSTR(hello world)(3)(2))

```

assigns the value `lo’ to `sym’.

`fig(label)’

This macro is a shorthand for `figure ref(label)’ and just makes the typing shorter, as in `see fig(schematic) for ..’ See `getfigurestring()’ and `setfigurestring()’ for the `figure’ text.

`figure(file)(caption)(label)’

Sets the picture in `file’ as a figure in the current document, using the descriptive text `caption’. The `label’ is defined as a placeholder for the figure number and can be used in a corresponding `ref’ statement. Note that the `file’ must be the filename without extension: By default, Yodl will supply `.gif’ when in HTML mode, or `.ps’ when in LaTeX mode. Figures in other modes may not (yet) haven been implemented.

When converting to html, this macro uses three attribute-strings (if available). The string pushed first using an attrib-call defines the attributes for its `<figcaption>’ html-markup; the string pushed next defines the attributes for its `<img>’ html-markup; the string pushed last defines the attributes for its `<figure>’ html-markup. The `figure’ macro’s html output is organized like this:

```
    <figure -attrib-string pushed last (if any)>

        <img ... -attrib-string pushed last but one>

        <figcaption -attrib-string pushed 2nd to last>

            ...

        </figcaption>

    </figure>

```

Starting with Yodl 3.07.00 no `alt="Figure # is shown here..."’ attribute is defined anymore for the `img’ markup: an `alt’-attribute can easily be defined at the last attrib-call, using `getfigurestring()’ to obtain `Figure’ or its language-specific translation, and `COUNTERVALUE(XXfigurecounter)’ to obtain the order-number of the figure shown in the next `figure’-macro call.

`file(text)’

Sets `text’ as filename, usually boldface. In html `attrib’ macro applies to the `<strong>’ tag.

`findex()’

Generate an index entry for LaTex() or texinfo f-indices. Its argument is the index entry. See also the `[cptv]index’ macro.

`footnote(text)’

Sets `text’ as a footnote, or between parentheses when the output format does not allow footnotes.

`gagmacrowarning(name name ...)’

Prevents the `yodl’ program from printing cannot expand possible user macro. E.g., if you have in your document `the file(s) are ..’ then you might want to put before that: `gagmacrowarning(file)’. Calls `NOUSERMACRO’.

`getaffilstring()’

Expands to the string that defines the name of Affiliation Information, by default AFFILIATION INFORMATION. Can be redefined for national language support by `setaffilstring()’. Currently, it is relevant only for txt.

`getauthorstring()’

Expands to the string that defines the name of Author Information, by default AUTHOR INFORMATION. Can be redefined for national language support by `setauthorstring()’. Currently, it is relevant only for txt.

`getchapterstring()’

Expands to the string that defines a `chapter’ entry, by default Chapter. Can be redefined for national language support by `setchapterstring()’.

`getdatestring()’

Expands to the string that defines the name of Date Information, by default DATE INFORMATION. Can be redefined for national language support by `setdatestring()’. Currently, it is relevant only for txt.

`getfigurestring()’

Returns the string that defines a `figure’ text, in captions or in the `fig()’ macro. The string can be redefined using the `setfiguretext()’ macro.

`getpartstring()’

Expands to the string that defines a `part’ entry, by default Part. Can be redefined for national language support by `setpartstring()’.

`gettitlestring()’

Expands to the string that defines the name of Title Information, by default TITLE INFORMATION. Can be redefined for national language support by `settitlestring()’. Currently, it is relevant only for txt.

`gettocstring()’

Expands to the string that defines the name of the table of contents, by default Table of Contents. Can be redefined for national language support by `settocstring()’.

`htmlcommand(cmd)’

Writes `cmd’ to the output when converting to html. The `cmd’ is not further expanded by Yodl.

`htmlheadfile(file)’

Adds the contents of `file’ to the `head’ section of an HTML document. The contents of file are not interpreted and should contain plain html text. This option can be useful when large bodies of text, like the contents of `<script>’ sections, must be included into the head section of html documents. This macro is only active in the preamble, should only specified once, and is only interpreted for html conversions.

`htmlheadopt(option)’

Adds the literal text `option’ to the current information in the `head’ section of an HTML document. `Option’ may (or: should) contain plain html text. A commonly occurring head option is `link’, defining, e.g., a style sheet. Since that option is frequently used, it has received a dedicated macro: `htmlstylesheet’. When large bodies of html-text must be added to html documents the macro `htmlheadfile’ should be used. This macro is only active in the preamble and is only interpreted for html conversions.

`htmlnewfile()’

In HTML output, starts a new file. All other formats are not affected. Note that you must take your own provisions to access the new file; say via links. Also, it’s safe to start a new file just befoore opening a new section, since sections are accessible from the clickable table of contents. The HTML converter normally only starts new files prior to a `chapter’ definition.

`htmlstyle(tag)(definition)’

Adds a `<style type="text/css"> ... </style>’ element to the head section of an HTML document.

Use `htmlstyle’ to specify one or more CSS definitions which are eventually inserted at the ellipsis (`...’) in the generic `style’ definition shown above. E.g., (using `#rrggbb’ to specify a color, where `rr’ are two hexadecimal digits specifying the color’s red component, `gg’ two hexadecimal digits specifying the color’s green component, and `bb’ two hexadecimal digits specifying the color’s blue component) specifying

```
    htmlstyle(body)(color: #rrggbb; background-color: #rrggbb)

    htmlstyle(h1)(color: blue; text-align: center)

    htmlstyle(h2)(color: green)

```

results in the element

```
    <style type="text/css">

        body {color: #rrggbb; background-color: #rrggbb;}

        h1 {color: blue; text-align: center;}

        h2 {color: green;}

    </style>

```

The macros `htmlheadopt’ and `htmlstylesheet’ could also be used to put information into the head-section of an HTML document, but `htmlheadopt’ is of a much more general nature, while `htmlstylesheet’ refers to CSS elements stored in an external file. The macro `attrib’ can be used to define inline styles.

The `htmlstyle’ macro is only active in the preamble and is only interpreted for html conversions.

Refer to available CSS specifications (cf., http://www.w3schools.com/cssref/ for an overview of how CSS specifications are used, and which CSS specifications are available).

By default the internal style specification

`figure {text-align: center;} img {vertical-align: center;}’

is used. If this is not appropriate, specify `nohtmlimgstyle()’ in the preamble.

`htmlstylesheet(url)’

Adds a `<link rel="stylesheet" type="text/css" ...>’ element to the head section of an HTML document, using `url’ in its `href’ field. The argument `url’ is not expanded, and should be plain HTML text, without surrounding quotes. The macro `htmlheadopt’ can also be used to put information in the head-section of an HTML document, but `htmlheadopt’ is of a much more general nature. This macro is only active in the preamble and is only interpreted for html conversions.

`htmltag(tagname)(start)’

Sets `tagname’ as a HTML tag, enclosed by `<’ and `>’. When `start’ is zero, the `tagname’ is prefixed with `/’. As not all html tags are available through predefined Yodl-macros (there are too many of them, some are used very infrequently, and you can easily define macros for the tags for which Yodl doesn’t offer predefined ones), the `htmltag’ macro can be used to handle your own set of macros. In html the `attrib’ macro is supported. E.g.,

```
attrib(title="World Health Organization")    htmltag(abbr)()WHO+htmltag(abbr)(0)

```

`ifnewparagraph(truelist)(falselist)’

The macro `ifnewparagraph’ should be called from the `PARAGRAPH’ macro, if defined. It will insert `truelist’ if a new paragraph is inserted, otherwise `falselist’ is inserted (e.g., following two consecutive calls of PARAGRAPH). This macro can be used to prevent outputting multiple blank lines.

`includefile(file)’

Includes `file’. The default extension `.yo’ is supplied if necessary.

Since Yodl version 3.00.0 Yodl’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’s file inclusion behavior now matches the way C’s `#include’ directive operates. The originally implemented file inclusion behavior is used when Yodl’s `-L’ (`--legacy-include’) option is used.

`includeverbatim(file)’

Include `file’ into the output. No processing is done, `file’ should be in preformatted form, e.g.:

```
whenhtml(includeverbatim(foo.html))
```

`it()’

Indicates an item in an itemized list. Items in `it’ macros are arguments of `itemization’ macros.

`itdesc(itemname)(contents)’

Starts an item and its description in a description list. Its name is `itemname’, the contents of the item is defined by `contents’. The `itemname’ is defined by using the `dit’ macro.

With `html’ conversions the contents are surrounded by `<dd>’ and `</dd>’ tags, resulting in contents which are indented relative to the itemname. When the `attrib’ macro is used it is applied to the itemname (`dt’-tags).

With other conversions the `contents’ are quoted (as if using `quote(contents)’).

`itemization(list)’

Sets `list’ as an itemizationd list. Use `it()’ to indicate items in the list.

`kindex()’

Generate an index entry for LaTex() or texinfo k-indices. Its argument is the index entry. See also the `[cfptv]vindex’ macro.

`label(labelname)’

Defines `labelname’ as an anchor for a `link’ command, or to stand for the last numbering of a section or figure in a `ref’ command.

`langle()’

Character <

`languagedutch()’

Defines the Dutch-language specific headers. Active this macro via setlanguage(dutch).

`languageenglish()’

Defines the English-language specific headers. Active this macro via setlanguage(english).

`languageportugese()’

Defines the Portugese-language specific headers. Active this macro via setlanguage(portugese).

`LaTeX()’

The LaTeX symbol.

`latexaddlayout(arg)’

This macro is provided to add Yodl-interpreted text to your own LaTeX layout commands. The command is terminated with an end-of-line. See also the macro `latexlayoutcmds()’

`latexcommand(cmd)’

Writes `cmd’ plus a white space to the output when converting to LaTeX. The `cmd’ is not further expanded by Yodl.

`latexdocumentclass(class)’

Forces the LaTeX `\documentclass{...}’ setting to `class’. Normally the class is defined by the macros `article’, `report’ or `book’. This macro is an escape route in case you need to specify your own document class for LaTeX. This option is a modifier and must appear before the `article’, `report’ or `book’ macros.

`latexlayoutcmds(NOTRANSs)’

This macro is provided in case you want to put your own LaTeX layout commands into LaTeX output. The `NOTRANSs’ are pasted right after the `\documentclass’ stanza. The default is, of course, no local LaTeX commands. Note that this macro does not overrule my favorite LaTeX layout. Use `nosloppyhfuzz()’ and `standardlayout()’ to disable my favorite LaTeX layout.

`latexoptions(options)’

Set latex options: `documentclass[options]’. This command must appear before the document type is stated by `article’, `report’, etc..

`latexpackage(options)(name)’

Include latex package(s), a useful package is, e.g., `epsf’. This command must appear before the document type is stated by `article’, `report’, etc..

`lchapter(label)(title)’

Starts a new chapter in books or reports, setting a label at the beginning of the chapter.

`letter(language)(date)(subject)(opening)(salutation)(author)’

Starts a letter written in the indicated language. The date of the letter is set to `date’, the subject of the letter will be `subject’. The letter starts with `opening’. It is based on the `letter.cls’ document class definition. The macro is available for LaTeX only. Preamble command suggestions:

o

`latexoptions(11pt)’

o

`a4enlarged()’

o

`letterreplyto(name)(address)(postalcode/city)’

o

`letterfootitem(phone)(number)’, maybe e-mail too.

o

`letteradmin(yourdate)(yourref)’

o

`letterto(addressitem)’. Use a separate `letterto()’ macro call for each new line of the address.

`letteraddenda(type)(value)’

Adds an addendum at the end of a letter. `type’ should be `bijlagen’, `cc’ or `ps’.

`letteradmin(yourdate)(yourref)’

Puts `yourletterfrom’ and `yourreference’ elements in the letter. If left empty, two dashes are inserted.

`letterfootitem(name)(value)’

Puts a footer at the bottom of letter-pages. Up to three will usually fit. LaTeX only.

`letterreplyto(name)(address)(zip city)’

Defines the `reply to’ address in LaTeX or txt-letters.

`letterto(element)’

Adds `element’ as an additional line to the address in LaTeX letters.

`link(description)(labelname)’

In HTML output a clickable link with the text `description’ is created that points to the place where `labelname’ is defined using the `label’ macro, and `attrib’ macro applies to the `<a>’ tag. Using `link’ is similar to `url’, except that a hyperlink is set pointing to a location in the same document. For output formats other than HTML, only the `description’ appears.

`lref(description)(labelname)’

This macro is a combination of the `ref’ and `link’ macros. In HTML output a clickable link with the text `description’ and the label value is created that points to the place where `labelname’ is defined using the `label’ macro, and `attrib’ macro applies to the `<a>’ tag. For output formats other than HTML, only the `description’ and the label value appears.

`lsect(label)(title)’

Starts a new section, setting a label at the beginning of the section. In html `attrib’ macro applies to the `<h2>’ tag.

`lsubsect(label)(title)’

Starts a new subsection. Other sectioning commands are `subsubsect’ and `subsubsubsect’. A label is added just before the subsection. In html `attrib’ macro applies to the `<h3>’ tag.

`lsubsubsect(label)(title)’

Starts a sub-subsection, a label is added just before the section In html `attrib’ macro applies to the `<h4>’ tag.

`lsubsubsubsect(label)(title)’

Starts a sub-sub-sub section. This level of sectioning is not numbered, in contrast to `higher’ sectionings. A label is added just before the subsubsubection.

`lurl(locator)’

An url described by its Locator. For small urls with readable addresses.

`mailto(address)’

Defines the default `mailto’ address for HTML output. Must appear before the document type is stated by `article’, `report’, etc..

`makeindex()’

Make index for latex.

`mancommand(cmd)’

Writes `cmd’ to the output when converting to man. The `cmd’ is not further expanded by Yodl.

`manpage(title)(section)(date)(source)(manual)’

Starts a manual page document. The `section’ argument must be a number, stating to which section the manpage belongs to. Most often used are commands (1), file formats (5) and macro packages (7). The sectioning commands in a manpage are not `(n)sect’ etc., but `manpage...()’. The first section must be the `manpagename’, the last section must be the `manpageauthor’. The standard manpage for section 1 contains the following sections (in the given order): `manpagename’, `manpagesynopsis’, `manpagedescription’, `manpageoptions’, `manpagefiles’, `manpageseealso’, `manpagediagnostics’, `manpagebugs’, `manpageauthor’. Optional extra sections can be added with `manpagesection’. Standard manpageframes for several manpagesections are provided in `/usr/local/share/yodl/manframes’. YODL manual pages can be converted to `groff, html’, or plain ascii text formats.

`manpageauthor()’

Starts the AUTHOR entry in a `manpage’ document. Must be the last section of a `manpage’.

`manpagebugs()’

Starts the BUGS entry in a `manpage’ document.

`manpagedescription()’

Starts the DESCRIPTION entry in a `manpage’ document.

`manpagediagnostics()’

Starts the DIAGNOSTICS entry in a `manpage’ document.

`manpagefiles()’

Starts the FILES entry in a `manpage’ document.

`manpagename(name)(short description)’

Starts the NAME entry in a `manpage’ document. The short description is used by, e.g., the `whatis’ database.

`manpageoptions()’

Starts the OPTIONS entry in a `manpage’ document.

`manpagesection(SECTIONNAME)’

Inserts a non-required section named `SECTIONNAME’ in a `manpage’ document. This macro can be used to augment `standard’ manual pages with extra sections, e.g., EXAMPLES. Note that the name of the extra section should appear in upper case, which is consistent with the normal typesetting of manual pages.

`manpageseealso()’

Starts the SEE ALSO entry in a `manpage’ document.

`manpagesynopsis()’

Starts the SYNOPSIS entry in a `manpage’ document.

`manttquoted(onOff)’

With man-conversions arguments of tt macros are displayed as normal text. To enhance their visibility arguments of tt macros may be quoted, in which case they are surrounded by backtics and normal quotes. By default arguments of tt macros are not quoted. Quotation is used after calling `manttquoted(1)’, and is suppressed after calling `manttquoted(0)’. The macro is only active when converting to man.

`mbox()’

Unbreakable box in LaTeX. Other formats may have different opitions on our unbreakable boxex.

`metaC(text)’

Put a line comment in the output.

`metaCOMMENT(text)’

Write format-specific comment to the output.

`mscommand(cmd)’

Writes `cmd’ to the output when converting to ms. The `cmd’ is not further expanded by Yodl.

`nbsp(count)’

Inserts `count’ `non-breaking space’ characters into the generated output; i.e., the space character is not optimized away. If the argument list is empty one non-breaking space is inserted.

`nchapter(title)’

Starts a chapter (in a `book’ or `report’) without generating a number before the title and without placing an entry for the chapter in the table of contents. In html `attrib’ macro applies to the `<h1>’ tag.

`nemail(name)(address)’

Named email. A more consistent naming for url, lurl, email and nemail would be nice.

`nl()’

Forces a newline; i.e., breaks the current line in two.

`nodeprefix(text)’

Prepend text to node names, e.g.

```
nodeprefix(LilyPond) sect(Overview)
```

Currently used in texinfo descriptions only.

`nodeprefix(text)’

Prepend text to node names, e.g.

```
nodeprefix(LilyPond) sect(Overview)
```

Currently used in texinfo descriptions only.

`nodetext(text)’

Use text as description for the next node, e.g.

```
nodetext(The GNU Music Typesetter)chapter(LilyPond)
```

Currently used in texinfo descriptions only.

`nohtmlfive()’

Starting yodl 3.05 html-conversions by default use html5. This can be suppressed (in favor of using html4) by calling this macro. This macro merely suppresses writing the initial `<!DOCTYPE html>’ to generated html files; it is only active in the preamble and is only interpreted for html conversions.

`nohtmlimgstyle()’

By default html-pages specify

`(<style type="text/css" img {vertical-align: bottom;}></style>)’

This macro suppresses this `img’ CSS style specification. This macro is only active in the preamble and is only interpreted for html conversions.

`nop(text)’

Expand to text, to avoid spaces before macros e.g.: a. Although a+sups(2) should have the same effect.

`nosloppyhfuzz()’

By default, LaTeX output contains commands that cause it to shut up about hboxes that are less than 4pt overfull. When `nosloppyhfuzz()’ appears before stating the document type, LaTeX complaints are `vanilla’.

`notableofcontents()’

Prevents the generation of a table of contents. This is default in, e.g., `manpage’ and `plainhtml’ documents. When present, this option must appear before stating the document type with `article’, `report’ etc..

`notitleclearpage()’

Prevents the generation of a `clearpage()’ instruction after the typesetting of title information. This instruction is default in all non `article’ documents. When present, must appear before stating the document type with `article’, `book’ or `report’.

`notocclearpage()’

With the LaTeX converter, no `clearpage()’ instruction is inserted immediately beyond the document’s table of contents. The `clearpage()’ instruction is default in all but the `article’ document type. When present, must appear before stating the document type with `article’, `book’ or `report’. With other converters than the LaTeX converter, it is ignored.

`notransinclude(filename)’

Reads filename and inserts it literally in the text not subject to macro expansion or character translation. No information is written either before or after the file’s contents, not even a newline.

`noxlatin()’

When used in the preamble, the LaTeX converter disables the inclusion of the file `xlatin1.tex’. Normally this file gets included in the LateX output files to ensure the conversion of high ASCII characters (like e) to LaTeX-understandable codes. (The file `xlatin1.tex’ comes with the YODL distribution.)

`nparagraph(title)’

Starts a non-numbered paragraph (duh, corresponds to subparagraph in latex).

`npart(title)’

Starts a part in a `book’ document, but without numbering it and without entering the title of the part in the table of contents. In html `attrib’ macro applies to the `<h1>’ tag.

`nsect(title)’

Starts a section, but does not generate a number before the `title’ nor an entry in the table of contents. Further sectioning commands are `nsubsect’, `nsubsubsect’ and `nsubsubsubsect’. In html `attrib’ macro applies to the `<h2>’ tag.

`nsubsect(title)’

Starts a non-numbered subsection. In html the `attrib’ macro applies to the `<h3>’ tag.

`nsubsubsect(title)’

Starts a non-numbered sub-sub section. In html `attrib’ macro applies to the `<p>’ tag.

`nsubsubsect(title)’

Starts a non-numbered sub-subsection.

`paragraph(title)’

Starts a paragraph. This level of sectioning is not numbered, in contrast to `higher’ sectionings (duh, corresponds to subparagraph in latex). In html `attrib’ macro applies to the `<p>’ tag.

`part(title)’

Starts a new part in a `book’ document. In html `attrib’ macro applies to the `<h1>’ tag.

`pindex()’

Generate an index entry for LaTex() or texinfo p-indices. Its argument is the index entry. See also the `[cftv]index’ macro.

`plainhtml(title)’

Starts a document for only a plain HTML conversion. Not available in other output formats. Similar to `article’, except that an author- and date field are not needed.

`printindex()’

Make index for texinfo (?).

`quote(text)’

Sets the text as a quotation. Usually, the text is indented, depending on the output format. In html the `attrib’ macro is recognized by the `<blockquote>’ tag.

`rangle()’

Inserts the right angle character (>).

`redef(macro)(nrofargs)(redefinition)’

Defines macro `macro’ to expand to `redefinition’. Similar to `def’, but any pre-existing definition is overruled. Use `ARG’x in the redefinition part to indicate where the arguments should be pasted. E.g., `ARG1’ places the first argument, `ARG2’ the second argument, etc...

`redefinemacro(macro)(nrofargs)(redefinition)’

Defines macro `macro’ to expand to `redefinition’. Similar to `def’, but any pre-existing definition is overruled. Use `ARG’x in the redefinition part to indicate where the arguments should be pasted. E.g., `ARG1’ places the first argument, `ARG2’ the second argument, etc... This commands is actually calling redef().

`ref(labelname)’

Sets the reference for `labelname’. Use `label’ to define a label.

`report(title)(author)(date)’

Starts a report type document. The top-level sectioning command in a report is `chapter’. In html the way the headings are displayed can be tuned using CSS id selector specifications: the title has `id="title"’, the author `id="author"’, and the date `id="date"’.

`roffcmd(dotcmd)(sameline)(secondline)(thirdline)’

Sets a t/nroff command that starts with a dot, on its own line. The arguments are: `dotcmd’ - the command itself, e.g., `.IP’; `sameline’ - when not empty, `sameline’ is set on the same line, following the `dotcmd’; `secondline’ - when not empty, is set on the next line; `thirdline’ - when not empty, is set on the third line. Note: `dotcmd’ and `thirdline’ are not further expanded by YODL, the other arguments are.

`row(contents)’

The argument `contents’ may contain a man-page alignment specification (only one specification can be entered per row), using `setmanalign()’. If omitted, the standard alignment is used. Furthermore it contains the contents of the elements of the row, using `cell()’ or `cells()’ macros. If `cells()’ is used, `setmanalign()’ should have been used too. In this macro call only the `cell()’, `cells()’ and `setmanalign()’ macros should be called. Any other macro call may produce unexpected results.

The `row’ macro defines a counter `XXcol’ that can be inspected and is incremented by predefined macros adding columns to a row. The counter is initially 0. Predefined macros adding columns to a row add the number of columns they add to the row inserting the contents of those columns. These macros rely on the correct value of this counter and any user-defined macros adding columns to table rows should correctly update `XXcol’. In html `attrib’ macro applies to the `<tr>’ tag.

Instead of using `row’ in `table’, consider using `tr’ in `tbl’.

`rowline()’

Sets a horizontal line over the full width of the table. See also the `columnline’ macro. Use `rowline’ instead of a `row’ macro call to provide a table with a horizontal line-separator.

Instead of using `rowline’ consider using `tline’ in a `tbl’ argument.

`sc(text)’

Set `text’ in the tt (code) font, using small caps. In html the `attrib’ macro is not supported, while the code section is embedded in a `<div style="font-size: 90%">’ section.

`sect(title)’

Starts a new section. In html the `attrib’ macro is recognized by the `<h2>’ tag.

`setaffilstring(name)’

Defines `name’ as the `affiliation information’ string, by default AFFILIATION INFORMATION. E.g., after `setaffilstring(AFILIACION)’, YODL outputs this Spanish string to describe the affiliation information. Currently, it is relevant only for txt.

`setauthorstring(name)’

Defines `name’ as the `Author information’ string, by default AUTHOR INFORMATION. E.g., after `setauthorstring(AUTOR)’, YODL outputs this portuguese string to describe the author information. Currently, it is relevant only for txt.

`setchapterstring(name)’

Defines `name’ as the `chapter’ string, by default Chapter. E.g., after `setchapterstring(Hoofdstuk)’, YODL gains some measure of national language support for Dutch. Note that LaTeX support has its own NLS, this macro doesn’t affect the way LaTeX output looks.

`setdatestring(name)’

Defines `name’ as the `date information’ string, by default DATE INFORMATION. E.g., after `setdatestring(DATA)’, YODL outputs this portuguese string to describe the date information. Currently, it is relevant only for txt.

`setfigureext(name)’

Defines the `name’ as the `figure’ extension. The extension should include the period, if used. E.g., use setfigureext(.ps) if the extensions of the figure-images should end in `.ps’

`setfigurestring(name)’

Defines the `name’ as the `figure’ text, used e.g. in figure captions. E.g., after `setfigurestring(Figuur)’, Yodl uses Dutch names for figures.

`sethtmlfigureext(ext)’

Defines the filename extension for HTML figures, defaults to `.jpg’. Note that a leading dot must be included in `ext’. The new extension takes effect starting with the following usage of the `figure’ macro. It is only active in html, but otherwise acts identically as setfigureext().

See also the `setlatexfigureext’ macro.

`htmlmetacharset(meta-charset)’

Adds `<meta charset="meta-charset">’ to the head of html documents. By default `<meta charset="UTF-8">’ is used. This macro is only active in the preamble and is only interpreted for html conversions.

`setincludepath(name)’

Sets a new value of the include-path specification used when opening .yo files. A warning is issued when the path specification does not include a .: element. Note that the local directory may still be an element of the new include path, as the local directory may be the only or the last element of the specification. For these eventualities the new path specification is not checked.

`setlanguage(name)’

Installs the headers specific to a language. The argument must be the name of a language, whose headers have been set by a corresponding languageXXX() call. For example: languagedutch(). The language macros should set the names of the headers of the following elements: table of contents, affiliation, author, chapter, date, figure, part and title

`setlatexalign(alignment)’

This macro defines the table alignment used when setting tables in LaTeX. Use as many `l’ (for left-alignment), `r’ (for right alignment), and `c’ (for centered-alignment) characters as there are columns in the table. See also `table()’.

Instead of using the `table’ macro consider using the `tbl’ macro.

`setlatexfigureext(ext)’

Defines the filename extension for encapsulated PostScript figures in LaTeX, defaults to `.ps’. The dot must be included in t new extension `ext’. The new extension takes effect starting with a following usage of the `figure’ macro. It is only active in LaTeX, but otherwise acts identically as setfigureext().

See also the `sethtmlfigureext’ macro.

`setlatexverbchar(char)’

Set the char used to quote LaTeX \verb sequences

`setmanalign(alignment)’

This macro defines the table alignment in the context of the `table’ macro, and is used when setting tables in man-pages (see tbl(1)).

Use as many `l’ (for left-alignment), `r’ (for right alignment), and `c’ (for centered-alignment) characters as there are columns in the table.

Use `s’ to indicate that the column to its left is combined (spans into) the current column. Use this specification when cells spanning multiple columns must be defined.

Each row in a table which must be convertible to a manpage may be preceded by its own `setmanalign’ call.

Note that neither `rowline’ nor `columnline’ requires `setmanalign’ specifications, as these macros define rows by themselves. It is the responsibility of the author to ensure that the number of alignment characters is equal to the number of columns of the table.

Instead of using the `table’ macro consider using the `tbl’ macro.

`setpartstring(name)’

Defines `name’ as the `part’ string, by default Part. E.g., after `setpartstring(Teil)’, Yodl identifies parts in the German way. Note that LaTeX output does its own national language support; this macro doesn’t affect the way LaTeX output looks.

`setrofftab(x)’

Sets the character separating items in a line of input data of a `roff’ (manpage) table. By default it is set to `~’. This separator is used internally, and needs only be changed (into some unique character) if the table elements themselves contain `~’ characters.

This macro can be used in the context of the `table’ and `tbl’ macros.

`setrofftableoptions(optionlist)’

Set options used for man-conversion, as used by the `tbl’ and `table’ macros. By default no options are used. Multiple options should be separated by blanks. From the tbl(1) manpage, the following options are available:

o

`center’ Centers the table; default is left-justified. In the context of the `tbl’ macro this is implied when the `tbl’ macro is specified as argument of the `center’ macro.

o

`expand’ Makes the table as wide as the current line length

o

`box’ Encloses the table in a box

o

`allbox’ Encloses each item of the table in a box

See also `setrofftab’ which is used to set the character separating items in a line of input data.

`settitlestring(name)’

Defines `name’ as the `title information’ string, by default TITLE INFORMATION. E.g., after `settitlestring(TITEL)’, YODL outputs this Dutch string to describe the title information. Currently, it is relevant only for txt.

`settocstring(name)’

Defines `name’ as the `table of contents’ string, by default Table of Contents. E.g., after `settocstring(Inhalt)’, YODL identifies the table of contents in the German way. Note that LaTeX output does its own national language support; this macro doesn’t affect the way LaTeX output looks.

`sgmlcommand(cmd)’

Writes `cmd’ to the output when converting to sgml. The `cmd’ is not further expanded by Yodl.

`sgmltag(tag)(onoff)’

Similar to `htmltag’, but used in the SGML converter.

`sloppyhfuzz(points)’

By default, LaTeX output contains commands that cause it to shut up about hboxes that are less than 4pt overfull. When `sloppyhfuzz()’ appears before stating the document type, LaTeX complaints occur only if hboxes are overfull by more than `points’.

`standardlayout()’

Enables the default LaTeX layout. When this macro is absent, then the first lines of paragraphs are not indented and the space between paragraphs is somewhat larger. The `standardlayout()’ directive must appear before stating the document type as `article’, `report’, etc..

`strong(contents)’

In html and xml the `contents’ are set between `<strong>’ and `</strong>’ tags. In html `attrib’ macro applies to the `<strong>’ tag.

`subs(text)’

Sets text in subscript in supporting formats. In html the `attrib’ macro is recognized by the `<sub>’ tag.

For superscripting, the `sups’ macro can be used.

`subsect(title)’

Starts a new subsection. Other sectioning commands are `subsubsect’ and `subsubsubsect’. In html `attrib’ macro applies to the `<h3>’ tag.

`subsubsect(title)’

Starts a sub-subsection. In html `attrib’ macro applies to the `<h4>’ tag.

`subsubsubsect(title)’

Starts a sub-sub-sub-subsection. This level of sectioning is not numbered, in contrast to `higher’ sectionings.

`sups(text)’

Sets text in superscript in supporting formats In html the `attrib’ macro is recognized by the `<sup>’ tag.

For subscripting, the `subs’ macro can be used.

`table(nColumns)(alignment)(Contents)’

Instead of using the `table’ macro, consider using the `tbl’ macro.

The `table()’-macro defines a table. Its first argument specifies the number of columns in the table.

Its second argument specifies the (standard) alignment of the information within the cells as used by LaTeX or man/ms. Use `l’ for left-alignment, `c’ for centered-alignment and `r’ for right alignment.

Its third argument defines the contents of the table which are the rows, each containing column-specifications and optionally man/ms alignment definitions for this row.

See also the `tableatt’ macro and the specialized `setmanalign()’ macro.

`tableatt(nColumns)(alignment)(Contents)’

Instead of using the `tableatt’ macro, consider using the `tbl’ macro.

The `tableatt()’-macro defines a table. The last `attrib’ call that was specified before using the `tableatt()’-macro is used to specify html attributes for the table. E.g., to center a table in html use

```
    attrib(style="margin-left:auto;margin-right:auto;")

    tableatt(...)

```

The macro’s first argument specifies the number of columns in the table. Its second argument specifies the (standard) alignment of the information within the cells as used by LaTeX or man/ms. Use `l’ for left-alignment, `c’ for centered-alignment and `r’ for right alignment. Its third argument defines the contents of the table which are the rows, each containing column-specifications and optionally man/ms alignment definitions for this row.

See also the `table’ macro and the specialized `setmanalign()’ macro.

`tac(alignment)(contents)’

This macro is one of the four macros that can be used to define column contents of rows of tables defined by the `tbl’ macro. Alternatively, `tc, tnc’, and `tnac’ can be used.

The `tac’ macro is used as argument of the `tr’ macro. The cell’s alignment is defined by the `alignment’ specification, containing at most two alignment specifications: a horizontal alignment (one of c, l, r (centered, left-aligned, right-aligned)) and a vertical alignment (one of t, b (vertical top- and bottom-alignment)) (not all conversion types may support all alignment types, e.g., man-conversion does not support vertical bottom alignment). Specifications other than c, l, r, b, and t and specifications beyond the second one are ignored. The result of specifying conflicting alignment types (e.g., `lr’ or `tb’) is not defined.

When converting to `man’, if the table’s contents should span multiple rows, then a groff/troff(1) text block must be used. Since most tables do not use this, a text block is not generated by default. To actually wrap the contents of column elements in a text block while converting to `man’ prefix the first text block requiring a text-block wrapping by `twrap(1)’, and end the last text block requiring a text-block wrapping by `wrap(0)’.

The `tao’ macro can be used to overrule the specified alignment for a specific conversion type.

The macro `tac’ recognizes `attrib’.

`tao(type)(specification)’

This macro is used inside the `tbl’ macro to override the alignment specification that would otherwise be used for the next table element. It is only active for the next `tc, tnc, tac,’ or `tnac’ call. Its first argument defines the conversion type for which the override should be used, its second argument defines the alignment specification to use.

Here are some examples:

```
tbl(lr)(

    tr(

        tc(left aligned)

        tc(right aligned)

    )

    tr(

        tao(html)(c)

          tc(left aligned, centered with html)

        tao(latex)(l)

        tao(man)(l)

          tac(c)(centered, latex and man: left aligned)

    )
)

```

Further details about the `tao’ macro are provided in the yodltables(7) man-page.

`tbl(align)(contents)’

The `tbl’ macro refines the more basic `table’ macro. It was named after the tbl(1) table formatting program used with troff(1) documents.

The `tbl’ macro currently is available for `html, man/ms, latex’ and `txt’ conversions.

Its first argument defines the alignment of the information in the table’s columns, and is used by all conversions except `txt’. Use `l’ for left-alignment, `c’ for centered-alignment and `r’ for right-alignment. Individual cells of the table may override these default settings using the macros `tac’ and `tnac’.

Its second argument defines the contents of the table consisting of rows (using `tr’), and horizontal lines (using `tline’), which may extend over the full table width or may cover one or more individual columns. With `txt’ conversion rough approximations of horizontal lines are used.

Tables defined by the `tbl’ macro are centered (pseudo centering (8 space characters) is used for `txt’ conversion) when used as argument of the `center’ macro.

See also the `tao’ macro for information about how to realize specific alignments for specific conversion types.

When defining `tbl’ tables it is advised to clearly layout the table specification. To avoid inadvertently introducing new lines lines should end in a backslash (or The macro `tbl’ recognizes `attrib’.

`tc(contents)’

This macro is one of the four macros that can be used to define column contents of rows of tables defined by the `tbl’ macro. Alternatively, `tnc, tac’, and `tnac’ can be used.

The `tc’ macro is used as argument of the `tr’ macro. Its order within a row defines its type attribute, using the alignment specification defined by the first argument of the `tbl’ call. E.g., if `tbl(clr)(...)’ was used, then the contents of the first `tc’ call in a `tr’ is centered in the table’s first column; the contents of the second `tc’ call is left-aligned in the table’s second column; and the contents of the third `tc’ call is right-aligned in the table’s third column.

When converting to `man’, if the table’s contents should span multiple rows, then a groff/troff(1) text block must be used. Since most tables do not use this, a text block is not generated by default. To actually wrap the contents of column elements in a text block while converting to `man’ prefix the first text block requiring a text-block wrapping by `twrap(1)’, and end the last text block requiring a text-block wrapping by `wrap(0)’.

The `tao’ macro can be used to overrule the default alignment specification for a specific conversion type.

The macro `tc’ recognizes `attrib’.

`tcell(text)’

Roff helper to set a table text-cell, i.e., a paragraph. For LaTeX special table formatting p{} should be used.

When using the `tbl’ macro for defining tables the `twrap’ macro can be used to set table elements in text-blocks (i.e., enclosing text, possibly containing newlines in `T{’ and `T}’ sequences).

`telycommand(cmd)’

Writes `cmd’ to the output when converting to tely. The `cmd’ is not further expanded by Yodl.

`TeX()’

The TeX symbol.

`texinfocommand(cmd)’

Writes `cmd’ to the output when converting to texinfo. The `cmd’ is not further expanded by Yodl.

`tindex()’

Generate an index entry for LaTex() or texinfo t-indices. Its argument is the index entry. See also the `[cfpv]index’ macro.

`titleclearpage()’

Forces a new page (using `clearpage’) following the title of a document. This is already the default in books and reports, but can be overruled using `notitleclearpage’. When present, it must appear in the preamble, i.e., before the document type is stated as article, book or report.

`tline(beginNr)(endNr)’

This macro is used to insert a horizontal line spanning one or more columns of a table defined by the `tbl’ macro.

If `endNr’ is not specified, and the `tline’ call does not follow a previous `line’ call in which `endNr’ was specified, then a horizontal line spanning the full width of the table is defined (except when converting to plain text in which case a line of `beginNr’ - (minus) characters is written; if `beginNr’ is not specified then a line of 60 - characters is written).

If `endNr’ is not specified, but the `tline’ call follows previous `tline’ calls that did specify `endNr’ then the current row is ended.

If `endNr’ is specified, then a horizontal line is set, starting at column number `beginNr’ continuing through column number `endNr’. Note that these are numbers, not offsets: `beginNr’ should be at least 1, `endNr’ must at least be equal to `beginNr’ and should be at most equal to the number of columns in the table. The `beginNr’ values of subsequent `tline’ calls refer to the same row as the first `tline’ call, and must exceed `endNr’ of the previous `tline’ call.

Examples:

```
    tline()()       sets a line spanning the full table width

    tline(1)(1)     sets a line in column 1

    tline(3)(4)     sets another line in column 3 and 4

    tline()()       ends the previous line

    tline()()       sets a line spanning the full table width

```

`tnac(nCells)(alignment)(contents)’

This macro is one of the four macros that can be used to define column contents of rows of tables defined by the `tbl’ macro. Alternatively, `tc, tac’, and `tnc’ can be used.

The `tnac’ macro is used as argument of the `tr’ macro. Its first argument defines the number of columns spanned by the contents (2nd argument) of the `tnc’ macro.

The cell’s alignment is defined by the macro’s second (`alignment’) specification, containing at most two alignment specifications: a horizontal alignment (one of c, l, r (centered, left-aligned, right-aligned)) and a vertical alignment (one of t, b (vertical top- and bottom-alignment)) (not all conversion types may support all alignment types). Specifications other than c, l, r, b, and t and specifications beyond the second one are ignored. The result of specifying conflicting alignment types (e.g., `lr’ or `tb’) is not defined.

When converting to `man’, if the table’s contents should span multiple rows, then a groff/troff(1) text block must be used. Since most tables do not use this, a text block is not generated by default. To actually wrap the contents of column elements in a text block while converting to `man’ prefix the first text block requiring a text-block wrapping by `twrap(1)’, and end the last text block requiring a text-block wrapping by `wrap(0)’. Multiple rows in a text block are top-aligned with left and righ neighboring cells.

The `tao’ macro can be used to overrule the default alignment specification for a specific conversion type.

The macro `tnac’ recognizes `attrib’.

`tnc(nCells)(contents)’

This macro is one of the four macros that can be used to define the column contents of rows of tables that are defined by the `tbl’ macro. Alternatively, `tc, tac’, and `tnac’ can be used.

The `tnc’ macro is used as argument to the `tr’ macro. Its first argument defines the number of columns spanned by the contents (2nd argument) of the `tnc’ macro. The contents are centered in the `nCells’ columns.

When converting to `man’, if the table’s contents should span multiple rows, then a groff/troff(1) text block must be used. Since most tables do not use this, a text block is not generated by default. To actually wrap the contents of column elements in a text block while converting to `man’ prefix the first text block requiring a text-block wrapping by `twrap(1)’, and end the last text block requiring a text-block wrapping by `wrap(0)’. Multiple rows in a text block are top-aligned with left and righ neighboring cells.

The `tao’ macro can be used to overrule the default alignment specification for a specific conversion type.

The macro `tc’ recognizes `attrib’.

`tocclearpage()’

With the LaTeX converter, a `clearpage()’ directive if inserted, immediately following the document’s table of contents. This is already the default in all but the `article’ document type, but it can be overruled by `notocclearpage()’. When present, it must appear in the preamble; i.e., before the document type is stated with `article’, `book’ or `report’. With other converters than the LaTeX converter, it is ignored.

`tr(contents)’

This macro defines the rows of a table that is defined by the `tbl’ macro.

The macro `tr’ expects one argument: the contents of the row, defining the row’s column elements. It is not used for defining a (partial) horizontal line: to set horizontal lines in a table defined by the `tbl’ macro use the macro `tline’.

Normally the contents of the columns in a (`tr’) row is defined by of one or more calls to the macros `tc, tac, tnc,’ and/or `tnac’.

The macro `tr’ recognizes `attrib’.

`tt(text)’

Sets `text’ in teletype font, and prevents it from being expanded. When converting to man, `text’ is surrounded by a backtick and a single quote character.

For unbalanced parameter lists, use `CHAR(40)’ to get `(’ and `CHAR(41)’ to get `)’.

The `tt’ macro does interpret character tables as well as any `SUBST’ definitions. This is usually what is intended. In situations where this is unwelcome the `ttbegin’ and `ttend’ pair of macros can be used, between which the builtin commands `PUSHSUBST, POPSUBST, NOEXPAND’ and/or `NOTRANS’ can be used. E.g., to clearly show two hyphens in LaTeX teletype font use

```
    ttbegin()--ttend()

```

rather than

```
    tt(--)

```

Likewise, use `ttbegin’ and `ttend’ if the teletype text contains accented letters like e. To set this in teletype font use `ttbegin()\"’`e+ttend()’.

With html conversions the `attrib’ macro applies to the `<code>’ tag.

With man conversions the arguments of tt macros can be quoted. See the `manttquoted’ macro for details.

`ttbegin()’

Initiates text set in teletype font. Following the text to set in teletype font a `ttend()’ macro should be called.

Usually the `tt’ macro can be used instead of the `ttbegin’ -- `ttend’ combination. However, `tt’ interprets character tables as well as `SUBST’ definitions. In situations where this is unwelcome the `ttbegin’ and `ttend’ pair of macros can be used, between which builtin commands like `PUSHSUBST, POPSUBST, NOEXPAND’ and/or `NOTRANS’ can be used.

In html the `attrib’ macro applies to the `<code>’ tag.

`ttend()’

Ends text set in teletype font following `ttbegin’. Refer to the `ttbegin’ macro’s description for details.

`twrap(value)’

Used for man/ms conversions only: when called with a non-zero argument before using the `tc, tnc, tac’, and `tnac’ macros then their contents are wrapped in text blocks (`T{ ... T}’ blocks). To end the wrapping `twrap(0)’ must be called. E.g., in the following row-definition the contents of columns three and four are set in T-blocks when converting to man/ms:

```
    tr(tc(one)tc(two)twrap(1)tc(one)tc(two)twrap(0))
```

`txtcommand(cmd)’

Writes `cmd’ to the output when converting to txt. The `cmd’ is not further expanded by Yodl.

`url(description)(locator)’

In LaTeX documents the `description’ is sent to the output. For HTML, a link is created with the descriptive text `description’ and pointing to `locator’. The `locator’ should be the full URL, including service; e.g, `http://www.icce.rug.nl’, but excluding the double quotes that are necessary in plain HTML. Use the macro `link’ to create links within the same document. For other formats, something like description [locator] will appear. In html `attrib’ macro applies to the `<a>’ tag.

`verb(text)’

Sets `text’ in verbatim mode: not subject to macro expansion or character table expansion, and starting with Yodl version 4.00.00: not using `SUBST’ definitions. See also `verborg’, which does not provide the protection against `SUBST’ definitions.

While converting Yodl-documents to target document types Yodl frequently uses the (not further documented) builtin function `XXSUBST’. In the unlikely event that the text `XXSUBST(...)’ must be written in a document, the sequence

```
    XXSUBST+CHAR(40)...CHAR(41)

```

can be used.

The text that is passed as argument to the `verb’-macro appears literally on the output, usually in a teletype font (that depends on the output format). This macro is for larger chunks, e.g., listings.

When starting the `verb(’ macro on a line by itself and writing the closing parenthesis on a line by itself then those newlines also appear in the resulting verbatim text. To omit those lines immediately start the first line of text after `verb’ and append the closing parenthesis to the last line of verbatim text. E.g.,

```
verb(    First line of indented literal text

    Last line of indented literal text)
```

When unbalanced parameter lists are required, use `CHAR(40)’ to get `(’ and `CHAR(41)’ to get `)’.

`verbinclude(filename)’

Reads filename and inserts it literally in the text, set in verbatim mode. not subject to macro expansion. The text appears literally on the output, usually in a teletype font (that depends on the output format). This macro is an alternative to `verb(...)’, when the text to set in verbatim mode is better kept in a separate file.

`verbinsert(args)’

Passes `args’ to yodlverbinsert(1), inserting its output into the converted file. This macro can be used to insert, e.g., a line-numbered indented file, or a labeled subsection of a file, into the file that’s currently being written by `yodl’. E.g,

```
verbinsert(-ans4 file)       -- inserts file, showing line

                                numbers, using a 4 blank-space

                                character wide indentation.
verbinsert(-ns4 //SECT file) -- inserts the section of file,

                                labeled //SECT file, showing

                                line numbers, using a 4

                                blank-space character wide

                                indentation.

```

`verborg(text)’

Sets `text’ in verbatim mode: not subject to macro expansion or character table expansion, and starting with Yodl version 4.00.00: this macro replaces the previosly defined `verb’ macro. The current `verb’ macro surrounds this macro by `PUSHSUBST’ and `POPSUBST’.

The text that is passed as argument to the `verborg’-macro appears literally on the output, albeit that `SUBST’ definitions are processed, usually in a teletype font (that depends on the output format). This macro is for larger chunks, e.g., listings.

When unbalanced parameter lists are required, use `CHAR(40)’ to get `(’ and `CHAR(41)’ to get `)’.

`verbpipe(command)(text)’

Pipe text through command, but don’t expand the output.

`vindex()’

Generate an index entry for LaTex() or texinfo v-indices. Its argument is the index entry. See also the `[cfkpt]index’ macro.

`whenhtml(text)’

Sends `text’ to the output when in HTML conversion mode. The text is further expanded if necessary.

`whenlatex(text)’

Sends `text’ to the output when in LATEX conversion mode. The text is further expanded if necessary.

`whenman(text)’

Sends `text’ to the output when in MAN conversion mode. The text is further expanded if necessary.

`whenms(text)’

Sends `text’ to the output when in MS conversion mode. The text is further expanded if necessary.

`whensgml(text)’

Sends `text’ to the output when in SGML conversion mode. The text is further expanded if necessary.

`whentely(text)’

Sends `text’ to the output when in TELY conversion mode. The text is further expanded if necessary.

`whentexinfo(text)’

Sends `text’ to the output when in TEXINFO conversion mode. The text is further expanded if necessary.

`whentxt(text)’

Sends `text’ to the output when in TXT conversion mode. The text is further expanded if necessary.

`whenxml(text)’

Sends `text’ to the output when in XML conversion mode. The text is further expanded if necessary.

`xit(itemname)’

Starts an xml menu item where the file to which the menu refers to is the argument of the xit() macro. It should be used as argument to xmlmenu(), which has a 3rd argument: the default path prefixed to the xit() elements.

This macro is only available within the xml-conversion mode. The argument must be a full filename, including .xml extension, if applicable.

No .xml extension indicates a subdirectory, containing another sub-menu.

`xmlcommand(cmd)’

Writes `cmd’ to the output when converting to xml. The `cmd’ is not further expanded by Yodl.

`xmlmenu(order)(title)(menulist)’

Starts an xmlmenu. Use itemization() to define the items. Only available in xml conversion. The menutitle appears in the menu as the heading of the menu. The menulist is a series of xit() elements, containing the name of the file to which the menu refers as their argument (including a final /). Prefixed to evert every xit()-element is the value of XXdocumentbase.

Order is the the `order’ of the menu. If omitted, no order is defined.

`xmlnewfile()’

In XML output, starts a new file. All other formats are not affected. Note that you must take your own provisions to access the new file; say via links. Also, it’s safe to start a new file just befoore opening a new section, since sections are accessible from the clickable table of contents. The XML converter normally only starts new files prior to a `chapter’ definition.

`xmlsetdocumentbase(name)’

Defines `name’ as the XML document base. No default. Only interpreted with xml conversions. It is used with the figure and xmlmenu macros.

`xmltag(tag)(onoff)’

Similar to `htmltag’, but used in the XML converter.

## OPTIONS
No options are relevant in respect to the macros.

## FILES
The files in tmp/wip/macros define the converter’s macro packages. The scripts yodl2tex, yodl2html, yodl2man etc. perform the conversions.

## SEE ALSO
yodl(1), yodlbuiltins(7), yodlconverters(1), yodlletter(7), yodlmanpage(7), yodlpost(1), yodlstriproff(1), yodltables(7), yodlverbinsert(1).

## BUGS
-

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


yodlmanpage

package: yodl

title: yodlmanpage(7)

summary: Yodl\(cqs `manpage\(cq document type

text:
# yodlmanpage(7)

## NAME
yodlmanpage - Yodl’s `manpage’ document type

## SYNOPSIS
The manpage document type was specifically implemented to write Unix-style manual pages. Other Yodl document formats, such as article, report and book are documented in the Yodl guide and in the manpage for yodlmacros.

## DESCRIPTION
This manual page briefly describes the manpage document type of the Yodl document language. This document type is specific enough that it warrants a separate manpage.

Yodl mapage documents can be converted to `groff’ documents (using `yodl2man’), to `html’ documents (using `yodl2html’), or to plain ascii text documents (using `yodl2txt’).

manpage documents do not use the `standard’ sectioning commands (e.g., sect() and subsect()), but have specific manpage...() macros. You can however use (and are encouraged to..) other `normal’ macros, such as description(...) or itemization(...) for lists, or bf() for boldface and em() for emphasis. As for fonts, the following is suggested:

o

Use em(text) when text is a variable, or a placeholder, etc..

o

Use bf(text) when text is literal, such as a command, a filename, a directory. Each manpage document in Yodl must be organized as follows:

o

manpage(name) (section) (date) (package) (source): This is the preamble of the document. It states whatever the page describes, the section where it belongs, the release date, the package that it belongs to, and the source of the package. The section number should be (according to the Linux manpage on man): 1 for commands, 2 for system calls, 3 for library calls, 4 for special files, 5 for file formats, 6 for games, 7 for macro packages and conventions, 8 for system management commands, and 9 for other special subjects (e.g., kernel commands).

o

manpagename(name) (short description): The name is again whatever is described, the short description is what e.g., the whatis database uses for descriptions.

o

manpagesynopsis(): a very short `usage’ information or similar. Keep this section short, e.g., a line with all program options is acceptable but without descriptions (these come later).

o

manpagedescription(): the purpose of the program and such. This is also the place to document the workings.

o

manpageoptions(): This is the place to document e.g. the flags that are stated in the manpagesynopsis(). This section is optional, but when present, must appear at this place.

o

manpagefiles(): relevant files are described in this section.

o

manpageseealso(): this section lists related manual pages.

o

manpagediagnostics(): Error conditions, error messages, etc..

o

manpagebugs(): This is where known bugs are described. This section is optional.

o

manpageauthor(): stating the author and/or the maintainer.

o

manpagesection(NAME): This macro starts a generic, non-required section. E.g., you might want a manpagesection(EXAMPLES) in your document. As a typographic suggestion, use upper case for the NAME argument for consistency reasons.

## SEE ALSO
yodl(1), yodlbuiltins(7), yodlconverters(1), yodlletter(7), yodlmacros(7), yodlpost(1), yodlstriproff(1), yodltables(7), yodlverbinsert(1).

## BUGS
-

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


yodltables

title: yodltables(7)

summary: Yodl\(cqs table support

text:
# yodltables(7)

## NAME
yodltables - Yodl’s table support

## SYNOPSIS
Tables are preferably defined using the `tbl’ macro, although the `table’ macro remains available. The macros that are used in combination with `tbl’ are described in this man-page and also in the yodlmacros(7) man-page. The macros that are used in combination with the `table’ macros are described in the yodlmacros(7) man-page only.

## DESCRIPTION
o

To start a table the `tbl’ macro is used. It is currently available for `html, man/ms, latex’ and `txt’ conversions. When specifying `tbl’ as an argument of the `center’ macro, the resulting table will be centered on the page or html screen. In text mode centering is simulated by starting each row with eight blank space characters.

Its first argument defines the alignment of the information in the table’s columns, and is used by all conversions except `txt’. Use `l’ for left-alignment, `c’ for centered-alignment and `r’ for right-alignment. Individual cells of the table may override these default settings using the macros `tac’ and `tnac’.

Its second argument defines the contents of the table consisting of rows (using `tr’), and horizontal lines (using `tline’), which may extend over the full table width or may cover one or more individual columns. With `txt’ conversion rough approximations of horizontal lines are used.

When defining tables it is advised to clearly layout the table specification. To avoid inadvertently introducing new lines lines should end in a backslash (or comment).

Example:

```
tbl(lcr)(\// 3 columns, resp. left, center and right aligned

    \// contents go here
)\

```

The macro `tbl’ recognizes `attrib’.

o

Rows of a table are defined by the `tr’-macro. It expects one argument: the contents of the row, defining the row’s column elements. Instead of rows defining column elements (partial) horizontal lines may be inserted. The `tline’ macro is used for that (see below).

Example:

```
tbl(lcr)(\

    tr(\//              1st row

        \// row elements go here

    )\

    tr(\//              2nd row

        \// row elements go here

    )\
)\

```

The macro `tr’ recognizes `attrib’.

o

Column elements are defined by the `tc, tn, tac,’ and `tnac’ macros. Each of these macros recognizes `attrib’.

o

The `tc’ macro defines the contents of column element: its order number in a row is aligned as specified by the corresponding letter in `tbl’s’ first argument. E.g.,

```
tbl(lcr)(\

    tr(\

       tc(left aligned)\

       tc(centered)\

       tc(right aligned)\

    )\
)\

```

o

The `tnc’ macro defines the contents of column element. It expects two arguments: the number of columns covered by this macro, and the contents of those elements. The contents are centered in the rows covered by the `tnc’ macro. E.g.,

```
tbl(lcr)(\

    tr(\

       tc(left aligned)\

       tnc(2)(centered)\//    spans columns 2 and 3.

    )\
)\

```

o

The `tac’ macro defines the contents of column element, defining a specific alignment for its contents. It expects two arguments: the alignment to be used for this element and the element’s contents.

At most two alignment specification characters are used: a specification for the horizontal alignment (one of c, l, r (centered, left-aligned, right-aligned)) and a specification for the vertical alignment (one of t, b (vertical top- and bottom-alignment)) (not all conversion types may support all alignment types). Specifications other than c, l, r, b, and t are ignored. If only a vertical alignment type is specified, then usually the horizontal centered alignment is used. As a rule of thumb always also specify a horizontal alignment type if a vertical alignment type is specified. The result of specifying conflicting alignment types (e.g., `lr’ or `tb’) is not defined.

Vertical alignment is handled differently by different conversion types. E.g., when table cells span multiple lines then LaTeX uses the vertical alignment specification for that cell to align the neighboring cells: with LaTeX conversions the following aligns `rows’ and `second’:

```
tac(b)(two+nl()rows)
tc(second)

```

but with html-conversions `second’ is vertically center-aligned: in between `two’ and `rows’. Bottom line: provide each column element in a row that you want to be top- or bottom-aligned with a `t’ or `b’ specification.

When using man-conversions the situation is complex in that bottom alignment does not appear to be supported. Moreover, unless long lines are wrapped in `text blocks’ (see below at `twrap’) there won’t be any wrapping of long lines. The same holds true for LaTeX conversions, but with LaTeX columns may be given fixed physical widths, resulting in automatically wrapping long lines. Also, bottom alignment appears not to be supported when converting to man. At this point bottom alignment when converting to man is realized by defining a separate table row containing the last contents of a long line. This may require some iterations. The specification could then look somewhat like this (again: for `twrap’ see below):

```
tbl(lr)(\

    tr(\

        twrap(1)\

        tac(lb)(Lorem ipsum dolor sit amet,

                consectetur adipiscing elit, sed

                do eiusmod tempor incididunt ut

                labore et dolore magna aliqua.)\

        twrap(0)\

        tc()\//           empty cell

    )\

    tr(\//                simulated bottom alignment,

        tac(l)(Ut enim ad minim veniam)\

        tac(rb)(left)\

    )\
)\

```

In some cases (e.g., using LaTeX conversions where a column width must be specified) more elaborate alignment specifications are required. For that the `tao’ (table alignment override) and `twrap’ macros are available (see below).

E.g.,

```
tbl(lcr)(\

    tr(\

       tc(left aligned)\

       tac(l)(left aligned)\// left alignment instead

                           \// of centered

       tac(rb)(left+nl()aligned)\// right-bottom

                           \// alignment

    )\
)\

```

o

The `tnac’ macro defines the contents of column element, defining a specific alignment for its contents. It expects three arguments: the number of columns spanned by the contents of this macro, the alignment to be used and the element’s contents.

The alignment specifications and considerations are the same as with the `tac’ macro: see `tac’s’ description for the details.

## HORIZONTAL LINES
Horizontal lines (partially) spanning the width of tables defined by the `tbl’ macro are defined using the `tline’ macro. The `tline’ macro expects two arguments:

o

If both arguments are specified, then the first argument defines the column number (so, not the column offset!) where a horizontal line must start, and the second argument defines the column number through where the horizontal line should continue. If a series of `tline’ macros is specified then the first argument of the first `tline’ macro call must be at least 1; the second argument of the last `tline’ macro call must be at most equal to the table’s number of columns. In addition the second arguments of `tline’ calls must at least be equal to their first arguments, and the first arguments of subsequent `tline’ calls must exceed the value of the second argument of the preceding `tline’ macro call. A series of (at least one) `line’ calls in which both arguments are specified must be followed by a `tline’ call with two empty arguments. For example:

```
tbl(ccccc)(\

    tr(... row contents )\

    tline(1)(1)\//    horizontal line at column 1

    tline(3)(4)\//    horizontal line at columns 3 and 4

    tline()()\//      now defined.

    tr(... row contents )\
)\

```

o

Except for ending a series of `tline’ calls in which both arguments are specified, a `tline’ call not specifying its second argument sets a line over the full width of the table. In that case, when converting to txt a line of 60 minus (`-’) characters is written. If another number of minus characters is required then specify the required number as `tline’s’ first argument. When using other conversion types `tline’s’ first argument is ignored if its second argument is empty. Here is the previous example again, this time setting a horizontal line before and after the table’s contents:

```
tbl(ccccc)(\

    tline()()\//      horizontal line spanning the full width

    tr(... row contents )\

    tline(1)(1)\//    horizontal line at column 1

    tline(3)(4)\//    horizontal line at columns 3 and 4

    tline()()\//      now defined.

    tr(... row contents )\

    tline()()\//      horizontal line spanning the full width
)\

```

## SUPPORT MACROS

Two support macros are available: `twrap’ for wrapping the contents of a cell in a `text block’ when converting to man, and `tao’ (table alignment override) for overriding a cell’s alignment specification for a specific conversion type.

The twrap macro

The `twrap’ macro is only interpreted when converting to man. It expects one numeric argument. If zero then the table’s cells are used as specified; if non-zero then the table’s cells are wrapped in groff/troff text blocks.

If no text block is specified (i.e., `twrap(0)’ (the default) is in effect) and a cell contains a long line the long line will continue on one physical line, disproportionally widening that cell’s column; when using newlines are used in cell contents, and horizontal lines are used the resulting table may set the horizontal lines at unexpected rows.

When requesting text blocks (i.e., `twrap(1)’ was specified) long lines are automatically split up in lines of reasonable widths, and they will be left-aligned in their columns. Those long lines may also contain explicit newline macros, forcing new lines at user-defined positions.

Once a `twrap’ has been called, it remains in effect until the next `twrap’ call is encountered.

The tao macro

The `tao’ macro (table alignment override) is used to override the alignment specification that would otherwise be used for the next table element. It is only active for the next `tc, tnc, tac,’ or `tnac’ call. It expect two arguments: its first argument defines the conversion type for which the override should be used, its second argument defines the alignment specification to use.

Here are some examples:

```
tbl(lr)(\

    tr(\

        tc(left aligned)\

        tc(right aligned)\

    )\

    tr(\

        tao(html)(c)\

          tc(left aligned, except with html: then centered)\

        tao(latex)(l)tao(man)(l)\

          tac(c)(centered, but left aligned for latex and man)\

    )\
)

```

o

Details when converting to html:

The `t’ and `b’ specifications can be used to respectively top- and bottom-align cells in a table row. Usually `tao’ doesn’t have to be used, as the `tac’ macro already provides facilities for aligning cell contents. E.g., `tac(cb)(...)’ centers the contents, and aligns its bottom line with the remaining cells on its line.

o

Details when converting to LaTeX:

To request a top-aligned table element of a specified width (e.g., 4 cm.) the following `tao’ specification can be used:

```
tao(latex)(NOTRANS(t{p{4cm}}))

```

Similarly, for a center-aligned element use `c{p{4cm}}’. But to align the bottom-line of a multi-line element with its neighboring cells use

```
tao(latex)(NOTRANS(b{b{4cm}}))

```

(combinations are also possible: if one cell uses top alignment, and another bottom alignment, then the top line of the former cell and the bottom line of the latter cell appear on the same physical line).

Alternatively, instead of using fixed widths explicit newlines can be used. In that case, a specification like `tao(latex)(rb)’ will align its bottom line with the other cells in its row, while right-aligning its contents.

When a fixed width is specified for a cell, then other cells in its column not automatically also use that width. If other cells should also use a fixed width they must explicitly specify their widths.

## SEE ALSO

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

## BUGS

-

## AUTHOR

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


dracut.zfs

package: zfs-utils

title: dracut.zfs(7)

summary: overview of ZFS dracut hooks

text:
# dracut.zfs(7)

## NAME
dracut.zfs — overview of ZFS dracut hooks

## SYNOPSIS

```
                      parse-zfs.sh → dracut-cmdline.service
                          |                     ↓
                          |                     …
                          |                     ↓
                          \————————→ dracut-initqueue.service
                                                |                      zfs-import-opts.sh
   zfs-load-module.service                      ↓                          |       |
     |                  |                sysinit.target                    ↓       |
     ↓                  |                       |        zfs-import-scan.service   ↓
zfs-import-scan.service ↓                       ↓           | zfs-import-cache.service
     |   zfs-import-cache.service         basic.target      |     |
     \__________________|                       |           ↓     ↓
                        ↓                       |     zfs-load-key.sh
     zfs-env-bootfs.service                     |         |
                        ↓                       ↓         ↓
                 zfs-import.target → dracut-pre-mount.service
                        |          ↑            |
                        | dracut-zfs-generator  |
                        | _____________________/|
                        |/                      ↓
                        |                   sysroot.mount ←——— dracut-zfs-generator
                        |                       |
                        |                       ↓
                        |             initrd-root-fs.target ←— zfs-nonroot-necessities.service
                        |                       |                                 |
                        |                       ↓                                 |
                        ↓             dracut-mount.service                        |
       zfs-snapshot-bootfs.service              |                                 |
                        |                       ↓                                 |
                        ↓                       …                                 |
       zfs-rollback-bootfs.service              |                                 |
                        |                       ↓                                 |
                        |          /sysroot/{usr,etc,lib,&c.} ←———————————————————/
                        |                       |
                        |                       ↓
                        |                initrd-fs.target
                        \______________________ |
                                               \|
                                                ↓
        export-zfs.sh                      initrd.target
              |                                 |
              ↓                                 ↓
   dracut-shutdown.service                      …
                                                |
                                                ↓
                 zfs-needshutdown.sh → initrd-cleanup.service
```

Compare dracut.bootup(7) for the full flowchart.

## DESCRIPTION
Under dracut, booting with ZFS-on-/ is facilitated by a number of hooks in the 90zfs module.

Booting into a ZFS dataset requires mountpoint=/ to be set on the dataset containing the root filesystem (henceforth "the boot dataset") and at the very least either the bootfs property to be set to that dataset, or the root= kernel cmdline (or dracut drop-in) argument to specify it.

All children of the boot dataset with canmount=on with mountpoints matching /etc, /bin, /lib, /lib??, /libx32, and /usr globs are deemed essential and will be mounted as well.

zfs-mount-generator(8) is recommended for proper functioning of the system afterward (correct mount properties, remounting, &c.).

## CMDLINE

### Standard
root=zfs:dataset, root=ZFS=dataset

Use dataset as the boot dataset. All pluses (‘+’) are replaced with spaces (‘ ’).

root=zfs:AUTO, root=zfs:, root=zfs, [root=]

After import, search for the first pool with the bootfs property set, use its value as-if specified as the dataset above.

rootfstype=zfs root=dataset

Equivalent to root=zfs:dataset.

rootfstype=zfs [root=]

Equivalent to root=zfs:AUTO.

rootflags=flags

Mount the boot dataset with -o flags; cf. Temporary Mount Point Properties in zfsprops(7). These properties will not last, since all filesystems will be re-mounted from the real root.

debug

If specified, dracut-zfs-generator logs to the journal.

Be careful about setting neither rootfstype=zfs nor root=zfs:dataset — other automatic boot selection methods, like systemd-gpt-auto-generator and systemd-fstab-generator might take precedent.

### ZFS-specific
bootfs.snapshot[=snapshot-name]

Execute zfs snapshot boot-dataset@snapshot-name before pivoting to the real root. snapshot-name defaults to the current kernel release.

bootfs.rollback[=snapshot-name]

Execute zfs rollback -Rf boot-dataset@snapshot-name before pivoting to the real root. snapshot-name defaults to the current kernel release.

spl_hostid=host-id

Use zgenhostid(8) to set the host ID to host-id; otherwise, /etc/hostid inherited from the real root is used.

zfs_force, zfs.force, zfsforce

Appends -f to all zpool import invocations; primarily useful in conjunction with spl_hostid=, or if no host ID was inherited.

## FILES
parse-zfs.sh (cmdline)

Processes spl_hostid=. If root= matches a known pattern, above, provides /dev/root and delays the initqueue until zfs(4) is loaded,

zfs-import-opts.sh (systemd environment generator)

Turns zfs_force, zfs.force, or zfsforce into ZPOOL_IMPORT_OPTS=-f for zfs-import-scan.service or zfs-import-cache.service.

zfs-load-key.sh (pre-mount)

Loads encryption keys for the boot dataset and its essential descendants. keylocation=prompt

Is prompted for via systemd-ask-password thrice.

keylocation=https://URL, keylocation=http://URL

network-online.target is started before loading.

keylocation=file://path

If path doesn't exist, udevadm is settled. If it still doesn't, it's waited for for up to 10s.

zfs-env-bootfs.service (systemd service)

After pool import, sets BOOTFS= in the systemd environment to the first non-null bootfs value in iteration order.

dracut-zfs-generator (systemd generator)

Generates sysroot.mount (using rootflags=, if any). If an explicit boot dataset was specified, also generates essential mountpoints (sysroot-etc.mount, sysroot-bin.mount, &c.), otherwise generates zfs-nonroot-necessities.service which mounts them explicitly after /sysroot using BOOTFS=.

zfs-snapshot-bootfs.service, zfs-rollback-bootfs.service (systemd services)

Consume bootfs.snapshot and bootfs.rollback as described in CMDLINE. Use BOOTFS= if no explicit boot dataset was specified.

zfs-needshutdown.sh (cleanup)

If any pools were imported, signals that shutdown hooks are required.

export-zfs.sh (shutdown)

Forcibly exports all pools.

/etc/hostid, /etc/zfs/zpool.cache, /etc/zfs/vdev_id.conf (regular files)

Included verbatim, hostonly.

mount-zfs.sh (mount)

Does nothing on systemd systems (if dracut-zfs-generator succeeded). Otherwise, loads encryption key for the boot dataset from the console or via plymouth. It may not work at all!

## SEE ALSO
dracut.bootup(7), zfsprops(7), zpoolprops(7), dracut-shutdown.service(8), systemd-fstab-generator(8), systemd-gpt-auto-generator(8), zfs-mount-generator(8), zgenhostid(8)


vdevprops

title: vdevprops(7)

text:
# vdevprops(7)

## NAME
vdevprops — native and user-defined properties of ZFS vdevs

## DESCRIPTION
Properties are divided into two types, native properties and user-defined (or "user") properties. Native properties either export internal statistics or control ZFS behavior. In addition, native properties are either editable or read-only. User properties have no effect on ZFS behavior, but you can use them to annotate vdevs in a way that is meaningful in your environment. For more information about user properties, see the User Properties section, below.

### Native Properties
Every vdev has a set of properties that export statistics about the vdev as well as control various behaviors. Properties are not inherited from top-level vdevs, with the exception of checksum_n, checksum_t, io_n, io_t, slow_io_events, slow_io_n, and slow_io_t.

The values of numeric properties can be specified using human-readable suffixes (for example, k, KB, M, Gb, and so forth, up to Z for zettabyte). The following are all valid (and equal) specifications: 1536M, 1.5g, 1.50GB.

The values of non-numeric properties are case sensitive and must be lowercase.

The following native properties consist of read-only statistics about the vdev. These properties can not be changed.

capacity

Percentage of vdev space used

state

state of this vdev such as online, faulted, or offline

guid

globally unique id of this vdev

asize

The allocatable size of this vdev

psize

The physical size of this vdev

ashift

The physical sector size of this vdev expressed as the power of two

size

The total size of this vdev

free

The amount of remaining free space on this vdev

allocated

The amount of allocated space on this vdev

expandsize

How much this vdev can expand by

fragmentation

Percent of fragmentation in this vdev

parity

The level of parity for this vdev

devid

The device id for this vdev

physpath

The physical path to the device

encpath

The enclosure path to the device

fru

Field Replaceable Unit, usually a model number

parent

Parent of this vdev

children

Comma separated list of children of this vdev

numchildren

The number of children belonging to this vdev

read_errors, write_errors, checksum_errors, initialize_errors, trim_errors

The number of errors of each type encountered by this vdev

slow_ios

This indicates the number of slow I/O operations encountered by this vdev. A slow I/O is defined as an operation that did not complete within the zio_slow_io_ms threshold in milliseconds (30000 by default). For RAIDZ and DRAID configurations, this value also represents the number of times the vdev was identified as an outlier and excluded from participating in read I/O operations.

null_ops, read_ops, write_ops, free_ops, claim_ops, trim_ops

The number of I/O operations of each type performed by this vdev

null_bytes, read_bytes, write_bytes, free_bytes, claim_bytes, trim_bytes

The cumulative size of all operations of each type performed by this vdev

removing

If this device is currently being removed from the pool

trim_support

Indicates if a leaf device supports trim operations.

The following native properties can be used to change the behavior of a vdev.

checksum_n, checksum_t, io_n, io_t, slow_io_n, slow_io_t

Tune the fault management daemon by specifying checksum/io thresholds of <N> errors in <T> seconds, respectively. These properties can be set on leaf and top-level vdevs. When the property is set on the leaf and top-level vdev, the value of the leaf vdev will be used. If the property is only set on the top-level vdev, this value will be used. The value of these properties do not persist across vdev replacement. For this reason, it is advisable to set the property on the top-level vdev - not on the leaf vdev itself. The default values for OpenZFS on Linux are 10 errors in 600 seconds. For OpenZFS on FreeBSD defaults see zfsd(8). The

slow_io_events

property controls whether slow I/O events are generated. Even when disabled, slow I/Os will be included in the zpool status -s output.

comment

A text comment up to 8192 characters long

bootsize

The amount of space to reserve for the EFI system partition

failfast

If this device should propagate BIO errors back to ZFS, used to disable failfast.

sit_out

Only valid for RAIDZ and DRAID vdevs. True when a slow disk outlier was detected and the vdev is currently in a sit out state. This property can be manually set to cause vdevs to sit out. It will also be automatically set by the autosit logic if that is enabled. While sitting out, the vdev will not participate in normal reads, instead its data will be reconstructed as needed from parity.

autosit

Only valid for RAIDZ and DRAID vdevs. If set, this enables the kernel-level slow disk detection logic. This logic automatically causes any vdevs that are significant negative performance outliers to sit out, as described in the sit_out property.

path

The path to the device for this vdev

allocating

If this device should perform new allocations, used to disable a device when it is scheduled for later removal. See zpool-remove(8).

### User Properties
In addition to the standard native properties, ZFS supports arbitrary user properties. User properties have no effect on ZFS behavior, but applications or administrators can use them to annotate vdevs.

User property names must contain a colon (":") character to distinguish them from native properties. They may contain lowercase letters, numbers, and the following punctuation characters: colon (":"), dash ("-"), period ("."), and underscore ("_"). The expected convention is that the property name is divided into two portions such as module:property, but this namespace is not enforced by ZFS. User property names can be at most 256 characters, and cannot begin with a dash ("-").

When making programmatic use of user properties, it is strongly suggested to use a reversed DNS domain name for the module component of property names to reduce the chance that two independently-developed packages use the same property name for different purposes.

The values of user properties are arbitrary strings and are never validated. Use the zpool set command with a blank value to clear a user property. Property values are limited to 8192 bytes.

## SEE ALSO
zpoolprops(7), zpool-set(8)