pud-base - a description of the Portable Unix Documentation base language

The macros in this package have been ported to both HTML and troff.

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

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:

For I am foo.

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

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. Several item modes (custom, mark, enumeration). Several enumeration modes (roman, arabic, alphabetic). The style of a list can be changed while in the middle of it. Nuther item. 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. Items can be optionally and automatically right and/or left delimited. The current item is delimited with square brackets. Items can be left or right aligned. Items can be stacked, which is supported only when compact is off.

Beginning with this item, compact is off.

is now possible.

(back to right-align) The itemcounter just keeps running by the way. (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). Hubris Laziness Impatience Are the three virtues of programming.

This concludes a listing showing most of the itemize capabilities.

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.

Top of table, anomalous unit (ems), default 0.

Don't put paragraph skips inbetween items, default 0 (do it).

Put item and description on same line, default 0 (don't do it).

Width of item column in ems.

Width of separating column in ems.

E.g. • (if type=mark), affects \item.

One of left or right (item alignment), default left.

Shows underlying table structure in html.

What's printed immediately to the left of an item.

What's printed immediately to the right of an item.

One of mark, roman, abc, arabic, affects \item.

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}

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.

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

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.

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

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.

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, look up the macros and adapt them according to your needs.

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.

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

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.

There is currently not a way to get bold (Roman) numerals using the automatic enumeration mode within itemize, or to change the appearance of any of the other enumeration types.

If you use fractional values for w1 and w2 in the itemize environment, 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.

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.