aephea-ref(7) MISCELLANEOUS aephea-ref(7)
NAME
aephea-ref - A description of the Aephea definitions for referencing
DESCRIPTION
The following definitions are used by the Aephea simpledocument class as well as the Portable Unix Documentation (pud) manual and faq
classes (see pud-man(7) and pud-faq(7)).
MACROS
efload#2
efloadx#2
Both macros take as first argument a label that uniquely defines the reference. The second argument is a vararg containing key-value
pairs.
These macros are usually not needed in Aephea classes; they are lower level facilities.
ef#2
The first argument is a label. The second argument should be a key associated with that label. The result is the value associated with the
label/key pair.
These macros are usually not needed in Aephea classes; they are lower level facilities used by high level Aephea definitions (e.g.
iref#2, and secref#1).
efcaption#1
efnumber#1
eflevel#1
The argument is a label. The result is respectively the caption, number, or level associated with that label.
eference#1
efer#1
The first associates a number with the label that is in the first argument, and prints it inbeween square brackets. The label is anchored
to this location. The second outputs the associated number inbetween brackets, and makes it carry a link to the anchor. For example, I am
about to create a link [1] and another link [2] to the items appearing below.
[1] The first reference.
[2] The second reference.
If you prefer another bibliography style, find the macros and adapt them according to your needs - they are very simple.
eference#2 currently writes data to the file \__fnbase__.zmr, to be read back in using a load{\__fnbase__.zmr} statement. This is
automatically done when using any of the Aephea classes.
aephea-ref 1.002, 10-008 8 Jan 2010 aephea-ref(7)
Check Out this Related Man Page
pud-man(7) MISCELLANEOUS pud-man(7)
NAME
pud-man - A description of the Portable Unix Documentation Language for writing manual pages
DESCRIPTION
This document describes the Portable Unix Documentation (PUD) manual page mini-language. PUD-man is built on top of the macro interpreter
zoem. A PUD document is generally well-structured, relatively free of formatting statements, compact to write and easily extendable. It can
be converted to both troff and html, for viewing in terminals and browsers. High quality Postscript and plain text formats can be derived
from the troff output.
Write your own manual pages by copying the example page buzzz.azm and modifying it to your needs. If you are documenting foo, the usual
approach is to create foo.azm, and from that create foo.1 and foo.html as follows:
zoem -i foo -d html
zoem -i foo -d html
zoem -i foo -d roff -o foo.1
zoem -i foo -d roff -o foo.1
This generates files foo.html and foo.1. Each device is run twice to be certain that references are found and linked. PostScript and text
versions can be made from foo.1 as follows:
groff -man foo.1 > foo.ps
groff -t -e -mandoc -Tascii foo.1 | col -bx > foo.txt
Note though that foo.1 does not use any groff specific extensions; it should be acceptable input to ancient roffs as well. Exceptions to
this imply a bug in the PUD man macros.
You are advised to start by inspecting a template manual page such as buzzz.azm. The current manual page documents the facilities and macros
made available by the PUD manual language by importing the file man.zmm. The structure of a manual page thus typically looks like this:
import{man.zmm}
egin{pud::man}{
{name}{pud-man}
{html_title}{The PUD manual page mini-language}
{author}{Stijn van Dongen}
{section}{7}
{year}{2009}
{month}{Jan}
{day}{15}
{tag}{1.002}
{stamp}{09-015}
{defstyle}{long}
{synstyle}{long}
}
${html}{"pud::man::maketoc"}
sec{name}{NAME}
NAME{pud-man}{A description of the Portable Unix Documentation Language for writing manual pages}
sec{description}{DESCRIPTION}
par{ ..... .....}
sec{some}{SECTION}
par{ ..... .....}
end{pud::man}
The PUD manual page macro package automatically imports a set of generic macros from the aephea-base and aephea-ref packages. The aephea-
base(7) and aephea-ref(7) manual pages document those macros, which are also essential for writing manual pages. The most important are
i) The itemize environment (used as egin{itemize}[{options}] ... end{itemize}) and its associated macros item#1, items#1, item item-
skip, intermezzo, and others.
ii) The font style/appearance macros f#1, it#1, t#1, v#1, the font size macros ftinc#2 and ftdec#2.
iii) The paragraph mark par#1 (required for each paragraph).
iv) The verbatim macros verbatim#1 and verbatix#1.
v) The link macros httpref#1, sibref#2, iref#2, lref#2, aref#2.
vi) In aephea-ref(7) the pair of
eference#2 and
efer#1.
For the authorative listing consult the aephea-base manual page. The listing above includes a silly demonstration of some itemize features
such as alignment and automatic numbering. Read the Zoem User Manual for a better understanding of zoem macro packages and the design of
zoem.
MACROS
The $man key in the pud::man environment can be used to set the centered heading found in all UNIX roff manual pages. If not set, a heading
is derived from the $section macro. Below is the listing of default headers. It can probably be improved.
1 USER COMMANDS
2 SYSTEM CALLS
3 LIBRARY CALLS
4 SPECIAL FILES
5 FILE FORMATS
6 GAMES
7 MACRO PACKAGES
8 SYSTEM ADMINISTRATION
9 KERNEL ROUTINES
The last textual item in a manual page must be the macro "man::postamble". See the example page buzzz.azm.
sec#2
secref#1
Start a section, refer to a section. The first argument of sec#2 is the anchor for that section, the second argument is the title. The
macro secref#1 takes an anchor and outputs the title of the associated section.
The NAME section should be written like the example below, taken from the zoem interpreter manual.
sec{name}{NAME}
NAME{zoem}{interpreter for the Zoem macro/programming language.}
Usage of the NAME macro ensures that the troff output complies with the format expected by apropos.
defopt#2
defopt#3
defkvp#3
Write entry in the options section. typical usage is within an item#1 macro. For all macros the first argument is the option being
described, and the last argument is a short string describing the option. This string is printed in case the macro "man::defstyle" is set
to long. The macro defopt#3 is used for options taking arguments; the second argument is the name describing the argument. The macro
defkvp#3 is used for long options of the form --mode=str, which you would enter as defkvp{mode}{str}{set foo mode}. Long options of the
form --verbose are simply entered using defopt#2.
optref#2
Refer to an option. The first argument is the option, the second argument is the text associated with the link. This text will indeed be
linking in html, but nothing special will happen in troff - the text is printed as is.
synoptopt#2
synoptopt#3
synreqopt#2
synreqopt#3
Write entries in the synopsis section. This assumes that somewhere an option was created using one of the defopt family members described
below.
For all 'syn' options the first argument is simply the option itself. From this argument the anchor is reconstructed that was created by
one of the defopt macros. The last argument is always a short string describing the option. It depends on the style chosen, i.e. whether
"man::synstyle" is long or short, whether this string shows up or not. The macros in this group that take two arguments describe unary
options that take no argument. The macros taking three arguments describe options that do take an argument.
Here is an example from the zoem manual page:
synoptopt{--trace}{trace mode, default}
synoptopt{--trace-all-long}{long trace mode}
synoptopt{--trace-all-short}{short trace mode}
synoptopt{--trace-regex}{trace regexes}
synoptopt{--show-tracebits}{show trace bits}
synoptopt{-trace}{k}{trace mode, explicit}
synoptopt{--stats}{show symbol table stats after run}
"man::synstyle"
"man::defstyle"
Before importing the manual macros, set these to your prefered style. Each of these should be set either to short or long.
genopt#1
genopt#2
genarg#1
useopt#1
useopt#2
usearg#1
genkvp#2
usekvp#2
These are for creating a consistent style when refering to options. One is free to disregard these altogether. They are meant as conve-
nience, but some may find the extra typing annoying.
The idea is that the 'gen' macros are used when generic mention is made of an option and possibly its argument. The 'use' macros are used
when explicit usage is mentioned. An example is the following:
Modes can be chosen using -mode str where str is any of small, medium, or large. Use -mode small if your hardware is outdated.
Use --mileage=str to set the mileage, e.g. --mileage=high or --mileage=astronomical.
SEE ALSO
The pud manual page gives an overview of PUD.
pud-man 1.002, 10-008 8 Jan 2010 pud-man(7)