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

      You  are  advised  to start by inspecting a template manual page such as
      buzzz.azm. The current manual page documents the facilities  and  macros
      made available by the PUD manual language by importing the file man.zmm.
      The structure of a manual page thus typically looks like this:

      \import{man.zmm}

         \begin{pud::man}{

            {name}{pud-man}
            {html_title}{The PUD manual page mini-language}
            {author}{Stijn van Dongen}
            {section}{7}
            {year}{2009}
            {month}{Jan}
            {day}{15}
            {tag}{1.002}
            {stamp}{09-015}
            {defstyle}{long}
            {synstyle}{long}

         }

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

         \sec{name}{NAME}
         \NAME{pud-man}{A description of the Portable Unix Documentation Language for writing manual pages}

         \sec{description}{DESCRIPTION}
         \par{ .....  .....}

         \sec{some}{SECTION}
         \par{ .....  .....}

         \end{pud::man}

      The PUD manual page macro package automatically imports a set of generic
      macros  from the aephea-base and aephea-ref packages. The aephea-base(7)
      and aephea-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#1 (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 aephea-ref(7) the pair of \reference#2 and \refer#1.

      For the authorative listing consult the  aephea-base  manual  page.  The
      listing  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
      The  \$man  key  in the pud::man environment can be used to set the cen-
      tered heading found in all UNIX roff manual pages. If not set, a heading
      is  derived  from  the  \$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

      The last textual item in a manual page must be the macro  \"man::postam-
      ble".  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 arguments;
        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 argu-
        ment  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 --mileage=str to set  the  mileage,  e.g.  --mileage=high  or
          --mileage=astronomical.

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



  pud-man 1.002, 10-008             8 Jan 2010                        pud-man(7)