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 [email protected] 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
  <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).

\CTANref{tag} 

  make reference to a <tag> 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 <intro-text> is set before the reference,
  and is "see question" by default.  The <anchor-text> 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
  <label> is defined somewhere in the document as a \Question
  command's optional argument

\TUGboat{} <vol>(<number>)

  TUGboat reference (we have surprisingly many, quite apart from Seb's
  adverts for 16(3) ;-).  Really does have that syntax \TUGboat{}
  16(3), though as far as the exiciting translator is concerned, the
  command ends at \TUGboat{} so it doesn't matter if it gets split as
  I just did...

Environment booklabel

  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

\cs{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...

\Q{query}

  Typesets <query> as a marginpar in typewriter.  If you know the
  answer to any of these things, or have an opinion to offer, contact
  RF

\checked{intials}{date}

  Records when an answer (or part of an answer) was checked, and by
  whom.  Currently typsets as nothing.

\Email|<name>@<address>|
\FTP|<site-address>|
\File|<file-path>|
\path|<file-path>|
\CTAN|<CTAN-relative-path>|
\Newsgroup|<usenet-group-name|
\URL|<protocol>://site/path|

  All these things typeset their argument in typewriter, but allowing
  line-splitting at appropriate characters (using a fiendish bit of
  code by Alan Jeffrey)

Robin Fairbairns
23 Oct 94