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 (e.g., in the footnote that lists the names of the committee members). 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 `|'. You will perhaps note that various of the path/address-type commands are defined with | as argument delimiter; if the definition of shortvrb is changed, all of those commands, and all of the \CTANref commands will fall in a neat little heap on the floor. Rules for managing the text --------------------------- 1. Always acquire a `token' by email from rf@cl.cam.ac.uk before starting work. Make clear whether you want to work on the entire document or whether you want to amend a particular question, or to write a new one. 2. Always acquire the current copy of the text before proceeding. (See below for details of doing that.) 3. Keep the ChangeLog file up to date. An entry for the log is requested to accompany each and every submission of text. 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 texnames.sty An update of the file most recently edited by Nelson Beebe 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 ftp://ftp.cl.cam.ac.uk/users/rf/faq Markup commands --------------- The faq is written in LaTeX (it requires a production LaTeX2e), since it uses at least one command that wasn't in any of the \beta-releases. 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). \CTANref{tag} make reference to a defined by a \CTANfile or \CTANdirectory command. \Question[label]{question-title} Set the title of a question, and (optionally) define a label for it (in fact, an unusual sort of subsection command) \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 the html variant of the document as the anchor for jumping to the labelled question (it's not used in the LaTeX processing). The