Provided by: yodl_1.31.18-7_i386

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

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.

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

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

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

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.

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

manpagesynopsis()
Starts the SYNOPSIS entry in a manpage document.

makeindex()
Make index for latex (urg).

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

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

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

nsect(title)
Starts a section, but does not  generate  a  number  before  the
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)
of Contents. E.g., after settocstring(Inhalt),  YODL  identifies
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.

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
formats, something like description [locator] will appear.

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

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

#### SEEALSO

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)