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
|
Writing text for the TeX FAQ -- the requirements
There are some ground rules for text for the FAQ which need to be
adhered to. Some of the rules relate to the perl program that's used
to create an HTML file of the FAQ from the TeX source, or to the
nature of the macros that Sebastian, Alan and I have written; others
relate to the way in which I try to manage change. Please remember
that we're attempting distributed authoring of a relatively small
document over a tight timescale; while I _can_ in principle work into
the night to put things right after a submission, my employers tend to
prefer me awake during the working day...
Rules for presentation of text
------------------------------
1. Don't line wrap in macro calls. Ignore the fact that this can mean
very long lines. This restriction applies equally to the
[]-surrounded optional arguments of macros (e.g., \item).
2. Always put {} after `name' macros (such as \TeX{}). Do this
- even if you prefer \TeX\ to ensure the name's delimited
- even if the name's immediately followed by punctuation
3. Don't use \verb or \shortvrb -- find alternatives in other
constructions like \csx, \cmdinvoke, etc.
Rules for managing the text
---------------------------
The first version of the FAQ was developed in a distributed fashion by
the members of the committee of UKTUG. Just now, it's under my (RF's)
sole control; if there were a clamour for other people to contribute,
I guess the thing to do _today_ would be to create a sourceforge
project. (Sourceforge, or anything like it, wasn't even a gleam in
anyone's eye back in 1994 when we were first discussing the FAQ.)
Source of the text
------------------
The text currently resides in
newfaq.tex The body of the text
filectan.tex Declarations of the locations of individual files on
CTAN archives
dirctan.tex Declarations of the directories on CTAN archives
faq.sty The main package
This pre-production version of the text is printed (by default) in
Adobe Times Roman, etc. An alternative font may by used by setting
yourself up with a file faqfont.cfg that contains the commands that
should be used to define what fonts are needed.
A faqfont.cfg which does nothing, and hence leaves LaTeX with its
default of cm* fonts, is available with the text; if you *want* the
faq printed in Times Roman, you should not transfer the file (or you
should delete it once you *have* transferred it).
All these files are to be found in the CTAN distribution of the FAQ,
in usergrps/uktug/faq
Markup commands
---------------
The faq is written in LaTeX. Commands to use are:
\CTANdirectory{tag}{directory-path}
\CTANfile{tag}{file-path}
These are used in dirctan.tex and filectan.tex, respectively. The
<tag> is used in the \CTANref command, and the <*-path> is is what
gets typeset in respect of a \CTANref (and what becomes the anchor
of an html link to retrieve the referenced thing).
\CTANdirectory*{tag}{directory-path}
As \CTANdirectory, but appears in HTML as "browse directory" only
\CTANref{tag} (and the ctanrefs environment)
make reference to a <tag> defined by a \CTANfile or \CTANdirectory
command; will usually appear in a ctanrefs environment at the end of
an answer. Refer to the files with markup such as \Package,
\Class or \ProgName in the body of the question, and then say:
\begin{ctanrefs}
\item[blah.sty]\CTANref{blah}
\end{ctanrefs}
\Question[label]{question-title}
Set the title of a question, and define a label for it (in fact, an
unusual sort of subsection command). The [label] is (now)
mandatory, and must be prefixed by "Q-" (as in
\Question[Q-newans]{Submitting new material for the FAQ}).
\Qref[intro-text]{anchor-text}{label}
Refer to a question. The <intro-text> is set before the reference,
and is "see question" by default. The <anchor-text> is used in
hyper-enabled output, as the anchor for jumping to the labelled
question. The <label> is defined somewhere in the document as a
\Question command's (nominally) optional argument.
\Qref*{anchor-text}{label}
Refer to a question. In hyper-enabled output, results are the same
as for \Qref; in DVI output, produces
anchor-text (see question <label>)
special care being taken with surrounding quotes.
\TUGboat{} <vol>(<number>)
TUGboat reference (we have surprisingly many). Really does have
that syntax \TUGboat{} 16(3), though as far as the HTML translator
is concerned, the command ends at \TUGboat{} so it doesn't matter if
it gets split across lines.
Environment booklist
Is used to set lists of books; it uses \item in the same way that
the description environment does, but sets the label thus defined in
normal weight italic text from the current family
\htmlignore ... \endhtmlignore
Brackets around bits of text that are to be ignored by the html
generator (deprecated: use environment typesetversion instead
Environment htmlversion
Text to appear in HTML but not in the typeset versions of the FAQ.
(The body of the environment will be processed before appearing in
the HTML output, just the same as text for joint use.)
Similar are:
Environment dviversion (DVI output only)
Environment pdfversion (PDF output only)
Environment narrowversion (DVI output only -- narrow since 2-col output)
Environment wideversion (HTML or PDF output only)
Note that we use narrow for non-hyper, and wide for hyper versions
of the source.
\htmlonly{text}
\narrowonly{text}
\wideonly{text}
These three are command versions of the corresponding environments
\nothtml{text}
Text not to appear in the HTML version
\latexhtml{latex text}{HTML text}
Typesets latex text, or processes HTML text, according to context
\csx{name}
A robust command to typeset a control sequence in typewriter. The
<name> should only have letters or (at most) others in it -- no
active characters, please...
\cmdinvoke{cmd name}<arguments>
Typesets a complete command invocation, and all its arguments.
The LaTeX macro will take arbitrary sequences of optional and
mandatory arguments, but while the HTML processor will deal with a
wide range of variants, its stunning simplemindedness means it's
always good to check such output.
\cmdinvoke*{cmd name}<arguments>
As \cmdinvoke, but arguments are typeset with \emph
\checked{intials}{date}
Records when an answer (or part of an answer) was checked, and by
whom. Currently typsets as nothing.
\LastEdit{date}
Date of last editing a Question; argument is yyyy-mm-dd (ISO form)
(placed at the end of an answer)
\LastEdit*{date}
Last edit was the initial version
\keywords{<stuff>}
For labelling questions. Doesn't currently have any effect at all.
\Email{<name>@<address>}
\FTP{<site-address>}
\File{file-path>}
\path{file-path>}
\Newsgroup{usenet-group-name}
\URL{protocol>://site/path}
\mailto{mail@ddress}
All these things typeset their argument in typewriter, but allowing
line-splitting at appropriate characters (using url.sty). The last
two (\URL and \mailto) become active in both the HTML and PDF
versions of the FAQ; \Email is for formatting a name (e.g., a finger
identifier) that the reader is _not_ supposed to mail.
\Package{package name} % (no .sty)
\Class{class name} % (no .cls)
\ProgName{executable command name}
Set the item in an appropriate fashion. _Please_ use these commands
wherever appropriate.
Names, logos, etc., for use whenever needed (to be used just as
\name{}):
\AllTeX [(La)TeX], \LaTeXe, \LaTeXo [LaTeX 2.09, with requisite
precautions about dealing with the undead], \MF, \MP [MetaPost], \BV
[Baskerville], \PDFTeX, \PDFLaTeX, \CONTeXT, \NTS, \eTeX, \Eplain,
\TeXsis, \YandY [the firm, whose name is a bit tricky in HTML],
\WYSIWYG, \dots, \ldots, \pounds, \arrowhyph [->, used in
descriptions of selections from menus, and looking better when
typeset], \textpercent, \textasciitilde
Typesetting things, arguments in braces:
\acro [for upper-case acronyms such as CTAN], \emph, \textit,
\textsl, \meta [as in doc.sty], \texttt, \thinspace, \ISBN
Typesetting environments:
quote, description, itemize, enumerate, verbatim
Other odds and ends:
$\pi$, $...$, \$, \#, \ , \&, ~ [just produces a space]
Robin Fairbairns
2009-06-13
\LastEdit{2009-03-27}
|
