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 `|'.  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
---------------------------

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
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 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).

\CTANref{tag} (and the ctanrefs environment)

  make reference to a <tag> defined by a \CTANfile or \CTANdirectory
  command; should usually appear in a ctanrefs environment at the end
  of a question.  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 (optionally) 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 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

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.)

\nothtml{text}

  Text not to appear in the HTML version

\htmlonly{text}

  Text only to appear (after processing) 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.  The LaTeX macro will take
  arbitrary sequences of optional and mandatory arguments, but the
  HTML processor will (at present) only take

    \cmdinvoke{cmd}{mandatory}
    \cmdinvoke{cmd}[optional]{mandatory}
    \cmdinvoke{cmd}{mandatory1}{mandatory2}

\checked{intials}{date}

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

\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|email@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|
or...
\Package{...}, \Class{....}, \ProgName{...}

  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
23 Oct 94