Provided by:
zoem-doc_06-234-1_all 
NAME
pud-base - a description of the Portable Unix Documentation base lan‐
guage
The macros in this package have been ported to both HTML and troff.
DESCRIPTION
pud-base - A description of the Portable Unix Documentation (PUD) base
language. The macros in this package have been ported to both HTML and
troff. This package is used by the PUD mini-language for authoring man‐
ual pages (pud-man) and the PUD language for FAQ authoring (pud-faq).
There is a small list of known issues in the ISSUES section, mostly con‐
cerning the troff device. These should generally be of no concern at
all, but if you run into trouble look there first. A quick glance
through the list before you run into trouble may be the wisest thing to
do.
INTRODUCTION TO THE ITEMIZE ENVIRONMENT
The itemize environemnt is the PUD workhorse for lists, enumerations,
itemizations, and other tailed creatures. A simple and valid use is for
example
\begin{itemize}
\item{\bf{foo}}
For I am foo.
\items{
{\bf{barra}}
{\bf{zuttelezut}}
}
For we are bar and zut.
\end{itemize}
This source result in the following output:
foo
For I am foo.
barra
zuttelezut
For we are bar and zut.
This is not impressive at all, but it gives an idea of how itemize
works. The following example is a single itemize environment providing
a rollercoasterride through most of the features of the itemize environ‐
ment. As shown below, it is possible to change all the itemize settings
and styles at will even within a single itemize instance. Of course this
is not useful at all except for demonstrating the itemize capabilities,
but it goes to show that the itemize macros are quite robust (by virtue
of modularity).
NOTE
The entire listing below was put in PUD’s spacing environment, described
further below. The environment was used to create extra margins on the
two sides. .
1 Several spacing modes (contiguous, compact, indent). The
mode in the current list is both compact and contiguous.
Compact means that the itemize token and the ensuing text
are on the same line. Contiguous means that there is no
paragraph skip between different item-description pairs.
Below, compact mode is switched off (approximately) halfway.
2 Several item modes (custom, mark, enumeration).
3 Several enumeration modes (roman, arabic, alphabetic).
iv) The style of a list can be changed while in the middle of
it.
v) Nuther item.
vi) The list can be ’interupted’ and resumed (by means of the
\intermezzo#1 macro).
Perhaps you wonder what good is THAT for, and justly so. The
\intermezzo#1 macro should only be used inbetween different items,
i.e. it should not split content belonging to a single item.
[7] Items can be optionally and automatically right and/or left
delimited. The current item is delimited with square brack‐
ets.
[8] Items can be left or right aligned.
[9] Items can be stacked, which is supported only when compact
is off.
[10]
Beginning with this item, compact is off.
Implying
That
Stacking
is now possible.
[12]
(back to right-align) The itemcounter just keeps running by
the way.
[18] (back to compact) But the counter can be manipulated at
will.
· A bullet item, with an ugly bullet in HTML. Unfortunately
the • entity is not widely supported yet. I decided to
stick with a plain asterisk until that time arrives.
· We now switch to contiguous=0 mode (affecting the current
list), and start a new list that is contiguous to the
present text (by setting margintop to 0).
a. Hubris
b. Laziness
c. Impatience
Are the three virtues of programming.
· This concludes a listing showing most of the itemize capa‐
bilities.
USING THE ITEMIZE ENVIRONMENT
You steer the itemize environment by providing it with tag-value pairs
like so:
\begin{itemize}{
{compact}{1}
{contiguous}{1}
{align}{right}
{type}{abc}
{rp}{.}
}
This is the list of tags that you may use.
margintop
Top of table, anomalous unit (ems), default 0.
contiguous
Don’t put paragraph skips inbetween items, default 0 (do it).
compact
Put item and description on same line, default 0 (don’t do it).
w1
Width of item column in ems.
w2
Width of separating column in ems.
mark
E.g. · (if type=mark), affects \item.
align
One of left or right (item alignment), default left.
debug
Shows underlying table structure in html.
lp
What’s printed immediately to the left of an item.
rp
What’s printed immediately to the right of an item.
type
One of mark, roman, abc, arabic, affects \item.
itemcount
The count of items seen so far, e.g. 11 right now.
You need to know that the itemize environment internally maps these tags
to dollar keys simply by prepending a dollar. Thus, if you want to
reset one of the values associated with such a tag, you need to do e.g.
\set{$align}{right}
\set{$itemcount}{30}
THE SPACING ENVIRONMENT
Its syntax is identical to that of the itemize environment. It accepts
tags left, right, top, and bottom. These should receive numeric values.
The associated unit is millimeter.
The troff device does not yet support the top and bottom tags.
MACROS
\enref#2
\iref#2
\lref#2
\aref#2
\httpref#1
\sibref#1
\sibref#2
\sibref#3
\enref#2 creates a link for which the first argument is the anchor
and for which the second argument is the content (which can be left
empty). \iref#2 takes such an anchor as the first argument and it
takes content that carries the link as the second argument. \lref#2
takes a file name (possibly including a relative or absolute path) as
the first argument and content as the second argument. \aref#2 takes
a URL (later possibly a URI) as the first argument and content as the
second argument. \sibref#2 takes a label as argument which presumably
is the name of some application. It may append an extension depend‐
ing on the current device, and it assumes that label + extension is
the name of a file in the current directory. The second argument is
displayed in the text. For \sibref#1 the displayed text is the same
as the label. For \sibref#3 the second argument is an additional
anchor within the file being linked to, and the third argument is the
displayed text. \httpref#1 simply prints a URL which will be active
when html is output.
\par#1
\cpar#2
\car#1
\ccar#2
These are all paragraph macros that carry the paragraph content as
the last argument. The first argument of \cpar#2 and \ccar#2 is the
caption. These macros will ensure wellformedness for devices that
support it, such as HTML. For more information on the differences
between these macros consult the entries below.
\par
\cpar#1
\car
\ccar#1
use \car where you don’t need a paragraph skip, but just need to
indicate that you are in text mode again. You can simply always use
\par and never use \car. If you care about the details of spacing
though, or if you have particular trouble for example in creating an
itemize environment where you do not want top and bottom margins,
then it could be worthwile to turn to \car under very specific cir‐
cumstances. Examples for using \car are:
- After an environment that always carries a bottom margin.
- After a caption that always carries a bottom margin, such as most
sectioning commands (e.g. \sec in the manual macros).
- After an environment that does not carry a bottom margin, and
where you specifically want the environment to be contiguous to
the enclosing text. The listing you are currently reading is an
example of this.
As promised. The \car macro may feel a little unusual. If you don’t
mind standing the chance of a little spurious vertical white-space
just use \par all the time. If you really need it, such as in an
’inline’ listing as above, the \car macro is ready to do the job.
\bf#1
\it#1
\tt#1
\v#1
\ftinc#2
\ftdec#2
The first four items set their argument in the font specified. \tt#1
and \v#1 both denote a typewriter font. These macros should not be
nested if troff is to be among the output devices. Support for the
last two items is not yet very robust. They temporarily increment
respectively decrement the font by the amount of the first argument
and apply the resulting setting to the second argument.
\verbatim#1
\verbatix#1
Make the device output the contents verbatim in a mono-spaced font,
obeying spaces and newlines. This does not prohibit expansion of zoem
macros, use \protect#1 for that. The macro \verbatim#1 will create a
non-breaking environment.
\"html::charset"
Set this e.g. to ISO-8859-5 or some other acceptable charset label.
Do this before you use the preamble key from the base package that
you are using (e.g. the man.zmm or faq.zmm macros).
ISSUES
Nesting
Do not nest \bf#1, \it#1, \tt#1, or \v#1 macros if troff is among the
output devices. It will yield unexpected results.
The rest of this list pertains to the itemize environment.
Boldness
There is currently not a way to get bold (Roman) numerals using the
automatic enumeration mode within itemize, or to change the appear‐
ance of any of the other enumeration types.
Margins
If you use fractional values for w1 and w2 in the itemize environ‐
ment, you may well run into a problem with troff (c.q. nroff) Suppose
you use w1=1.6 and w2=0.8. Nroff will round both these values as well
as the sum of the two, thus incrementing by 2 and 1, followed by a
decrement of 2.
Misc
Refrain from doing
\begin{itemize}
\begin{spacing}
\item{foo}
FOO
\item{bar}
BAR
\end{spacing}
\end{itemize}
Because the \item#1 invocations will update keys in the dictionary
pushed by the spacing environment rather than the dictionary beneath
it that was pushed by the itemize environment. On the other hand,
you can do this:
\begin{spacing}
\begin{itemize}
\item{foo}
FOO
\item{bar}
BAR
\end{itemize}
\end{spacing}
The reason being that the spacing environment does not facilitate
associated keys within the dictionary scope it creates. Compare with
this with the itemize environment, that facilitates the use of
\item#1, \item, and \items#1.
pud-base 1.002, 06-234 22 Aug 2006 pud-base(7)