summaryrefslogtreecommitdiff
path: root/usergrps/uktug/baskervi/4_6/markup
diff options
context:
space:
mode:
Diffstat (limited to 'usergrps/uktug/baskervi/4_6/markup')
-rw-r--r--usergrps/uktug/baskervi/4_6/markup147
1 files changed, 147 insertions, 0 deletions
diff --git a/usergrps/uktug/baskervi/4_6/markup b/usergrps/uktug/baskervi/4_6/markup
new file mode 100644
index 0000000000..5d2de2038b
--- /dev/null
+++ b/usergrps/uktug/baskervi/4_6/markup
@@ -0,0 +1,147 @@
+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
+ <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
+
+Environment booklabel
+
+ Is used to set lists of books; it use \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