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

\begin{pud::man}{

   {name}{pud-ref}
   {html_title}{The PUD ref macros}
   {author}{Stijn van Dongen}
   {section}{7}
   {defstyle}{long}
   {synstyle}{long}

   \man_share
}

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

\sec{name}{NAME}
\NAME{pud-ref}{A description of the Portable Unix Documentation macros for referencing} 

\sec{description}{DESCRIPTION}

\par{
   The following macros are used by the PUD manual macros
   (see \sibref7{pud-man}) and the PUD FAQ macros
   (\sibref7{pud-faq}).}

\sec{macro}{MACROS}

\begin{itemize}{
   {flow}{cascade}
   {interitem}{1}
}

\items{
   {\defmac{refload#2}}
   {\defmac{refloadx#2}}
}
\car{
   Both macros take as first argument
   a label that uniquely defines the reference.
   The second argument is a vararg containing key-value pairs.}

\par{
   These macros are usually not needed in PUD documents; they are
   lower level facilities used by high level PUD macros.}

\item{\defmac{ref#2}}
\car{
   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.}

\par{
   These macros are usually not needed in PUD documents; they are
   lower level facilities used by high level PUD macros (e.g. \mc{iref#2},
   and \mc{secref#1}).}

\items{
   {\defmac{refcaption#1}}
   {\defmac{refnumber#1}}
   {\defmac{reflevel#1}}
}
\car{
   The argument is a label. The result is respectively the caption, number,
   or level associated with that label.}

\items{
   {\defmac{reference}{reference#1}}
   {\defmac{refer}{refer#1}}
}
\car{
   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\~\refer{pub1} and another link\~\refer{pub2}
   to the items appearing below.}

\par{
   \reference{pub1} The first reference.}

\par{
   \reference{pub2} The second reference.}

\par{
   If you prefer another bibliography style, find the macros
   and adapt them according to your needs \- they are very simple.}

\par{
   \mc{reference#2} currently writes data to the file \mc{__fnbase__.zmr},
   to be read back in using a \mc{load{\\__fnbase__.zmr}} statement.
   This is automatically done when using the PUD man or FAQ packages.}

\end{itemize}

\end{pud::man}

