diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /usergrps/uktug/baskervi/4_6/markup |
Initial commit
Diffstat (limited to 'usergrps/uktug/baskervi/4_6/markup')
-rw-r--r-- | usergrps/uktug/baskervi/4_6/markup | 147 |
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 |