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 change the shortvrb character from `|'; it interacts with other definitions. 4. Avoid shortvrb syntax, anyway ... most common uses are now covered by specific macros; if a need arises, more such macros can be developed, rather than using shortvrb. 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 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 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 is set before the reference, and is "see question" by default. The is used in hyper-enabled output, as the anchor for jumping to the labelled question. The