Zoem faq macros FAQ(7)

NAME
zoem faq FAQ - faqs and facts about the Zoem faq language. This document describes the zoem faq language in the style of a FAQ.

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:
.....
\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"
The zoem manual macros are documented in the man_zmm manual page.

RESOURCES
The Zoem User Manual.
The man_zmm manual page.

TOC
How do I create and link to questions and sections?
How do I start a section?
How do I make a faq entry?
How do I link to a question?
How do I link to a section?
Is that not a whole lot of typing just for linking? Miscellaneous
Is it really possible to have more than one section?
Is there an easy way to get back to the TOC?
Show me a real FAQ, not this nonsense.
I want to change the appearance of my FAQ.
Show me the source to this FAQ.

FAQ
How do I create and link to questions and sections? How do I start a section? You would for example type
\begin{faqsec}{
   {ref}{kind}
   {cap}{How do I link to questions and sections?}
}
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:
   ...
How do I link to a question?
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. How do I link to a section?
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. 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 Is it really possible to have more than one section? QED 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. 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. http://micans.org/mcl/src/mcl-latest/src/doc/mclfaq.azm
http://micans.org/mcl/src/mcl-latest/src/doc/mclfaq.html
http://micans.org/mcl/src/mcl-latest/src/doc/mclfaq.ps
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. Show me the source to this FAQ. 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 Answer 2.3 gives a more realistic impression.

AUTHOR
Stijn van Dongen.

SEE ALSO
The 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.
The generic_zmm manual page, documenting base authoring facilities ported to both html and troff.
The first zoem-formatted FAQ ever written; source, html, and PostScript.
The source of this FAQ faq_zmm.azm.
The Zoem User Manual. Comprehensive overview of the Zoem language and how it is interpreted.
The zoem manual page. This describes the options available for the zoem interpreter.
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.