pud-faq(7)                      MISCELLANEOUS                       pud-faq(7)



  NAME
          pud-faq  -  faqs and facts about the Portable Unix Documentation FAQ
          authoring language.

          This document describes the Portable Unix  Documentation  (PUD)  faq
          mini-language  in the style of a FAQ. PUD-faq 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 eas-
          ily 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. Refer to  pud-man
          for examples.

  DESCRIPTION
          The  PUD faq macros extend the PUD manual macros; a PUD faq document
          must import both man.zmm and faq.zmm. There are  only  a  few  addi-
          tional  faq  macros in faq.zmm. The overall layout of a faq document
          is as follows:


          \import{man.zmm}
          \import{faq.zmm}

          \begin{pud::man}{
             {name}{pud-faq}
             {html_title}{The PUD faq mini-language FAQ}
             {author}{Stijn van Dongen}
             {section}{7}
          }

          \"faq::preamble"

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

          \sec{toc}{TOC}
          \"faq::maketoc"

          \begin{faqsec}{{ref}{Labelx}{cap}{Captionx}}
             content
          \end{faqsec}

          \begin{faqsec}{{ref}{Labely}{cap}{Captiony}}
             content
          \end{faqsec}

          \end{pud::man}

          The PUD manual macros are documented in the pud-man manual page.

          Create your FAQ according to the lay-out above and as described fur-
          ther below. Refer to Question 2.3 for full-size examples.

          Once you have written your FAQ, process it as follows.

             zoem -i your-faq.azm -d html
             zoem -i your-faq.azm -d html
             zoem -i your-faq.azm -d roff -o your-faq.7
             zoem -i your-faq.azm -d roff -o your-faq.7

          This  generates  files your-faq.html and your-faq.7.  Each device is
          run twice to be certain that references are found and linked.

  RESOURCES
          o The Zoem User Manual.
          o The pud-man manual page.

  TOC
  1...... How do I create and link to questions and sections?
   1.1... How do I start a section?
   1.2... How do I make a faq entry?
   1.3... How do I link to a question?
   1.4... How do I link to a section?
   1.5... Is that not a whole lot of typing just for linking?

  2...... Miscellaneous
   2.1... Is it really possible to have more than one section?
   2.2... Is there an easy way to get back to the TOC?
   2.3... Show me a real FAQ, not this nonsense.
   2.4... I want to change the appearance of my FAQ.
   2.5... Show me the source to this FAQ.

  FAQ
                  How do I create and link to questions and sections?

   1.1    How do I start a section?

          You would for example type

          \begin{faqsec}{
             {ref}{kind}
             {cap}{How do I link to questions and sections?}
          }

   1.2    How do I make a faq entry?

          You create an entry as follows:

          \faq{q_question}{How do I make a faq entry?}
             You create an entry as follows:
             ...

   1.3    How do I link to a question?

          \car{Like this: linking to
          \iref{q_qlink}{Question\~\refnumber{q_qlink}},
          or a silly link to the \iref{q_qlink}{current question}.
          Linking to \iref{s_basics}{Question\~\refnumber{q_slink}},
          or a link to the \iref{q_slink}{next question}.}

          \par{
          Of course, you have to use wordings such that the
          text still makes sense in the absence of links
          (assuming you are intested in the troff version of
          the FAQ you are writing), so normally you just refer to
          \iref{q_slink}{Question\~\refnumber{q_slink}} and be done
          with it.}

          Like this: linking to Question 1.3, or a silly link to  the  current
          question.   Linking to Question 1.4, or a link to the next question.

          Of course, you have to use wordings such that the text  still  makes
          sense  in  the  absence  of  links (assuming you are intested in the
          troff version of the FAQ you are  writing),  so  normally  you  just
          refer to Question 1.4 and be done with it.

   1.4    How do I link to a section?

          \car{Like this: linking to
          \iref{q_qlink}{Section\~\refnumber{s_basics}} and
          linking to \iref{q_stupid}{Section\~\refnumber{s_stupid}}.}

          Like this: linking to Section 1 and linking to Section 2.

   1.5    Is that not a whole lot of typing just for linking?

          It  sure is. Note the repeating elements though. Feel free to create
          your own shortcuts by using Zoem's macro facilities.

                                     Miscellaneous

   2.1    Is it really possible to have more than one section?

          QED

   2.2    Is there an easy way to get back to the TOC?

          In the HTML version of the faq, one can click on the number  to  the
          left  of the question; this will take you to the top of the TOC part
          pertaining to the section that question belongs to.

   2.3    Show me a real FAQ, not this nonsense.

          The reason I began writing zoem and PUD was  that  I  wanted  decent
          (both  HTML and troff) and easy to write documentation for my imple-
          mentation of the MCL cluster algorithm.

          o http://micans.org/mcl/src/mcl-latest/doc/mclfaq.azm
          o http://micans.org/mcl/src/mcl-latest/doc/mclfaq.html
          o http://micans.org/mcl/src/mcl-latest/doc/mclfaq.ps

   2.4    I want to change the appearance of my FAQ.

          Well, you need to make a copy of the faq macros and possibly the man
          macros,  and  hack  those changes in.  Zoem itself is very flexible,
          but the PUD faq macros are not, in this respect. They  can  be  made
          so, if you wish.  If you just want to change or add some style sheet
          rules for the HTML version, it will be quite easy.  The  same  holds
          for changing font styles and possibly even spacing rules.

   2.5    Show me the source to this FAQ.

          Search  for  pud-faq.azm  in your install of zoem.  Take note though
          that I played a few silly tricks in this FAQ, so  the  source  looks
          more  unreadable  than  your  average  FAQ.   The  FAQ pointed to in
          Answer 2.3 gives a more realistic impression.

  AUTHOR
          Stijn van Dongen.

  SEE ALSO
          The pud-man manual page, documenting the PUD  manual  language.  The
          FAQ  language  imports the manual definitions and you use these e.g.
          for sectioning commands as described above.

          The pud manual page gives an overview of PUD.



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