\def{"man::synstyle"}{long}
\def{"man::defstyle"}{long}

\import{man.zmm}
\import{zoem.zmm}

\set{"man::name"}{pud-base}
\set{"man::html-title"}{The PUD base language}
\set{"man::author"}{Stijn van Dongen}
\set{"man::section"}{7}

\"man::preamble"
\${html}{\"man::maketoc"}

\: iref#2, lref#2, enref#2, aref#2.
\: evn{spacing}
\: bf#1 it#1 v#1 tt#1
\: ftinc#2 ftdec#2
\: httpref#1 sibref#2
\: par car cpar#1 ccar#1
\: par#1 car#1 cpar#2 ccar#2


\sec{name}{NAME}
\NAME{pud-base}{a description of the Portable Unix Documentation base language}

\par{
   The macros in this package have been ported to both HTML and
   troff.}


\sec{description}{DESCRIPTION}
\par{
   \it{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 (\sibref{pud-man}) and the PUD language
   for FAQ authoring (\sibref{pud-faq}).}

\par{
   There is a small list of known issues in the \secref{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 \it{before} you run into trouble may be the
   wisest thing to do.}


\sec{itemintro}{INTRODUCTION TO THE ITEMIZE ENVIRONMENT}

\par
   The \it{itemize} environemnt is the PUD workhorse for lists,
   enumerations, itemizations, and other tailed creatures. A simple and
   valid use is for example

\set{tmp}{\!{  \begin{itemize}
      \item{\bf{foo}}
         For I am foo.
      \items{
         {\bf{barra}}
         {\bf{zuttelezut}}
      }
         For we are bar and zut.
   \end{itemize}}}

\verbatim{\apply{protect#1}{{\tmp}}}
\car
   This source result in the following output:

\apply{_#1{\1}}{{\tmp}}

\par
   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 \it{itemize} capabilities, but it goes
   to show that the itemize macros are quite robust (by virtue of modularity).

\cpar{NOTE}
   The entire listing below was put in PUD's \it{spacing} environment,
   described further below. The environment was used to create
   extra margins on the two sides.
   \${html}{The listing was furthermore output in \it{debug} mode, which 
   shows the underlying table structure in the rendered HTML output}.
  
\begin{spacing}{{left}{5}{right}{10}}
\begin{itemize}{
   {compact}{1}
   {contiguous}{1}
   {type}{arabic}
   {align}{right}
   {debug}{1}
   {w1}{5}
   {w2}{3}
   {mark}{\*{bullet}}
}

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

\item
   Several item modes (custom, mark, enumeration).

\item
   Several enumeration modes (roman, arabic, alphabetic).

\set{$type}{roman}
\set{$rp}{)}
\item
   The style of a list can be changed while in the middle of it.

\item
   Nuther item.

\item
   The list can be 'interupted' and resumed (by means of
   the \mc{intermezzo#1} macro).

\intermezzo{Perhaps you wonder what good is THAT for, and justly so.
The \mc{intermezzo#1} macro should only be used inbetween different
items,  i.e. it should \it{not} split content belonging to a single item.
}

\set{$type}{arabic}
\set{$rp}{]}
\set{$lp}{[}
\item
   Items can be optionally and automatically
   right and/or left delimited. The current
   item is delimited with square brackets.

\set{$align}{left}
\item
   Items can be left or right aligned.

\item
   Items can be stacked, which is supported only when compact is off.

\set{$compact}{0}
\item
   Beginning with this item, compact is off.

\items{
   {Implying}
   {That}
   {Stacking}
}
   is now possible.

\set{$align}{right}
\item
   (back to right-align) The itemcounter just keeps running by the way.

\set{$compact}{1}
\setx{$itemcount}{\f{+}{\$itemcount}{5}}
\item
   (back to compact) But the counter can be manipulated at will.

\set{$type}{mark}
\set{$rp}{}
\set{$lp}{}
\item
   A bullet item, with an ugly bullet in HTML.  Unfortunately the \v{&bull;}
   entity is not widely supported yet. I decided to stick with a plain asterisk
   until that time arrives.

\set{$contiguous}{0}
\item
   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).

\begin{itemize}{
   {margintop}{0}
   {compact}{1}
   {contiguous}{1}
   {w1}{4}
   {w2}{2}
   {align}{right}
   {type}{abc}
   {rp}{.}
   {debug}{1}
}
\item
   Hubris
\item
   Laziness
\item
   Impatience
\end{itemize}
\car
   Are the three virtues of programming.

\item
   This concludes a listing showing most of the itemize capabilities.
\end{itemize}
\end{spacing}


\sec{itemuse}{USING THE ITEMIZE ENVIRONMENT}
\par
You steer the itemize environment by providing it with tag-value pairs like
so:

\verbatim{\
   \\begin{itemize}{
      {compact}{1}
      {contiguous}{1}
      {align}{right}
      {type}{abc}
      {rp}{.}
   }}

\car
This is the list of tags that you may use.

\begin{itemize}{}
\apply{_#2{\!item{\!it{\1}}\@{\N}\2}}{
   {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. \*{bullet} (if type=mark), affects \mc{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 \mc{item}.}

                     \: hum ho, being clever we need \!$itemcount
                     \: rather than \$itemcount.
                     \: that's the downside of macro cleverness.
   {itemcount}
   {The count of items seen so far, e.g. \!$itemcount right now.}
}
\end{itemize}


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

\verbatim{\\set{$align}{right}
\\set{$itemcount}{30}}


\sec{spacing}{THE SPACING ENVIRONMENT}
\par
   Its syntax is identical to that of the \it{itemize} environment.
   It accepts tags \it{left}, \it{right}, \it{top}, and \it{bottom}.
   These should receive numeric values. The associated
   unit is millimeter.

\par
   The troff device does not yet support the \it{top} and \it{bottom}
   tags.

\sec{macros}{MACROS}

\begin{itemize}

\items{
   {\defmac{enref2}{enref#2}}
   {\defmac{iref2}{iref#2}}
   {\defmac{lref2}{lref#2}}
   {\defmac{aref2}{aref#2}}
   {\defmac{httpref1}{httpref#1}}
   {\defmac{sibref1}{sibref#1}}
   {\defmac{sibref2}{sibref#2}}
   {\defmac{sibref3}{sibref#3}}
}
\car{
   \mc{enref#2} \it{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).
   \mc{iref#2} takes such an anchor as the first argument and it takes content
   that carries the link as the second argument.  \mc{lref#2} takes a file name
   (possibly including a relative or absolute path) as the first argument and
   content as the second argument.  \mc{aref#2} takes a URL (later possibly a
   URI) as the first argument and content as the second argument.  \mc{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 \v{label + extension} is the name of a file in the current directory.
   The second argument is displayed in the text. For \mc{sibref#1} the
   displayed text is the same as the label. For \mc{sibref#3} the second
   argument is an additional anchor within the file being linked to, and
   the third argument is the displayed text.
   \mc{httpref#1} simply prints a URL which will be active when html is output.}

\items{
   {\defmac{par1}{par#1}}
   {\defmac{cpar2}{cpar#2}}
   {\defmac{car1}{car#1}}
   {\defmac{ccar2}{ccar#2}}
}
   These are all paragraph macros that carry the paragraph content as
   the last argument. The first argument of \mc{cpar#2} and \mc{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.

\items{
   {\defmac{par}{par}}
   {\defmac{cpar1}{cpar#1}}
   {\defmac{car}{car}}
   {\defmac{ccar1}{ccar#1}}
}
   use \v{\\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
   \v{\\par} and never use \v{\\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 \v{\\car} under very specific circumstances.  Examples
   for using \v{\\car} are:

\begin{itemize}{
   {margintop}{0}
   {mark}{\-}
   {compact}{1}
   {align}{right}
   {contiguous}{1}
}
\item
   After an environment that always carries a bottom margin.

\item
   After a caption that always carries a bottom margin, such
   as most sectioning commands (e.g. \v{\\sec} in the manual macros).

\item
   After an environment that does \it{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.

\end{itemize}
\car
As promised. The \v{\\car} macro may feel a little unusual.  If you don't mind
standing the chance of a little spurious vertical white-space just use
\v{\\par} all the time.  If you really need it, such as in an 'inline' listing
as above, the \v{\\car} macro is ready to do the job.

\items{
   {\defmac{bf1}{bf#1}}
   {\defmac{it1}{it#1}}
   {\defmac{tt1}{tt#1}}
   {\defmac{v1}{v#1}}
   {\defmac{ftinc2}{ftinc#2}}
   {\defmac{ftdec2}{ftdec#2}}
}
   The first four items set their argument in the \bf{font} \it{specified}.
   \mc{tt#1} and \mc{v#1} both denote a typewriter font. \it{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.

\items{
   {\defmac{verbatim1}{verbatim#1}}
   {\defmac{verbatix1}{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 \mc{protect#1} for that.  The macro \mc{verbatim#1} will
   create a non-breaking environment.

\item{\defmac{"html::charset"}}
   Set this e.g. to ISO-8859-5 or some other acceptable charset label.
   Do this \it{before} you use the \v{preamble} key from the base package
   that you are using (e.g. the \v{man.zmm} or \v{faq.zmm} macros).

\end{itemize}


\sec{issues}{ISSUES}

\begin{itemize}
\item{\bf{Nesting}}
   Do not nest \mc{bf#1}, \mc{it#1}, \mc{tt#1}, or \mc{v#1} macros if troff is
   among the output devices. It will yield unexpected results.

\intermezzo{The rest of this list pertains to the \it{itemize} environment.}

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

\item{\bf{Margins}}
   If you use fractional values for \v{w1} and \v{w2} in the itemize
   environment, you may well run into a problem with troff (c.q. nroff)
   Suppose you use \v{w1=1.6} and \v{w2=0.8}.  Nroff will round both these
   values as well as the sum of the two, thus incrementing by \v{2} and \v{1},
   followed by a decrement of \v{2}.

\item{\bf{Misc}}
   Refrain from doing

\verbatim{\
   \\begin{itemize}
   \\begin{spacing}
   \\item{foo}
   FOO
   \\item{bar}
   BAR
   \\end{spacing}
   \\end{itemize}}

\car
   Because the \v{\\item#1} invocations will update keys in the dictionary
   pushed by the \it{spacing} environment rather than the dictionary beneath
   it that was pushed by the \it{itemize} environment.
   On the other hand, you \it{can} do this:

\verbatim{\
   \\begin{spacing}
   \\begin{itemize}
   \\item{foo}
   FOO
   \\item{bar}
   BAR
   \\end{itemize}
   \\end{spacing}}

\car
   The reason being that the \it{spacing} environment does not facilitate
   associated keys within the dictionary scope it creates.
   Compare with this with the \it{itemize} environment, that facilitates
   the use of \v{\\item#1}, \v{\\item}, and \v{\\items#1}.

\end{itemize}

\"man::postamble"

