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

\import{aephea.shared}

\: NOTE
\: Better use the mcl FAQ as example,
\:    http://micans.org/mcl/src/mcl-latest/mclfaq.azm
\:    http://micans.org/mcl/src/mcl-latest/mclfaq.html
\: This FAQ contains a few silly tricks because several pieces of
\: expressions are used twice; i) to construct the output and ii)
\: to create examples. The result is a slightly obfuscated source.
\: Also, the current FAQ is a bit short.

\begin{pud::man}{
   {name}{pud-faq}
   {html_title}{The PUD faq mini-language FAQ}
   {author}{Stijn van Dongen}
   {section}{7}
   {css_append}{ .pink { background-color: pink; } }
   \man_share
}

\"faq::preamble"

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

\sec{name}{NAME}
\NAME{pud-faq}{faqs and facts about the Portable Unix Documentation FAQ  authoring language.}

   \: this \ftinc is a bit anomalous, it temporarily increases the
   \: the fonts size. Just because I think it looks slightly better.

\par{
   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 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. Refer to \sibref{pud-man}
   for examples.}

\sec{description}{DESCRIPTION}
\car{
   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 additional
   faq macros in faq.zmm. The overall layout of a faq document is as
   follows:}

\verbatim{\protect{
\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}}}


\par{
   The PUD manual macros are documented in the
   \sibref{pud-man}{pud-man} manual page.}

\par{
   Create your FAQ according to the lay-out above and as described further
   below. Refer to \iref{q_real}{Question\~\refnumber{q_real}} for
   full-size examples.}
   
\par{
   Once you have written your FAQ, process it as follows.}

\verbatim{\:/
   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}
 
 \car{
   This generates files your-faq.html and your-faq.7.
   Each device is run twice to be certain that references
   are found and linked.}

\sec{resources}{RESOURCES}

\begin{itemize}{
   {flow}{compact}
   {interitem}{0}
   {align}{right}
}
\item
\car{
   The \lref{../doc/zum.html}{Zoem User Manual}.
   }

\item
\car{
   The \sibref{pud-man}{pud-man} manual page.
   }

\end{itemize}

\sec{toc}{TOC}

\"faq::maketoc"

\sec{faq}{FAQ}

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

\faq{qsection}{How do I start a section?}
\car{
   You would for example type
   }

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

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

\faq{q_qlink}{How do I link to a question?}
\set{tmp}{\!{\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.}}}

\verbatim{\apply{protect#1}{{\tmp}}}
\apply{_#1{\1}}{{\tmp}}



\faq{q_slink}{How do I link to a section?}
   \set{tmp}{\!{\car{Like this: linking to
\iref{q_qlink}{Section\~\refnumber{s_basics}} and
linking to \iref{q_stupid}{Section\~\refnumber{s_stupid}}.}}}

\verbatim{\apply{protect#1}{{\tmp}}}
\apply{_#1{\1}}{{\tmp}}


\faq{q_typing}{Is that not a whole lot of typing just for linking?}
\car{
   It sure is. Note the repeating elements though.  Feel free to create your own
   shortcuts by using Zoem's macro facilities.
   }

\end{faqsec}

\begin{faqsec}{
   {ref}{s_stupid}
   {cap}{Miscellaneous}
}

\faq{q_really}{Is it really possible to have more than one section?}
\car{
   QED
   }

\faq{q_toc}{Is there an easy way to get back to the TOC?}
\car{
   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.}

\faq{q_real}{Show me a real FAQ, not this nonsense.}
\car{
   The reason I began writing zoem and PUD was that I wanted decent (both
   HTML and troff) and easy to write documentation for my implementation
   of the MCL cluster algorithm.}

\begin{itemize}{
   {interitem}{0}
   {flow}{compact}
   {align}{right}
}
\item
   \httpref{http://micans.org/mcl/src/mcl-latest/doc/mclfaq.azm}
\item
   \httpref{http://micans.org/mcl/src/mcl-latest/doc/mclfaq.html}
\item
   \httpref{http://micans.org/mcl/src/mcl-latest/doc/mclfaq.ps}
\end{itemize}

\faq{q_change}{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.

\faq{q_self}{Show me the source to this FAQ.}
   \${html}{\lref{pud-faq.azm}{Behold pud-faq.azm.}}
   \${roff}{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 \iref{q_real}{Answer\~\refnumber{q_real}}
   gives a more realistic impression.

\end{faqsec}

\sec{author}{AUTHOR}
\par{
   Stijn van Dongen.
   }

\sec{seealso}{SEE ALSO}

\par{
   The \sibref{pud-man}{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.}

\par{
   The \sibref{pud} manual page gives an overview of PUD.}

\""{
   There are a lot of guidelines on writing FAQs out there, a Google
   search yields plenty. I stopped looking at them when confronted too
   often with the advice that FAQs be written in some standard like
   DocBook.  DocBook seems to be an ontology of some sort aimed at
   conceptualizing every way in which you would ever want to document.
   Such a categorization ideal is akin to the feverish dreams of
   philosophers and librarians alike.  Pursueing it invariably leads to
   horrific monstrosities from which all life and conceivable causes for
   joy have withered away.  The preconconcted DocBook manual page tags are
   enough to make little scary arthropods scurry away.}

\: Every once in a while I go back and check the DocBook stuff, because
\: I know all too well this zoem project is a little bit nutty.

\end{pud::man}