diff options
Diffstat (limited to 'Master/texmf-doc/doc/english/FAQ-en/markup-syntax')
-rw-r--r-- | Master/texmf-doc/doc/english/FAQ-en/markup-syntax | 94 |
1 files changed, 54 insertions, 40 deletions
diff --git a/Master/texmf-doc/doc/english/FAQ-en/markup-syntax b/Master/texmf-doc/doc/english/FAQ-en/markup-syntax index 4c2c2e7ff65..087f32fd945 100644 --- a/Master/texmf-doc/doc/english/FAQ-en/markup-syntax +++ b/Master/texmf-doc/doc/english/FAQ-en/markup-syntax @@ -21,11 +21,12 @@ Rules for presentation of text - 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. +3. Don't change the shortvrb character from `|'; it interacts with + other definitions. + +4. Avoid shortvrb syntax, anyway ... most common uses are now covered + by specific macros; if a need arises, more such macros can be + developed, rather than using shortvrb. Rules for managing the text --------------------------- @@ -48,8 +49,6 @@ filectan.tex Declarations of the locations of individual files on 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 @@ -77,11 +76,15 @@ The faq is written in LaTeX. Commands to use are: 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; should usually appear in a ctanrefs environment at the end - of a question. Refer to the files with markup such as \Package, + 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} @@ -89,27 +92,32 @@ The faq is written in LaTeX. Commands to use are: \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 + 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 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 + 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, 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... + 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 @@ -127,6 +135,11 @@ 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) \nothtml{text} @@ -148,13 +161,15 @@ Environment htmlversion \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 + 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> - \cmdinvoke{cmd}{mandatory} - \cmdinvoke{cmd}[optional]{mandatory} - \cmdinvoke{cmd}{mandatory1}{mandatory2} + As \cmdinvoke, but arguments are typeset with \emph \checked{intials}{date} @@ -165,13 +180,13 @@ Environment htmlversion 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| +\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 @@ -179,11 +194,9 @@ Environment htmlversion 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{...} +\Package{ackage name}(no .sty) +\Class{lass name} (no .cls) +\ProgName{executable command name} Set the item in an appropriate fashion. _Please_ use these commands wherever appropriate. @@ -207,6 +220,7 @@ Typesetting things, arguments in braces: Typesetting environments: quote, description, itemize, enumerate, verbatim + Other odds and ends: $\pi$, $...$, \$, \#, \ , \&, ~ [just produces a space] |