summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/FAQ-en/faqbody.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/FAQ-en/faqbody.tex')
-rw-r--r--Master/texmf-dist/doc/generic/FAQ-en/faqbody.tex2466
1 files changed, 1816 insertions, 650 deletions
diff --git a/Master/texmf-dist/doc/generic/FAQ-en/faqbody.tex b/Master/texmf-dist/doc/generic/FAQ-en/faqbody.tex
index 1b35a314993..2fd9eff8f33 100644
--- a/Master/texmf-dist/doc/generic/FAQ-en/faqbody.tex
+++ b/Master/texmf-dist/doc/generic/FAQ-en/faqbody.tex
@@ -1,4 +1,4 @@
-\def\faqfileversion{3.18} \def\faqfiledate{2008-06-20}
+\def\faqfileversion{3.19} \def\faqfiledate{2009-06-10}
%
% The above line defines the file version and date, and must remain
% the first line with any `assignment' in the file, or things will
@@ -16,90 +16,73 @@
% ... files
\input{filectan}
+% this environment is for the benefit of new-style file generation
+\begin{introduction}
+% suppress section numbers until end environment
+\nothtml{\csname c@secnumdepth\endcsname=-1 }
\section{Introduction}
This is a set of Frequently Asked Questions (\acro{FAQ}) for
-English-speaking users of \TeX{}. The questions answered here cover a
-wide range of topics, but the actual typesetting issues are mostly
+English-speaking users of \TeX{}. The questions answered here cover
+a wide range of topics, but the actual typesetting issues are mostly
covered from the viewpoint of a \LaTeX{} user.
You may use the \acro{FAQ}
\begin{itemize}
-\item by reading a printed document,
+\item by reading a printed document,
\item by viewing a \acro{PDF} file, with hyperlinks to assist
browsing: copies are available formatted for printing on
\CTANhref{faq-a4}{A4 paper} or on % ! line break
\CTANhref{faq-letter}{North American ``letter'' paper}, or
\item by using the \acro{FAQ}'s web interface (base \acro{URL}:
- \URL{http://www.tex.ac.uk/faq}); this version provides simple search
- capabilities, as well as a link to Google for a more sophisticated
- search restricted to the \acro{FAQ} itself, or
+ \URL{http://www.tex.ac.uk/faq}); this version provides simple
+ search capabilities, as well as a link to Google for a more
+ sophisticated search restricted to the \acro{FAQ} itself, or
\item via Scott Pakin's \CTANhref{visualFAQ}{Visual FAQ}.
\end{itemize}
-\begin{htmlversion}
-% pseudo-subsection here, because of limitations of latex->html translator
-\textbf{Caveat: Acquiring files}
-
-Most answers in this \acro{FAQ} provide links for downloading
-software; a large proportion of these links direct you to entire
-directories on the \acro{CTAN} archives. Unfortunately, some browsers
-issue a sequence of commands that causes \acro{CTAN} servers to deny
-the existence of compressed archive files of the directory, that the
-server would be happy to create ``on the fly''. The \acro{FAQ}
-therefore offers three possible links for downloading directories
-(that aren't already designated ``browse only''): the links give you
-\extension{zip} and \extension{tar.gz} archives, and a link for browsing
-the directory.
-
-Fortunately, \acro{CTAN} is switching to statically-generated
-directory archive files; many directories mentioned in this \acro{FAQ}
-will also exist as \extension{zip} files on the archives, and won't fall
-foul of the browser problem. Of course, if the \extension{zip} file
-does not exist, and the browser is playing up, you will need to use
-the ``browse'' link.
-\end{htmlversion}
-
-\htmlignore
-\subsection*{Finding the Files}
-
-Unless otherwise specified, all files mentioned in this \acro{FAQ} are
-available from a \acro{CTAN} archive, or from one of their mirrors.
-\Qref[Question]{}{Q-archives} % this one doesn't need anchor text
-gives details of the \acro{CTAN} archives, and how to retrieve files from
-them. If you don't have access to the Internet, the
-\Qref*{\texlive{} distribution}{Q-CD} offers off-line snapshots of
-the archives.
-
-The reader should also note that the first directory name of the path
-name of every file on \acro{CTAN} has been elided from what follows, for the
-simple reason that it's always the same (\path{tex-archive/}).
-
-To avoid confusion, we've also elided the full stop
-from the end of any sentence whose last item is a path name (such
-sentences are rare, and only occur at the end of paragraphs). Though
-the path names are set in a different font from running text, it's not
-easy to distinguish the font of a single dot!
-\endhtmlignore
+\subsection{Finding the Files}
+
+Unless otherwise specified, all files mentioned in this \acro{FAQ}
+are available from a \acro{CTAN} archive, or from a mirror of
+\acro{CTAN}~--- see \Qref[question]{later discussion}{Q-archives}% ! space
+\narrowonly{, which gives details} of the \acro{CTAN}
+archives\wideonly{ and}\narrowonly{, including} how to retrieve files
+from them. If you don't have access to the internet, the
+\Qref*{\texlive{} distribution}{Q-CD} offers off-line snapshots of the
+archives.
+
+The reader should also note that the first directory name of the
+path name of every file on \acro{CTAN} is omitted from what
+follows, for the simple reason that, while it's always the same
+(\path{tex-archive/}) on the main sites, mirror sites often choose
+something else.
+
+To avoid confusion, we also omit the full stop from the end of
+any sentence whose last item is a path name (such sentences are
+rare, and only occur at the end of paragraphs). Though the path
+names are set in a different font from running text, it's not easy
+to distinguish the font of a single dot!
\latexhtml{\subsection*{Origins}}{\textbf{Origins}}
-The \acro{FAQ} was originated by the Committee of the \acro{UK} \TeX{}
-Users' Group (\acro{UK}~\acro{TUG}) as a development of a regular
-posting to the \emph{Usenet} newsgroup \Newsgroup{comp.text.tex} that
-was maintained for some time by Bobby Bodenheimer. The first
-\acro{UK} version was much re-arranged and corrected from the
-original, and little of Bodenheimer's work now remains.
+The \acro{FAQ} was originated by the Committee of the \acro{UK}
+\TeX{} Users' Group (\acro{UK}~\acro{TUG}) as a development of a
+regular posting to the \emph{Usenet} newsgroup
+\Newsgroup{comp.text.tex} that was maintained for some time by Bobby
+Bodenheimer. The first \acro{UK} version was much re-arranged and
+corrected from the original, and little of Bodenheimer's work now
+remains.
The following people (at least~--- there are almost certainly others
whose names weren't correctly recorded) have contributed help or
-advice on the development of the \acro{FAQ}:
-Donald Arseneau,
+advice on the development of the \acro{FAQ}: Donald Arseneau,
Rosemary Bailey, % lots of initial set of maths answers
Barbara Beeton, % one of first reviewers outside cttee
-Karl Berry,
+Karl Berry, % often provides comments & suggestions
Giuseppe Bilotta,
Charles Cameron,
+Fran\c{c}ois Charette, % update of q-xetex
Damian Cugley,
Michael Dewey,
Michael Downes, % (RIP) on (ams)maths stuff
@@ -130,7 +113,8 @@ Oleg Katsitadze, % revision of q-eplain
Isaac Khabaza, % kindersley book
Ulrich Klauer, % pointed out twaddle in TeXpronounce
Markus Kohm, % help with functionality of Koma-script
-David Kraus, % help with tocbibind (spotted embarrassing typo :-} )
+Stefan Kottwitz % picked up text of q-wideflt
+David Kraus, % help with tocbibind (spotted embarrassing typo :-} )
Ryszard Kubiak, % comment about q-driver
Simon Law,
Daniel Luecking,
@@ -140,7 +124,7 @@ Andreas Matthias,
Brooks Moses, % editorial suggestion
Iain Murray, % alternative solution in q-hyperdupdest
Vilar Camara Neto, % explain breakurl pkg, suggest use of numprint
-Dick Nickalls, % now a member of the committee
+Dick Nickalls,
Ted Nieland,
Hans Nordhaug,
Pat Rau,
@@ -148,23 +132,27 @@ Heiko Oberdiek,
Piet van Oostrum,
Scott Pakin,
Oren Patashnik,
+Manuel P\'egouri\'e-Gonnard, % improvement of q-luatex
Steve Peter, % comprehensive review, lots of typos etc
Sebastian Rahtz, % without whom there would be no...
Philip Ratcliffe, % help with a bibtex oddity
Chris Rowley, % founding father
-Jos\'e Carlos Santos, % very assiduous reader of new versions
+Jos\'e Carlos Santos, % assiduous reader of new versions
Walter Schmidt,
Hans-Peter Schr\"ocker,
Joachim Schrod,
Maarten Sneep, % summary of c.t.t thread for outszwrng, inter alia
Axel Sommerfeldt, % suggested rewrite of q-hyperdupdest
+Philipp Stephani, % xlation of komascript keyval stuff
James Szinger, % who responded on c.t.t to request for answer
Ulrik Vieth,
Mike Vulis,
Chris Walker, % revtex alert, ite suggestion (q-labelfig)
Peter Wilson, % several, incl functionality of memoir
+Joseph Wright, % help with keyval
Rick Zaccone and
Reinhard Zierke.
+\end{introduction}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -176,8 +164,12 @@ Reinhard Zierke.
\href{http://sunburn.stanford.edu/~knuth/}{Donald E. Knuth}, who
says in the Preface to his book on \TeX{}
(see \Qref[question]{books about TeX}{Q-books}) that it is
-%% beware line wrap
-``\emph{intended for the creation of beautiful books~--- and especially for books that contain a lot of mathematics}''.
+%% !line wrap avoided by two commands
+``\emph{intended for the creation of beautiful books~---}
+\emph{and especially for books that contain a lot of mathematics}''.
+(If \TeX{} were \emph{only} good for mathematical books, much of its
+use nowadays would not happen: it's actually a pretty good general
+typesetting system.)
Knuth is Emeritus Professor of the Art of Computer Programming at
Stanford University in California, \acro{USA}. Knuth developed the
@@ -279,6 +271,191 @@ A mailing list discussing \MP{} is available;
The \acro{TUG} website also hosts a % ! line break
\href{http://tug.org/metapost.html}{\MP{} summary page}.
+%****
+\Question[Q-texthings]{Things with ``\TeX{}'' in the name}
+
+New \TeX{} users are often baffled by the myriad terms with ``\TeX{}''
+in the name. The goal of this answer is to clarify some of the more
+common \TeX{} terms.
+
+\paragraph{\TeX{} itself}
+\TeX{} proper is a typesetting system based on a set of low-level
+control sequences that instruct \TeX{} how to lay out text on the
+page. For example, \csx{hskip} inserts a given amount of horizontal
+space into the document, and \csx{font} makes a given font available
+to \TeX{}. \TeX{} is fully programmable using an integrated macro
+scripting language that supports variables, scoping, conditional
+execution, control flow, and function (really, macro) definitions.
+See % ! line break
+\Qref[question]{What is \TeX{}?}{Q-whatTeX} for some background
+information on \TeX{} and % ! line break
+\Qref[question]{Reference documents}{Q-ref-doc} for pointers to
+descriptions of \TeX{} control sequences, data types, and other key
+parts of \TeX{}.
+
+\paragraph{\TeX{} macro packages (a.k.a.~\TeX{} formats)}
+\TeX{}'s control sequences are tedious to use directly; they are
+intended primarily as building blocks for higher-level---and therefore
+more user-friendly---abstractions. For example, there is no way in
+base \TeX{} to specify that a piece of text should be typeset in a
+larger font. Instead, one must keep track of the current size and
+typeface, load a new font with the same typeface but a (specified)
+larger size, and tell \TeX{} to use that new font until instructed
+otherwise. Fortunately, because \TeX{} is programmable, it is
+possible to write a macro that hides this complexity behind a simple,
+new control sequence. For example,
+%
+\cmdinvoke{larger}{my text} can be defined to typeset ``my text'' in
+the next larger font).
+
+While some users write their own, perfectly customized set of
+macros---which they then typically reuse across many documents---it is
+far more common to rely upon a \emph{macro package}, a collection of
+\TeX{} macros written by experts. For the user's convenience, these
+macro packages are often combined with the base \TeX{} engine into a
+standalone executable. The following are some of that macro packages
+that you are likely to encounter:
+\begin{description}
+ \item[Plain \TeX{} (executable: \ProgName{tex})]
+ See
+ \Qref[questions]{Books on \TeX{} and its relations}{Q-books},
+ \Qref[]{Online introductions: \TeX{}}{Q-man-tex},
+ \Qref[]{Should I use Plain \TeX{} or \LaTeX{}?}{Q-plainvltx} and
+ \Qref[]{Freely available \AllTeX{} books}{Q-ol-books}.
+ Note that the Plain \TeX{} executable is called \ProgName{tex}; the
+ base \TeX{} engine is generally provided by a separate executable
+ such as \ProgName{initex} or as a \texttt{-ini} flag to
+ \ProgName{tex}.
+
+ \item[\LaTeX{} (executable: \ProgName{latex})]
+ See
+ \Qref[questions]{Books on \TeX{} and its relations}{Q-books},
+ \Qref[]{\AllTeX{} Tutorials, etc.}{Q-tutorials*},
+ \Qref[]{Online introductions: \LaTeX{}}{Q-man-latex},
+ \Qref[]{Specialized \AllTeX{} tutorials}{Q-tutbitslatex} and
+ \Qref[]{Directories of \AllTeX{} information}{Q-doc-dirs}.
+ Note that there have been two major versions of \LaTeX{}: \LaTeXe{}
+ refers to the current version of \LaTeX{} while \LaTeXo{} is the
+ long-since-obsolete (since 1994) version (cf.~%
+ \Qref[question]{What is \LaTeXe{}?}{Q-latex2e} for more information).
+
+ \item[\CONTeXT{} (executable: \ProgName{texexec})]
+ See
+ \Qref[question]{What is \CONTeXT{}?}{Q-context}.
+
+ \item[Texinfo (executables: \ProgName{tex}, \ProgName{makeinfo})]
+ See
+ \Qref[question]{What is Texinfo?}{Q-texinfo}. \ProgName{makeinfo}
+ converts Texinfo documents to \acro{HTML}, DocBook, Emacs info,
+ \acro{XML}, and plain text. \ProgName{Tex} (or wrappers such as
+ \ProgName{texi2pdf} and \ProgName{texi2pdf}) produce one of \TeX{}'s
+ usual output formats such as \acro{DVI} or \acro{PDF}. Because
+ \ProgName{tex} loads the Plain \TeX{} macros, not the Texinfo ones,
+ a Texinfo document must begin with \cmdinvoke{input}{texinfo} to
+ explicitly load the Texinfo macro package.
+
+ \item[\Eplain{}---Extended Plain \TeX{} (executable: \ProgName{eplain})]
+ See
+ \Qref[question]{What is \Eplain{}?}{Q-eplain}.
+\end{description}
+
+\paragraph{Modified \ProgName{tex} executables}
+The original \ProgName{tex} executable was produced in the late 1970s
+(cf.~\Qref[question]{What is \TeX{}?}{Q-whatTeX}) and consequently
+lacked some features that users have come to expect from today's
+software. The following programs address these issues by augmenting
+the \TeX{} engine with some additional useful features:
+
+\begin{description}
+ \item[\PDFTeX{} (executable: \ProgName{pdftex})]
+ \TeX{}, which predates the \acro{PDF} file format by a decade,
+ outputs files in a \TeX{}-specific format called \acro{DVI}
+ (cf.~\Qref[question]{What is a \acro{DVI} file?}{Q-dvi}). In
+ contrast, \PDFTeX{} can output both \acro{DVI} \emph{and} \acro{PDF}
+ files. In \acro{PDF} mode, it lets documents exploit various
+ \acro{PDF} features such as hyperlinks, bookmarks, and annotations,
+ \PDFTeX{} additionally supports two sophisticated micro-typographic
+ features: character protrusion and font expansion. See
+ \Qref[question]{What is \PDFTeX{}?}{Q-whatpdftex}.
+
+ \item[\xetex{} (executable: \ProgName{xetex})]
+ \TeX{} not only predates all major font technologies in use today
+ (e.g.,~TrueType, OpenType, and PostScript Type~1) but also predates
+ the notion that fonts be included with an operating system.
+ Consequently, \TeX{} uses its own font formats, which are
+ incompatible with anything a user is likely to have preinstalled.
+ \xetex{} addresses this issue by enhancing \TeX{}'s \csx{font}
+ control sequence to support all of the fonts made available by the
+ operating system. See
+ \Qref[question]{What is \xetex{}?}{Q-xetex}.
+
+ \item[\LuaTeX{} (executable: \ProgName{luatex})]
+ \TeX{} is programmed in its own, integrated, macro-based programming
+ language. Many users have criticized this language for being
+ needlessly difficult to program. \LuaTeX{} addresses that criticism
+ by integrating a modern scripting language, Lua, into the base
+ \TeX{} engine. See
+ \Qref[question]{What is \LuaTeX{}?}{Q-luatex}.
+
+ \item[\eTeX{} (executable: \ProgName{etex})]
+ \eTeX{} provides a number of features that are only indirectly
+ useful to end users but that can be immensely useful to package
+ developers. Consequently, there is an increasing number of macro
+ packages that require the use of \eTeX{}. (Note: Be careful not to
+ confuse \eTeX{}, which enhances the \TeX{} engine, with \Eplain{},
+ which enhances the Plain \TeX{} macro package.) See
+ \Qref[question]{What is \eTeX{}?}{Q-etex}.
+\end{description}
+
+Because each of the above modifies only the base \TeX{} engine, it is
+possible to combine any of those with any of the \TeX{} macro packages
+listed earlier to produce executables with both sets of features. For
+example, the \ProgName{pdflatex}, \ProgName{xelatex} and
+\ProgName{lualatex} executables each combine
+\LaTeX{} with an enhanced \TeX{} engine. Some executables combine the
+features of multiple enhanced \TeX{} engine: \ProgName{pdfetex}
+combines \PDFTeX{} and \eTeX{} into a single executable.
+
+As combining features is a generally desirable tendency, current
+\TeX{} distributions (see below) incorporate the features of \PDFTeX{}
+and \eTeX{} into a single executable. This executable may be
+offered with a \LaTeX{} format (as \ProgName{latex} or
+\ProgName{pdflatex}) or with a \plaintex{} format (as
+\ProgName{pdftex}). (\ProgName{Tex} remains with an unadorned \TeX{}
+executable using \plaintex{}, for people such as Knuth himself, who
+want the certainty of the ``original''.)
+
+
+\paragraph{\TeX{} distributions}
+A \emph{\TeX{} distribution} is a collection of \TeX{}-related
+software. Generally, a \TeX{} distribution includes a set of core
+\TeX{} executables such as \ProgName{tex} and \ProgName{latex};
+various fonts optimized for use with \TeX{}; helper programs such as
+the \BibTeX{} bibliographic-database formatter, editors, integrated
+development environments, file-format-conversion programs; numerous
+\LaTeX{} packages; configuration tools; and any other goodies the
+distributor chooses to include. Commonly encountered \TeX{}
+distributions include \texlive{}, \miktex{} and Mac\TeX{}; older ones
+include oz\TeX{}, \acro{CM}ac\TeX{} and te\TeX{}. Some \TeX{}
+distributions target a specific operating system and/or processor
+architecture; others run on multiple platforms. Some \TeX{}
+distributions are free; others require payment. See % ! line break
+\Qref[question]{\AllTeX{} for different machines}{Q-TeXsystems} for a
+list of free and shareware \TeX{} distributions and % ! line break
+\Qref[question]{Commercial \TeX{} implementations}{Q-commercial} for a
+list of commercial \TeX{} distributions.
+
+
+\paragraph{Summary}
+If your document begins with \csx{documentclass}, you're using some
+form of the \LaTeX{} macro package. Even if hidden behind a button in
+a \TeX{}-aware GUI, this document is getting compiled by a \TeX{}
+executable---probably \ProgName{latex} or \ProgName{pdflatex}---to
+produce an output file. The executable came bundled as part of a
+\TeX{} distribution such as \miktex{}, which includes various other
+\TeX{}-related components.
+%****
+
\Question[Q-triptrap]{How can I be sure it's really \TeX{}?}
\TeX{} (and \MF{} and \MP{}) are written in a
@@ -399,10 +576,17 @@ individually contributed) may require \eTeX{} for optimum performance.
\Question[Q-whatpdftex]{What is \PDFTeX{}?}
-\PDFTeX{} has entered the main stream of \TeX{} distributions: most
-\LaTeX{} and \CONTeXT{} users nowadays use \PDFTeX{} whether they know
-it or not (more precisely, they use an amalgam of \PDFTeX{} and
-\Qref*{\eTeX{}}{Q-etex}). So what is \PDFTeX{}?
+One can reasonably say that \PDFTeX{} is (today) the main stream of
+\TeX{} distributions: most \LaTeX{} and \CONTeXT{} users nowadays use
+\PDFTeX{} whether they know it or not (more precisely, they use
+\PDFTeX{} extended by
+\begin{wideversion}
+ \Qref*{\eTeX{}}{Q-etex}).
+\end{wideversion}
+\begin{narrowversion}
+ \eTeX{}~--- \Qref{}{Q-etex}).
+\end{narrowversion}
+So what is \PDFTeX{}?
\PDFTeX{} is a development of \TeX{} that is capable of generating
typeset \acro{PDF} output in place of \acro{DVI}. \PDFTeX{} has
@@ -457,14 +641,20 @@ was superseded in 1994 by a new version (\LaTeXe{}) provided by
\Qref*{the \LaTeX{} team}{Q-LaTeX3}.
\LaTeXe{} is now the only readily-available version of
\LaTeX{}, and draws together several threads of \LaTeX{} development
-from the later days of \LaTeXo{}.
+from the later days of \LaTeXo{}. The ``e'' of the name is (in the
+% next (ghastly) line needed to maintain typesetting
+\wideonly{\Qref{official logo}{Q-logos}}\narrowonly{official logo~--- \Qref{\relax}{Q-logos}})
+% the \relax allows sanitize to cope with the line. just don't ask...
+a single-stroke epsilon
+(\latexhtml{\ensuremath{\varepsilon}}{ε}, supposedly
+indicative of no more than a small change.
\LaTeXe{} has several enhancements over \LaTeXo{}, but they were all
rather minor, with a view to continuity and stability rather than the
``big push'' that some had expected from the team. \LaTeXe{}
continues to this day to offer a compatibility mode in which most
files prepared for use with \LaTeXo{} will run (albeit with somewhat
-reduced performance, and subject to bitter complaints in the log
+reduced performance, and subject to voluminous complaints in the log
file). Differences between \LaTeXe{} and \LaTeXo{} are
outlined in a series of `guide' files that are available in every
\LaTeX{} distribution (the same directory also contains ``news'' about
@@ -473,20 +663,18 @@ each new release of \LaTeXe{}).
\item[\nothtml{\rmfamily}\LaTeX{} guides and news]\CTANref{latexdoc}
\end{ctanrefs}
-
-\nothtml{\begingroup\ifboldmathavail\boldmath\fi}
\Question[Q-latexpronounce]{How should I pronounce ``\LaTeX{}(\twee{})''?}
-\nothtml{\afterquestion}
Lamport never recommended how one should pronounce \LaTeX{}, but a lot
of people pronounce it `Lay \TeX{}' or perhaps `Lah \TeX{}' (with
\TeX{} pronounced as the program itself; see
\Qref[question]{the rules for TeX}{Q-TeXpronounce}). It is definitely
-\emph{not} to be pronounced in the same way as the rubber-tree gum.
+\emph{not} to be pronounced in the same way as the rubber-tree gum
+(which would be `lay teks').
-The `epsilon' in `\LaTeXe{}' is supposed to be suggestive of a small
-improvement over the old \LaTeXo{}. Nevertheless, most people
-pronounce the name as `\LaTeX{}-two-ee'.
+The \LaTeXe{} logo is supposed to end with an
+\latexhtml{\ensuremath{\varepsilon}}{ε}; nevertheless, most
+people pronounce the name as `\LaTeX{}-two-ee'.
\Question[Q-plainvltx]{Should I use \plaintex{} or \LaTeX{}?}
@@ -495,12 +683,13 @@ by \plaintex{}, and produce highly respectable documents using it
(Knuth is an example of this, of course). But equally, many people
are happy to let someone else take the design decisions for them,
accepting a small loss of flexibility in exchange for a saving of
-brain power.
+(mental) effort.
The arguments around this topic can provoke huge amounts of noise and
-heat, without offering much by way of light; your best bet is to find
-out what those around you are using, and to go with the crowd. Later
-on, you can always switch your allegiance; don't bother about it.
+heat, without offering much by way of light; your best bet may be to
+find out what those around you are using, and to follow them in the
+hope of some support. Later on, you can always switch your
+allegiance; don't bother about it.
If you are preparing a manuscript for a publisher or journal, ask them
what markup they want before you
@@ -583,9 +772,7 @@ prodigious energy. Support is available via a % ! line break
\item[\nothtml{\rmfamily}\CONTeXT{} distribution]\CTANref{context}
\end{ctanrefs}
-\nothtml{\begingroup\ifboldmathavail\boldmath\fi}
\Question[Q-AMSpkg]{What are the \acro{AMS} packages (\AMSTeX{}, \emph{etc}.)?}
-\nothtml{\afterquestion}
\AMSTeX{} is a \TeX{} macro package, originally written by Michael Spivak for
the American Mathematical Society (\acro{AMS}) during 1983--1985 and
@@ -599,14 +786,12 @@ numbering, ellipsis dots, matrices, double accents, multi-line
subscripts, syntax checking (faster processing on initial
error-checking \TeX{} runs), and other things.
-As \LaTeX{} increased in popularity, authors asked to submit papers to
-the \acro{AMS} in \LaTeX{}, and so the \acro{AMS} developed
-\AMSLaTeX{}, which is a
-collection of \LaTeX{} packages and classes that offer authors most of
+As \LaTeX{} increased in popularity, authors sought to submit papers to
+the \acro{AMS} in \LaTeX{}, so \AMSLaTeX{} was developed. \AMSLaTeX{}
+is a collection of \LaTeX{} packages and classes that offer authors most of
the functionality of \AMSTeX{}.
The \acro{AMS} no longer recommends the use of \AMSTeX{}, and urges
-its users to use \AMSLaTeX{} instead.
-\checked{RAB}{1994/11/12} % edited by RF; input from Michael Downes, too
+its authors to use \AMSLaTeX{} instead.
\begin{ctanrefs}
\item[\nothtml{\rmfamily}\AMSTeX{} distribution]\CTANref{amstex}
\item[\nothtml{\rmfamily}\AMSLaTeX{} distribution]\CTANref{amslatex}
@@ -617,9 +802,10 @@ its users to use \AMSLaTeX{} instead.
The \href{http://tug.org/eplain}{\Eplain{}}
macro package expands on and extends the definitions in \plaintex{}.
\Eplain{} is not intended to provide ``generic typesetting
-capabilities'', as do \LaTeX{} or \Qref*{Texinfo}{Q-texinfo}. Instead, it
-defines macro tools that should be useful whatever commands you choose
-to use when you prepare your manuscript.
+capabilities'', as do \CONTeXT{}, \LaTeX{} or
+\Qref*{Texinfo}{Q-texinfo}. Instead, it defines macro tools that
+should be useful whatever commands you choose to use when you prepare
+your manuscript.
For example, \Eplain{} does not have a command \csx{section},
which would format section headings in an ``appropriate'' way, as
@@ -632,9 +818,9 @@ of luck.
On the other hand, almost everyone would like capabilities such as
cross-referencing by labels, so that you don't have to put actual page
-numbers in the manuscript. The authors of \Eplain{} are not aware of
-any generally available macro packages that do not force their
-typographic style on an author, and yet provide such capabilities.
+numbers in the manuscript. The authors of \Eplain{} believe it is the
+only generally available macro package that does not force its
+typographic style on an author, and yet provides these such capabilities.
Another useful feature of \Eplain{} is the ability to create PDF files
with hyperlinks. The cross-referencing macros can implicitly generate
@@ -757,16 +943,18 @@ he will continue to fix any bugs that are reported to him (though
bugs are rare). This decision was made soon after
\TeX{} version~3.0 was released; at each bug-fix release
the version number acquires one more digit, so that it tends to the
-limit~\ensuremath{\pi} (at the time of writing, Knuth's latest release is version
-3.141592). Knuth wants \TeX{} to be frozen at version~\ensuremath{\pi} when he
-dies; thereafter, no further changes may be made to Knuth's source.
-(A similar rule is applied to \MF{}; its version number tends to the
-limit~\ensuremath{e}, and currently stands at 2.71828.)
+limit~\ensuremath{\pi} (at the time of writing, Knuth's latest release
+is version 3.1415926). Knuth wants \TeX{} to be frozen at
+version~\ensuremath{\pi} when he dies; thereafter, no further changes
+may be made to Knuth's source. (A similar rule is applied to \MF{};
+its version number tends to the limit~\ensuremath{e}, and currently
+stands at 2.718281.)
Knuth explains his decision, and exhorts us all to respect it, in a
-paper originally published in \TUGboat{} 11(4) (and reprinted in the
-% ! line break
-\href{http://www.ntg.nl/maps/pdf/5_34.pdf}{NTG journal MAPS}).
+paper originally published in % ! line break
+\href{http://tug.org/TUGboat/Articles/tb11-4/tb30knut.pdf}{\TUGboat{} 11(4)},
+and reprinted in the % ! line break
+\href{http://www.ntg.nl/maps/pdf/5_34.pdf}{NTG journal MAPS}.
There are projects (some of them long-term
projects: see, for example,
@@ -976,7 +1164,9 @@ other books covering \TeX{}:
Krantz (CRC Press, 1994, \ISBN{0-849-37159-7})
\item[\TeX{} by Topic]by Victor Eijkhout (Addison-Wesley, 1992,
\ISBN{0-201-56882-9}~--- now out of print, but see
- \Qref[question]{online books}{Q-ol-books})
+ \Qref[question]{online books}{Q-ol-books}; you can now buy a copy
+ printed, on demand, by Lulu~--- see
+ \url{http://www.lulu.com/content/2555607})
\item[\TeX{} for the Beginner]by Wynter Snow (Addison-Wesley, 1992,
\ISBN{0-201-54799-6})
\item[\TeX{} for the Impatient]by Paul W.~Abrahams, Karl Berry and
@@ -1208,13 +1398,14 @@ Other non-English \acro{FAQ}s are available (off-\acro{CTAN}):
\item[German]Posted regularly to \Newsgroup{de.comp.tex}, and archived
on \acro{CTAN}; the \acro{FAQ} also appears at
\URL{http://www.dante.de/faq/de-tex-faq/}
-\item[French]An interactive (full-screen!) FAQ may be found at
- \URL{http://www.frenchpro6.com/screen.pdf/FAQscreen.pdf}, and a copy
- for printing at \URL{http://frenchle.free.fr/FAQ.pdf};
+\item[French]%
+%% An interactive (full-screen!) FAQ may be found at
+%% \URL{http://www.frenchpro6.com/screen.pdf/FAQscreen.pdf}, and a copy
+%% for printing at \URL{http://frenchle.free.fr/FAQ.pdf};
A FAQ used to be posted regularly to
\Newsgroup{fr.comp.text.tex}, and is archived on \acro{CTAN}~---
sadly, that effort seems to have fallen by the wayside.
-\item[Spanish]See \URL{http://apolo.us.es/CervanTeX/FAQ/}
+%% \item[Spanish]See \URL{http://apolo.us.es/CervanTeX/FAQ/}
\item[Czech]See \URL{http://www.fi.muni.cz/cstug/csfaq/}
\end{booklist}
@@ -1238,8 +1429,8 @@ don't know what to do.
If you are seeking a particular package or program, look on your own
system first: you might already have it~--- the better \TeX{}
distributions contain a wide range of supporting material. The
-\acro{CTAN} Catalogue can also help: you can
-\href{http://www.tex.ac.uk/search}{search it}, or you can browse it
+\acro{CTAN} Catalogue can also identify packages that might help: you
+can \href{http://www.tex.ac.uk/search}{search it}, or you can browse it
% !!!! line break
``\href{http://www.tex.ac.uk/tex-archive/help/Catalogue/bytopic.html}{by topic}''.
A catalogue entry has a brief description of the package, and links to
@@ -1359,6 +1550,12 @@ application of your own common sense.
needs your local \Class{xyzthesis} class, or some other resource
not generally available, be sure to include a pointer to how the
resource can be obtained.
+\item Figures are special, of course. Sometimes the figure itself is
+ \emph{really} needed, but most problems may be demonstrated with a
+ ``figure substitute'' in the form of a
+ \cmdinvoke*{rule}{width}{height} command, for some value of
+ \meta{width} and \meta{height}. If the (real) figure is needed,
+ don't try posting it: far better to put it on the web somewhere.
\item Be as succinct as possible. Your helpers don't usually need to
know \emph{why} you're doing something, just \emph{what} you're
doing and where the problem is.
@@ -1490,12 +1687,17 @@ available on the web at \URL{http://www.ntg.nl/doc/wilkins/pllong.pdf}
\Question[Q-man-latex]{Online introductions: \LaTeX{}}
+A pleasing little document, ``Getting something out of \LaTeX{}'' is
+designed to give a feel of \LaTeX{} to someone who's never used it at
+all. It's not a tutorial, merely helps the user to decide whether to
+go on to a tutorial, and to `real' use of \LaTeX{}.
+
Tobias Oetiker's `(Not so) Short Introduction to \LaTeXe{}', is
regularly updated, as people suggest better ways of explaining things,
etc. The introduction is available on \acro{CTAN}, together with
translations into a rather large set of languages.
-Peter Flynn's ``Beginner's \LaTeX{}'' (which also started as course
+Peter Flynn's ``Beginner's \LaTeX{}'' (which started life as course
material) is a pleasing read. A complete copy may be found on
\acro{CTAN}, but it may also be browsed over the web
(\URL{http://www.tex.ac.uk/tex-archive/info/beginlatex/html/}).
@@ -1543,6 +1745,7 @@ tutorial is available from \acro{CTAN} as a \acro{PDF} file (though
the source is also available).
\begin{ctanrefs}
\item[\nothtml{\rmfamily}Beginner's \LaTeX{}]\CTANref{beginlatex-pdf}
+\item[\nothtml{\rmfamily}First \LaTeX{} document]\CTANref{first-latex-doc}
\item[\nothtml{\rmfamily}Not so Short Introduction]\CTANref{lshort}
(in English, you may browse for sources and other language versions at
\CTANref{lshort-parent})
@@ -1559,8 +1762,9 @@ The \acro{AMS} publishes a ``Short Math Guide for \LaTeX{}'', which is
available (in several formats) via
\URL{http://www.ams.org/tex/short-math-guide.html}
-Herbert Vo\ss{} is developing a parallel document, that is also very
-useful; it's part of his ``\Qref*{tips and tricks}{Q-doc-dirs}'' and
+Herbert Vo\ss{} has written an extensive guide to mathematics in
+\LaTeX{} (a German version of which is published as a book). The
+guide is part of his ``\Qref*{tips and tricks}{Q-doc-dirs}'' and
a copy is maintained on \acro{CTAN}.
%\URL{http://www.perce.de/LaTeX/math/Mathmode-TeX.pdf}
@@ -1594,7 +1798,7 @@ soon'').
Kjell Magne Fauske offers a set of examples of the use of the drawing
packages % ! line break
\Qref*{\acro{PGF} and \acro{T}ik\acro{Z}}{Q-drawing}; the % ! line break
-\href{http://www.fauskes.net/pgftikzexamples/}{examples catalogue}
+\href{http://www.texample.net/tikz/examples/}{examples catalogue}
includes examples (with output) from the package documentation as well
as code written by the author himself.
@@ -1677,14 +1881,26 @@ description, which includes page references to the \TeX{}book.
There doesn't seem to be a reference that takes in \plaintex{} as
well as the primitive commands.
+An interesting \LaTeX{} ``cheat sheet'' is available from \acro{CTAN}:
+it's a list of (more or less) everything you `ought to' remember, for
+basic \LaTeX{} use. (It's laid out very compactly for printing on N.\
+American `letter'; printed on \acro{ISO} \acro{A}4, it strains aged eyes\dots{})
+
Similarly, there's no completely reliable command-organised reference
-to \LaTeX{}, but the NASA % ! line break
+to \LaTeX{}. The page (provided by NASA) % ! line break
\href{http://www.giss.nasa.gov/latex/}{Hypertext Help with LaTeX} is
recently much improved. It still talks in \LaTeXo{}-isms in places,
-but it's been updated for current \LaTeX{}; there are a number of
+but it's been updated for current \LaTeX{}. There are a number of
mirrors of the site, and it may be worth choosing a ``local'' one if
you're going to use it a lot.
+Another \LaTeXe{} reference (provided by the Emerson Center of Emory
+University) is: % ! line break
+\href{http://www.emerson.emory.edu/services/latex/latex2e/latex2e_toc.html}{LaTeXe help}
+\begin{ctanrefs}
+\item[\nothtml{\rmfamily}Cheat sheet]\CTANref{latexcheat}
+\end{ctanrefs}
+
\Question[Q-doc-wiki]{WIKI pages for \TeX{} and friends}
The \emph{WIKI} concept can be a boon to everyone, if used sensibly.
@@ -1694,18 +1910,20 @@ for chaos, there is evidence that a strong user community can keep a
WIKI under control.
Following the encouraging performance of the % ! line break
-\href{http://contextgarden.net/}{\CONTeXT{} WIKI}, both a
-\href{http://en.wikibooks.org/wiki/TeX}{(Plain) \TeX{} WIKI} and a
-\href{http://en.wikibooks.org/wiki/LaTeX}{\LaTeX{} WIKI} have been
-established. Both seem rather sparse, as yet, and the \LaTeX{} WIKI
-contains some suggestions that go counter to established advice (e.g.,
-the \LaTeX{} WIKI has details on the % ! line break
-\Qref*{use of the \environment{eqnarray} environment}{Q-eqnarray});
-however one may hope that both will become useful resources in the
-longer term.
+\href{http://contextgarden.net/}{\CONTeXT{} WIKI}, valiant efforts
+have been made generating ``WIKI books'' for \AllTeX{} users. Thus we
+have \href{http://en.wikibooks.org/wiki/TeX}{(Plain) \TeX{} WIKI} and
+\href{http://en.wikibooks.org/wiki/LaTeX}{\LaTeX{} WIKI} are well
+established. Neither would seem yet to be of publication quality, but
+they both seem useful reference sources.
\Question[Q-typo-style]{Typography tutorials}
+Peter Wilson's manual for his \Class{memoir} class has a lengthy
+introductory section on typographic considerations, which is a fine
+tutorial, written by someone who is aware of the issues as they apply
+to \AllTeX{} users.
+
There's also (at least one) typographic style tutorial available on
the Web, the excellent % ! line break
``\href*{http://www.nbcs.rutgers.edu/~hedrick/typography/typography.janson-syntax.107514.pdf}{Guidelines for Typography in NBCS}''.
@@ -1718,11 +1936,6 @@ ambition to supplant such excellent books as
\Qref*{Bringhurst's}{Q-typebooks}, but the document (though it does
contain its Rutgers-local matter) is a fine introduction to the issues
of producing readable documents.
-
-Peter Wilson's manual for his \Class{memoir} class has a lengthy
-introductory section on typographic considerations, which is a fine
-tutorial, written by someone who is aware of the issues as they apply
-to \AllTeX{} users.
\begin{ctanrefs}
\item[memoir \nothtml{\rmfamily}distribution]\CTANref{memoir}
\end{ctanrefs}
@@ -1746,7 +1959,10 @@ the web, and until relatively recently this demand went un-answered.
The first to appear was Victor Eijkhout's excellent ``\TeX{} by
Topic'' in 2001 (it had been published by Addison-Wesley, but was long
out of print). The book is now available on \acro{CTAN}; it's not a
-beginner's tutorial but it's a fine reference.
+beginner's tutorial but it's a fine reference. It's also available,
+as a printed copy, via the on-line publishers
+\href{http://www.lulu.com/content/2555607/}{Lulu} (not quite free, of
+course, but not a \emph{bad} deal\dots{}).
Addison-Wesley have also released the copyright of ``\TeX{} for the
Impatient'' by Paul W.~Abrahams, Karl Berry and Kathryn A.~Hargreaves,
@@ -1784,9 +2000,9 @@ distributions, the \ProgName{texdoc} command often helps, as in:
texdoc footmisc
\end{verbatim}
\end{quote}
-which opens a \acro{DVI} viewer window showing documentation of the
+which opens a window showing documentation of the
\Package{footmisc} package. According to the type of file
-\ProgName{texdoc} finds, it will launch a \acro{DVI} or \PS{} viewer
+\ProgName{texdoc} finds, it will launch a \acro{DVI} viewer
or a \acro{PDF} reader.
If \ProgName{texdoc} can't find any documentation, it may launch a Web
@@ -1862,9 +2078,12 @@ knowledge it is possible to use the documented source of \LaTeX{} as
reference material (dedicated authors will acquaint themselves with the
source as a matter of course). A complete set of the documented
source of \LaTeX{} may be prepared by processing the file
-\File{source2e.tex} in the \LaTeX{} distribution, but individual files
-in the distribution may be processed separately with \LaTeX{}, like
-any well-constructed \Qref*{\extension{dtx} file}{Q-dtx}.
+\File{source2e.tex} in the \LaTeX{} distribution. Such processing is
+noticeably tedious, but Heiko Oberdiek has prepared a well-linked
+\acro{PDF} version, which is in the file \File{base.tds.zip} of his
+\ProgName{latex-tds} distribution. Individual files in the \LaTeX{}
+distribution may be processed separately with \LaTeX{}, like any
+well-constructed \Qref*{\extension{dtx} file}{Q-dtx}.
Writing good classes is not easy; it's a good idea to read some
established ones (\File{classes.dtx}, for example, is the documented
@@ -1882,6 +2101,7 @@ understanding \File{classes.dtx}
\begin{ctanrefs}
\item[classes.dtx]\CTANref{latex-classes}
\item[clsguide.pdf]\CTANref{clsguide}
+\item[latex-tds \nothtml{rmfamily}collection]\CTANref{latex-tds}
\item[ltxguide.cls]\CTANref{ltxguide}
\item[\nothtml{\rmfamily}\LaTeX{} documentation]\CTANref{latexdoc}
\item[source2e.tex]\CTANref{latex-source}
@@ -1934,7 +2154,6 @@ written more as a document, and presented in \acro{PDF}.
\begin{ctanrefs}
\item[\nothtml{\rmfamily}Beginners' guide]\CTANref{mf-beginners}
\item[\nothtml{\rmfamily}Peter Wilson's ``experiences'']\CTANref{metafp-pdf}
- (\acro{PDF} format)
\item[\nothtml{\rmfamily}Vincent Zoonekynd's examples]\CTANref{zoon-mp-eg}
\end{ctanrefs}
@@ -1964,8 +2183,6 @@ may also be found on \acro{CTAN}. A summary and \acro{FAQ}
recommended.
\begin{ctanrefs}
\item[\nothtml{\rmfamily}\BibTeX{} documentation]\CTANref{bibtex-doc}
-\item[\nothtml{\rmfamily}\BibTeX{} documentation, in \acro{PDF}]%
- \CTANref{bibtex-doc-pdf}
\item[btxFAQ.pdf]\CTANref{bibtex-faq}
\item[\nothtml{\rmfamily}Tame the BeaST]\CTANref{ttb-pdf}
\end{ctanrefs}
@@ -1980,7 +2197,7 @@ of which are not shown (or even mentioned) in \AllTeX{} books.
\emph{The Comprehensive \LaTeX{} Symbol List} (by Scott Pakin
% beware line wrap
\emph{et al.}\@) illustrates over 2000 symbols, and details the
-commands and packages needed to produce them.
+commands and the \LaTeX{} packages needed to produce them.
Other questions in this \acro{FAQ} offer specific help on kinds of
symbols:
@@ -2164,6 +2381,71 @@ fonts (it uses \TeX{} to parse a description of the virtual font, and
\item[qdtexvpl]\CTANref{qdtexvpl}
\end{ctanrefs}
+\Question[Q-whatmacros]{What are (\TeX{}) macros}
+
+\TeX{} is a \emph{macro processor}: this is a computer-science-y term
+meaning ``text expander'' (more or less); \TeX{} typesets text as it
+goes along, but \emph{expands} each macro it finds. \TeX{}'s macros
+may include instructions to \TeX{} itself, on top of the simple text
+generation one might expect.
+
+Macros are a \emph{good thing}, since they allow the user to
+manipulate documents according to context. For example, the macro
+\csx{TeX} is usually defined to produce ``TEX'' with the `E' lowered,
+but in these \acro{FAQ}s the default definition of the macro is
+overridden, and it simply expands to the letters ``TeX''. (\emph{You}
+may not think this a good thing, but the author of the macros has his
+reasons~-- see \Qref[question]{\TeX{}-related logos}{Q-logos}.)
+
+Macro names are conventionally built from a \texttt{\textbackslash }
+followed by a sequence of letters, which may be upper or lower case
+(as in \csx{TeX}, mentioned above). They may also be % ! line break
+\texttt{\textbackslash \meta{any single character}}, which allows all
+sorts of oddities (many built in to most \TeX{} macro sets, all the
+way up from the apparently simple `\csx{ }' meaning ``insert a space
+here'').
+
+Macro programming can be a complicated business, but at their very
+simplest they need little introduction~--- you'll hardly need to be
+told that:
+\begin{quote}
+\begin{verbatim}
+\def\foo{bar}
+\end{verbatim}
+\end{quote}
+replaces each instance of \csx{foo} with the text ``bar''. The
+command \csx{def} is \plaintex{} syntax for defining commands;
+\LaTeX{} offers a macro \csx{newcommand} that goes some way towards
+protecting users from themselves, but basically does the same thing:
+\begin{quote}
+\begin{verbatim}
+\newcommand{\foo}{bar}
+\end{verbatim}
+\end{quote}
+Macros may have ``arguments'', which are used to substitute for marked
+bits of the macro expansion:
+\begin{quote}
+\begin{verbatim}
+\def\foo#1{This is a #1 bar}
+...
+\foo{2/4}
+\end{verbatim}
+\end{quote}
+or, in \LaTeX{} speak:
+\begin{quote}
+\begin{verbatim}
+\newcommand{\foo}[1]{This is a #1 bar}
+...
+\foo{3/4}
+\end{verbatim}
+\end{quote}
+Macro writing can get very complicated, very quickly. If you are a
+beginner \AllTeX{} programmer, you are well advised to read something
+along the lines of the \Qref*{\TeX{}book}{Q-books}; once you're under
+way, \Qref*{\TeX{} by Topic}{Q-ol-books} is possibly a more satisfactory
+choice. Rather a lot of the answers in these \acro{FAQ}s tell you
+about various issues of how to write macros.
+
\Question[Q-specials]{\csx{special} commands}
\TeX{} provides the means to express things that device drivers can
@@ -2213,8 +2495,10 @@ to a single language at a single locale needs to be able to change its
hyphenation rules from time to time.
\TeX{} uses a pretty good system for hyphenation (originally designed
-by Frank Liang), and while it's capable of missing ``sensible''
-hyphenation points, it seldom selects grossly wrong ones. The
+by Frank Liang~--- you may view his % ! line break
+\href{http://tug.org/docs/liang/}{Ph.D.\ thesis online}), and while
+it's capable of missing ``sensible'' hyphenation points, it seldom
+selects grossly wrong ones. The
algorithm matches candidates for hyphenation against a set of
``hyphenation patterns''. The candidates for hyphenation must be
sequences of letters (or other single characters that \TeX{} may be
@@ -2526,10 +2810,10 @@ available on \acro{CTAN}.
\item[\nothtml{\rmfamily}\acro{TDS} specification]\CTANref{tds}
\end{ctanrefs}
-\Question[Q-eps]{What is ``Encapsulated \PS{}'' (``\acro{EPS}'')}
+\Question[Q-eps]{What is ``Encapsulated \PS{}'' (``\acro{EPS}'')?}
\PS{} has been for many years a \emph{lingua franca} of powerful
-printers (modern high-quality printers now tend to require some
+printers (though modern high-quality printers now tend to require some
constrained form of Adobe Acrobat, instead); since \PS{} is also a
powerful graphical programming language, it is commonly used as an
output medium for drawing (and other) packages.
@@ -2617,7 +2901,7 @@ change colour within a Type~1 font glyph, but there's no such
restriction on a Type~3 font, which opens opportunities for some
startling effects.
-\Question[Q-resolns]{What are ``resolutions''}
+\Question[Q-resolns]{What are ``resolutions''?}
``Resolution'' is a word that is used with little concern for its
multiple meanings, in computer equipment marketing. The word suggests
@@ -2671,7 +2955,7 @@ One commonly-used approach is to declare a resolution of 8000 (``better
than any device''), and this is reasonably successful though it does
have its \Qref*{problems}{Q-8000}.
-\Question[Q-fontname]{What is the ``Berry naming scheme''}
+\Question[Q-fontname]{What is the ``Berry naming scheme''?}
In the olden days, \AllTeX{} distributions were limited by the
feebleness of file systems' ability to represent long names. (The
@@ -2757,8 +3041,9 @@ To access a particular thing through the \texttt{mirror.ctan.org}
mechanism, simply place the \acro{CTAN} path after the base
\acro{URL}; so
\URL{http://mirror.ctan.org/macros/latex/contrib/footmisc/} will
-connect you to the \Package{footmisc} directory~--- note that the
-\File{tex-archive} part of the \acro{CTAN} path isn't needed.
+connect you to the \Package{footmisc} directory at some \acro{CTAN}
+site~--- note that the \File{tex-archive} part of the \acro{CTAN} path
+isn't needed.
For details of how to find files at \acro{CTAN} sites, see
``\Qref*{finding \AllTeX{} files}{Q-findfiles}''.
@@ -2767,25 +3052,31 @@ The \TeX{} user who has no access to any sort of
network may buy a copy of the archive as part of the
\Qref*{\texlive{} distribution}{Q-CD}.
-\Question[Q-tds-zip]{Prebuilt installation files on the archive}
+\Question[Q-tds-zip]{Ready-built installation files on the archive}
The \Qref*{\acro{TDS}}{Q-tds} is a simple structure, and almost all
files can be installed simply by putting them in the ``right'' place,
and updating a single index. (Note, this simple idea typically
doesn't work for fonts, unless they're distributed as \MF{} source.)
-The CTAN network is therefore acquiring ``\acro{TDS-ZIP}'' files,
+The CTAN network is therefore acquiring ``\acro{TDS}-\acro{ZIP}'' files,
which have a built-in directory structure that matches the \acro{TDS}.
These files have to be built, and the \acro{CTAN} team has asked that
package authors supply them (the team will advise, of course, if the
-author has trouble). Everyone hopes that the extra work involved will
-contrinute to happier lives for package users, which in turn must
-surely help keep the TeX community lively and active.
+author has trouble). The \acro{CTAN} team hopes that the extra work
+involved will contribute to happier lives for package users, which in
+turn must surely help keep the TeX community lively and active.
+
+At the time of writing, there are rather few \extension{tds.zip}
+files (by comparison with the huge number of packages that are
+available). As packages are updated, the number of files is
+steadily increasing, but it will be a long time before the whole set
+is covered.
Use of the files is discussed in % ! line break
-``\Qref*{installing using preformatted \acro{ZIP} files}{Q-inst-tds-zip}''.
+``\Qref*{installing using ready-built \acro{ZIP} files}{Q-inst-tds-zip}''.
-\Question[Q-nonfree]{What's the \acro{CTAN} \texttt{nonfree} tree?}
+\Question[Q-nonfree]{What is the \acro{CTAN} \texttt{nonfree} tree?}
When \acro{CTAN} was founded, in the 1990s, it was unusual to publish
the terms under which a \TeX{}-related package was distributed (or, at
@@ -2806,7 +3097,7 @@ From the start, the \texttt{nonfree} tree was controversial: the terms
under which a package would be placed on the tree were hotly
contested, and the \acro{CTAN} team were only able slowly to populate
the tree. It is now obvious to the team that the project would never
-be completed.
+have been completed.
The \acro{CTAN} catalogue now records the nature of the licences of a
good proportion of the packages it describes (though there remain
@@ -2819,44 +3110,24 @@ the general rule for distributors has become
whether you should distribute; if the package is not listed in the
catalogue, don't think of distributing it''.
\end{quote}
-
(The catalogue only has a modest % ! line break
\CTANhref{cat-licences}{list of licences}, but it covers the set used
by packages on \acro{CTAN}, with a wild-card ``\texttt{other-free}''
which covers packages that the \acro{CTAN} administrators believe to
be free even though the authors haven't used a standard licence.)
+There is a corollary to the `general rule': if you notice something
+that ought to be in the distributions, for which there is no catalogue
+entry, please let the \acro{CTAN} team (\mailto{ctan@dante.de}) know.
+It may well be that the package has simply been missed, but some aren't
+catalogued because there's no documentation and the team just doesn't
+understand the package.
+
In the light of the above, the \texttt{nonfree} tree is being
-dismantled, and its contents moved to the main \acro{CTAN} tree. So
-the answer to the question is, now, ``the nonfree tree is a part of
-\acro{CTAN}, and is now being merged with the main tree''.
-
-
-% The \acro{CTAN} archives are currently restructuring their holdings
-% so that files that are `not free' are held in a separate tree. The
-% definition of what is `free' (for this purpose) is influenced by, but
-% not exactly the same as the
-% \begin{narrowversion} % really non-hyper version
-% Debian Free Software Guidelines (\acro{DFSG}: see
-% \URL{http://www.debian.org/social_contract#guidelines}).
-% \end{narrowversion}
-% \begin{wideversion}
-% % don't let the line wrap...
-% \href{http://www.debian.org/social_contract#guidelines}{Debian Free Software Guidelines (\acro{DFSG})}.
-% \end{wideversion}
-
-% Material is placed on the \texttt{nonfree} tree if it is not
-% freely-usable (e.g., if the material is shareware, commercial, or if
-% its usage is not permitted in certain domains at all, or without
-% payment). Users of the archive should check that they are entitled to
-% use material they have retrieved from the \texttt{nonfree} tree.
-
-% The Catalogue (one of the prime sources for finding \TeX{}-related
-% material via \nothtml{web search~--- }%
-% \Qref{web search}{Q-findfiles}) lists the licence details in each
-% entry in its lists.
-% For details of the licence categories, see its % !line break
-% \href{http://www.tex.ac.uk/tex-archive/help/Catalogue/licenses.html}{list of licences}.
+dismantled, and its contents moved (or moved \emph{back}) to the main
+\acro{CTAN} tree. So the answer to the question is, now, ``the
+nonfree tree is a part of \acro{CTAN}, and is now being merged with
+the main tree''.
\Question[Q-uploads]{Contributing a file to the archives}
@@ -3089,13 +3360,19 @@ see \Qref{}{Q-commercial} for details of commercial packages.
\Qref*{\TeX{} collection}{Q-CD}.
Members of many \TeX{} user groups receive copies of the collection
- (on \acro{CD} and \acro{DVD}), as part of their membership of the
- groups.
+ (on \acro{DVD}), as part of their membership of the groups.
MacOS/X is also a Unix-based system; however users should refer to
the information below, under item ``Mac''.
+
+ \texlive{} may also be installed ``over the network''; a network
+ installer is provided, and once you have a system, a manager
+ (\ProgName{tlmgr}) can both keep your installation up-to-date and
+ add packages you didn't install at first.
+
\begin{ctanrefs}
\item[texlive]Browse \CTANref{texlive}
+ \item[texlive installer (Unix)]\CTANref{texlive-unix}
\end{ctanrefs}
\item[Linux] GNU/Linux users are supported by \texlive{} (as noted
above).
@@ -3106,19 +3383,37 @@ see \Qref{}{Q-commercial} for details of commercial packages.
production of \acro{PDF} from \AllTeX{} input. Sadly, it's no
longer supported, and the ready-built images are made for use with a
rather ancient Linux kernel.
+
+ For the future, the \miktex{} developer intends to release a version
+ of that excellent (Windows) system for use on Linux; a beta version
+ is available via \href{http://miktex.org/unx/}{the \miktex{} site}.
\begin{ctanrefs}
\item[texlive]Browse \CTANref{texlive}
\item[vtex]\CTANref{vtex-linux}
\item[vtex \nothtml{\rmfamily}required common files]\CTANref{vtex-common}
\end{ctanrefs}
-\item[\acro{PC}: Windows post-95]
+\item[\acro{PC}: Windows]
\miktex{}, by Christian Schenk, is a comprehensive distribution. It has
its own previewer, \acro{YAP}, which is itself capable of printing,
though the distribution also includes a port of \ProgName{dvips}.
The current version is available for file-by-file download (the
- \acro{HTML} files in the directory offer hints
- on what you need to get going). The \miktex{} developers provide a
- ready-to-run copy of the distribution, on \acro{CD} (for purchase) via the
+ \acro{HTML} files in the directory offer hints on what you need to
+ get going). \miktex{} can automatically install packages that it
+ ``knows about'', but that aren't in your system (it gets them over
+ the network). Furthermore, users may keep their installation
+ up-to-date, over the network: the distribution contains a ``package
+ manager'', through which the user may select individual packages, or
+ request that every extant update be retrieved.
+
+ \miktex{} may also be used in a configuration which involves no
+ installation at all: its ``portable'' distribution may be unpacked
+ on a memory stick, and used on any windows computer without making
+ any direct use of the hard drive. This is the first ``official''
+ release of such a setup, though a similar object has been available
+ on the net for some time.
+
+ The \miktex{} developers also provide a ready-to-run copy of the
+ distribution, on \acro{CD} (for purchase) via the % ! line break
\href{http://www.miktex.org/cd/}{\miktex{} web site}; otherwise the
\File{setup} executable is available on \acro{CTAN}, together with
all the optional packages.
@@ -3132,8 +3427,8 @@ see \Qref{}{Q-commercial} for details of commercial packages.
Windows users are also supported directly by the \texlive{}
distribution; a system is provided on the installation disc of the
- \TeX{} collection (and it can, with some difficulty, be run ``from
- the disc'' without installing \emph{anything}).
+ \TeX{} collection. The system may also be installed over the
+ network, using an installer application tailored for use with Windows.
\href{http://foundry.supelec.fr/projects/xemtex/}{XEm\TeX{}}, by
Fabrice Popineau (he who created the excellent, but now defunct,
@@ -3174,9 +3469,11 @@ see \Qref{}{Q-commercial} for details of commercial packages.
\item[miktex]Acquire \CTANref{miktex-setup} (also available from the
\miktex{} web site), and read installation instructions from %
% ! line break
- \href{http://www.miktex.org/2.5/Setup.aspx}{the \miktex{} installation page}
+ \href{http://www.miktex.org/2.7/setup}{the \miktex{} installation page}
+ \item[\nothtml{\bgroup\rmfamily}Portable\nothtml{\egroup} miktex]\CTANref{miktex-portable}
\item[protext.exe]\CTANref{protext}
- \item[tetex]\CTANref{tetex}
+ \item[texlive]Browse \CTANref{texlive}
+ \item[texlive installer (Windows)]\CTANref{texlive-windows}
\end{ctanrefs}
\item[\acro{PC}: \MSDOS{} or \acro{OS/}2] Em\TeX{}, by Eberhard Mattes,
includes \LaTeX{}, \BibTeX{}, previewers, and drivers, and is
@@ -3303,20 +3600,21 @@ There are good \TeX{}-writing environments and editors for most
operating systems; some are described below, but this is only a
personal selection:
\begin{description}
-\item[Unix] Try
+\item[Unix] The commonest choices are \ProgName{[X]Emacs} or
+ \ProgName{vim}, though several others are available.
+
\href{http://www.gnu.org/software/emacs/emacs.html}{\acro{GNU}\nobreakspace\ProgName{emacs}}
- or \href{http://www.xemacs.org/}{\ProgName{XEmacs}}, and
- the \acro{AUC}-\TeX{}
+ and \href{http://www.xemacs.org/}{\ProgName{XEmacs}} are supported
+ by the \acro{AUC}-\TeX{}
bundle (available from \acro{CTAN}). \acro{AUC}-\TeX{} provides menu
items and control sequences for common constructs, checks syntax,
lays out markup nicely, lets you call \TeX{} and drivers from
within the editor, and everything else like this that you can think
of. Complex, but very powerful.
- Many who consider the versions of \ProgName{emacs} spawn of the devil, prefer
- \href{http://vim.sourceforge.net}{\ProgName{vim}}, a highly configurable
- editor (also available for Windows and Macintosh systems). Many
- plugins are available to support the needs of the \AllTeX{} user,
+ \href{http://vim.sourceforge.net}{\ProgName{Vim}} is also highly
+ configurable (also available for Windows and Macintosh systems).
+ Many plugins are available to support the needs of the \AllTeX{} user,
including syntax highlighting, calling \TeX{} programs,
auto-insertion and -completion of common \AllTeX{} structures, and
browsing \LaTeX{} help. The scripts \File{auctex.vim} and
@@ -3371,13 +3669,20 @@ personal selection:
works with MacOS~X.
For MacOS~X users, the free tool of choice appears to be
- \href{http://www.uoregon.edu/~koch/texshop/texshop.html}{TeXShop}, which
+ \href{http://www.uoregon.edu/~koch/texshop/texshop.html}{\texshop{}}, which
combines an editor and a shell with a coherent philosophy of dealing
with \AllTeX{} in the OS~X environment. TeXShop is distributed as
part of the MacTeX system, and will therefore be available out of
the box on machines on which MacTeX has been installed.
\ProgName{Vim} is also available for use on Macintosh systems.
+\item[Wildcard] \acro{TUG} is sponsoring the development of a
+ cross-platform editor and shell, modelled on the excellent
+ \texshop{} for the Macintosh. While this program,
+ \href{http://www.tug.org/texworks/}{\texworks{}}, is still under
+ development, it is already quite usable: if you're looking for a
+ \AllTeX{} development environment, and are willing to step beyond
+ the boundaries, it may be for you.
\end{description}
Atari, Amiga and \acro{N}e\acro{XT} users also have nice
environments. \LaTeX{} users looking for \ProgName{make}-like
@@ -3508,7 +3813,7 @@ also have email, and normal telephone and fax support.
Source: Mail from Christopher Mabb, August 2007
\item[Macintosh; Textures] ``A \TeX{} system `for the rest of
us'\,''. A beta release of Textures for MacOS/X is
- available \URL{http://www.bluesky.com/news/220b.html}
+ available~--- see \URL{http://www.bluesky.com/news/news_frames.html}
(Blue Sky also gives away a \MF{} implementation and some
font manipulation tools for Macs.)
@@ -3653,9 +3958,10 @@ source~--- not everything that you can write in \AllTeX{} can be
translated to \acro{HTML} (at least, portable \acro{HTML} that may be
viewed in `most' browsers), so the commonest avoiding action is to
generate a bitmap of the missing bit. Examples are maths (a maths
-extension to the |*|\acro{ML} family is available but not widely
-used), and `exotic' typescripts (ones that you cannot guarantee your
-readers will have available). Other common examples are generation of
+extension to the `|*|\acro{ML}' family is available but not
+universally supported by browsers), and `exotic' typescripts (ones
+that you cannot guarantee your readers will have available). Other
+common examples are generation of
sample bitmaps, and generation for insertion into some other
application's display~--- to insert equations into Microsoft
PowerPoint, or to support the enhanced-\ProgName{emacs} setup called
@@ -3691,21 +3997,30 @@ for speed.
\section{Support Packages for \TeX{}}
-\Question[Q-fig]{Fig, a \AllTeX{}-friendly drawing package}
+\Question[Q-figetc]{\AllTeX{}-friendly drawing packages}
+\AliasQuestion{Q-xfig}
\ProgName{(X)Fig} is a menu driven tool that allows you to
draw objects on the screen of an \acro{X} workstation; \ProgName{transfig}
is a set of tools which translate the code \ProgName{fig}. The list
of export formats is very long, and includes \MF{} and \MP{},
Encapsulated \PS{} and \acro{PDF}, as well as combinations that wrap
-a graphics format in a \LaTeX{} import file.
+a graphics format in a \LaTeX{} import file, which may include
+\LaTeX{} commands to place text (compiled by \LaTeX{} itself) as
+labels, etc., in the figures.
There's no explicit port of \ProgName{xfig} to windows (although it is
believed to work under \ProgName{cygwin} with their X-windows system).
However, the program % ! line break
\href{http://tech-www.informatik.uni-hamburg.de/applets/javafig/}{\ProgName{jfig}}
is thought by many to be an acceptable substitute, written in Java.
+
+\ProgName{Asymptote} is a widely-praised development of the \MP{}
+language, which can draw 2D or 3D diagrams, and can also label
+diagrams with \LaTeX{} text; copious documentation is available via
+\href{http://asymptote.sourceforge.net}{\ProgName{asymptote}'s web site}.
\begin{ctanrefs}
+\item[asymptote]\CTANref{asymptote}
\item[xfig]\CTANref{xfig}
\item[transfig]\CTANref{transfig}
\end{ctanrefs}
@@ -3799,15 +4114,27 @@ easily configured (see documentation inside the script).
\ProgName{Winedt} (see \Qref[question]{editors and shells}{Q-editors})
provides this functionality direct in the Windows environment.
-Simply stripping \AllTeX{} markup isn't entirely reliable, however:
-that markup itself may contribute typeset words, and this could be a
-problem. The \Package{wordcount} package
+\ProgName{TeXcount} also goes a long way with heuristics for counting,
+starting from a \LaTeX{} file; the documentation is comprehensive, and
+you may try the script on-line via the % ! line break
+\begin{wideversion}
+ \href{http://folk.uio.no/einarro/Comp/texwordcount.html}{package home page}.
+\end{wideversion}
+\begin{narrowversion}
+ package home page~(see
+ \URL{http://folk.uio.no/einarro/Comp/texwordcount.html}).
+\end{narrowversion}
+Even quite sophisticated stripping of \AllTeX{} markup can never be
+entirely reliable, however: that markup itself may contribute typeset
+words, and this could be a problem. The \Package{wordcount} package
contains a Bourne shell (i.e., typically Unix) script for running a
\LaTeX{} file with a special piece of supporting \TeX{} code, and then
counting word indications in the log file. This is probably as
-accurate automatic counting as you can get.
+accurate automatic counting as you can get, if it works for you.
\begin{ctanrefs}
\item[detex]\CTANref{detex}
+\item[latexcount.pl]\CTANref{latexcount}
+\item[TeXcount]\CTANref{texcount}
\item[wordcount]\CTANref{wordcount}
\end{ctanrefs}
@@ -4086,7 +4413,11 @@ For today, possible packages are:
\ProgName{tex4ht}'s macros included. As a result, it's pretty
robust against the macros you include in your document, and it's
also pretty fast.
-\item[\ProgName{TeXpider}] a commercial program from
+\item[\ProgName{plasTeX}]a Python-based \LaTeX{} document processing
+ framework. It gives DOM-like access to a \LaTeX{} document, as
+ well as the ability to generate mulitple output formats
+ (e.g. HTML, DocBook, tBook, etc.).
+\item[\ProgName{TeXpider}]a commercial program from
\Qref*{Micropress}{Q-commercial}, which is
described on \URL{http://www.micropress-inc.com/webb/wbstart.htm};
it uses bitmaps for equations.
@@ -4107,6 +4438,7 @@ The World Wide Web Consortium maintains a list of ``filters'' to
\URL{http://www.w3.org/Tools/Word_proc_filters.html}
\begin{ctanrefs}
\item[latex2html]Browse \CTANref{latex2html}
+\item[plasTeX]Browse \CTANref{plastex}
\item[tex4ht]\CTANref{tex4ht}
\item[tth]\CTANref{tth}
\end{ctanrefs}
@@ -4139,8 +4471,8 @@ The World Wide Web Consortium maintains a list of ``filters'' to
converting Microsoft's Rich Text Format to \TeX{}. There is also a
converter to \LaTeX{} by Erwin Wechtl, called \ProgName{rtf2latex}.
The latest converter, by Ujwal Sathyam and Scott Prahl, is
- \ProgName{rtf2latex2e}; this system seems rather good already, and
- is still being improved.
+ \ProgName{rtf2latex2e} which seems rather good, though development
+ of it seems to have stalled.
Translation \emph{to} \acro{RTF} may be done (for a somewhat
constrained set of \LaTeX{} documents) by \TeX{}2\acro{RTF}, which
@@ -4269,7 +4601,7 @@ thence to well-formed \acro{XHTML}, and import the results into
Microsoft \ProgName{Word} (2000 or later). From there, one may
convert to \AllTeX{} using one of the techniques discussed in
% beware line break
-\htmlonly{``}\Qref[question]{converting to and from \AllTeX{}}{Q-fmtconv}\htmlonly{''}.
+\wideonly{``}\Qref[question]{converting to and from \AllTeX{}}{Q-fmtconv}\wideonly{''}.
The result will typically (at best) be poorly marked-up. Problems may
also arise from the oddity of typical \TeX{} font encodings (notably
@@ -4342,12 +4674,16 @@ How did you learn about the package?
If the information came from these \acro{FAQ}s, you should already
have a link to the file (there are lists at the end of each answer):
\begin{narrowversion}
- copy that link into a browser,
+ make a browser link from \URL{http://mirror.ctan.org/} and the text
+ in the list; if the link returns a directory listing, you can
+ generally retrieve the whole directory by appending the link with
+ \extension{zip}
\end{narrowversion}
\begin{wideversion}
- click on that link,
+ click on one of the links associated with the package, and you can
+ get the package (which may be one file or several).
+% need searate wording for pdfversion and htmlversion, here
\end{wideversion}
-and you can get the file, one way or another.
If you heard about the file somewhere else, it's possible that the
source told you where to look; if not, try the \acro{CTAN} searching
@@ -4539,7 +4875,7 @@ The % ! line break
suggests that you should create % ! line break
``\texttt{C:\textbackslash Local TeX Files}'', which is good if you
manage your own machine, but often not even possible in corporate, or
-similar, environments~­-- in such situations, the user may have no
+similar, environments~--- in such situations, the user may have no
control over the hard disc of the computer, at all.
So the real criterion is that your local tree should be somewhere that
@@ -4547,7 +4883,7 @@ So the real criterion is that your local tree should be somewhere that
provide a ``home directory'' for each user, mounted as a network
drive; this is a natural home for the user's local tree. Other (often
academic) environments assume the user is going to provide a memory
-stick, and will assign it a defined drive letter~­-- another good
+stick, and will assign it a defined drive letter~--- another good
candidate location. Note that the semantics of such a tree are
indistinguishable from those of a % ! line break
\Qref*{``home'' \acro{TEXMF} tree}{Q-privinst}.
@@ -4556,7 +4892,7 @@ There are circumstances when you might not wish to use the `local' tree:
\begin{itemize}
\item if the package, or whatever, is ``personal'' (for example,
something commercial that has been licensed to you alone, or
- something you're developing yourself), the package should go in your
+ something you're developing yourself), it should go in your
\Qref*{``home'' \acro{TEXMF} tree}{Q-privinst};
\item if you \emph{know} that the package you are installing is a
replacement for the copy on the \acro{TEXMF} tree of your \AllTeX{}
@@ -4573,7 +4909,7 @@ have an effect like:
\begin{itemize}
\item distribution comes with package version \ensuremath{n};
\item you install package version \ensuremath{n+1} on the local tree; and
-\item the updated distribution comes with package version \ensuremath{n+2}.
+\item the updated distribution provides package version \ensuremath{n+2}.
\end{itemize}
In such a situation, you will find yourself using version
\ensuremath{n+1} (from the local tree) \emph{after} the new
@@ -4743,7 +5079,7 @@ mpm --install=<package>
(which of course assumes you know the name by which \miktex{} refers to
your package).
-\Question[Q-inst-tds-zip]{Installing using preformatted \acro{ZIP} files}
+\Question[Q-inst-tds-zip]{Installing using ready-built \acro{ZIP} files}
Installing packages, as they (``traditionally'') appear on
\acro{CTAN}, involves:
@@ -4756,15 +5092,15 @@ Installing packages, as they (``traditionally'') appear on
Most people, for most packages, find the first two steps onerous, the
last being easy (unless it is forgotten!).
-Preformatted \acro{ZIP} files (also known as % ! line break
-\Qref{\acro{TDS} \acro{ZIP} files}{Q-tds-zip}) are designed to lighten
+Ready-built \acro{ZIP} files~--- also known as % ! line break
+\Qref*{\acro{TDS}-\acro{ZIP} files}{Q-tds-zip}~--- are designed to lighten
the load of performing the first two steps of installation: they
contain all the files that are that's to be installed for a given
package, in their ``correct'' locations in a % ! line break
\Qref*{\acro{TDS} tree}{Q-tds}.
To install such a file on a Unix system (we assume that you'll install
-into the local \acro{TEXMF} tree):
+into the local \acro{TEXMF} tree, at \texttt{\$TEXMFLOCAL}):
\begin{quote}
\begin{verbatim}
cd $TEXMFLOCAL
@@ -4785,12 +5121,6 @@ the package provides a font, you also need to enable the font's map,
which is discussed in % ! line break
``\Qref*{Installing a Type~1 font}{Q-instt1font}''
-At the time of writing, there are rather few \extension{tds.zip}
-files (by comparison with the huge number of packages that are
-available). As packages are updated, the number of files is
-steadily increasing, but it will be a long time before the whole set
-is covered.
-
\Question[Q-tempinst]{``Temporary'' installation of \AllTeX{} files}
Operating systems and applications need to know where to find files:
@@ -5295,49 +5625,45 @@ which may be found on \acro{CTAN}.
\Question[Q-useMF]{Getting \MF{} to do what you want}
\MF{} allows you to create your own fonts, and most \TeX{} users
-will never need to use it. \MF{}, unlike \TeX{}, requires some
-customisation: each output device for which you will be generating
-fonts needs a mode associated with it. Modes are defined using the
-|mode_def| convention described on page~94 of \emph{The \MF{}book}
+will never need to use it~--- modern \AllTeX{} systems contain
+rather few \MF{} fonts of any significance, and when \MF{} output is
+needed the font generation is done, automatically, ``on the fly''.
+
+If you find you have some special requirement that the system doesn't
+satisfy, you need to know about \MF{} in rather more detail. \MF{},
+unlike \TeX{}, requires customisation for each output device: such
+customisation is conventionally held in a ``mode'' associated with the
+device. Modes are commonly defined using the \texttt{mode\_def}
+convention described on page~94 of \emph{The \MF{}book} % ! line break
(see \Qref[question]{\TeX{}-related books}{Q-books}). You will need
-a file, which conventionally called \File{local.mf}, containing all the
-|mode_def|s you will be using. If \File{local.mf} doesn't already
-exist, Karl Berry's collection of modes (\File{modes.mf})
-is a good starting point
-(it can be used as a `\File{local.mf}' without modification in a `big
-enough' implementation of \MF{}). Lists of
+a file, conventionally called \File{local.mf}, containing all the
+\texttt{mode\_def}s you will be using. In the unlikely event that
+\File{local.mf} doesn't already exist, Karl Berry's collection of
+modes (\File{modes.mf}) is a good starting point
+(it can be used as a `\File{local.mf}' without modification in a
+typical modern implementation of \MF{}). Lists of
settings for various output devices are also published periodically in
\textsl{TUGboat} (see \Qref[question]{\acro{TUG}}{Q-TUG*}). Now create
-a \texttt{plain} base
-file using \ProgName{inimf}, \texttt{plain.mf}, and \texttt{local.mf}:
+a \texttt{plain} base file using \ProgName{mf} (in ``initialisation''
+mode), \texttt{plain.mf}, and \texttt{local.mf}:
\begin{htmlversion}
+\begin{quote}
\begin{verbatim}
- % inimf
- This is METAFONT...
- **plain # you type plain
- (output)
- *input local # you type this
- (output)
- *dump # you type this
- Beginning to dump on file plain...
- (output)
+% mf -ini
+This is METAFONT...
+**plain # you type plain
+(output)
+*input local # you type this
+(output)
+*dump # you type this
+Beginning to dump on file plain...
+(output)
\end{verbatim}
+\end{quote}
\end{htmlversion}
\htmlignore
-\par\vspace{\topsep}
-%\begin{tabular}{@{}l@{}l@{}}
-%|% inimf|\\
-%This is METAFONT\dots{}\\{}
-%**|plain|& you type `|plain|'\\{}
-%(output)\\{}
-%*|input local|& you type this\\{}
-%(output)\\{}
-%*|dump|& you type this\\{}
-%Beginning to dump on file plain\dots{}\\{}
-%(output)\\{}
-%\end{tabular}\par
\begin{list}{}{}\item\relax
- |% inimf|\\
+ \texttt{\% mf -ini}\\
This is METAFONT\dots{}\\{}
\fullline{**\texttt{plain}\hss you type `\texttt{plain}'}
(\emph{output})\\{}
@@ -5348,32 +5674,26 @@ file using \ProgName{inimf}, \texttt{plain.mf}, and \texttt{local.mf}:
(\emph{output})
\end{list}\par
\endhtmlignore
-This will create a base file named \File{plain.base} (or something
-similar; for example, it will be
-\htmlignore
-\acro{\File{PLAIN.BAS}}
-\endhtmlignore
-\begin{htmlversion}
- \File{PLAIN.BAS}
-\end{htmlversion}
-on \MSDOS{} systems) which should be moved to the directory containing
-the base files on your system (note that some systems have two or more
-such directories, one for each `size' of \MF{} used).
+This will create a base file named \File{plain.base}
+(or something similar; for example, it will be \File{PLAIN.BAS}
+on \MSDOS{} systems). Move the file to the directory containing
+the base files on your system.
Now you need to make sure \MF{} loads this new base when it starts up. If
\MF{} loads the \texttt{plain} base by default on your system, then you're
-ready to go. Under Unix (using the default \ProgName{web2c}
-distribution%
+ready to go. Under Unix (using the default \texlive{} (and earlier)
+distributions this does indeed happen, but we could for instance
+define a command \ProgName{plainmf}%
\begin{footnoteenv}
- The \ProgName{command_name} is symbolically linked to
- \ProgName{virmf}, and \ProgName{virmf} loads \File{command_name.base}
-\end{footnoteenv})
-this does indeed happen, but we could for instance define a command
-\ProgName{mf} which executes \texttt{virmf \&plain} loading the
-\texttt{plain} base file.
-
-The usual way to create a font with \texttt{plain} \MF{} is to start
-it with the
+ On the grounds that a command \ProgName{plain} could be misconstrued
+ as a reference to \plaintex{}
+\end{footnoteenv}
+which executes `\texttt{mf -base=plain}' (or, in more traditional
+style `\texttt{mf \&plain}') which loads the \texttt{plain} base
+file.
+
+The usual way to create a font with \MF{} (with an appropriate base
+file loaded) is to start \MF{}'s input with the
\begin{narrowversion}
lines
\begin{quote}
@@ -5389,55 +5709,60 @@ line
\end{verbatim}
\end{wideversion}
in response to the `\texttt{**}' prompt or on the \MF{} command line. (If
-\texttt{<mode name>} is unknown or omitted, the mode defaults to `proof' and
-\MF{} will produce an output file called
-% beware!! -- argument of \File naturally breaks across line end
+\texttt{<mode name>} is unknown or omitted, the mode defaults to
+`proof' mode and \MF{} will produce an output file called % ! line break
\File{<font file name>.2602gf})
The \texttt{<magnification>} is a floating point number or
`magstep' (magsteps are defined in \emph{The \MF{}book} and
\emph{The \TeX{}book}).
If \texttt{mag=<magnification>} is omitted, then the default
-is 1 (magstep 0). For example, to generate cmr10 at 12pt for an epson
-printer you would type
+is 1~(magstep 0). For example, to generate cmr10 at 12pt for an Epson
+printer you might type
+\begin{quote}
\begin{verbatim}
- mf \mode=epson; mag=magstep 1; input cmr10
+mf \mode=epson; mag=magstep 1; input cmr10
\end{verbatim}
+\end{quote}
Note that under Unix the \texttt{\textbackslash } and \texttt{;}
characters must usually be quoted or escaped, so this would typically
look something like
+\begin{quote}
\begin{verbatim}
mf '\mode=epson; mag=magstep 1; input cmr10'
\end{verbatim}
-
-If you don't have \ProgName{inimf} or need a special mode that isn't
-in the base, you can put its commands in a file (\emph{e.g.},
-\File{ln03.mf}) and invoke it on the fly with the \csx{smode} command.
-For example, to create \File{cmr10.300gf} for an \acro{LN}03 printer, using
-the file
+\end{quote}
+If you need a special mode that isn't in the base, you can put its
+commands in a file (\emph{e.g.}, \File{ln03.mf}) and invoke it on the
+fly with the \csx{smode} command. For example, to create
+\File{cmr10.300gf} for an \acro{LN}03 printer, using the file
+\begin{quote}
\begin{verbatim}
- % This is ln03.mf as of 1990/02/27
- % mode_def courtesy of John Sauter
- proofing:=0;
- fontmaking:=1;
- tracingtitles:=0;
- pixels_per_inch:=300;
- blacker:=0.65;
- fillin:=-0.1;
- o_correction:=.5;
+% This is ln03.mf as of 1990/02/27
+% mode_def courtesy of John Sauter
+proofing:=0;
+fontmaking:=1;
+tracingtitles:=0;
+pixels_per_inch:=300;
+blacker:=0.65;
+fillin:=-0.1;
+o_correction:=.5;
\end{verbatim}
+\end{quote}
(note the absence of the \texttt{mode\_def} and \texttt{enddef}
commands), you would type
+\begin{quote}
\begin{verbatim}
- mf \smode="ln03"; input cmr10
+mf \smode="ln03"; input cmr10
\end{verbatim}
+\end{quote}
This technique isn't one you should regularly use, but it may
prove useful if you acquire a new printer and want to experiment with
parameters, or for some other reason are regularly editing the
parameters you're using. Once you've settled on an appropriate set of
parameters, you should use them to rebuild the base file that you use.
-Other sources of help are mentioned in % beware line break
-\Qref[question]{\MF{} and \MP{} Tutorials}{Q-mfptutorials}.
+Other sources of help are discussed in our list of % ! line break
+\Qref*{\MF{} and \MP{} Tutorials}{Q-mfptutorials}.
\begin{ctanrefs}
\item[modes.mf]\CTANref{modes-file}
\end{ctanrefs}
@@ -5602,7 +5927,7 @@ this, you have three options:
\PS{} previewer. Some systems offer this capability as
standard, but most people will need to use a separate previewer such
as \ProgName{ghostscript} or \ProgName{ghostscript}-based viewers
- such as \ProgName{ghostview} or shareware offering \ProgName{GSview}.
+ such as \ProgName{gv} or shareware offering \ProgName{GSview}.
\item Under Windows on a \acro{PC}, or on a Macintosh, let Adobe Type Manager
display the fonts (textures, on the Macintosh, works like this).
%% , and under
@@ -5627,9 +5952,9 @@ this, you have three options:
\end{itemize}
\begin{ctanrefs}
\item[ghostscript]Browse \CTANref{ghostscript}
-\item[ghostview]Browse \CTANref{ghostview}
\item[gsftopk]\CTANref{gsftopk}
\item[GSview]Browse \CTANref{gsview}
+\item[gv]Browse \CTANref{gv}
\item[ps2pk]\CTANref{ps2pk}
\item[xdvi]\CTANref{xdvi}
\end{ctanrefs}
@@ -5899,8 +6224,9 @@ commercially, include:
set of files for use with \LaTeX{}. The \acro{CM} Bright fonts are
supplied in Type~1 format by MicroPress, Inc. The
\Package{hfbright} bundle offers free Type~1 fonts for text using
- the \acro{OT}1 encoding~--- the \Package{cm-super} set for
- use with \acro{T}1 texts doesn't (yet) offer support for mathematics.
+ the \acro{OT}1 encoding~--- the \Package{cm-super} fonts provide the
+ fonts in \acro{T}1 text encoding but don't support \acro{CM} bright
+ mathematics.
\nothtml{\bgroup\raggedwithindent}
For further details of Micropress' offering (including samples) see\\
@@ -6220,7 +6546,6 @@ If you want to use an italic version of \csx{foo}, you need to use
Text set using nonstdfont italic...
\end{verbatim}
\end{quote}
-
This is all very elementary stuff, and serves for simple use of fonts.
However, there are wrinkles, the most important of which is the matter
of \Qref*{font encodings}{Q-whatenc}. Unfortunately, many fonts that
@@ -6285,6 +6610,14 @@ document is going to use, and the package provides commands to select
fonts as they're needed. The distribution includes a configuration to
use Adobe `standard' fonts for typesetting text. (\Eplain{} itself
seems not to offer a font selection scheme.)
+
+Simply to change font \emph{size} in a document (i.e., not changing
+the default font itself), may be done using the rather straightforward
+\Package{varisize}, which offers font sizes ranging from 7~points to
+20~points (nominal sizes, all). Font size commands are generated when
+any of the package files is loaded, so the \File{11pt.tex} defines a
+command \csx{elevenpoint}; each of the files ensures there's a ``way
+back'', by defining a \csx{tenpoint} command.
\begin{ctanrefs}
\item[ec-plain]\CTANref{ec-plain}
\item[fontch]\CTANref{fontch}
@@ -6292,6 +6625,7 @@ seems not to offer a font selection scheme.)
\item[ofs]\CTANref{ofs}
\item[pdcmac]\CTANref{pdcmac}
\item[plnfss]\CTANref{plnfss}
+\item[varisize]\CTANref{varisize}
\end{ctanrefs}
\subsection{Particular font families}
@@ -6385,8 +6719,8 @@ files), but copy the other three into your existing Local
\Qref*{update the filename database}{Q-inst-wlcf}.
Now, incorporate the fonts in the set searched by \PDFLaTeX{},
-\ProgName{dvips}, \ProgName{dvipdfm}, your previewers and
-Type~1-to-\acro{PK} conversion programs, by
+\ProgName{dvips}, \ProgName{dvipdfm}/\ProgName{dvipdfmx}, your
+previewers and Type~1-to-\acro{PK} conversion programs, by
\begin{itemize}
\item On a te\TeX{} system earlier than version~2.0, edit the file
\File{$TEXMF/dvips/config/updmap} and insert an absolute path for
@@ -6519,13 +6853,14 @@ can operate using \PDFTeX{} primitives, the hyper\TeX{}
\csx{special}s, or \acro{DVI} driver-specific \csx{special} commands.
Both \ProgName{dvips} and \YandY{}'s \acro{\ProgName{DVIPSONE}} can
translate the \acro{DVI} with these \csx{special} commands into
-\PS{} acceptable to Distiller, and \ProgName{dvipdfm} has \csx{special}
-commands of its own.
+\PS{} acceptable to Distiller, and
+\ProgName{dvipdfm} and \ProgName{dvipdfmx} have \csx{special} commands of
+its own.
If you use \plaintex{}, the \Qref*{\Eplain{} macros}{Q-eplain} can
help you create \acro{PDF} documents with hyper-references.
It can operate using \PDFTeX{} primitives, or \csx{special} commands
-for the \ProgName{dvipdfm} \acro{DVI} driver.
+for the \ProgName{dvipdfm}/\ProgName{dvipdfmx} \acro{DVI} drivers.
While there is no free implementation of all of \ProgName{Adobe}
\ProgName{Distiller}'s
@@ -6537,9 +6872,8 @@ For viewing (and printing) the resulting files, Adobe's
\ProgName{Acrobat} \ProgName{Reader} is available for a fair range of
platforms; for those for which Adobe's reader is unavailable, remotely
current versions of \ProgName{ghostscript} combined with
-\ProgName{gv}, \ProgName{GSview} (or even the unsupported
-\ProgName{ghostview}) can display and print \acro{PDF} files, as can
-\ProgName{xpdf}.
+\ProgName{gv} or \ProgName{GSview} can display and print \acro{PDF}
+files, as can \ProgName{xpdf}.
In many circumstances, \ProgName{Ghostscript} combined with a viewer
application is actually preferable to Acrobat Reader. For example, on
@@ -6554,9 +6888,8 @@ mistake.
\item[dvipdfm]\CTANref{dvipdfm}
\item[dvipdfmx]\CTANref{dvipdfmx}
\item[ghostscript]Browse \CTANref{ghostscript}
-\item[ghostview]Browse \CTANref{ghostview}
\item[GSview]Browse \CTANref{gsview}
-\item[gv]\CTANref{gv}
+\item[gv]Browse \CTANref{gv}
\item[hyper.sty]\CTANref{hyper}
\item[hyperref.sty]\CTANref{hyperref}
\end{ctanrefs}
@@ -7028,10 +7361,13 @@ the above two cases), but their code could be configured for others.
The obvious next step was to make the code configurable dynamically.
The \LaTeX{} standard \Package{graphics} package and its derivatives
-made this step: it is strongly preferred for all current work. It can
-also be used (with the help of the \Package{miniltx} ``\LaTeX{}
-emulator'' and the \Package{graphicx.tex} front-end) in documents
-written in \plaintex{}.
+made this step: it is strongly preferred for all current work.
+
+Users of \plaintex{} have two options allowing them to use
+\Package{graphicx}: the \Package{miniltx} ``\LaTeX{} emulator'' and
+the \Package{graphicx.tex} front-end allow you to load
+\Package{graphicx}, and \Qref*{\Eplain}{Q-eplain} allows you to load
+it (using the full \LaTeX{} syntax) direct.
The \Package{graphics} package takes a variety of ``driver
options''~--- package options that select code to generate the
@@ -7209,17 +7545,17 @@ which is targeted at the use of \Package{pstricks} in
\Question[Q-dvipdfmgraphics]{Imported graphics in \ProgName{dvipdfm}}
-\ProgName{Dvipdfm} translates direct from \acro{DVI} to \acro{PDF}
-(all other available routes produce \PS{} output using
-\ProgName{dvips} and then convert that to \acro{PDF} with
+\ProgName{Dvipdfm} (and \ProgName{dvipdfmx}) translates direct from
+\acro{DVI} to \acro{PDF} (all other available routes produce \PS{}
+output using \ProgName{dvips} and then convert that to \acro{PDF} with
\ProgName{ghostscript} or \ProgName{Acrobat} \ProgName{Distiller}).
-\ProgName{Dvipdfm} is a particularly flexible application. It will
-permit the inclusion of bitmap and \acro{PDF} graphics, as does
-\Qref*{\PDFTeX{}}{Q-pdftexgraphics}, but is also capable of employing
-\ProgName{ghostscript} ``on the fly'' so as to be able to permit the
-inclusion of encapsulated \PS{} (\extension{eps}) files by translating
-them to \acro{PDF}. In this way, \ProgName{dvipdfm} combines the good
+\ProgName{Dvipdfm}/\ProgName{Dvipdfmx} are particularly flexible
+applications. They permit the inclusion of bitmap and \acro{PDF}
+graphics, as does \Qref*{\PDFTeX{}}{Q-pdftexgraphics}, but are also
+capable of employing \ProgName{ghostscript} ``on the fly'' so as to be
+able to permit the inclusion of encapsulated \PS{} (\extension{eps})
+files by translating them to \acro{PDF}. In this way, they combine the good
qualities of \ProgName{dvips} and of \PDFTeX{} as a means of
processing illustrated documents.
@@ -7246,7 +7582,7 @@ containing the information; the above numbers came from an
%%CreationDate: Mon Mar 8 15:17:47 2004
\end{verbatim}
\end{quote}
-However, if such a file is available, you may abbreviate the inclusion
+If such a file is available, you may abbreviate the inclusion
code, above, to read:
\begin{quote}
\begin{verbatim}
@@ -7269,9 +7605,59 @@ configuration file (of most distributions) ``guesses'' the
\texttt{dvips} option if you're using \TeX{}.
\begin{ctanrefs}
\item[dvipdfm]\CTANref{dvipdfm}
+\item[dvipdfmx]\CTANref{dvipdfmx}
\item[ebb]Distributed as part of \CTANref{dvipdfm}
\end{ctanrefs}
+\Question[Q-grffilenames]{``Modern'' graphics file names}
+
+\TeX{} was designed in a world where file names were very simple
+indeed, typically strictly limited both in character set and length.
+In modern systems, such restrictions have largely disappeared, which
+leaves \TeX{} rather at odds with its environment. Particular
+problems arise with spaces in file names, but things like multiple
+period characters can seriously confuse the \Package{graphics}
+package.
+
+The specification of \TeX{} leaves some leeway for distributions to
+adopt file access appropriate to their operating system, but this
+hasn't got us very far. Many modern distributions allow you to
+specify a file name as \texttt{"file name.tex"} (for example), which
+helps somewhat, but while this allows us to say
+\begin{quote}
+\begin{verbatim}
+\input "foo bar.tex"
+\end{verbatim}
+\end{quote}
+the analogous usage
+\begin{quote}
+\begin{verbatim}
+\includegraphics{"gappy graphics.eps"}
+\end{verbatim}
+\end{quote}
+using ``ordinary'' \LaTeX{} causes confusion in \ProgName{xdvi} and
+\ProgName{dvips}, even though it works at compilation time. Sadly,
+even within such quotes, multiple dots give \csx{includegraphics}
+difficulties. Note that
+\begin{quote}
+\begin{verbatim}
+\includegraphics{"gappy graphics.pdf"}
+\end{verbatim}
+\end{quote}
+works in a similar version of \PDFTeX{}.
+
+If you're using the \Package{graphics} package, the \Package{grffile}
+package will help. The package offers several options, the simplest
+of which are \pkgoption{multidot} (allowing more than one dot in a
+file name) and \pkgoption{space} (allowing space in a file name). The
+\pkgoption{space} option requires that you're running on a
+sufficiently recent version of \PDFTeX{}, in \acro{PDF} mode~--- and
+even then it won't work for \MP{} files, which are read as \TeX{}
+input, and therefore use the standard input mechanism).
+\begin{ctanrefs}
+\item[grffile.sty]Distributed as part of \CTANref{oberdiek}
+\end{ctanrefs}
+
\Question[Q-graphicspath]{Importing graphics from ``somewhere else''}
By default, graphics commands like \csx{includegraphics} look
@@ -7615,14 +8001,25 @@ the question\dots{}
There are many packages to do pictures in \AllTeX{} itself (rather than
importing graphics created externally), ranging from simple use of
\LaTeX{} \environment{picture} environment, through enhancements like
-\ProgName{epic}, to
+\ProgName{eepic}, to
sophisticated (but slow) drawing with \PiCTeX{}. Depending on your type
of drawing, and setup, here are a few systems you may consider:
\begin{itemize}
+\item \PiCTeX{} is a venerable, and very powerful, system, that draws
+ by placing dots on the page to give the effect of a line or curve. While
+ this has the potential of great power, it is (of course) much slower
+ than any of the other established packages. What's more, there
+ are problems with its \Qref*{documentation}{Q-docpictex}.
+\item \Package{epic} was designed to make use of the \LaTeX{}
+ \environment{picture} environment somewhat less agonising;
+ \Package{eepic} extends it, and is capable of using \ProgName{tpic}
+ \csx{special} commands to improve printing performance. (If the
+ \csx{special}s aren't available, the \Package{eepicemu} will do the
+ business, far less efficiently.
\item \Package{pict2e}; this was advertised in % !line break
\Qref*{the \LaTeX{} manual}{Q-books}, but didn't appear for nearly
ten years after publication of the book! It removes all the petty
- niggles that surround the use of the \environment{picture}
+ restrictions that surround the use of the \environment{picture}
environment. It therefore suffers \emph{only} from the rather
eccentric drawing language of the environment, and is a far more
useful tool than the original environment has ever been. (Note that
@@ -7631,9 +8028,11 @@ of drawing, and setup, here are a few systems you may consider:
\item \Package{PSTricks}; this gives you access to all the power of
\PS{} from \TeX{} itself, by sophisticated use of
\Qref*{\csx{special} commands}{Q-specials}. Since \PS{} is itself a
- pretty powerful programming language, many astounding things can in
- principle be achieved using \Package{PSTricks}.
- \Package{pstricks}' \csx{special}s are
+ pretty powerful programming language, many astounding things can in
+ principle be achieved using \Package{PSTricks} (a wide range of
+ contributed packages, ranging from world mapping to lens design
+ diagrams, is available).
+ \Package{Pstricks}' \csx{special}s are
by default specific to \ProgName{dvips}, but V\TeX{} (both in its
commercial and in its free versions) understands them. \PDFTeX{}
users may use \Package{pst-pdf}, which (like
@@ -7675,12 +8074,16 @@ of drawing, and setup, here are a few systems you may consider:
\end{itemize}
\begin{ctanrefs}
\item[dratex.sty]\CTANref{dratex}
+\item[epic.sty]\CTANref{epic}
+\item[eepic.sty]\CTANref{eepic}
+\item[eepicemu.sty]\CTANref{eepic}
\item[mfpic]\CTANref{mfpic}
\item[preview.sty]\CTANref{preview}
\item[pspicture.sty]\CTANref{pspicture}
\item[pst-pdf.sty]\CTANref{pst-pdf}
\item[pgf.sty]\CTANref{pgf}
\item[pict2e.sty]\CTANref{pict2e}
+\item[pictex.sty]\CTANref{pictex}
\item[pstricks]\CTANref{pstricks}
\item[tikz.sty]Distributed with \CTANref{pgf}
\end{ctanrefs}
@@ -8886,9 +9289,9 @@ the \Package{natbib} and \Package{hyperref} packages will interwork.
A convention sometimes used in physics journals is to ``collapse'' a group of
related citations into a single entry in the bibliography. \BibTeX{},
by default, can't cope with this arrangement, but the \Package{mcite}
-package deals with the problem.
+and \Package{mciteplus} packages deal with the problem.
-The package overloads the \csx{cite} command to recognise a
+\Package{mcite} overloads the \csx{cite} command to recognise a
``\texttt{*}'' at the start of a key, so that citations of the form
\begin{quote}
\begin{verbatim}
@@ -8913,19 +9316,32 @@ You need to make a small change to the bibliography style
(\extension{bst}) file you use; the \Package{mcite} package
documentation tells you how to do that.
-Unfortunately, the \Class{revtex} system doesn't play with
-\Package{mcite}. As a result, for that (primarily physics-targeted
-system) you need to play silly games like:
+(Despite these multiple citations being primarily a physics-oriented
+requirement, the \Class{RevTeX} (Physics support) class doesn't work
+with \Package{mcite}.
+
+The \Package{mciteplus} package adresses many of the infelicites of
+\Package{mcite}, and \emph{does} work with \Class{RevTeX}. Again,
+`ordinary' \extension{bst} files will not work with
+\Package{mciteplus}, but the package documentation explains how to
+patch an existing \BibTeX{} style.
+
+The \Package{collref} package takes a rather different approach to the
+problem, and will work with most (if not all) \BibTeX{} packages.
+\Package{Collref} spots common subsets of the references, so if it
+sees a sequence
\begin{quote}
\begin{verbatim}
-\cite{paper0,paper1,paper3}
-\nocite{paper2}
+\cite{paper0,paper1,paper2,paper3}
+...
+\cite{some_other_paper,paper1,paper2,and_another}
\end{verbatim}
\end{quote}
-and then edit the \extension{bbl} file to merge the two citations, to
-achieve the effects of \Package{mcite}.
+it will collect \texttt{paper1} and \texttt{paper2} as a multiple reference.
\begin{ctanrefs}
+\item[collref.sty]\CTANref{collref}
\item[mcite.sty]\CTANref{mcite}
+\item[mciteplus.sty]\CTANref{mciteplus}
\item[revtex \nothtml{\rmfamily}bundle]\CTANref{revtex}
\end{ctanrefs}
@@ -8986,6 +9402,11 @@ simple~--- add
\end{quote}
to the preamble of your document.
+The \Package{compactbib} package has a similar effect. Its primary
+purpose is to produce two bibliographies, and it seems to preclude use
+of \BibTeX{} (though the package documentation, in the package file
+itself, isn't particularly clear).
+
Otherwise, one is into unseemly hacking of something or other. The
\Package{mdwlist} package actually does the job, but it doesn't work
here, because it makes a different-named list, while the name
@@ -9006,6 +9427,7 @@ plethora of space-saving measures: you can, in principle, suppress all
its other actions, and have it provide you a compressed bibliography
\emph{only}.
\begin{ctanrefs}
+\item[compactbib.sty]\CTANref{compactbib}
\item[mdwlist.sty]Distributed as part of \CTANref{mdwtools}
\item[natbib.sty]\CTANref{natbib}
\item[savetrees.sty]\CTANref{savetrees}
@@ -9393,12 +9815,13 @@ route):
Thesis styles are usually very specific to your University, so it's
usually not profitable to ask around for a package outside your own
University. Since many Universities (in their eccentric way) still
-require double-spacing, you may care to refer to
-\Qref[question]{the relevant question}{Q-linespace}.
-If you want to write your own, a good place to start is the University
-of California style, but it's not worth going to a lot of trouble. (If
-officials won't allow standard typographic conventions, you won't be
-able to produce an \ae{}sthetically pleasing document anyway!)
+require double-spaced thesis text, you may also need separately to set
+up \Qref*{double spacing}{Q-linespace}.
+
+If you want to write a new thesis class of your own, a good place to
+start is the University of California style, but remember that it's
+often difficult to produce a thesis that both looks good and conforms
+with the style that your Univeristy demands.
\begin{ctanrefs}
\item[UC thesis style]\CTANref{ucthesis}
\end{ctanrefs}
@@ -9412,8 +9835,8 @@ public archives.
Nevertheless, there are considerable numbers of macros of one sort or
another available on \acro{CTAN}; searching for your journal name in
-the CTAN catalogue (see % ! line wrap
-\Qref[question]{searching \acro{CTAN}}{Q-findfiles})
+the CTAN catalogue~--- see % ! line break
+\Qref{searching \acro{CTAN}}{Q-findfiles})~---
may well turn up what you're seeking.
Failing that, you may be well advised to contact the prospective
@@ -9598,7 +10021,8 @@ may not be optimal~--- but they're certainly practical.
More satisfactory are the \emph{\acro{KOMA}-script} classes, which are
designed to work properly with the class option files that come with
\Package{extsizes}, and the \Class{memoir} class that has its own
-options for document font sizes 9pt, 14pt and 17pt.
+options for document font sizes 9pt--12pt, 14pt, 17pt, 20pt, 25pt,
+30pt, 36pt, 48pt and 60pt.
\begin{ctanrefs}
\item[extsizes bundle]\CTANref{extsizes}
\item[\nothtml{\rmfamily}KOMA script bundle]\CTANref{koma-script}
@@ -9704,8 +10128,8 @@ to program alternative % don't let these \href suffer line-breaks
\href{http://zoonek.free.fr/LaTeX/LaTeX_samples_chapter/0.html}{chapter heading styles}
and
\href{http://zoonek.free.fr/LaTeX/LaTeX_samples_section/0.html}{section heading styles}.
-The web pages are not useful to users unless they are willing to do
-their own \LaTeX{} programming.
+The web pages provide programming examples, and expect users to adapt
+them to their own \LaTeX{} use.
\begin{ctanrefs}
\item[anonchap.sty]\CTANref{anonchap}
\item[fncychap.sty]\CTANref{fncychap}
@@ -10311,8 +10735,6 @@ was written: it does the obvious things, and more.
Users have been known to ask for running page numbers within a
section, but this really doesn't make sense: you need to run page
numbers within document objects that always start on a fresh page.
-
-Documentation of \Package{chappg} is to be found in the package file.
\begin{ctanrefs}
\item[chappg.sty]\CTANref{chappg}
\end{ctanrefs}
@@ -10355,6 +10777,7 @@ together with a sample document and prototype outputs.
\end{ctanrefs}
\Question[Q-acroantics]{Adobe \ProgName{Reader} messing with print size}
+\AliasQuestion{Q-outszwrng}
Printing from Adobe \ProgName{Reader} shrinks the page ``to fit''
(\emph{by default}). Unfortunately, its calculation doesn't consider
@@ -10364,17 +10787,22 @@ The effect typically looks as if your margins have expanded.
Solve this problem by adjusting the \ProgName{Reader}'s default in the
print dialogue; unfortunately, this dialogue varies from one version
-to the next. On \ProgName{Reader} version 7, there are two entries to
-check:
-\begin{quote}
+to the next:
+\begin{itemize}
+\item \ProgName{Reader} version 7:\\
Page Scaling (default: ``Fit to printer margins'')~--- change to
``None'', and\\
- Scale (default 95\textpercent {} of Normal size)~--- change to
+ Scale (default 95\textpercent{} of Normal size)~--- change to
``100\textpercent''.
-% NB the space after \textpercent seems to be necessary for the health
-% of sanitize.pl :-(
-\end{quote}
-
+\item Adobe Reader 6:\\
+ in the print dialogue, on the ``copies \& pages'' pane, you'll find a
+ popup menu/drop-down list titled ``Page Scaling''~--- change to ``None''.
+\item Windows, Linux Acrobat (Reader) 5.0:\\
+ In the print dialog, make sure the ``Shrink oversized pages to fit''
+ checkbox is unchecked. It may also be useful to uncheck the
+ ``Expand small pages to fit paper size'' checkbox as well.
+\end{itemize}
+
\Question[Q-papergeom]{Getting the right paper geometry from \AllTeX{}}
If your output is the wrong size, and you've checked that it's not due
@@ -10496,8 +10924,10 @@ Style'~--- ``don't do it''~--- should not lightly be ignored.
This set of \acro{FAQ}s recommends that you use a package to establish
consistent settings of the parameters: the interrelationships are
-taken care of in the established packages, without you needing to
-think about them, but
+taken care of in the established packages, without you \emph{needing}
+to think about them, but remember~--- the packages only provide
+consistent, working, mechanisms: they don't analyse the quality of
+what you propose to do.
The following answers deal with the ways one may choose to proceed:
\begin{itemize}
@@ -10631,10 +11061,12 @@ environment (which is a close relation of the \LaTeX{}
as far as \TeX{} is concerned: it merely moves text around inside the
width that \TeX{} believes in.
-The \Package{changepage} package provides ready-built commands to do the
-above; it includes provision for changing the shifts applied to your
-text according to whether you're on an odd (\emph{recto}) or an even
-(\emph{verso}) page of a two-sided document.
+The \Package{changepage} package provides ready-built commands to do
+the above; it includes provision for changing the shifts applied to
+your text according to whether you're on an odd (\emph{recto}) or an
+even (\emph{verso}) page of a two-sided document.
+\Package{Changepage}'s structure matches that of the \Class{memoir}
+class.
The (earlier) package \Package{chngpage} provides the same facilities,
but it uses rather different syntax. \Package{Changepage}'s structure
@@ -10655,10 +11087,15 @@ to make the page one line longer, or
\enlargethispage{-\baselineskip}
\end{verbatim}
\end{quote}
-to make the page one line shorter.
+to make the page one line shorter. The process is (to an extent)
+simplified by the \Package{addlines} package: its \csx{addlines}
+command takes as argument the \emph{number} of lines to add to the
+page (rather than a length): the package documentation also provides a
+useful analysis of when the command may (or may not) be expected to
+work.
\begin{ctanrefs}
+\item[addlines.sty]\CTANref{addlines}
\item[changepage.sty]\CTANref{changepage}
-\item[chngpage.sty]\CTANref{chngpage}
\end{ctanrefs}
\Question[Q-nopageno]{How to get rid of page numbers}
@@ -11181,33 +11618,33 @@ facilities.
\item[quotchap.sty]\CTANref{quotchap}
\end{ctanrefs}
-\Question[Q-outszwrng]{\AllTeX{} \acro{PDF} output prints at wrong size}
-
-Having got everything \emph{else} right, you should be aware that the
-problem may have nothing to do with \AllTeX{} and everything to do
-with the program you use for printing. A regular cause for such
-problems lies with Acrobat Reader, which by default enables its option
-to scale pages to fit on the printable area of the paper. Since a
-printer can rarely print right to the edge, this means that pdf-files
-will be shrunk by some (small) factor (even if the pdf-file is
-formatted for A4, and your paper size is set to A4 as well).
-
-Correcting this silliness is not very hard, but the exact details
-depend on the version of Acrobat Reader (or "Adobe Reader" from
-version 6.0 onwards) you have installed:
-\begin{itemize}
-\item Mac OS X, Adobe Reader 6:\\
- in the print dialogue, on the ``copies \& pages'' pane, you'll find a
- popup menu titled ``Page Scaling''. Make sure that the menu reads
- ``None''.
-\item Windows, Adobe Reader 6:\\
- in the print dialogue, select ``None'' from the drop-down list
- ``Page Scaling''.
-\item Windows, Linux Acrobat (Reader) 5.0:\\
- In the print dialog, make sure the ``Shrink oversized pages to fit''
- checkbox is unchecked. It may also be useful to uncheck the
- ``Expand small pages to fit paper size'' checkbox as well.
-\end{itemize}
+% \Question[Q-outszwrng]{\AllTeX{} \acro{PDF} output prints at wrong size}
+
+% Having got everything \emph{else} right, you should be aware that the
+% problem may have nothing to do with \AllTeX{} and everything to do
+% with the program you use for printing. A regular cause for such
+% problems lies with Acrobat Reader, which by default enables its option
+% to scale pages to fit on the printable area of the paper. Since a
+% printer can rarely print right to the edge, this means that pdf-files
+% will be shrunk by some (small) factor (even if the pdf-file is
+% formatted for A4, and your paper size is set to A4 as well).
+
+% Correcting this silliness is not very hard, but the exact details
+% depend on the version of Acrobat Reader (or "Adobe Reader" from
+% version 6.0 onwards) you have installed:
+% \begin{itemize}
+% \item Mac OS X, Adobe Reader 6:\\
+% in the print dialogue, on the ``copies \& pages'' pane, you'll find a
+% popup menu titled ``Page Scaling''. Make sure that the menu reads
+% ``None''.
+% \item Windows, Adobe Reader 6:\\
+% in the print dialogue, select ``None'' from the drop-down list
+% ``Page Scaling''.
+% \item Windows, Linux Acrobat (Reader) 5.0:\\
+% In the print dialog, make sure the ``Shrink oversized pages to fit''
+% checkbox is unchecked. It may also be useful to uncheck the
+% ``Expand small pages to fit paper size'' checkbox as well.
+%\end{itemize}
\subsection{Spacing of characters and lines}
@@ -11439,13 +11876,16 @@ The \Class{memoir} class includes the relevant functionality of the
For general numbering of lines, there are two packages for use with
\LaTeX{}, \Package{lineno} (which permits labels attached to
individual lines of typeset output) and \Package{numline}.
+(\Package{Numline} is considered obsolete, but remains available from
+the archive.)
Both of these packages play fast and loose with the \LaTeX{} output
routine, which can cause problems: the user should beware\dots{}
If the requirement is for numbering verbatim text, \Package{moreverb},
-\Class{memoir} or \Package{fancyvrb} (see % beware line break
+or \Package{fancyvrb} (see % ! line break
\Qref[question]{including files verbatim}{Q-verbfile}) may be used.
+Class \Class{memoir} also provides the necessary facilities.
One common use of line numbers is in critical editions of texts, and
for this the \Package{edmac} package offers comprehensive support;
@@ -11765,9 +12205,17 @@ There are three packages that help solve this problem:
maths mode. It can produce (\LaTeX{}-style) `robust' commands
% beware line break within paren
(\htmlonly{see }\Qref{use of \csx{protect}}{Q-protect}) for use
- within moving arguments. Note that, because the operation is
- conducted in maths mode, spaces within the \acro{URL} argument are
- ignored unless special steps are taken.
+ within moving arguments.
+
+ The package ordinarily ignores spaces in the \acro{URL}, but
+ unfortunately \acro{URL}s that contain spaces do exist; to typeset
+ them, call the package with the \pkgoption{obeyspaces} option. Two
+ other useful options allow line breaks in the \acro{URL} in places
+ where they are ordinarily suppressed to avoid confusion:
+ \pkgoption{spaces} to allow breaks at spaces (note, this requires
+ \pkgoption{obeyspaces} as well, and \pkgoption{hyphens} to allow
+ breaks after hyphens. (Note that the package \emph{never} does
+ ``ordinary'' hyphenation of names inside an \acro{URL}.)
It is possible to use the \Package{url} package in \plaintex{},
with the assistance of the \Package{miniltx} package (which was
@@ -11930,24 +12378,24 @@ is to start a paragraph (in books, usually the first of a chapter)
with its first letter set large enough to span several lines.
This style is known as ``dropped capitals'', or (in French)
-\latexhtml{``lettrines''}{«lettrines»}, and \TeX{}'s primitive
-facilities for hanging indentation make its (simple) implementation
-pretty straightforward.
+\latexhtml{``lettrines''}{\htmlentity{laquo}lettrines\htmlentity{raquo}},
+and \TeX{}'s primitive facilities for hanging indentation make its
+(simple) implementation pretty straightforward.
The \Package{dropping} package does the job simply, but has a curious
attitude to the calculation of the size of the font to be used for the
big letters. Examples appear in the package documentation, so before
-you process the \extension{dtx}, the package itself must already be installed.
-Unfortunately, \Package{dropping} has an intimate relation to the set
-of device drivers available in an early version of the \LaTeX{}
-graphics package, and it cannot be trusted to work with recent
-offerings like \PDFTeX{}, V\TeX{} or \acro{DVI}pdfm.
-
-On such occasions, the more recent \Package{lettrine} package is more
-likely to succeed. It has a well-constructed array of options, and
-the examples (a pretty impressive set) come as a separate file in the
-distribution (also available in \PS{}, so that they can be viewed
-without installing the package itself).
+you process the \extension{dtx}, the package itself must already be
+installed. Unfortunately, \Package{dropping} has an intimate relation
+to the set of device drivers available in an early version of the
+\LaTeX{} graphics package, and it cannot be trusted to work with
+modern offerings such as \PDFTeX{}, V\TeX{} or \acro{DVI}pdfm, let
+alone such modernisms as \xetex{}. As a result, the package is widely
+deprecated, nowadays.
+
+The more recent \Package{lettrine} package is generally more reliable.
+It has a well-constructed array of options, and an impressive set of
+examples adds to the package's document.
\begin{ctanrefs}
\item[dropping]\CTANref{dropping}
\item[lettrine]\CTANref{lettrine}
@@ -12632,9 +13080,26 @@ have the .aux file, write:
\end{verbatim}
\end{narrowversion}
\end{quote}
+Heiko Oberdiek's experimental \Package{zref} bundle includes a
+hyper-crossreferencing mechanism using its \Package{zref-xr} module.
+Usage is closely modelled on \Package{xr} and \Package{xr-hyper}; a
+trivial example (from a \Newsgroup{comp.text.tex} posting) is
+\begin{quote}
+\begin{verbatim}
+\usepackage{zref-xr,zref-user}
+\zexternaldocument*{xr02}
+...
+\zref{foo}
+\end{verbatim}
+\end{quote}
+The module provides all the facilities of the older packages, and can
+deal both with ``traditional'' \LaTeX{} labels and with
+\Package{zref}'s style of labels.
\begin{ctanrefs}
\item[xr.sty]Distributed as part of \CTANref{2etools}
\item[xr-hyper.sty]Distributed with \CTANref{hyperref}
+\item[zref \nothtml{\rmfamily\itshape}bundle]Distributed as part of
+ \CTANref{oberdiek}
\end{ctanrefs}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -13559,6 +14024,24 @@ which feels just as ``natural'' as the \Package{mdwtools} facility,
and has the advantage of playing well with the other excellent
facilities of \Package{enumitem}.
+\Package{Expdlist} has a neat way of providing for comments, with its
+\csx{listpart} command. The command's argument becomes a comment
+between items of the list:
+\begin{quote}
+\begin{verbatim}
+\begin{enumerate}
+\item item 1
+\item item 2
+ \listpart{interpolated comment}
+\item item 3
+\end{enumerate}
+\end{verbatim}
+\end{quote}
+This, you will realise, means it doesn't even have to think about
+suspending or resuming the list, and of course it works equally well
+in any of the list environments (thought it's not actually
+\emph{necessary} for any but \environment{enumerate}).
+
\Package{Enumitem} also allows multi-level suspension and resumption
of lists:
\begin{quote}
@@ -13582,13 +14065,14 @@ of lists:
% end outer enumerate
\end{enumerate}
\end{verbatim}
-However, the comment interpolated in the nested enumeration appears as
-if it were a second paragraph to ``outer item 2'', which is hardly
-satisfactory.
\end{quote}
+However, the `nested comment' interpolated in the nested enumeration
+appears as if it were a second paragraph to ``outer item 2'', which is
+hardly satisfactory.
\begin{ctanrefs}
\item[enumerate.sty]Distributed as part of \CTANref{2etools}
\item[enumitem.sty]\CTANref{enumitem}
+\item[expdlist.sty]\CTANref{expdlist}
\item[mdwlist.sty]Distributed as part of \CTANref{mdwtools}
\end{ctanrefs}
@@ -13633,7 +14117,7 @@ position wrong (by \texttt{10pt}) if you simply write:
The \Package{topcapt} package solves this problem:
\begin{quote}
\begin{verbatim}
-\usepackage{topcaption}
+\usepackage{topcapt}
...
\begin{table}
\topcaption{Example table}
@@ -14288,7 +14772,7 @@ than columns. So, we set things up by:
\end{wideversion}
\end{quote}
Now, we put `\texttt{\$}' before the first column specifier; and we
-put `\texttt{\textasciicircum}'
+put `\texttt{\textasciicircum{}}'
before the modifiers of subsequent ones. We then use \csx{rowstyle} at
the start of each row we want to modify:
\begin{quote}
@@ -14517,6 +15001,47 @@ not work with obsolete (pre-\LaTeXe{}) packages such as
\Qref[question]{graphics inclusion}{Q-impgraph} for discussion of the
genesis of \csx{includegraphics}.
+\Question[Q-wideflt]{Centring a very wide figure or table}
+
+The normal means of centring a figure or table object is to include
+\csx{centering} at the top of the float. This doesn't help if the
+object is wider than \csx{textwidth}~--- the object starts at the left
+margin and juts out into the right margin (which is actually doubly
+unsatisfactory, since as well as looking bad, the float won't be
+placed until the next \csx{clearpage} or the like.)
+
+You can avoid the problem by rescaling the figure or table to fit, but
+this is often not satisfactory, for several reasons.
+
+Otherwise, if the object is wider than the printable area of the page,
+you've no choice other than to \Qref*{rotate it}{Q-landscape}. If,
+however, the object is \emph{just} wider than the text block, you can
+make it pretend to be the right size by:
+\begin{quote}
+\begin{wideversion}
+\begin{verbatim}
+\begin{figure}
+ \noindent
+ \makebox[\textwidth]{\includegraphics{my-wide-figure}}%
+ \caption{This figure juts out into both margins}
+\end{figure}
+\end{verbatim}
+\end{wideversion}
+\begin{narrowversion}
+\begin{verbatim}
+\begin{figure}
+ \noindent
+ \makebox[\textwidth]{%
+ \includegraphics{my-wide-figure}%
+ }%
+ \caption{This figure juts out into both margins}
+\end{figure}
+\end{verbatim}
+\end{narrowversion}
+\end{quote}
+Note the \csx{noindent}: the \csx{makebox} starts a paragraph, and you
+really don't want that indented by \csx{parindent}.
+
\Question[Q-2colfloat]{Placing two-column floats at bottom of page}
You specified placement `\texttt{[htbp]}' for your full-width figure or
@@ -14721,10 +15246,26 @@ overtake ``real floats'', so that the numbers of figures will be out
of order: figure 6 could be on page 12, while figure 5 had floated to
page 13. It's best, therefore, either to stay with floating figures
throughout a document, or to use fixed figures throughout.
+
+If it's really impossible to follow that counsel of perfection, you
+can use the \Package{perpage} package's command \csx{MakeSorted}
+command:
+\begin{quote}
+\begin{verbatim}
+...
+\usepackage{float}
+\usepackage{perpage}
+\MakeSorted{figure}
+\MakeSorted{table}
+...
+\end{verbatim}
+\end{quote}
+and the sequence of float numbers is all correct.
\begin{ctanrefs}
\item[capt-of.sty]\CTANref{capt-of}
\item[caption.sty]\CTANref{caption}
\item[float.sty]\CTANref{float}
+\item[perpage.sty]Distributed as part \CTANref{bigfoot}
\end{ctanrefs}
\subsection{Footnotes}
@@ -14832,12 +15373,18 @@ To suppress the footnote in headings and table of contents:
Footnotes in captions are especially tricky: they present problems of
their own, on top of the problems one experiences with
-\Qref*{footnotes in section titles}{Q-ftnsect} and with % ! line break
-\Qref*{footnotes in tables}{Q-footintab}. Fortunately, the
-requirement for footnotes in captions is extremely rare: if you are
-experiencing problems, it is worth reviewing what you are trying to
-say by placing this footnote. Note that the \Package{threeparttable}
-scheme (see, again, % ! line break
+\Qref*{footnotes in section titles}{Q-ftnsect} (footnotes migrating to
+to the list of figures or tables, or % ! line break
+\Qref{apparently random errors}{Q-extrabrace} because
+\csx{footnote} is a fragile command), and with % ! line break
+\Qref*{footnotes in tables}{Q-footintab} (typically, the footnote
+simply disappears). Fortunately, the requirement for footnotes in
+captions is extremely rare: if you are experiencing problems, it is
+worth reviewing what you are trying to say by placing this footnote:
+other options are to place text at the bottom of the float, or to
+place a footnote at the point where you refer to the float.
+
+Note that the \Package{threeparttable} scheme (see, again, % ! line break
\Qref[question]{footnotes in tables}{Q-footintab}) also applies
to notes in captions, and may very well be preferable to whatever you
were thinking of.
@@ -14872,10 +15419,10 @@ command in a \environment{minipage} environment within a float (as
in the example above) can produce \emph{two} copies of the footnote
body ``blah''. (In fact, the effect only occurs with captions that are
long enough to require two lines to be typeset, and so wouldn't appear
-with such a short caption.)
+with such a short caption as that in the example above.)
The documentation of the \Package{ccaption} package describes a really
-rather awful work-around.
+rather awful work-around for this problem.
\begin{ctanrefs}
\item[ccaption.sty]\CTANref{ccaption}
\item[threeparttable.sty]\CTANref{threeparttable}
@@ -15000,13 +15547,13 @@ The obvious solution is to make the footnote number reset whenever the
page number is stepped, using the % ! line break
\Qref*{\LaTeX{} internal mechanism}{Q-addtoreset}. Sadly, the place
in the document where the page number is stepped is unpredictable, not
-(``tidily'') at the end of the printed page; so the link only ever
-works by luck.
+(``tidily'') at the end of the printed page; so changing the footnote
+number only ever works by `luck'.
As a result, resetting footnotes is inevitably a complicated process,
using labels of some sort. It's nevertheless important, given the
common requirement for footnotes marked by symbols (with painfully
-small symbol sets). There are three packages that manage it, one way
+small symbol sets). There are four packages that manage it, one way
or another.
The \Package{perpage} package provides a general mechanism for
@@ -15015,7 +15562,14 @@ The interface is pretty simple: \cmdinvoke{MakePerPage}{footnote} will
do the job. If you want to restart the counter at something other
than~1 (for example to avoid something in the \LaTeX{} footnote symbol
list), you can use: \cmdinvoke{MakePerPage}[2]{footnote}. It's a
-first-rate package, small and efficient
+first-rate package, small and efficient.
+
+The \Package{zref} package provides the same facilities with its
+\pkgoption{perpage} module, which defines a command \csx{zmakeperpage}
+whose syntax is identical to that of \Package{perpage}, above. You can
+load the module by \cmdinvoke{usepackage}[perpage]{zref} (or as
+\cmdinvoke{usepackage}{zref-perpage}, if your needs so require~---
+look at \Package{zref}'s documentation for details).
The \Package{footmisc} package provides a variety of means of
controlling footnote appearance, among them a package option
@@ -15031,6 +15585,9 @@ probably not particularly useful any more. (Documentation is
\item[footmisc.sty]\CTANref{footmisc}
\item[footnpag.sty]\CTANref{footnpag}
\item[perpage.sty]Distributed as part \CTANref{bigfoot}
+\item[zref.sty]Distributed as a collection member in \CTANref{oberdiek}
+\item[zref-perpage.sty]Distributed as a collection member in
+ \CTANref{oberdiek}
\end{ctanrefs}
\Question[Q-run-fn-nos]{Not resetting footnote numbers per chapter}
@@ -15560,8 +16117,8 @@ following minimal solution:
\begin{wideversion}
\begin{verbatim}
\def\RCS$#1: #2 ${\expandafter\def\csname RCS#1\endcsname{#2}}
-\RCS$Revision: 1.548 $ % or any RCS keyword
-\RCS$Date: 2008/06/20 13:37:44 $
+\RCS$Revision: 1.612 $ % or any RCS keyword
+\RCS$Date: 2009/06/09 22:45:20 $
...
\date{Revision \RCSRevision, \RCSDate}
\end{verbatim}
@@ -15571,8 +16128,8 @@ following minimal solution:
\def\RCS$#1: #2 ${\expandafter
\def\csname RCS#1\endcsname{#2}%
}
-\RCS$Revision: 1.548 $ % or any RCS keyword
-\RCS$Date: 2008/06/20 13:37:44 $
+\RCS$Revision: 1.612 $ % or any RCS keyword
+\RCS$Date: 2009/06/09 22:45:20 $
...
\date{Revision \RCSRevision, \RCSDate}
\end{verbatim}
@@ -16230,25 +16787,14 @@ the selections before setting up hyphenation exceptions.
Knuth was making a particular point about the capabilities of \TeX{}
when he defined the logo. Unfortunately, many believe, he thereby
opened floodgates to give the world a whole range of rather silly
-`bumpy road' logos such as \AMSTeX{}, \PiCTeX{}, \BibTeX{}, and so on,
-produced in a flurry of different fonts, sizes, and baselines~--- indeed,
-everything one might hope to cause them to obstruct the reading process.
-In particular, Lamport invented \LaTeX{}
-\htmlignore
-(silly enough in itself)
-\endhtmlignore
-\begin{htmlversion}
- (silly enough in itself, with a raised small `A' and a lowered `E')
-\end{htmlversion}
-and marketing input from Addison-Wesley led to the even
-stranger current logo
-\htmlignore
-\LaTeXe{}.
-\endhtmlignore
-\begin{htmlversion}
- \LaTeXe{}, which appends a lowered single-stroke Greek letter
- epsilon.
-\end{htmlversion}
+`bumpy road' logos for \TeX{} entities such as \AMSTeX{}, \PiCTeX{},
+\BibTeX{}, and so on, produced in a flurry of different fonts, sizes,
+and baselines~--- indeed, everything one might hope to cause them to
+obstruct the reading process. In particular, Lamport invented
+\LaTeX{} (silly enough in itself, with a raised small `A' and a
+lowered `E') and marketing input from Addison-Wesley led to the even
+stranger current logo for \LaTeXe{}, which appends a lowered % !line break
+\latexhtml{\ensuremath{\varepsilon}}{single-stroke Greek letter &epsilon;}.
Sensible users don't have to follow this stuff wherever it goes,
but, for those who insist, a large collection of logos is defined in
@@ -16265,23 +16811,16 @@ use of the Knuthian font for \MP{} (you might get
% which is nice, given the feebleness of representing all these silly
% logos in html otherwise...
\begin{htmlversion}
- something like `META&nbsp;O&nbsp;T').
+ something like `META\&nbsp;\&nbsp;O\&nbsp;\&nbsp;T').
\end{htmlversion}
-You needn't despair, however~--- the author himself uses just `MetaPost'.
+You needn't despair, however~--- most versions of the logo font
+distributed nowadays contain the missing letters, and the author
+himself uses just `MetaPost'.
For those who don't wish to acquire the `proper' logos, the canonical
thing to do is to say \texttt{AMS-}\cmdinvoke{TeX}{}
-\htmlignore
-(\acro{AMS}-\TeX{})
-\endhtmlignore
for \AMSTeX{}, \texttt{Pic}\cmdinvoke{TeX}{}
-\htmlignore
-(Pic\TeX{})
-\endhtmlignore
for \PiCTeX{}, \texttt{Bib}\cmdinvoke{TeX}{}
-\htmlignore
-(Bib\TeX{})
-\endhtmlignore
for \BibTeX{}, and so on.
\begin{ctanrefs}
\item[mflogo.sty]\CTANref{mflogo}
@@ -16433,24 +16972,70 @@ a variety of jobs.
\section{Symbols, etc.}
+\Question[Q-usesymb]{Using symbols}
+
+Most symbol font sets come with a package that defines commands for
+every symbol in the font. While this is convenient, it can lead to
+difficulties, particularly with name clashes when you load packages
+that cover fonts which duplicate symbols~--- an issue which is
+discussed in
+\begin{narrowversion}
+ \Qref[question]{}{Q-alreadydef}.
+\end{narrowversion}
+\begin{wideversion}
+ ``\Qref{symbol already defined}{Q-alreadydef}''.
+\end{wideversion}
+Some font sets (for example, \FontName{MnSymbol}) are huge, and the
+accompanying macros cover so many symbols that name clashes are surely
+a serious problem.
+
+The \Package{pifont} package (originally designed to use the Adobe
+\FontName{Zapf Dingbats} font) avoids this sort of problem: it requires
+you to know the font position of any symbol you want to use (the
+documentation provides font tables). The basic command is
+\cmdinvoke*{ding}{number} for a single symbol; there are commands for
+other fancier uses. \Package{Pifont} also allows you to select other
+fonts, for similar use.
+
+The \Package{yagusylo} describes itself as ``an extended version of
+\Package{pifont}, gone technicolor''. It provides all the facilities
+of \Package{pifont}, but allows you to create your own mnemonic names
+for symbols. Thus, while you can say % ! line break
+\cmdinvoke*{yagding}[family]{symbol number}[colour], you can also
+define symbol names with \csx{defdingname}, and then use them
+with \cmdinvoke*{yagding*}{symbol name} (the defined name carries the
+font family and colour specified in the arguments of
+\csx{defdingname}).
+
+\Package{Yagusylo} is somewhat complicated, but its documentation is
+clear; it is probably the best tool to use for picking and choosing
+symbols from a variety of font families.
+\begin{ctanrefs}
+\item[mnsymbol \nothtml{\rmfamily}fonts]\CTANref{mnsymbol}
+\item[pifont.sty]Distributed as part of \CTANref{psnfss}
+\item[yagusylo.sty]\CTANref{yagusylo}
+\end{ctanrefs}
+
\Question[Q-numbersets]{Symbols for the number sets}
-It is a good idea to have commands such as \csx{R} for the real numbers and
+Mathematicians commonly use special lettering for the real numbers and
other standard number sets. Traditionally these were typeset in bold.
Because, in the ordinary course of events, mathematicians do not have
-access to bold chalk, they invented the special symbols that are now
-often used for \csx{R}, \csx{C}, \emph{etc}. These symbols are known
-as ``blackboard bold''. Before insisting on using them, consider
-whether going back to the old system of ordinary bold might not be
-acceptable (it is certainly simpler).
+access to bold chalk, they invented special symbols that are now
+often used for the number sets; these symbols are known as
+``blackboard bold'' (or double-stroked fonts); in place of the heavier
+strokes of a bold font, (some) strokes of the letters are doubled.
+The minimum useful set is upper-case letters `I', `N', `R', `Q' and
+`Z'; some fonts offer a figure `1' (for a unit matrix~--- not a number
+set at all).
A set of blackboard bold capitals is available in the \acro{AMS}
\FontName{msbm} fonts (\FontName{msbm} is available at a range of
-design sizes, with names such as \FontName{msbm10}). The pair of font
+design sizes, with names such as \FontName{msbm10}). The pair of font
families (the other is called \FontName{msam}) have a large number of
-mathematical symbols to supplement the ones in the standard \TeX{}
-distribution, and are available in Type~1 format with most modern
-distributions. Support files for using the fonts, both under
+mathematical symbols to supplement those provided in the Knuth's
+original \TeX{} distribution, and are available in Type~1 format in
+modern distributions. Support files for using the fonts, both under
\plaintex{} and \LaTeX{} (packages \Package{amssymb} and
\Package{amsfonts}), are available. The font shape is a rather
austere sans, which many people don't like (though it captures the
@@ -16472,6 +17057,11 @@ and sans shapes, at a single weight, and is available both as \MF{}
sources and as Type~1; the font covers the uppercase latin letters,
lowercase `h' and 'k', and the digit `1'.
+A document that shows the \FontName{bbm}, \FontName{bbold},
+\FontName{doublestroke} and \FontName{msbm} fonts, so that you can get
+a feel for their appearance, is available (\acro{CTAN} package
+\Package{blackboard}).
+
An alternative source of Type~1 fonts with blackboard bold characters
may be found in the steadily increasing set of complete families, both
commercial and free, that have been prepared for use with \AllTeX{}
@@ -16488,23 +17078,24 @@ the digit `1', and lower-case `k'.
The ``lazy person's'' blackboard bold macros:
\begin{quote}
\begin{verbatim}
-\newcommand{\R}{{\sf R\hspace*{-0.9ex}%
+\newcommand{\R}{{\textsf{R}\hspace*{-0.9ex}%
\rule{0.15ex}{1.5ex}\hspace*{0.9ex}}}
-\newcommand{\N}{{\sf N\hspace*{-1.0ex}%
+\newcommand{\N}{{\textsf{N}\hspace*{-1.0ex}%
\rule{0.15ex}{1.3ex}\hspace*{1.0ex}}}
-\newcommand{\Q}{{\sf Q\hspace*{-1.1ex}%
+\newcommand{\Q}{{\textsf{Q}\hspace*{-1.1ex}%
\rule{0.15ex}{1.5ex}\hspace*{1.1ex}}}
-\newcommand{\C}{{\sf C\hspace*{-0.9ex}%
+\newcommand{\C}{{\textsf{C}\hspace*{-0.9ex}%
\rule{0.15ex}{1.3ex}\hspace*{0.9ex}}}
\end{verbatim}
\end{quote}
are almost acceptable at normal size if the surrounding text is
-\FontName{cmr10}. However, they are not part of a proper maths font,
-and so do not work in sub- and superscripts. Moreover, the size and
-position of the vertical bar can be affected by the font of the
-surrounding text. As we've seen, there are plenty of alternatives:
-don't try the macros, or anything similar using capital `I' (which
-looks even worse!).
+\FontName{cmr10} (the position of the vertical bar can be affected by
+the surrounding font). However, they are not part of a proper maths font,
+and do not work in sub- and superscripts. As we've seen, there are
+plenty of alternatives: that mythical ``lazy'' person can inevitably
+do better than the macros, or anything similar using capital `I'
+(which looks even worse!). Voluntary \AllTeX{} effort has redefined
+the meaning of laziness (in this respect!).
\begin{ctanrefs}
\item[AMS support files (Plain)]\CTANref{amsfonts-plain}
\item[AMS support files (LaTeX)]\CTANref{amsfonts-latex}
@@ -16513,6 +17104,7 @@ looks even worse!).
\item[bbm fonts]\CTANref{bbm}
\item[bbm macros]\CTANref{bbm-macros}
\item[bbold fonts]\CTANref{bbold}
+\item[blackboard \nothtml{\rmfamily}evaluation set]\CTANref{blackboard}
\item[doublestroke fonts]\CTANref{doublestroke}
\item[fourier fonts]\CTANref{fourier}
\item[mathpazo fonts]\CTANref{mathpazo}
@@ -16535,11 +17127,9 @@ modern \TeX{} distributions.
distribution.
\item[RSFS] The \Package{mathrsfs} package uses a really fancy script
font (the name stands for ``Ralph Smith's Formal Script'') which is
- already part of most modern \TeX{} distributions. The package
+ already part of most modern \TeX{} distributions (Type~1 versions of
+ the font are also provided, courtesy of Taco Hoekwater). The package
creates a new command \csx{mathscr}.
-
- Type 1 versions of the font have been made available by Taco
- Hoekwater.
\item[Zapf Chancery] is the standard \PS{} calligraphic font. There
is no package but you can easily make it available by means of the
command
@@ -16560,8 +17150,9 @@ modern \TeX{} distributions.
Adobe Zapf Chancery (which the above examples use) is distributed in
any but the most basic \PS{} printers. A substantially identical
font (to the extent that the same metrics may be used) is
- available from \acro{URW} and is distributed with
- \ProgName{ghostscript}.
+ available from \acro{URW}, called URW Chancery L: it is distributed
+ with Ghostscript, and as part of the ``URW base35'' bundle, which is
+ available in most distributions.
\end{description}
Examples of the available styles are available on \acro{CTAN}.
\begin{ctanrefs}
@@ -16571,8 +17162,8 @@ Examples of the available styles are available on \acro{CTAN}.
\item[ghostscript]Browse \CTANref{ghostscript}
\item[mathrsfs.sty]Distributed as part of \CTANref{jknappen-macros}
\item[rsfs fonts]\CTANref{rsfs}
-\item[rsfs fonts, in Type 1 format]\CTANref{rsfs-type1}
\item[Script font examples]\CTANref{mathscript}
+\item[URW Chancery L]Distributed as part of \CTANref{urw-base35}
\end{ctanrefs}
\Question[Q-boldgreek]{Setting bold Greek letters in \LaTeX{}}
@@ -16831,12 +17422,252 @@ errors: you \emph{must} use
\end{verbatim}
\end{quote}
+\Question[Q-osf]{Using ``old-style'' figures}
+
+These numbers are also called medieval or lowercase figures and their
+use is mostly font-specific. Terminology is confusing since the
+lining figures (which are now the default) are a relatively recent
+development (19th century) and before they arrived, oldstyle figures
+were the norm, even when setting mathematics. (An example is Thomas
+Harriot's \emph{Artis Analyticae Praxis} published in 1631). In a
+typical old style 3, 4, 5, 7 and 9 have descenders and 6 and 8 ascend
+above the x-height; sometimes 2 will also ascend (this last seems to
+be a variation associated with French typography).
+
+\LaTeX{} provides a command \cmdinvoke*{oldstylenums}{digits}, which
+by default uses an old-style set embedded in Knuth's `math italic'
+font. The command isn't sensitive to the font style of surrounding
+text: the glyphs are only available to match the normal medium weight
+Computer Modern Roman fonts.
+
+The \Package{textcomp} package changes \csx{oldstylenums} to use the
+glyphs in the Text Companion fonts (\LaTeX{} \acro{TS}1 encoding) when
+in text mode, and also makes them available using the macros of the
+form \csx{text<number>oldstyle}, e.g., \csx{textzerooldstyle}.
+(Of course, not all font families can provide this facility.)
+
+Some font packages (e.g., \Package{mathpazo}) make old-style figures
+available and provide explicit support for making them the default:
+\cmdinvoke{usepackage}[osf]{mathpazo} selects a form where digits are
+always old-style in text. The \Package{fontinst} package will
+automatically generate ``old-style versions'' of commercial Adobe Type
+1 font families for which ``expert'' sets are available.
+
+It's also possible to make virtual fonts, that offer old-style digits,
+from existing font packages. The \FontName{cmolddig} bundle provides
+a such a virtual version of Knuth's originals, and the \FontName{eco}
+or \FontName{hfoldsty} bundles both provide versions of the \acro{EC}
+fonts. The \FontName{lm} family offers old-style figures to OpenType
+users (see below), but we have no stable mapping for \FontName{lm}
+with old-style digits from the Adobe Type 1 versions of the fonts.
+
+Originally, oldstyle figures were only to be found the expert sets of
+commercial fonts, but now they are increasingly widely available. An
+example is Matthew Carter's Georgia font, which has old-style figures
+as its normal form (the font was created for inclusion with certain
+Microsoft products and is intended for on-screen viewing).
+
+OpenType fonts have a pair of axes for number variations~---
+proportional/tabular and lining/oldstyle selections are commonly
+available. ``Full feature access'' to OpenType fonts, making such
+options available to the \AllTeX{} user, is already supported by
+\Qref*{\xetex{}}{Q-xetex} using, for example, the \Package{fontspec}
+package. Similar support is also in the works for
+\Qref*{\LuaTeX{}}{Q-luatex}.
+\begin{ctanrefs}
+\item[cmolddig \nothtml{\rmfamily}fonts]\CTANref{cmolddig}
+\item[eco \nothtml{\rmfamily}fonts]\CTANref{eco}
+\item[fontinst]\CTANref{fontinst}
+\item[fontspec.sty]\CTANref{fontspec}
+\item[mathpazo \nothtml{\rmfamily}fonts]\CTANref{mathpazo}
+\end{ctanrefs}
+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Macro programming}
\subsection{``Generic'' macros and techniques}
+\Question[Q-linmacnames]{Non-letters in macro names}
+
+New \LaTeX{} users are often suprised that macro definitions
+containing non-letters, such as
+\begin{quote}
+\begin{verbatim}
+\newcommand{\cul8r}{Goodbye!}
+\end{verbatim}
+\end{quote}
+fail to compile. The reason is that the \TeX{} macro language, unlike
+most programming languages, allows % ! loin break (twatbili)
+\Qref*{nothing but letters in macro names}{Q-whatmacros}.
+
+There are a number of techniques for defining a macro with a name like
+\csx{cul8r}. Unfortunately, none of the techniques is particularly
+good:
+\begin{enumerate}
+\item Use \csx{csname}\dots\csx{endcsname} to define and invoke the
+ macro:
+ \begin{quote}
+\begin{narrowversion}
+\begin{verbatim}
+\expandafter\newcommand
+ \csname cul8r\endcsname{Goodbye!}
+I said, ``\csname cul8r\endcsname''.
+\end{verbatim}
+\end{narrowversion}
+\begin{wideversion}
+\begin{verbatim}
+\expandafter\newcommand\csname cul8r\endcsname{Goodbye!}
+I said, ``\csname cul8r\endcsname''.
+\end{verbatim}
+\end{wideversion}
+ \end{quote}
+ \begin{description}
+ \item[Pro:] No unexpected side effects
+ \item[Con:] So verbose as to be unusable
+ \end{description}
+\item Define a ``special-command generator'', and use the resulting
+ commands:
+\begin{quote}
+\begin{narrowversion}
+\begin{verbatim}
+\newcommand{\DefineRemark}[2]{%
+ \expandafter\newcommand
+ \csname rmk-#1\endcsname{#2}%
+}
+\newcommand{\Remark}[1]{%
+ \csname rmk-#1\endcsname%
+}
+...
+\DefineRemark{cul8r}{Goodbye!}
+...
+I said, ``\Remark{cul8r}''.
+\end{verbatim}
+\end{narrowversion}
+\begin{wideversion}
+\begin{verbatim}
+\newcommand{\DefineRemark}[2]{%
+ \expandafter\newcommand\csname rmk-#1\endcsname{#2}%
+}
+\newcommand{\Remark}[1]{\csname rmk-#1\endcsname}
+...
+\DefineRemark{cul8r}{Goodbye!}
+...
+\Remark{cul8r}
+\end{verbatim}
+\end{wideversion}
+\end{quote}
+ \begin{description}
+ \item[Pro:] Straightforward to use, not too untidy
+ \item[Con:] It's hardly doing what we set out to do (experts will
+ see that you are defining a macro, but others likely won't)
+ \end{description}
+\item Convince \TeX{} that ``\texttt{8}'' is a letter:
+ \begin{quote}
+\begin{verbatim}
+\catcode`8 = 11
+\newcommand{\cul8r}{Goodbye!}
+I said, ``\cul8r''.
+\end{verbatim}
+ \end{quote}
+ \begin{description}
+ \item[Pro:] \csx{cul8r} can be used directly
+ \item[Con:] Likely to break other uses of ``\texttt{8}'' (such as
+ numbers or dimensions; so
+ \cmdinvoke{setlength}{\csx{paperwidth}}{8in} tells us:
+ \begin{quote}
+\begin{verbatim}
+! Missing number, treated as zero.
+<to be read again>
+ 8
+\end{verbatim}
+ \end{quote}
+ \end{description}
+ As a general rule, changing category codes is something to use
+ \emph{in extremis}, after detailed examination of options. It is
+ conceivable that such drastic action could be useful for you, but
+ most ordinary users are well advised not even to try such a
+ technique.
+\item Define a macro \csx{cul} which must always be followed by
+ ``\texttt{8r}'':
+ \begin{quote}
+\begin{verbatim}
+\def\cul8r{Goodbye!}
+I said, ``\cul8r''.
+\end{verbatim}
+ \end{quote}
+ \begin{description}
+ \item[Pro:] \csx{cul8r} can be used directly
+ \item[Con~\#1:] Breaks if \csx{cul} is followed by anything other
+ than ``\texttt{8r}'', with a confusing diagnostic~---
+ \csx{cul99} produces:
+ \begin{quote}
+\begin{wideversion}
+\begin{verbatim}
+! Use of \cul doesn't match its definition.
+<*> \cul9
+ 9
+\end{verbatim}
+\end{wideversion}
+\begin{narrowversion}
+\begin{verbatim}
+! Use of \cul doesn't match its
+ definition.
+<*> \cul9
+ 9
+\end{verbatim}
+\end{narrowversion}
+ \end{quote}
+ (which would confuse someone who hadn't even realised there
+ \emph{was} a definition of \csx{cul} in the document).
+ \item[Con~\#2:] Silently redefines existing \csx{cul}, if any;
+ as a result, the technique cannot be used to define both a
+ \csx{cul8r} and, say, a \csx{cul123} macro in the same
+ document.
+ \end{description}
+\end{enumerate}
+Technique~3 is in fact commonly used~--- in a limited form~--- within
+most \LaTeX{} packages and within \LaTeX{} itself. The convention is to
+use ``\texttt{@}'' within the names of internal macros to hide them
+from the user and thereby prevent naming conflicts. To this end,
+\LaTeX{} automatically treats ``\texttt{@}'' as a letter while
+processing classes and packages and as a non-letter while processing
+the user's document. The key to this technique is the separation:
+internally a non-letter is used for macro names, and the user doesn't
+see anything of it, while the status remains ``frozen'' in all the
+definitions created within the class or package. See % ! line break
+\Qref[question]{\csx{@} and \texttt{@} in macro names}{Q-atsigns} for
+more information.
+
+Note that analogous use of technique~3 in this example would give us
+\begin{quote}
+\begin{verbatim}
+\begingroup
+ \catcode`8 = 11
+ \gdef\cul8r{Goodbye!}
+ \gdef\later{\cul8r}
+\endgroup
+I said, ``\later''.
+\end{verbatim}
+\end{quote}
+which works, but rather defeats the object of the exercise.
+(\csx{later} has the ``frozen'' catcode for `8', even though the value
+has reverted to normal by the time it's used; note, also, the use of
+the primitive command \csx{gdef}, since \csx{newcommand} can't make a
+macro that's available outside the group.)
+
+\emph{Recommendation}: Either choose another mechanism (such as
+\csx{DefineRemark} above), or choose another name for your macro, one
+that contains only ordinary letters. A common approach is to use
+roman numerals in place of arabic ones:
+\begin{quote}
+\begin{verbatim}
+\newcommand{\culVIIIr}{Goodbye!}
+\end{verbatim}
+\end{quote}
+which rather spoils the intent of the joke implicit in the example
+\csx{cul8r}!
+
\Question[Q-findwidth]{Finding the width of a letter, word, or phrase}
Put the word in a box, and measure the width of the box. For example,
@@ -16877,7 +17708,7 @@ would naturally write:
\end{quote}
However, this would not work: a call to \csx{splat} would execute
\csx{mumble}, and the call the redefined \csx{splat} again; this is an
-infinite recursive loop, that will quickly exhaust \TeX{}'s memory.
+unterminated recursion, that will quickly exhaust \TeX{}'s memory.
Fortunately, the \TeX{} primitive \csx{let} command comes to our
rescue; it allows us to take a ``snapshot'' of the current state of a
@@ -16948,7 +17779,12 @@ The \Package{etoolbox} (which provides user access to \eTeX{}'s
programming facilities) provides a command \csx{patchcmd} which will
perform a ``string substitution'' in a macro's definition. The
package also provides commands that prepend (\csx{pretocmd}) or append
-(\csx{apptocmd}) to the definition of a command.
+(\csx{apptocmd}) to the definition of a command. Not all commands may
+be patched in this way; the package provides a command
+\csx{ifpatchable} which checks the prerequisites, and checks that the
+target command's body does indeed include the patch string you propose
+to use. (The command \csx{ifpatchable*} omits the test on the patch
+string.)
Finally, we'll briefly consider a package that is (just about)
usable, but not really recommendable. \Package{Patch} gives you an
@@ -16966,7 +17802,7 @@ Fortunately, the file (\File{patch.doc}) may be input directly, and
Roughly speaking, one gives the command a set of instructions
analogous to \ProgName{sed} substitutions, and it regenerates the
command thus amended. Unless you can't do your job any other way, you
-had probably best avoid \Package{Patch}.
+had probably best avoid \Package{patch}.
\begin{ctanrefs}
\item[etoolbox.sty]\CTANref{etoolbox}
\item[patch.doc]\CTANref{patch}
@@ -17414,6 +18250,179 @@ accurately.
\item[keyval.sty]Distributed as part of \CTANref{graphics}
\end{ctanrefs}
+\Question[Q-keyval]{Key-value input for macros and package options}
+
+When we discussed % !line break
+\Qref*{extending the number of arguments to a macro}{Q-moren9}, we
+suggested that large numbers of arguments, distinguished only by their
+position, aren't very kind to the user, and that a package such as
+\Package{keyval} offers a more attractive user interface. We now
+consider the packages that the macro programmer might use, to create
+such a user interface.
+
+The simplest key-value processor remains \Package{keyval}; it has a
+command \csx{define@key} to declare a key and a \emph{handler} to
+process it, and a macro \csx{setkeys} to offer values to the handler
+of one or more keys. Thus:
+\begin{quote}
+\begin{verbatim}
+\define@key{my}{foo}{Foo is #1\par}
+\define@key{my}{bar}[99]{Bar is #1\par}
+...
+\setkeys{my}{foo=3,bar}
+\end{verbatim}
+\end{quote}
+will produce output saying:
+\begin{quote}
+ Foo is 3\par{}
+ Bar is 99
+\end{quote}
+This has defined two keys `\texttt{foo}' and `\texttt{bar}' in family
+`\texttt{my}', and then executed them, the first with argument
+`\texttt{3}' and the second with no argument, so that the default
+value of `\texttt{99}' is picked up. In effect, the two calls to
+\csx{define@key} are simply defining commands, as (for example):
+\begin{quote}
+\begin{verbatim}
+\newcommand{\KV@my@foo}[1]{Foo is #1}
+\end{verbatim}
+\end{quote}
+(the definition of \csx{KV@my@bar} is similar, but trickier). The
+command \csx{setkeys} knows how to find those commands when it needs to
+process each key~--- it is easy to regurgitate the structure of the
+command name, with family name (`\texttt{my}', here) after the first
+`\texttt{@}', and the key name after the second `\texttt{@}'. (The
+`\texttt{KV}' part is fixed, in \Package{keyval}.)
+
+These simple commands are enough, in fact, to process the botanical
+example offered as replacement for multi-argument commands in % ! line break
+\Qref[question]{the question mentioned above}{Q-moren9}, or the
+optional arguments of the \csx{includegraphics} command of the
+\Package{graphicx} package. (The last is, in fact, what
+\Package{keyval} was designed to do.)
+
+However, we need more if we're to to have package options in
+`key-value' form. Packages like \Package{hyperref} have enormously
+complicated package options which need key-value processing at
+\csx{ProcessOptions} time: \Package{keyval} can't do that on its own.
+
+Heiko Oberdiek's \Package{kvoptions} package comes to our help: it
+enables the programmer to declare class or package options that
+operate as key and value pairs. The package defines commands
+\csx{DeclareBoolOption} for options whose value should be either
+\emph{true} or \emph{false}, and \csx{DeclareStringOption} for all
+other options that have a value. Keys are declared using
+\Package{keyval} and may remain available for use within the document,
+or may be `cancelled' to avoid confusion. If you have loaded
+\Package{kvoptions}, the \LaTeX{} kernel's \csx{DeclareOption} becomes
+\csx{DeclareVoidOption} (it's an option with no value), and
+\csx{DeclareOption*} becomes \csx{DeclareDefaultOption}.
+
+Heiko also provides \Package{kvsetkeys} which is a more robust version
+of \Package{setkeys}, with some of the rough edges made smoother.
+
+Hendri Adriaens' \Package{xkeyval} offers more flexibility than
+the original \Package{keyval} and is more robust than the original,
+too. Like \Package{kvoptions}, the package also has mechanisms to
+allow class and package options in key-value form (macros
+\csx{DeclareOptionX}, \csx{ExecuteOptionsX} and \csx{ProcessOptionsX}.
+\Package{Pstricks} bundle packages use a \Package{xkeyval} derivative
+called \Package{pst-xkey} for their own key-value manipulation.
+% xkvview? (i think we can ignore xkvltxp for these purposes)
+
+The (widely-respected) \Package{pgf} graphics package has its own
+key-value package called \Package{pgfkeys}. The documentation of the
+package (part of the huge \Package{pgf} manual, in part 5,
+``utilities'') contains a useful comparison with other key-value
+systems; some notable differences are:
+\begin{itemize}
+\item key organisation: \Package{pgfkeys} uses a tree structure, while
+ \Package{keyval} and \Package{xkeyval} both associate keys with a family;
+\item \Package{pgfkeys} supports multi-argument key code; and
+\item \Package{pgfkeys} can support call-backs when an unknown key
+ appears (these things are called \emph{handlers}.
+\end{itemize}
+Keys are organized in a tree that is reminiscent of the Unix fille
+tree. A typical key might be, \File{/tikz/coordinate system/x} or
+just \File{/x}. When you specify keys you can provide the complete
+path of the key, but you usually just provide the name of the key
+(corresponding to the file name without any path) and the path is
+added automatically. So a \csx{pgfkeys} command might be:
+\begin{wideversion}
+\begin{quote}
+\begin{verbatim}
+\pgfkeys{/my key=hello,/your keys/main key=something\strange,
+ key name without path=something else}
+\end{verbatim}
+\end{quote}
+\end{wideversion}
+\begin{narrowversion}
+\begin{quote}
+\begin{verbatim}
+\pgfkeys{/my key=hello,
+ /your keys/main key=something\strange,
+ key name without path=something else}
+\end{verbatim}
+\end{quote}
+\end{narrowversion}
+and for each key mentioned, the associated code will be executed.
+\dots{} and that code is also set up using \csx{pgfkeys}:
+\begin{quote}
+\begin{verbatim}
+\pgfkeys{/my key/.code=The value is '#1'.}
+\end{verbatim}
+\end{quote}
+after which
+\begin{quote}
+\begin{verbatim}
+\pgfkeys{/my key=hi!}
+\end{verbatim}
+\end{quote}
+will produce just
+\begin{quote}
+ The value is 'hi!'.
+\end{quote}
+The manual goes on, showing how to define a key with two arguments,
+how to provide default value for a key, and how to define aliases for
+particular key sequences (which are called ``styles''). All in all,
+it seems a well thought-out system, offering a lot of flexibility that
+isn't available with the other keys packages. However, there seems to
+be no mechanism for using \Package{pgfkeys} keys as part of the
+options of another package, in the way that \Package{kvoptions} does.
+
+Another key-value system that's part of larger set of macros is
+\Package{scrbase}, which uses the facilities of \Package{keyval} to
+build a larger set of facilities, originally for use within the
+\Class{KOMA-script} bundle. For English-speaking authors, there are
+difficulties from the German-only documentation; however, from a
+partial translation available to the author of this answer, a summary
+is possible. The package may build on the facilities either of
+\Package{kyeval} or of \Package{xkeyval}, and builds its functionality
+on the structure of the `key family'. The user may define family
+`members' and keys are defined relative to the members. (For example,
+the package \Package{scrbase} is part of the \Class{KOMA-script}
+bundle; so its keys are all members of the \Package{scrbase.sty}
+family within the \Package{KOMA} family. The function
+\csx{FamilyProcessOptions} allows the programmer to decode the options
+of the package in terms of the package's key family. Note that there
+is no special provision made for ``traditional'' package options, as
+in the \Package{kvoptions} package.
+
+This brief summary was guided by input from two sources: a draft article
+for \textsl{TUGboat} by Joseph Wright, and the partial translation of the
+documentation of package \Package{scrbase} prepared by Philipp
+Stephani. At Joseph's suggestion, discussion of his \Package{keys3}
+package, which is designed for use with the experimental \LaTeX{}3,
+has been omitted.
+\begin{ctanrefs}
+\item[keyval.sty]Distributed as part of \CTANref{graphics}
+\item[kvoptions.sty]Distributed as part of \CTANref{oberdiek}
+\item[kvsetkeys.sty]Distributed as part of \CTANref{oberdiek}
+\item[pgfkeys.sty]Distributed as part of \CTANref{pgf}
+\item[scrbase.sty]Distributed as part of \CTANref{koma-script}
+\item[xkeyval.sty]\CTANref{xkeyval}
+\end{ctanrefs}
+
\Question[Q-activechars]{Defining characters as macros}
Single characters can act as macros (defined commands), and both
@@ -17827,9 +18836,9 @@ was present in the very first releases of \PDFTeX{}) is
\begin{quote}
\begin{verbatim}
\ifx\pdfoutput\undefined
- <not running PDFTeX>
+ ... % not running PDFTeX
\else
- <running PDFTeX>
+ ... % running PDFTeX
\fi
\end{verbatim}
\end{quote}
@@ -17852,12 +18861,12 @@ test may need to be elaborated:
\begin{quote}
\begin{verbatim}
\ifx\pdfoutput\undefined
- <not running PDFTeX>
+ ... % not running PDFTeX
\else
\ifx\pdfoutput\relax
- <not running PDFTeX>
+ ... % not running PDFTeX
\else
- <running PDFTeX>
+ ... % running PDFTeX
\fi
\fi
\end{verbatim}
@@ -17871,16 +18880,16 @@ output, you also need to know about the value of \csx{pdfoutput}:
\begin{quote}
\begin{verbatim}
\ifx\pdfoutput\undefined
- <not running PDFTeX>
+ ... % not running PDFTeX
\else
\ifx\pdfoutput\relax
- <not running PDFTeX>
+ ... % not running PDFTeX
\else
- <running PDFTeX, with...>
+ % running PDFTeX, with...
\ifnum\pdfoutput>0
- <...PDF output>
+ ... % PDF output
\else
- <...DVI output>
+ ... % DVI output
\fi
\fi
\fi
@@ -17889,8 +18898,17 @@ output, you also need to know about the value of \csx{pdfoutput}:
The above is, in essence, what Heiko Oberdiek's \Package{ifpdf}
package does; the reasoning is the \acro{FAQ}'s interpretation of
Heiko's explanation.
+
+As an aside: there are now analogous packages \Package{ifxetex} and
+\Package{ifluatex}, for the two up-and-coming \TeX{}-like engines (see
+the ``\TeX{} project'' answers covering % ! line break
+\Qref[\xetex{}~--- question]{\xetex{}}{Q-xetex}, and
+\Qref[\LuaTeX{}~--- question]{\LuaTeX{}}{Q-luatex}).
\begin{ctanrefs}
\item[ifpdf.sty]Distributed with Heiko Oberdiek's packages \CTANref{oberdiek}
+\item[ifluatex.sty]Distributed with Heiko Oberdiek's packages
+ \CTANref{oberdiek}
+\item[ifxetex.sty]\CTANref{ifxetex}
\end{ctanrefs}
\Question[Q-subverttoks]{Subverting a token register}
@@ -18986,19 +20004,13 @@ then examined (in a \Package{hyperref}-safe way) to set a conditional
\csx{ifoddpage}. Of course, the \csx{label} contributes to \LaTeX{}'s
``Rerun to get cross-references right'' error messages\dots{}
-The (older) \Package{chngpage} provides the same facilities (though it
-provides a \csx{ifcpoddpage} command; \Package{changepage} (whose
-functions are extracted from the author's \Class{memoir} class) is the
-designated successor to \Package{chngpage}.
-
The Koma-Script classes have an \environment{addmargin*} environment
-that also provides the sorts of facilities that the \Package{chngpage}
+that also provides the sorts of facilities that the \Package{changepage}
offers. Koma-Script's supporting command is % !line break
\cmdinvoke{ifthispageodd}{<true>}{<false>} executes different things
depending on the page number.
\begin{ctanrefs}
\item[changepage.sty]\CTANref{changepage}
-\item[chngpage.sty]\CTANref{chngpage}
\item[\nothtml{\rmfamily}KOMA script bundle]\CTANref{koma-script}
\item[memoir.cls]\CTANref{memoir}
\end{ctanrefs}
@@ -19962,7 +20974,7 @@ necessary?''.
address or the like, then the \csx{url} command from the
\Package{url} will help: it doesn't suffer from all the problems of
\csx{verb}, though it's still not robust; % ! line break
- ''\Qref*{typesetting \acro{URL}s}{Q-setURL}'' offers advice here.
+ ``\Qref*{typesetting \acro{URL}s}{Q-setURL}'' offers advice here.
\item If you're putting \csx{verb} into the argument of a boxing
command (such as \csx{fbox}), consider using the \environment{lrbox}
environment:
@@ -19983,13 +20995,13 @@ Otherwise, there are three partial solutions to the problem.
\item Some packages have macros which are designed to be responsive
to verbatim text in their arguments. For example,
the \Package{fancyvrb} package defines a command
- \csx{VerbatimFootnotes}, which redefines the \csx{footnotetext} (and
- hence the \csx{footnote}) commands in such a way that you can include
- \csx{verb} commands in its argument. This approach could in
- principle be extended to the arguments of other commands, but it can
- clash with other packages: for example, \csx{VerbatimFootnotes}
- interacts poorly with the |para| option to the \Package{footmisc}
- package.
+ \csx{VerbatimFootnotes}, which redefines the \csx{footnotetext}
+ command, and hence also the behaviour of the \csx{footnote})
+ command, in such a way that you can include \csx{verb} commands in
+ its argument. This approach could in principle be extended to the
+ arguments of other commands, but it can clash with other packages:
+ for example, \csx{VerbatimFootnotes} interacts poorly with the
+ \pkgoption{para} option of the \Package{footmisc} package.
The \Class{memoir} class defines its \csx{footnote} command so that
it will accept verbatim in its arguments, without any supporting package.
@@ -19998,8 +21010,9 @@ Otherwise, there are three partial solutions to the problem.
and then to reuse the content of its argument; for details of this
extremely powerful facility, see the package documentation.
- Rather simpler is the \Package{verbdef} package, which defines a
- (robust) command which expands to the verbatim argument given.
+ Rather simpler is the \Package{verbdef} package, whose \csx{verbdef}
+ command defines a (robust) command which expands to the verbatim
+ argument given.
\item If you have a single character that is giving trouble (in
its absence you could simply use \csx{texttt}), consider using
\csx{string}. \cmdinvoke{texttt}{my\csx{string}\_name}
@@ -20442,6 +21455,49 @@ parentheses, but the issue seldom arises since such arguments rarely
contain text. If it were to arise, the same solution (enclosing the
confused characters in braces) would solve the problem.
+\Question[Q-pdf-fig-chars]{Characters disappear from figures in \PDFTeX{}}
+
+You have a \acro{PDF} figure, which you want to use in your
+\PDFLaTeX{} document. When you compile the document, \PDFTeX{}
+complains about ``missing glyphs'', and some (or all) of the labelling
+text or symbols in the original figure is no longer visible.
+
+What has happened is:
+\begin{enumerate}
+\item Your figure file (say \File{fig.pdf}) has a font \File{font.pfb}
+ embedded in it.
+\item \PDFTeX{} notes that it has \File{font.pfb} on disc, and loads
+ that in place of the copy in \File{fig.pdf}.
+\item It turns out that the copy in \File{fig.pdf} has glyphs that
+ aren't in \File{font.pfb} on disc, so that you get errors while
+ compiling and you see that characters are missing when you view the
+ output. (\PDFTeX{} can't know that the fonts are different, since
+ they have the same name.)
+\end{enumerate}
+Which is all very undesirable.
+
+\PDFTeX{} does this to keep file sizes down: suppose you have a
+document that loads figures \File{fig1.pdf} and \File{fig2.pdf}; both
+of those use font \File{font.pfb}. If \PDFTeX{} takes no action,
+there will be \emph{two} copies of \File{font.pfb} in the output.
+(If your document also uses the font, there could be three copies.)
+
+A real case is the \acro{URW} font \File{NimbusRomNo9L-Regu} (a clone
+of Times Roman), which is available in a version with Cyrillic
+letters, while the version in \TeX{} distributions doesn't have those
+letters. Both versions, as distributed, have the same name.
+
+The simple (``quick and dirty'') solution is to add the command
+\begin{quote}
+ \csx{pdfinclusioncopyfonts}\texttt{=1}
+\end{quote}
+to the preamble of your document.
+
+The ``real'' solution is that one or other font should be renamed. In
+either case, this would require that you reconfigure some program's
+(\TeX{}'s or your drawing package's) font tables~--- inevitably a
+tiresome job.
+
\subsection{Common misunderstandings}
\Question[Q-include]{What's going on in my \csx{include} commands?}
@@ -21863,16 +22919,18 @@ There is nothing that can directly be done about this error, as you can't
extend the number of available registers without extending \TeX{}
itself.
\begin{htmlversion}
- Of course, \Qref{\eTeX{}}{Q-etex} and \Qref{Omega}{Q-omegaleph}
+ Of course, \Qref{\eTeX{}}{Q-etex}, \Qref{Omega}{Q-omegaleph} and
+ \Qref{\LuaTeX{}}{Q-luatex}
\end{htmlversion}
\htmlignore
% beware line wrap here
- Of course, \ensuremath{\Omega} and \eTeX{}~---
- \Qref[see questions]{}{Q-omegaleph} \Qref[and]{}{Q-etex} respectively~---
+ Of course, \eTeX{}, \ensuremath{\Omega} and \LuaTeX{}~---
+ \Qref[see questions]{}{Q-etex} \Qref[,]{}{Q-omegaleph} and
+ \Qref[and]{}{Q-luatex} respectively~---
\endhtmlignore
- both do this, as does \Qref*{MicroPress Inc's V\TeX{}}{Q-commercial}.
+all do this, as does \Qref*{MicroPress Inc's V\TeX{}}{Q-commercial}.
-The commonest way to encounter one of these error messages is to have
+One common way to encounter one of these error messages is to have
broken macros of some sort, or incorrect usage of macros (an example
is discussed in \Qref[question]{epsf problems}{Q-epsf}).
@@ -21880,14 +22938,41 @@ However, sometimes one just \emph{needs} more than \TeX{} can offer,
and when this happens, you've just got to work out a different way of
doing things. An example is the % beware line wrap
\Qref*{difficulty of loading \PiCTeX{} with \LaTeX{}}{Q-usepictex}.
-In cases like \PiCTeX{}, it may be possible to use
-\Qref*{\eTeX{}}{Q-etex} (all modern distributions provide it). The
-\LaTeX{} package \Package{etex} modifies the register allocation
-mechanism to make use of \eTeX{}'s extended register sets (it's a
+The more modern drawing package, \Package{pgf} with its higher-level
+interface \Package{TikZ} is a common problem.
+
+In such cases, it is usually possible to use the
+\Qref*{\eTeX{}}{Q-etex} extensions (all modern distributions provide
+them). The \LaTeX{} package \Package{etex} modifies the register allocation
+mechanism to make use of \eTeX{}'s extended register sets.
+\Package{Etex} is a
derivative of the \plaintex{} macro file \Package{etex.src}, which is
used in building the \eTeX{} Plain format; both files are part of the
-\eTeX{} distribution). Unfortunately, \eTeX{} doesn't help with
-\csx{read} or \csx{write} objects.
+\eTeX{} distribution and are available in current distributions.
+
+It is possible that, even with \Package{etex} loaded, you still find
+yourself running out of things. Problems could be caused by packages
+that use large numbers of ``inserts'' (combinations of counter, box,
+dimension and skip registers, used for storing floats and footnotes).
+\Package{Morefloats} does this, of course (naturally enough,
+allocating new floats), and footnote packages such as
+\Package{manyfoot} and \Package{bigfoot} (which uses \Package{manyfoot}
+can also give problems. The \Package{etex} allows you to deal with
+these things: the command \cmdinvoke*{reserveinserts}{n} ensures there
+is room for \meta{n} more inserts. (Hint: \Package{morefloats} needs
+18 inserts, and \Package{manyfoot} seems to be happy with 10
+reserved.) Load \Package{etex} before any others, and reserve the
+inserts immediately:
+\begin{quote}
+\begin{verbatim}
+\documentclass[...]{...}
+\usepackage{etex}
+\reserveinserts{28}
+\end{verbatim}
+\end{quote}
+
+Unfortunately, \eTeX{} doesn't help with \csx{read} or \csx{write}
+objects (and neither will the \Package{etex} package).
\Question[Q-epsf]{\texttt{epsf} gives up after a bit}
@@ -22741,7 +23826,7 @@ However, for those improbable (or machine-generated) situations,
some distributions offer the opportunity to adjust the parameter
|max_in_open| in a configuration file.
-\Question[Q-hyperdupdest]{\PDFTeX{} destination \dots{} ignored}
+\Question[Q-hyperdupdest]{\PDFTeX{} destination \dots{}\ ignored}
The warning:
\begin{quote}
@@ -23331,6 +24416,49 @@ This author has also encountered the error when developing macros that
used the \LaTeX{} internal float mechanisms. Most people doing that
sort of thing are expected to be able to work out their own problems\dots{}
+\Question[Q-texorpdf]{Token not allowed in PDFDocEncoded string}
+
+The package \Package{hyperref} produces this error when it doesn't
+know how to make something into a ``character'' that will go into one
+of its \acro{PDF} entries. For example, the (unlikely) sequence
+\begin{quote}
+\begin{verbatim}
+\newcommand{\filled}[2]{%
+ #1%
+ \hfil
+ #2%
+}
+\section{\filled{foo}{bar}}
+\end{verbatim}
+\end{quote}
+provokes the error. \Package{Hyperref} goes on to tell you:
+\begin{quote}
+\begin{verbatim}
+removing `\hfil' on input line ...
+\end{verbatim}
+\end{quote}
+It's not surprising: how would \emph{you} put the
+typesetting instruction \csx{hfil} into a \acro{PDF} bookmark?
+
+\Package{Hyperref} allows you to define an alternative for such
+things: the command \csx{texorpdfstring}, which takes two
+arguments~--- the first is what is typeset, the second is what is put
+into the bookmark. For example, what you would probably like in this
+case is just a single space in the bookmark; if so, the erroneous
+example above would become:
+\begin{quote}
+\begin{verbatim}
+\newcommand{\filled}[2]{%
+ #1%
+ \texorpdfstring{\hfil}{\space}%
+ #2%
+}
+\section{\filled{foo}{bar}}
+\end{verbatim}
+\end{quote}
+and with that definition, the example will compile succesfully
+(\Package{hyperref} knows about the macro \csx{space}).
+
\Question[Q-optionclash]{Option clash for package}
So you've innocently added:
@@ -23572,13 +24700,22 @@ found on the project web site
(\URL{http://www.latex-project.org/papers/}), as is some of the
project's experimental code
(see \URL{http://www.latex-project.org/code.html}, which allows you to
-read the project's source repository). You can
+read the project's source repository); a recent snapshot of two major
+collections from the code, \Package{expl3} and \Package{xpackages},
+are available. Contributed code, such as \Package{keys3} (for
+key-value argument decoding) and \Package{numparse3} (for number
+processing) are available in the \acro{CTAN} `\LaTeX{} experimental' tree.
+
+You can
participate in discussions of the future of \LaTeX{} through the
mailing list \texttt{latex-l}. Subscribe to the list by sending a
message `\texttt{subscribe latex-l <\emph{your name}>}' to
\mailto{listserv@urz.Uni-Heidelberg.de}
\begin{ctanrefs}
+\item[expl3 \nothtml{\rmfamily}bundle]\CTANref{expl3}
+\item[keys3.sty]\CTANref{keys3}
\item[\nothtml{\rmfamily}\LaTeX{} project publications]\CTANref{ltx3pub}
+\item[xpackages \nothtml{\rmfamily}bundle]\CTANref{xpackages}
\end{ctanrefs}
\Question[Q-mathml]{Future \acro{WWW} technologies and \AllTeX{}}
@@ -23672,25 +24809,27 @@ support for new Web standards.
onus on the browser user; and however technically proficient
\emph{you} are, it's never safe to assume too much of your readers.
An interesting alternative is
- \href{http://www.forkosh.com/mimetex.html}{Mime\TeX{}}, which sits
+ \href{http://www.forkosh.com/mathtex.html}{Math\TeX{}}, which sits
on your server as a \acro{CGI} script, and you use it to include
your \TeX{}, in your \acro{HTML}, as if it were an image:
\begin{quote}
\begin{wideversion}
\begin{verbatim}
-<img src="../cgi-bin/mimetex.cgi?f(x)=\int\limits_{-\infty}^xe^{-t^2}dt">
+<img src="/cgi-bin/mimetex.cgi?f(x)=\int\limits_{-\infty}^xe^{-t^2}dt">
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
-<img src="../cgi-bin/mimetex.cgi?f(x)=
+<img src="/cgi-bin/mimetex.cgi?f(x)=
\int\limits_{-\infty}^xe^{-t^2}dt">
\end{verbatim}
\end{narrowversion}
\end{quote}
+(\Package{Mathtex} supersedes the author's earlier \Package{mimetex}.)
\end{description}
\begin{ctanrefs}
\item[GELLMU]\CTANref{gellmu}
+\item[MathTeX]\CTANref{MimeTeX}
\item[MimeTeX]\CTANref{MimeTeX}
\item[TeX4HT]\CTANref{tex4ht}
\end{ctanrefs}
@@ -23833,19 +24972,113 @@ separate window), degree of correspondence of the display to the final
output, and the balance they strike between visual aid and visual
distraction.
\begin{ctanrefs}
-\item[preview-latex]Browse \CTANref{preview-latex}
+\item[preview-latex]Distributed as part of \CTANref{auctex}
\item[texmacs]Browse \CTANref{texmacs}
\end{ctanrefs}
+\Question[Q-omegaleph]{Omega and Aleph}
+
+Omega \nothtml{(\ensuremath{\Omega})} was developed as an extension of
+\TeX{}, to use with multilingual texts, expressed in a variety of
+input encodings. Omega uses 16-bit, Unicode-encoded, characters. It
+provides many innovative concepts, notably including the ``translation
+process'' that takes a character stream and transforms it according to
+various processes that may be internally specified, or be a separate
+program.
+
+While Omega showed a lot of promise at its mid-1990s announcement,
+progress was slow, and development was essentially dead by the time
+that one of the original developers withdrew (taking with him a bunch
+of research students).
+
+Before that distressing event, a separate thread of development had
+started, to produce a program % !avoid space between Aleph and comma
+called Aleph\nothtml{ (\ensuremath{\aleph})}, which merged the facilities of
+\Qref*{\eTeX{}}{Q-etex} into a stable Omega codebase and added other
+extensions. Aleph also proved an attractive platform for many people;
+but its development, too, has dried up.
+
+A presentation at Euro\TeX{} 2006 claimed that development of Omega
+was picking up again, in parallel with research into what the (new)
+developers consider a rational scheme for supporting \TeX{}-style
+typesetting. The new system was to be known as Omega-2
+(\latexhtml{\ensuremath{\Omega_2}}{Omega subscript 2}), and was to be
+designed in a modular fashion so that support of new facilities (such
+as use of advanced OpenType fonts) could be added in a relatively
+straightforward fashion. A quick web search leads to a recommendation
+that potential users consider \Qref{\LuaTeX{}}{Q-luatex} instead.
+Fortunately, lessons learned in Aleph project are being carried
+forward in the \Qref*{\LuaTeX{}}{Q-luatex} project.
+
+\Question[Q-xetex]{The \xetex{} project}
+
+\href{http://scripts.sil.org/xetex}{\xetex{}}, by Jonathan Kew, is a
+successor to the shareware \TeX{}/\acro{GX} program for Macintoshes.
+It is a Unicode-based \TeX{} implementation which is able to make
+direct use of the fonts installed on a system. It supports the
+advanced typographical features available in modern font technology
+(OpenType, \acro{AAT} on Mac~\acro{OS}~X, Graphite). \xetex{} was
+originally developed for Mac~\acro{OS}~X but it is now fully
+integrated in \texlive{} on a wide range of platforms, as well as
+being available as part of \miktex{}. \xetex{} supports Unicode
+character sets and bidirectional typesetting (via \eTeX{} primitives).
+It is popular among linguists and scholars in the humanities, as well
+as an increasing range of people working in other fields. Support for
+mathematical Unicode fonts (such as Asana Math and Cambria) is
+progressing.
+
+The project has an active % ! line break
+\href{http://www.tug.org/mailman/listinfo/xetex}{mailing list}; a
+collection of other information is to be found in a set of % ! line break
+\href{http://www.tug.org/xetex/}{links on the \acro{TUG} web site}.
+
+\Question[Q-luatex]{\PDFTeX{} and \LuaTeX{}}
+
+As is said elsewhere in these \acro{FAQ}s, development of
+\Qref*{\PDFTeX{}}{Q-whatpdftex} is ``in essence'' complete~---
+no new facilities are being developed, since the limitations of the
+present structure mean that the returns on effort invested are
+diminishing. The \PDFTeX{} team has announced that no further
+developments will be added after the release of \PDFTeX{} 1.50.0,
+which will be the next major release.
+
+In parallel with the running-down of \PDFTeX{} development,
+development of a new system, \LuaTeX{} is under way.
+\href{http://www.lua.org/}{\ProgName{Lua}} is a script
+language, designed to offer an interpreter that may be incorporated
+into other applications. \LuaTeX{} consists of a \TeX{}-like engine
+with a \ProgName{lua} interpreter built into it; the \ProgName{lua}
+interpreter has access to many of the data structures used for
+typesetting, and the user may also interpolate chunks of
+\ProgName{lua} code into their \AllTeX{} macros, or as `call-backs'
+for use when the \TeX{}-like engine does certain operations.
+
+This arrangement offers the prospect of a ``semi-soft'' typesetting
+engine: it will have its basic behaviour, but the user gets to
+redefine functionality if an idea occurs~--- there will be no need to
+persuade the world first, and then find a willing developer to work on
+the sources of of the distribution.
+
+The \href{http://www.luatex.org/}{\LuaTeX{} project} is (with monetary
+support from various sources) pursuing avenues that many of the other
+current projects have in their sights, notably Unicode character
+representations and support for OpenType fonts. The intention is
+to integrate the extensions pioneered by \Qref*{Aleph}{Q-omegaleph}.
+
+A release of \LuaTeX{} whose functionality is declared (version 0.50)
+has recently appeared. \texlive{} 2008 incorporates an early release
+of \LuaTeX{}, and the upcoming \miktex{} version 2.8 (no current
+release date) will probably incorporate \LuaTeX{}. \CONTeXT{}
+distributions can already make use of \LuaTeX{}.
+
\Question[Q-ant]{The \textsf{ANT} typesetting system}
-Achim Blumensath's \href{http://ant.berlios.de}{\textsf{ANT}} project,
-in contrast to \NTS{}, aims
-not to replicate \TeX{} with a different implementation technique, but
-rather to provide a replacement for \TeX{} which uses \TeX{}-like
-typesetting algorithms in a very different programming environment.
-\textsf{ANT} remains under development, but it is now approaching the
-status of a usable typesetting system.
+Achim Blumensath's \href{http://ant.berlios.de}{\textsf{ANT}} project
+aims not to replicate \TeX{} with a different implementation
+technique, but rather to provide a replacement for \TeX{} which uses
+\TeX{}-like typesetting algorithms in a very different programming
+environment. \textsf{ANT} remains under development, but it is now
+approaching the status of a usable typesetting system.
\textsf{ANT}'s markup language is immediately recognisable to the
\AllTeX{} user, but the scheme of implementing design in
@@ -23880,88 +25113,6 @@ filtering mechanisms will please those who have long struggled with
\ExTeX{} will accept Unicode input, from the start. In the longer
term, drawing primitives are to be considered.
-\Question[Q-omegaleph]{Omega and Aleph}
-
-Omega \nothtml{(\ensuremath{\Omega})} was developed as an extension of
-\TeX{}, to use with multilingual texts, expressed in a variety of
-input encodings. Omega uses 16-bit, Unicode-encoded, characters. It
-provides many innovative concepts, notably including the ``translation
-process'' that takes a character stream and transforms it according to
-various processes that may be internally specified, or be a separate
-program.
-
-While Omega showed a lot of promise at its mid-1990s announcement, its
-development was slow, and development was essentially dead by the time
-that one of the original developers withdrew (taking with him a bunch
-of research students).
-
-Before that distressing event, a separate thread of development was
-started, to produce a program called Aleph
-\nothtml{(\ensuremath{\aleph})}, which merged the facilities of
-\Qref*{\eTeX{}}{Q-etex} into a stable Omega codebase and added other
-extensions. Aleph also proved an attractive platform for many people;
-but its development, too, has dried up.
-
-The latest news (from Euro\TeX{} 2006) is that development of Omega is
-picking up again, in parallel with research into what the (new)
-authors consider a rational scheme for supporting \TeX{}-style
-typesetting. The new system is to be known as Omega-2
-(\latexhtml{\ensuremath{\Omega_2}}{Omega subscript 2}), and is being
-designed in a modular fashion so that support of new facilities (such
-as use of advanced OpenType fonts) can be added in a relatively
-straightforward fashion.
-
-The work done in the Aleph project is also being carried forward in
-the \Qref*{\LuaTeX{}}{Q-luatex} project.
-
-\Question[Q-luatex]{\PDFTeX{} becomes \LuaTeX{}}
-
-As is said elsewhere in these \acro{FAQ}s, development of
-\Qref*{\PDFTeX{}}{Q-whatpdftex} is ``in essence'' complete~---
-development of new facilities continues, but the limitations of the
-present structure impose a strong limit on what facilities are
-possible. (The \PDFTeX{} team has announced that no further
-developments will be added after the release of \PDFTeX{} 1.50.0,
-which will be the next major release.)
-
-In this context, the idea of \LuaTeX{} arose.
-\href{http://www.lua.org/}{\ProgName{Lua}} is a script
-language, designed to offer an interpreter with a very small
-``footprint'', so it is rather easy to build it into other
-applications. So \LuaTeX{} was launched as a \PDFTeX{}
-executable with a \ProgName{Lua} interpreter built into it.
-
-A \href{http://www.luatex.org/}{\LuaTeX{} project} is now proceeding
-(with monetary support from various sources) and is pursuing avenues
-that many of the other
-current projects have in their sights, notably Unicode character
-representations and support for OpenType fonts. Work is also in hand
-to integrate the extensions pioneered by \Qref*{Aleph}{Q-omegaleph}.
-
-The next release of \texlive{} (due in July 2008) and \miktex{}
-version 2.8 (no current release date) will incorporate \LuaTeX{}.
-\CONTeXT{} distributions can already make use of it.
-
-\Question[Q-xetex]{The \xetex{} project}
-
-\xetex{} (by Jonathan Kew) is a successor to the shareware \TeX{}/\acro{GX}
-program for Macintoshes. It is a Unicode-based (\acro{UTF}-8) TeX
-implementation which is able to make use of Mac~\acro{OS}~X \acro{AAT}
-(Apple Advanced Typography) \extension{dfonts} and OpenType fonts. It
-uses Apple's Quartz system (which facilitates the afore-mentioned font
-access) to generate \acro{PDF} output. \xetex{} supports Unicode
-character sets and bidirectional typesetting, and is widely used by
-people studying linguistics, as well as an increasing range of people
-working in other fields.
-
-A Linux and Unix-system version is available in \texlive{}~2007; that
-version (of course) relies on OpenType fonts alone. A version is
-planned for \miktex{} version 2.7 (currently planned for December 2007).
-
-The project has a \href{http://scripts.sil.org/xetex}{web site} for
-the user who wants more than this simple answer, and you can also sign
-up to a \href{http://www.tug.org/mailman/listinfo/xetex}{mailing list}.
-
\Question[Q-biblatex]{Replacing the \BibTeX{}--\LaTeX{} mechanism}
Producing a successor to \BibTeX{} has long been a favoured activity
@@ -24018,7 +25169,7 @@ a \cmdinvoke{nocite}{*} command enables \BibTeX{} to produce a usable
\Package{Amsrefs} is maintained by the AMS as part of its author
support programme,
-\Package{Biblatex} uses \BibTeX{} more-or-less as normal, but with
+\Package{Biblatex} uses \BibTeX{} simply to sort the citations using
\Package{biblatex}'s own style; the style of citations and of the
bibliography itself is determined by the way your \Package{biblatex}
style has been set up. This structure eliminates the collections of
@@ -24032,10 +25183,25 @@ sections of these \acro{FAQ}s.
\Package{Biblatex} is released as experimental software, but it's
clear that many users are already using it happily; Lehman is
responsive to problem reports, at the moment, but a set of expert
-users is already establishing itself.
+users is already establishing itself. A set of contributed styles has
+appeared, which cover some of the trickier bibliography styles. The
+road map of the project shows one more \emph{beta} release before the
+``stable'' \Package{biblatex}~1.0.
+
+A related project is
+\href{http://biblatex-biber.sourceforge.net/}{\ProgName{biber}} (or
+\ProgName{biblatex-biber}, to distinguish it from an older, defunct,
+\BibTeX{} replacement project). \ProgName{Biber} is a
+\ProgName{Perl}-based system to produce a \BibTeX{} replacement that
+is specifically tuned to the requirements of \Package{biblatex}.
+While it supports `traditional' \BibTeX{}, \ProgName{biber} aims at an
+interface language that is closely tuned to the requirements of
+\Package{biblatex}, including use of a Unicode-based character set to
+ease the generation multilingual citations.
\begin{ctanrefs}
\item[amsrefs.sty]\CTANref{amsrefs}
\item[biblatex.sty]\CTANref{biblatex}
+\item[\nothtml{\rmfamily}biblatex contributions]\CTANref{biblatex-contrib}
\item[\nothtml{\rmfamily}CrossTeX]\CTANref{crosstex}
\end{ctanrefs}