summaryrefslogtreecommitdiff
path: root/Master/texmf-doc/doc/english/FAQ-en/markup-syntax
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-doc/doc/english/FAQ-en/markup-syntax')
-rw-r--r--Master/texmf-doc/doc/english/FAQ-en/markup-syntax215
1 files changed, 215 insertions, 0 deletions
diff --git a/Master/texmf-doc/doc/english/FAQ-en/markup-syntax b/Master/texmf-doc/doc/english/FAQ-en/markup-syntax
new file mode 100644
index 00000000000..4c2c2e7ff65
--- /dev/null
+++ b/Master/texmf-doc/doc/english/FAQ-en/markup-syntax
@@ -0,0 +1,215 @@
+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