8 Jan 2010 pud-faq 1.002, 10-008
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:
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.
This generates files your-faq.html and your-faq.7. Each device is run twice to be certain that references are found and linked.
You would for example type
You create an entry as follows:
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.
It sure is. Note the repeating elements though. Feel free to create your own shortcuts by using Zoem's macro facilities.
QED
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.
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.
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.