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  ver-
      sions 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 imply  a
      bug in the PUD man macros.

      The PUD manual page macro package automatically imports a set of generic
      macros from the pud-base and pud-ref packages. The pud-base(7) and  pud-
      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  \begin{itemize}[{options}]  ...
         \end{itemize})  and  its  associated  macros \item#1, \items#1, \item
         \itemskip, \intermezzo, and others.

     ii) The font style/appearance macros \bf#1, \it#1, \tt#1, \v#1, the  font
         size macros \ftinc#2 and \ftdec#2.

    iii) The paragraph mark \par (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 pud-ref(7) the pair of \reference#2 and \refer#1.

      For  the authorative listing consult the pud-base manual page. The list-
      ing 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
      \"man::author"
      \"man::day"
      \"man::html-title"
      \"man::month"
      \"man::name"
      \"man::section"
      \"man::cat"
      \"man::tag"
      \"man::year"
         These  have  to  be  set  to  appropriate  values  before  the  macro
         \"man::preamble" is used.  See the example page buzzz.azm.

         The  \"man::cat"  macro can be used to set the centered heading found
         in all UNIX roff manual pages. If not set, a heading is derived  from
         the  \"man::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


      \"man::preamble"
      \"man::postamble"
         Before any text or  macro  resulting  in  output  occurs,  the  macro
         \"man::preamble"  has  to  be used.  This macro may certainly be pre-
         ceded by \def#2 uses and variants thereof. See the macros  listed  in
         the previous entry and the example page buzzz.azm.

         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  associ-
         ated 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 argu-
         ments; 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   --milage=str   to   set  the  milage,  e.g.  --milage=high  or
          --milage=astronomical.

  SEE ALSO
      The pud manual page gives an overview of PUD.



  pud-man 1.002, 08-248             4 Sep 2008                        pud-man(7)
