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 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
pud-man for examples.
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:
\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 further 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.
• The
Zoem User Manual.
• The
pud-man manual page.
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.
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 implementation of the MCL
cluster algorithm.
•
http://micans.org/mcl/src/mcl-latest/doc/mclfaq.azm
•
http://micans.org/mcl/src/mcl-latest/doc/mclfaq.html
•
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.
Stijn van Dongen.
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.