pud(7)                          MISCELLANEOUS                           pud(7)



  NAME
      pud - Portable Unix Documentation for manual pages and faq documents

  DESCRIPTION
      Portable Unix Documentation or pud currently provides two mini-languages
      for authoring in the UNIX environment.  The two mini-languages  are  for
      writing  UNIX  manual  pages and faq documents.  Source documents in pud
      languages can be compiled to either cross-linked html or to  troff.  The
      troff  output  can  be  further compiled into PostScript, pdf, and plain
      text.

  Table of Contents
       1. NAME
       2. DESCRIPTION
       3. Table of Contents
       4. Portable Unix Documentation extends Aephea and zoem
       5. Getting started
       6. UNIX manual pages in html, troff and PostScript
       7. faq documents in html, troff and PostScript
       8. Manuals and faq examples elsewhere
       9. DocBook considered harmful
      10. Info evil
      11. AUTHOR
      12. SEE ALSO

  Portable Unix Documentation extends Aephea and zoem
      Portable Unix Documentation (pud) is part of  the  Aephea  documentation
      framework.  Aephea  is built on top of zoem (http://micans.org/zoem), an
      all-purpose macro/programming language. Both Aephea  and  pud  documents
      are  processed by compiling them with the zoem processor.  The documents
      themselves are generally well-structured, relatively free of  formatting
      statements  and compact to write.  They can be easily extended since the
      full zoem language is available from within a pud document.

      Portable Unix Documentation is currently shipped with Aephea.  You  will
      also need to install zoem.

  Getting started
         i Get  and  install  both  Aephea (http://micans.org/aephea) and zoem
           (http://micans.org/zoem). Follow the  instructions  in  the  Aephea
           README file, which boil down to this recipe:

           Aephea:
              ./configure --prefix=$AEPHEAPREFIX
              make
              make install

           Zoem:
              ./configure --with-includepath=$AEPHEAPREFIX/share/aephea --prefix=$OTHERPREFIX
              make
              make install

           All  pud  files will be installed as you install Aephea. If you are
           reading this locally on your system, chances are  zoem  and  Aephea
           are installed.

        ii On  this page read the pointers in section Section 6 if you want to
           write a manual page.  Read the pointers in section Section 7 if you
           want to write an faq. The fastest way to get up to speed is to copy
           and modify a template or existing source document.

       iii While writing your document, consult the pud-man(7)  documentation,
           the  pud-faq(7) documentation, and the aephea-base(7) documentation
           as necessary.

        iv Off you go. If you need macro facilities or programming facilities,
           zoem is there to assist you.  Simple macro tasks are easy to accom-
           plish. For more involved stuff you might want to consult  the  Zoem
           User  Manual  (or zum).  zum should be installed locally.  Alterna-
           tively      view      the      latest      zum      at       micans
           (http://micans.org/zoem/doc/zum.html)  or  subscribe to the mailing
           list (http://micans.org/zoem/index.html#list).

  UNIX manual pages in html, troff and PostScript
      With the pud-man(7) package you create manual pages for output in either
      troff  (groff,  nroff) or html. The first can be viewed from a terminal,
      the second in a browser.

      The fictitious buzzz utility is described in a pud manual  page.  It  is
      shipped with every zoem distribution and the buzzz manual page should be
      installed locally in the same location as its source.  If  the  location
      is  hard to find you can just obtain the pud source from the zoem source
      distribution, or alternatively you may  view  the  latest  buzzz  source
      (http://micans.org/zoem/mac/buzzz.azm)   upstream  at  micans.   Further
      local links are to the PostScript version and the plain text format.

      For other examples consider the oldest pud manual page ever written: the
      mcl   manual  page  (http://micans.org/mcl/man/mcl.html),  the  same  in
      PostScript output (http://micans.org/mcl/man/mcl.ps), and the source for
      all  this  (http://micans.org/mcl/man/mcl.azm).   By using the venerable
      col program, the troff output can be converted  to  nice  looking  plain
      text  format (http://micans.org/mcl/man/mcl.txt).  Find the troff output
      (http://micans.org/mcl/man/mcl.1) disclosed as well.

      There are some 20+ manual pages for different utilities in the mcl  fam-
      ily (http://micans.org/mcl/man/).

  faq documents in html, troff and PostScript
      Create  faq documents with pud-faq(7) for output in either troff (groff,
      nroff) or html. The former can be viewed in a terminal via the UNIX  man
      page system, the latter can be viewed in a browser.

      The  pud  faq mini-language is described as a rather trivial faq itself.
      It can be viewed in PostScript (compiled from troff  compiled  from  the
      zoem source and in plain text (again compiled from troff).

      For        examples        behold       the       browsing       delight
      (http://micans.org/mcl/man/mclfaq.html) that is the  mcl  faq,  and  the
      PostScript  pleasure  (http://micans.org/mcl/man/mclfaq.ps).   Find  the
      noblest format (http://micans.org/mcl/man/mclfaq.txt),  the  impregnable
      troff     (http://micans.org/mcl/man/mclfaq.7),     and    the    source
      (http://micans.org/mcl/man/mclfaq.azm) for all that jazz.

  Manuals and faq examples elsewhere
      Other people exist writing pud. Not many yet.  Joost van Baal  has  used
      the  pud-faq package and the pud-man package to create documentation for
      GnuPG       (in       Dutch)       (http://mdcc.cx/gnupg/),       caspar
      (http://mdcc.cx/pub/caspar/caspar-latest/doc/),     and    the    strong
      (fire)walls of uruk (http://mdcc.cx/pub/uruk/uruk-latest/man/).

  DocBook considered harmful
      People justly wonder why pud turns away from the blazing light of  good-
      ness  that  is DocBook. DocBook does provide manual page elements and it
      does support gazillions of output  devices.   Nevertheless  DocBook  man
      pages are a cruelty, a curse and the bane of all things good and pure.

      DocBook  cannot  be  written, it cannot be maintained, it cannot be pro-
      grammed. Yes, XML and DocBook are not supposed  to  be  programmed,  but
      where is the decree that man should toil and suffer so that his documen-
      tation would be transmogrifyable into all eternity?

      DocBook provides some sort of manual page ontology,  describing  suppos-
      edly  every  element you might ever need. Inevitably you will want to do
      things that are not provided and then you are stuck.  DocBook lists  and
      enumerations  are  painful and limited. The verbosity of DocBook makes a
      mountain out of what should be a mole hill.

      pud manual pages are concise and can  be  easily  cross-referenced.  The
      source  is  a pleasure to read and output from self-documenting commands
      can be imported. Zoem IO, macro  and  programming  facilities  make  the
      source extendable so that new requirements can be coped with.

      Wise people argue that one cannot fathom the needs of future generations
      and urge the good people of UNIX to use DocBook.  The  fool  knows  that
      this  particular  premise  disproves the thesis and that joy begets joy.
      Factor the present into the authoring sustainability  equation  and  the
      scales tip.

      At  this juncture, I am hesitantly willing to bet that the pud languages
      can easily be ported to DocBook. None of the pain, all of the gain.  The
      pud  itemize  environment  is a sticking point though. It provides, hor-
      rors, a few formatting options. Optional paragraphs skips, compact mode,
      right-alignment  of  items,  automatic  enumeration, and the fantabulous
      intermezzo feature.

  Info evil
      The good people of info consider manual pages  obsolete.  What  more  is
      there       to      say?      It      is      all      written      here
      (http://micans.org/stijn/views/infoinferno.html).

  AUTHOR
      pud was written by Stijn van Dongen.

  SEE ALSO
      pud-man(7)
      pud-faq(7)
      aephea-base(7)
      aephea-ref(7)



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