1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<!-- Copyright (c) 2008 Stijn van Dongen -->
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<meta name="keywords" content="manual">
<style type="text/css">
body {
text-align: justify;
color: #001111;
background: white;
margin-left: 8%;
margin-right: 8%;
font-family: Helvetica, Univers, Verdana, sans-serif;
}
p.default {
font-family: Helvetica, Univers, Verdana, sans-serif;
text-align: justify;
}
p.L53 { font-size: 30pt; }
p.L52 { font-size: 20pt; }
p.L51 { font-size: 15pt; }
p.L50 { font-size: 12pt; }
p.L49 { font-size: 10pt; }
p.L48 { font-size: 9pt; }
p.L47 { font-size: 8pt; }
td {
font-family: Helvetica, Univers, Verdana, sans-serif;
text-align: justify;
}
h3 { margin-top:1em; }
h2 { margin-top:2em; }
.left { text-align: left; align: left; }
.right { text-align: right; align: right; }
.center { text-align: center; align: center; }
.nowrap { white-space: nowrap; }
a:link { text-decoration: none; }
a:active { text-decoration: none; }
a:visited { text-decoration: none; }
a:link { color: #1111aa; }
a:active { color: #1111aa; }
a:visited { color: #111166; }
a.local:link { color: #11aa11; }
a.local:active { color: #11aa11; }
a.local:visited { color: #116611; }
a.intern:link { color: #1111aa; }
a.intern:active { color: #1111aa; }
a.intern:visited { color: #111166; }
a.extern:link { color: #aa1111; }
a.extern:active { color: #aa1111; }
a.extern:visited { color: #661111; }
a.quiet:link { color: black; }
a.quiet:active { color: black; }
a.quiet:visited { color: black; }
div.copy
{ font-size: 12pt;
font-family: monospace;
text-align: left;
white-space: pre;
margin-left: 2em;
margin-top: 1em;
margin-bottom: 1em;
}
div.indent
{ margin-left: 8%;
margin-right: 0%;
}
</style>
<title>The PUD faq mini-language FAQ</title>
</head>
<body>
<p style="text-align:right">
4 Sep 2008
<a class="local" href="pud-faq.ps"><b>pud-faq</b></a>
1.002, 08-248
</p>
<div style="margin-top:1em">
<table
cellspacing="0" border=0
cellpadding="0" summary="itemize">
<tr><td width=48 valign="top" class="left nowrap">1.</td><td width=8> </td><td><div style="text-align:justify">
<a class="intern" href="#name">NAME</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">2.</td><td width=8> </td><td><div style="text-align:justify">
<a class="intern" href="#description">DESCRIPTION</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">3.</td><td width=8> </td><td><div style="text-align:justify">
<a class="intern" href="#resources">RESOURCES</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">4.</td><td width=8> </td><td><div style="text-align:justify">
<a class="intern" href="#toc">TOC</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">5.</td><td width=8> </td><td><div style="text-align:justify">
<a class="intern" href="#faq">FAQ</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">6.</td><td width=8> </td><td><div style="text-align:justify">
<a class="intern" href="#author">AUTHOR</a>
</div></td></tr><tr><td width=48 valign="top" class="left nowrap">7.</td><td width=8> </td><td><div style="text-align:justify">
<a class="intern" href="#seealso">SEE ALSO</a>
</div></td></tr>
</table>
</div>
<a name="name"></a>
<h2>NAME</h2>
<p class="default L50" style="margin-bottom:0">
pud-faq - faqs and facts about the Portable Unix Documentation FAQ authoring language.</p>
<p class="default L50" style="margin-bottom:0">
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 <a class="local" href="pud-man.html">pud-man</a>
for examples.</p>
<a name="description"></a>
<h2>DESCRIPTION</h2>
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
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:</p>
<pre>
.....
\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"</pre>
<p class="default L50" style="margin-bottom:0">
The PUD manual macros are documented in the
<a class="local" href="pud-man.html">pud-man</a> manual page.</p>
<p class="default L50" style="margin-bottom:0">
Create your FAQ according to the lay-out above and as described further
below. Refer to <a class="intern" href="#q_real">Question 2.3</a> for
full-size examples.</p>
<p class="default L50" style="margin-bottom:0">
Once you have written your FAQ, process it as follows.</p>
<pre> 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</pre>
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
This generates files your-faq.html and your-faq.7.
Each device is run twice to be certain that references
are found and linked.</p>
<a name="resources"></a>
<h2>RESOURCES</h2>
<div style="margin-top:1em">
<table
cellspacing="0" border=0
cellpadding="0" summary="itemize">
<tr><td width=32 valign="top" class=right>•</td><td width=8> </td><td><div style="text-align:justify">
The <a class="local" href="../doc/zum.html">Zoem User Manual</a>.
</div></td></tr><tr><td width=32 valign="top" class=right>•</td><td width=8> </td><td><div style="text-align:justify">
The <a class="local" href="pud-man.html">pud-man</a> manual page.
</div></td></tr>
</table>
</div>
<a name="toc"></a>
<h2>TOC</h2>
<hr>
<div style="margin-top:0em">
<table
cellspacing="0" border=0
cellpadding="0" summary="itemize">
<tr><td width=32 valign="top" class="left nowrap"><a name="toc-s_basics"></a><a class="quiet" href="#s_basics"><b>1</b></a></td><td width=8> </td><td><div style="text-align:justify">
<a class="quiet" href="#s_basics"><b>How do I create and link to questions and sections?</b></a>
</div></td></tr><tr><td width=32> </td><td width=8> </td><td></td></tr>
<tr><td width=32 valign="top" class="right nowrap"><a name="toc-qsection"></a> <a class="intern" href="#qsection"><b>1.1</b></a></td><td width=8> </td><td><div style="text-align:justify">
<a class="intern" href="#qsection"><b>How do I start a section?</b></a>
</div></td></tr><tr><td width=32 valign="top" class="right nowrap"><a name="toc-q_question"></a> <a class="intern" href="#q_question"><b>1.2</b></a></td><td width=8> </td><td><div style="text-align:justify">
<a class="intern" href="#q_question"><b>How do I make a faq entry?</b></a>
</div></td></tr><tr><td width=32 valign="top" class="right nowrap"><a name="toc-q_qlink"></a> <a class="intern" href="#q_qlink"><b>1.3</b></a></td><td width=8> </td><td><div style="text-align:justify">
<a class="intern" href="#q_qlink"><b>How do I link to a question?</b></a>
</div></td></tr><tr><td width=32 valign="top" class="right nowrap"><a name="toc-q_slink"></a> <a class="intern" href="#q_slink"><b>1.4</b></a></td><td width=8> </td><td><div style="text-align:justify">
<a class="intern" href="#q_slink"><b>How do I link to a section?</b></a>
</div></td></tr><tr><td width=32 valign="top" class="right nowrap"><a name="toc-q_typing"></a> <a class="intern" href="#q_typing"><b>1.5</b></a></td><td width=8> </td><td><div style="text-align:justify">
<a class="intern" href="#q_typing"><b>Is that not a whole lot of typing just for linking?</b></a>
</div></td></tr>
</table>
</div>
<hr>
<div style="margin-top:0em">
<table
cellspacing="0" border=0
cellpadding="0" summary="itemize">
<tr><td width=32 valign="top" class="left nowrap"><a name="toc-s_stupid"></a><a class="quiet" href="#s_stupid"><b>2</b></a></td><td width=8> </td><td><div style="text-align:justify">
<a class="quiet" href="#s_stupid"><b>Miscellaneous</b></a>
</div></td></tr><tr><td width=32> </td><td width=8> </td><td></td></tr>
<tr><td width=32 valign="top" class="right nowrap"><a name="toc-q_really"></a> <a class="intern" href="#q_really"><b>2.1</b></a></td><td width=8> </td><td><div style="text-align:justify">
<a class="intern" href="#q_really"><b>Is it really possible to have more than one section?</b></a>
</div></td></tr><tr><td width=32 valign="top" class="right nowrap"><a name="toc-q_toc"></a> <a class="intern" href="#q_toc"><b>2.2</b></a></td><td width=8> </td><td><div style="text-align:justify">
<a class="intern" href="#q_toc"><b>Is there an easy way to get back to the TOC?</b></a>
</div></td></tr><tr><td width=32 valign="top" class="right nowrap"><a name="toc-q_real"></a> <a class="intern" href="#q_real"><b>2.3</b></a></td><td width=8> </td><td><div style="text-align:justify">
<a class="intern" href="#q_real"><b>Show me a real FAQ, not this nonsense.</b></a>
</div></td></tr><tr><td width=32 valign="top" class="right nowrap"><a name="toc-q_change"></a> <a class="intern" href="#q_change"><b>2.4</b></a></td><td width=8> </td><td><div style="text-align:justify">
<a class="intern" href="#q_change"><b>I want to change the appearance of my FAQ.</b></a>
</div></td></tr><tr><td width=32 valign="top" class="right nowrap"><a name="toc-q_self"></a> <a class="intern" href="#q_self"><b>2.5</b></a></td><td width=8> </td><td><div style="text-align:justify">
<a class="intern" href="#q_self"><b>Show me the source to this FAQ.</b></a>
</div></td></tr>
</table>
</div>
<br><br>
<a name="faq"></a>
<h2>FAQ</h2>
<div align=center>
<h3><a name="s_basics"></a><a class="quiet" href="#toc-s_basics">1</a><br>How do I create and link to questions and sections?
</h3>
</div>
<div style="margin-top:1em">
<table
cellspacing="0" border=0
cellpadding="0" summary="itemize">
<tr><td width=32 valign="top" class="left nowrap"><a name="qsection"></a> <a class="quiet" href="#toc-s_basics">1.1</a></td><td width=8> </td><td><div style="text-align:justify"><b>How do I start a section?</b><p class="default L50">
You would for example type
<pre>\begin{faqsec}{
{ref}{kind}
{cap}{How do I link to questions and sections?}
}</pre>
</div></td></tr><tr><td width=32> </td><td width=8> </td><td></td></tr><tr><td width=32 valign="top" class="left nowrap"><a name="q_question"></a> <a class="quiet" href="#toc-s_basics">1.2</a></td><td width=8> </td><td><div style="text-align:justify"><b>How do I make a faq entry?</b><p class="default L50">
You create an entry as follows:
<pre>\faq{q_question}{How do I make a faq entry?}
You create an entry as follows:
...
</pre>
</div></td></tr><tr><td width=32> </td><td width=8> </td><td></td></tr><tr><td width=32 valign="top" class="left nowrap"><a name="q_qlink"></a> <a class="quiet" href="#toc-s_basics">1.3</a></td><td width=8> </td><td><div style="text-align:justify"><b>How do I link to a question?</b><p class="default L50">
<pre>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.</pre>
<p class="default L50">
Like this: linking to
<a class="intern" href="#q_qlink">Question 1.3</a>,
or a silly link to the <a class="intern" href="#q_qlink">current question</a>.
Linking to <a class="intern" href="#s_basics">Question 1.4</a>,
or a link to the <a class="intern" href="#q_slink">next question</a>.
<p class="default L50">
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
<a class="intern" href="#q_slink">Question 1.4</a> and be done
with it.
</div></td></tr><tr><td width=32> </td><td width=8> </td><td></td></tr><tr><td width=32 valign="top" class="left nowrap"><a name="q_slink"></a> <a class="quiet" href="#toc-s_basics">1.4</a></td><td width=8> </td><td><div style="text-align:justify"><b>How do I link to a section?</b><p class="default L50">
<pre>Like this: linking to
\iref{q_qlink}{Section\~\refnumber{s_basics}} and
linking to \iref{q_stupid}{Section\~\refnumber{s_stupid}}.</pre>
<p class="default L50">
Like this: linking to
<a class="intern" href="#q_qlink">Section 1</a> and
linking to <a class="intern" href="#q_stupid">Section 2</a>.
</div></td></tr><tr><td width=32> </td><td width=8> </td><td></td></tr><tr><td width=32 valign="top" class="left nowrap"><a name="q_typing"></a> <a class="quiet" href="#toc-s_basics">1.5</a></td><td width=8> </td><td><div style="text-align:justify"><b>Is that not a whole lot of typing just for linking?</b><p class="default L50">
It sure is. Note the repeating elements though. Feel free to create your own
shortcuts by using Zoem's macro facilities.
</div></td></tr>
</table>
</div>
<div align=center>
<h3><a name="s_stupid"></a><a class="quiet" href="#toc-s_stupid">2</a><br>Miscellaneous
</h3>
</div>
<div style="margin-top:1em">
<table
cellspacing="0" border=0
cellpadding="0" summary="itemize">
<tr><td width=32 valign="top" class="left nowrap"><a name="q_really"></a> <a class="quiet" href="#toc-s_stupid">2.1</a></td><td width=8> </td><td><div style="text-align:justify"><b>Is it really possible to have more than one section?</b><p class="default L50">
QED
</div></td></tr><tr><td width=32> </td><td width=8> </td><td></td></tr><tr><td width=32 valign="top" class="left nowrap"><a name="q_toc"></a> <a class="quiet" href="#toc-s_stupid">2.2</a></td><td width=8> </td><td><div style="text-align:justify"><b>Is there an easy way to get back to the TOC?</b><p class="default L50">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
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.</p>
</div></td></tr><tr><td width=32> </td><td width=8> </td><td></td></tr><tr><td width=32 valign="top" class="left nowrap"><a name="q_real"></a> <a class="quiet" href="#toc-s_stupid">2.3</a></td><td width=8> </td><td><div style="text-align:justify"><b>Show me a real FAQ, not this nonsense.</b><p class="default L50">
<p class="default L50" style="margin-top:0em; margin-bottom:0em">
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. I for one am now happy with it.</p>
<div style="margin-top:1em">
<table
cellspacing="0" border=0
cellpadding="0" summary="itemize">
<tr><td width=32 valign="top" class=right>•</td><td width=8> </td><td><div style="text-align:justify">
<a class="extern" href="http://micans.org/mcl/src/mcl-latest/doc/mclfaq.azm">http://micans.org/mcl/src/mcl-latest/doc/mclfaq.azm</a>
</div></td></tr><tr><td width=32 valign="top" class=right>•</td><td width=8> </td><td><div style="text-align:justify">
<a class="extern" href="http://micans.org/mcl/src/mcl-latest/doc/mclfaq.html">http://micans.org/mcl/src/mcl-latest/doc/mclfaq.html</a>
</div></td></tr><tr><td width=32 valign="top" class=right>•</td><td width=8> </td><td><div style="text-align:justify">
<a class="extern" href="http://micans.org/mcl/src/mcl-latest/doc/mclfaq.ps">http://micans.org/mcl/src/mcl-latest/doc/mclfaq.ps</a>
</div></td></tr>
</table>
</div>
</div></td></tr><tr><td width=32> </td><td width=8> </td><td></td></tr><tr><td width=32 valign="top" class="left nowrap"><a name="q_change"></a> <a class="quiet" href="#toc-s_stupid">2.4</a></td><td width=8> </td><td><div style="text-align:justify"><b>I want to change the appearance of my FAQ.</b><p class="default L50">
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.
</div></td></tr><tr><td width=32> </td><td width=8> </td><td></td></tr><tr><td width=32 valign="top" class="left nowrap"><a name="q_self"></a> <a class="quiet" href="#toc-s_stupid">2.5</a></td><td width=8> </td><td><div style="text-align:justify"><b>Show me the source to this FAQ.</b><p class="default L50">
<a class="local" href="pud-faq.azm">Behold pud-faq.azm.</a>
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 <a class="intern" href="#q_real">Answer 2.3</a>
gives a more realistic impression.
</div></td></tr>
</table>
</div>
<a name="author"></a>
<h2>AUTHOR</h2>
<p class="default L50">
Stijn van Dongen.
<a name="seealso"></a>
<h2>SEE ALSO</h2>
<p class="default L50" style="margin-bottom:0">
The <a class="local" href="pud-man.html">pud-man</a> 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.</p>
<p class="default L50" style="margin-bottom:0">
The <a class="local" href="pud.html">pud</a> manual page gives an overview of PUD.</p>
</body>
</html>
|
