\def{"man::synstyle"}{long}
\def{"man::defstyle"}{long}

\: 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.

\import{man.zmm}
\import{zoem.zmm}

\import{faq.zmm}

\set{"man::name"}{Zoem faq macros FAQ}
\set{"man::html-title"}{The zoem faq FAQ}
\set{"man::author"}{Stijn van Dongen}
\set{"man::section"}{7}

\"man::preamble"
\"faq::preamble"

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

\sec{name}{NAME}
\NAME{zoem faq FAQ}{faqs and facts about the Zoem faq 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 zoem faq language in the style of a FAQ.

\sec{description}{DESCRIPTION}
   The zoem faq macros extend the zoem manual macros; a zoem faq document
   must import both sets of macros. There are only a few additional faq
   macros. The overall layout of a faq document is as follows:

\verbatim{\protect{
.....
\import{man.zmm}
\import{faq.zmm}
.....
\"man::preamble"
\"faq::preamble"
.....
\${html}{\"man::maketoc"}
.....
\sec{toc}{TOC}
\"faq::maketoc"
.....
\begin{faqsec}{{ref}{Labelx}{cap}{Captionx}}
.....
\end{faqsec}
\begin{faqsec}{{ref}{Labely}{cap}{Captiony}}
.....
\end{faqsec}
.....
\"man::postamble"}}

\par
   The zoem manual macros are documented in the
   \sibref{man_zmm}{man_zmm} manual page.

\sec{resources}{RESOURCES}

\begin{itemize}{
   {compact}{1}
   {contiguous}{1}
   {align}{right}
}
   \item
      The \lref{../doc/zum.html}{Zoem User Manual}.

   \item
      The \sibref{man_zmm}{man_zmm} 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?}
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?}
   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}{\!{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}}}
\par
\apply{_#1{\1}}{{\tmp}}



\faq{q_slink}{How do I link to a section?}
   \set{tmp}{\!{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}}}
\par
\apply{_#1{\1}}{{\tmp}}

\""{(ignore)
\faq{q_double}{Did you enter all that stuff twice in the previous question?}
   No. This how it is was done:

\verbatim{\protect{\ans
\set{tmp}{\!{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}}}
\par
\apply{_#1{\1}}{{\tmp}}
}}

\par
   If you are new to zoem it might be best to forget about it though.
}

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

\end{faqsec}

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

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

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

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

\begin{itemize}{
   {contiguous}{1}
   {compact}{1}
   {align}{right}
}
\item
   \httpref{http://micans.org/mcl/src/mcl-latest/src/doc/mclfaq.azm}
\item
   \httpref{http://micans.org/mcl/src/mcl-latest/src/doc/mclfaq.html}
\item
   \httpref{http://micans.org/mcl/src/mcl-latest/src/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 zoem 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{faq_zmm.azm}{Behold faq_zmm.azm.}}
   \${roff}{Search for faq_zmm.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}

\begin{itemize}{
   {compact}{1}
   {margintop}{0}
   {align}{right}
}

\item
   The \sibref{man_zmm}{man_zmm} manual page, documenting
   the zoem manual language. The FAQ language imports the manual
   definitions and you use these e.g. for sectioning commands
   as described above.

\item
   The \sibref{generic_zmm}{generic_zmm} manual page, documenting
   base authoring facilities ported to both html and troff.

\item
   The first zoem-formatted FAQ ever written;
   \aref{http://micans.org/mcl/src/mcl-latest/src/doc/mclfaq.azm}{source},
   \aref{http://micans.org/mcl/src/mcl-latest/src/doc/mclfaq.html}{html}, and
   \aref{http://micans.org/mcl/src/mcl-latest/src/doc/mclfaq.ps}{PostScript}.

\item
   The source of this FAQ \lref{faq_zmm.azm}{faq_zmm.azm}.

\item
   The \sibref{../doc/zum}{Zoem User Manual.} Comprehensive overview
   of the Zoem language and how it is interpreted.

\item
   The \sibref{../doc/zoem}{zoem manual page.} This describes
   the options available for the zoem interpreter.

\end{itemize}

\par
   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.

\"man::postamble"

