Yodl macros(7)

NAME
yodlmacros - Macros for the Yodl converters

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

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

abstract(text)
    Defines an abstract for an article or report document. Abstracts are not implemented for books or manpages. Must appear before starting the document with the article or report macro.

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.

appendix()
    Start 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.

bind(text)
    Issue binding char after text.

bf(text)
    Sets text in boldface.

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.

center(text)
    Sets text centered, when the output format permits. Use nl() in the text to break lines.

chapter(title)
    Starts a new chapter in books or reports.

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

cite(1)
    Citation

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

setlatexverbchar(char)
    Set the char used to quote latex() \verb sequences

setrofftableoptions(optionlist)
    Set the options for tbl table, default: allbox

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 ).

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 descriptive list. The list is either enclosed by startdit() and enddit(), or is an argument to description().

ellipsis()
    Set ellipsis.

eit()
    Indicates an item in an enumerated list. The list is either enclosed by starteit() and endeit(), or is an argument to enumerate().

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.

nemail(name)(address)
    Named email (duh). A more consistent naming for url, lurl, email an nemail would be nice.

endcenter()
    Ends centered text that is started with startcenter().

enddit()
    Ends a descriptive list that is started with startdit().

endeit()
    Ends an enumerated list that is started with starteit().

endit()
    Ends an itemized list that is started with startit().

endmenu()
    DEPRECATED Ends a menu that is started with startmenu().

enumerate(list)
    Sets list as an enumerated list. Use eit() to indicate items in the list.

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: YODL will supply .gif when in HTML mode, or .ps when in LaTeX mode. Figures in other modes are not (yet) implemented.

file(text)
    Sets text as filename, usually boldface.

footnote(text)
    Sets text as a footnote, or in 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). Synonym for 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().

htmlbodyopt(option)(value)
    Adds option="value" to the options of the <body ...> tag in HTML files. Useful options are, e.g., fgcolor and bgcolor, whose values are expressed as #rrggbb, where rr are two hexadecimal digits of the red component, gg two hexadecimal digits of the green component, and bb two hexadecimal digits of the blue component.

htmlcommand(cmd)
    Sets cmd when converting to HTML. The cmd is not further parsed by YODL.

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.

htmltag(tagname)(start)
    Sets tagname as a HTML tag, enclosed by < and >. When start is zero, the tagname is prefixed with /.

includefile(file)
    Includes file and defines a label with the same name. The default extension .yo is supplied if necessary.

includeverbatim(file)
    Include file into the output. No processing is done, file should be in preformatted form, e.g.:

    whenhtml(includeverbatim(foo.html))

    .

cindex()
    Generate an index entry for index c.

findex()
    Generate an index entry for index f.

kindex()
    Generate an index entry for index k.

pindex()
    Generate an index entry for index p.

tindex()
    Generate an index entry for index t.

vindex()
    Generate an index entry for index v.

it()
    Indicates an item in an itemized list. The list is either surrounded by startit() and endit(), or it is an argument to itemize().

mit()
    DEPRECATED Indicates an item in a menu. The menu is surrounded by startmenu() and endmenu().

itemize(list)
    Sets list as an itemized list. Use it() to indicate items in the list.

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.

LaTeX()
    The LaTeX symbol.

latexcommand(cmd)
    Writes cmd 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 incase 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.

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..

latexoptions(options)
    Set latex options: documentclass[options]. Junk this? This command must appear before the document type is stated by article, report, etc..

latexlayoutcmds(latexcommands)
    This macro is provided incase you want to put your own LaTeX layout commands into LaTeX output. The latexcommands 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.

langle()
    Char langle

rangle()
    Char rangle

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. 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. For output formats other than HTML, only the description and the label value appears.

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

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.

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.

makeindex()
    Make index for latex (urg).

mbox()
    Inbreakable box. The roff command, anyone?

menu(list)
    DEPRICATED Sets list as a menu.

metaCOMMENT(text)
    Put a comment in the output.

metalC(text)
    Put a line comment in the output. FIXME: howto check if text has line breaks?

mscommand(cmd)
    Writes cmd to the output when converting to ms. The cmd is not further expanded by YODL.

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.

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

node(previous)(this)(next)(up)
    DEPRECATED Defines a node with name this, and links to nodes previous, next and (up), for the node command.

nodename(text)
     Use text as name for the next node, e.g.

    nodename(Options)manpagesynopsis()

    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.

nop(text)
    Expand to text, to avoid spaces before macros e.g.: a.

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()
    Prevents the generation of a clearpage() instruction after the typesetting of a table of contents. This instruction is default in all documents. When present, must appear before stating the document type with article, book or report.

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 é) 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.

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.

nsubsect(title)
    Starts a non-numbered subsection.

nsubsubsect(title)
    Starts a non-numbered sub-subsection.

nsubsubsubsect(title)
    Starts a non-numbered sub-sub-subsection.

paragraph(title)
    Starts a parapgraph. This level of sectioning is not numbered, in contrast to `higher' sectionings (duh, corresponds to subparagraph in latex).

part(title)
    Starts a new part in a book document.

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 (urg).

quote(text)
    Sets the text as a quotation. Usually, the text is indented, depending on the output format.

redef(macro)(nrofarguments)(redefinition)
    Defines macro macro to expand to redefinition. Similar to def, but any pre-existing definition is overruled. This command is a shorthand for redefinemacro.

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

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.

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, set following the dotcmd on the same line; secondline - when not empty, set on the next line; thirdline - when not empty, set on the third line. Note that dotcmd and thirdline are not further expanded by YODL, the other arguments are.

sc(text)
    Set text in small caps (or tt).

sect(title)
    Starts a new section.

lsect(label)(title)
    Starts a new section, setting a label at the beginning of the section.

setaffilstring(name)
    Defines name as the `affiliation information' string, by default AFFILIATION INFORMATION. E.g., after setaffilstring(AFILIAÇÃO), YODL outputs this portuguese 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.

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 .gif. Note that a leading dot must be included in ext. The new extension takes effect starting with the following usage of the figure macro.

sethtmlfigurealign(alignment)
    Redefines the alignment for figures in HTML. The default is bottom. Other options depend on the client browser, but top and center should be universal.

setlanguage(language)
    Sets the language to language. Currentley supported languages english and portuguese.

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.

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.

settitlestring(name)
    Defines name as the `title information' string, by default TITLE INFORMATION. E.g., after settitlestring(TÍTULO), YODL outputs this portuguese 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.

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..

startcenter()
    Starts centered text. Use endcenter() to stop centering text.

startdit()
    Starts a descriptive list. Use dit(item) to set items in the list, and use enddit() to end the list.

starteit()
    Starts an enumerated list. Use eit() in the list to indicate items, and use endeit() to end the list.

startit()
    Starts an itemized list. Use it() in the list to indicate items, and use endit() to end the list.

startmenu()
    DEPRECATED Starts a menu. Use mit() in the menu to indicate menu items, and use endmenu() to end the menu.

sups(text)
    Set superscript...

subs(text)
    Set subscript

subsect(title)
    Starts a new subsection. Other sectioning commands are subsubsect and subsubsubsect.

lsubsect(label)(title)
    Starts a new subsection. Other sectioning commands are subsubsect and subsubsubsect. A label is added just before the subsection.

subsubsect(title)
    Starts a sub-subsection.

lsubsubsect(label)(title)
    Starts a sub-subsection, a label is added just before the section

subsubsubsect(title)
    Starts a sub-sub-sub-subsection. This level of sectioning is not numbered, in contrast to `higher' sectionings.

lsubsubsubsect(label)(title)
    Starts a sub-sub-sub-subsection. This level of sectioning is not numbered, in contrast to `higher' sectionings. A label is added just before the subsubsubection.

texinfocommand(cmd)
    Writes cmd to the output when converting to Texinfo. The cmd is not further expanded by YODL.

TeX()
    The TeX symbol.

titleclearpage()
    Forces the generation of a clearpage() directive following the title of a document. This is already the default in books and reports, but can be overruled with notitleclearpage(). When present, must appear in the preamble; i.e., before the document type is stated with article, book or report.

tocclearpage()
    Forces the generation of a clearpage() directive following the table of contents in a document. This is already the default in all document types, but can be overruled with notocclearpage(). When present, must appear in the preamble; i.e., before the document type is stated with article, book or report.

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

txtcommand(cmd)
    Writes cmd to the output when converting to ASCII. 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.

lurl(locator)
    An url described by its Locator. For small urls with readable addresses.

verb(text)
    Sets text in verbatim mode: not subject to macro expansion or character table expansion. The text 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. For unbalanced parameter lists, 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.

verbpipe(command)(text)
    Pipe text through command, but don't expand the output.

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.

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 ASCII conversion mode. The text is further expanded if necessary.

starttable(nColumns)(LaTexAllignment)
    The arguments are the number of columns in the table, and the alignment specifications for LaTeX, which should consist of nColumns characters (l, r, or c). It is used internally by table()

endtable()
    This macro ends the definition of a table. It is used internally by table()

table(nColumns)(LaTeXallignment)(Contents)
    The table()-macro defines a table. Its first argument specifies the number of columns in the table. Its second argument specifies the LaTeX-alignment specifications: use l for left-alignment, r for right alignment, c for centered-alignment. The third argument defines the contents of the table which are the rows, each containing column-specifications.

row(Cells)
    The argument Cells contains the cells of one row of the table

cell(element)
    Set a table cell, i.e., one element in a row.

tcell(text)
    Roff helper to set a table textcell, i.e., a paragraph. For special table formatting p{} should be used.

cells(nColumns)(element)
    Set a table cell centered over nColumns columns. See also leftcells() and rightcells().

columnline(from)(to)
    Sets a horizontal line over a column in a row. See also rowline().

rowline()
    Sets a horizontal line over the width of the table. See also cellsline().

OPTIONS
No options are relevant in respect to the macros.

FILES
The files in /usr/local/lib/yodl/ define the macro package of the converter. The scripts yodl2tex, yodl2html, yodl2man etc. run the conversions.

SEE ALSO

o   yodl: the main Yodl converter

o   yodlmanpage: more detailed description of the manpage format

o   yodlconverters: divers converters for divers output formats

DIAGNOSTICS
Error messages and warnings are printed to stderr. There are too many warnings or error messages to enumerate, but they should be self-explanatory.

BUGS
The macro package may contain bugs, but I'm working on it. Furthermore, the macro package may not be complete.

AUTHOR
Karel Kubat (karel@icce.rug.nl)