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

\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