diff options
Diffstat (limited to 'Master/texmf-doc/doc/english/FAQ-en/faqbody.tex')
| -rw-r--r-- | Master/texmf-doc/doc/english/FAQ-en/faqbody.tex | 4252 |
1 files changed, 2977 insertions, 1275 deletions
diff --git a/Master/texmf-doc/doc/english/FAQ-en/faqbody.tex b/Master/texmf-doc/doc/english/FAQ-en/faqbody.tex index d9af0aadb16..01bf67ffedf 100644 --- a/Master/texmf-doc/doc/english/FAQ-en/faqbody.tex +++ b/Master/texmf-doc/doc/english/FAQ-en/faqbody.tex @@ -1,4 +1,4 @@ -\def\faqfileversion{3.14a} \def\faqfiledate{2005/07/07} +\def\faqfileversion{3.16b-1} \def\faqfiledate{2006/10/04} % % The above line defines the file version, and must remain the first % line with any `assignment' in the file, or things will blow up @@ -20,33 +20,78 @@ \section{Introduction} -This \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. +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 +covered from the viewpoint of a \LaTeX{} user. + +You may use the \acro{FAQ} +\begin{itemize} +\item by reading a printed document, +\item by browsing a \acro{PDF} file: copies, with hyperlinks to assist + browsing, are to be found on \acro{CTAN} at \CTANref{faq-a4} + (formatted for A4 paper) or at \CTANref{faq-letter} (formatted for + 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. +\end{itemize} -\htmlignore -An \acro{HTML} translation of the \acro{FAQ} is available on the -World-Wide Web, via \acro{URL} -\URL{http://www.tex.ac.uk/faq}; an alternative \acro{HTML} version -is also to -\endhtmlignore \begin{htmlversion} +% pseudo-subsection here, because of limitations of latex->html translator +\textbf{Caveat: Acquiring files} -An alternative \acro{HTML} version of the \acro{FAQ} may -\end{htmlversion} -be found in \Qref*{\TeX{}~Live}{Q-CD}. +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 +\texttt{.zip} and \texttt{.tar.gz} archives, and a link for browsing +the directory. -\begin{htmlversion} - A copy of the complete \acro{FAQ}, in \acro{PDF} with hyperlinks to - assist browsing, may be found on - \CTANref{faq-a4} (formatted for A4 paper) or - \CTANref{faq-letter} (formatted for North American ``letter'' - paper). +Fortunately, \acro{CTAN} is switching to statically-generated +directory archive files; many directories mentioned in this \acro{FAQ} +will also exist as \texttt{.zip} files on the archives, and won't fall +foul of the browser problem. Of course, if the \texttt{.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*{\TeX{}~Live 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 + +\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. + Most members of the committee of \acro{UK}~\acro{TUG}, over the years since 1994, have contributed to this \acro{FAQ} to some extent. The following people, who have never been members of the committee, have @@ -59,8 +104,10 @@ Charles Cameron, Damian Cugley, Michael Dewey, Michael Downes, % (RIP) on (ams)maths stuff +Jean-Pierre Drucbert, % corrected my interpretation of minitoc Thomas Esser, Ulrike Fischer, % spotted boondoggle in q-tabcellalign + % args like \section improvement Anthony Goreham, Norman Gray, Eitan Gurari, % comparative html translators @@ -72,7 +119,8 @@ Berthold Horn, % lots of stuff on fonts Ian Hutchinson, % comparative html translators Werner Icking, % (RIP) answer on tex-music Regnor Jernsletten, -David Kastrup, +David Kastrup, % inter alia, suggested mention of lilypond +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 @@ -81,6 +129,8 @@ Daniel Luecking, Sanjoy Mahajan, Andreas Matthias, Brooks Moses, % editorial suggestion +Iain Murray, % alternative solution in q-hyperdupdest +Vilar Camara Neto, % correct misunderstanding about breakurl pkg %Dick Nickalls, % now a member of the committee Ted Nieland, Hans Nordhaug, @@ -89,6 +139,7 @@ Heiko Oberdiek, Piet van Oostrum, Scott Pakin, Oren Patashnik, +Steve Peter, % comprehensive review, lots of typos etc Philip Ratcliffe, % help with a bibtex oddity Jos\'e Carlos Santos, % very assiduous reader of new versions Walter Schmidt, @@ -98,61 +149,11 @@ Maarten Sneep, % summary of c.t.t thread for outszwrng, inter alia James Szinger, % who responded on c.t.t to request for answer Ulrik Vieth, Mike Vulis, -Chris Walker, % revtex alert +Chris Walker, % revtex alert, ite suggestion (q-labelfig) Peter Wilson, % several, incl functionality of memoir Rick Zaccone and Reinhard Zierke. -\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 -\texttt{.zip} and \texttt{.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 \texttt{.zip} files on the archives, and won't fall -foul of the browser problem. Of course, if the \texttt{.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*{\TeX{}~Live distribution}{Q-CD} offers off-line snapshots of -the arhives. - -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% -\begin{footnoteenv} - `Full stop' (British English)==`period' (American English) -\end{footnoteenv} -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 - %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{The Background} @@ -173,11 +174,8 @@ first version of \TeX{} in 1978 to deal with revisions to his series Knuth produced a second version (in 1982) which is the basis of what we use today. -Knuth developed a system of -% beware line breaks -`\nothtml{literate programming' (}% beware line break -\Qref{literate programming}{Q-lit}\latexhtml{)}{'} -to write \TeX{}, +Knuth developed a system of % ! line breaks +`\Qref*{literate programming}{Q-lit}' to write \TeX{}, and he provides the literate (\acro{WEB}) source of \TeX{} free of charge, together with tools for processing the |web| source into something that can be compiled and something that can be printed; there's never @@ -201,18 +199,20 @@ they're programming in Plain \TeX{}. \Question[Q-TeXpronounce]{How should I pronounce ``\TeX{}''?} The `X' is ``really'' the Greek letter % ! line break -Chi\nothtml{ (\ensuremath{\chi}, in lower case)}, -and is pronounced by English-speakers either a bit like the `ch' in -the Scots word `loch' ([x] in the IPA) or like `k'. It definitely is -not pronounced `ks' (the Greek letter with that sound doesn't look -remotely like the Latin alphabet `X'). +Chi\nothtml{ (\ensuremath{\chi}, in lower case)}, and is pronounced by +English-speakers either a bit like the `ch' in the Scots word `loch' +([x] in the IPA) or (at a pinch, if you can't do the Greek sound) like +`k'. It definitely is not pronounced `ks' (the Greek letter with that +sound doesn't look remotely like the Latin alphabet `X'). This curious usage derives from Knuth's explanation in the \TeX{}book that the name comes from the Greek word for `art' or `craft' (`\latexhtml{\ensuremath{\tau\epsilon\chi\nu\eta}}{\emph{techni}}'), -which is the root of the English word `technology'; the logo \TeX{} is +which is the root of the English word `technology'. Knuth's logo for \TeX{} is merely the uppercase version of the first three (Greek) letters of the -word. +word, jiggled about a bit; we don't use that logo (and logos like it) +in this \acro{FAQ} (see % ! line break +\Qref[question]{Typesetting \TeX{}-related logos}{Q-logos}). \Question[Q-MF]{What is \MF{}?} @@ -294,7 +294,10 @@ pretty incomprehensible! Once an implementation of \TeX{} has passed its \texttt{trip} test, or an implementation of \MF{} has passed its \texttt{trap} test, then it may -reasonably be distributed as a working version. +in principe be distributed as a working version. (In practice, any +distributor would test new versions against ``real'' documents or +fonts, too; \texttt{trip} and \texttt{trap} don't actually test any +for real world problems. \Question[Q-y2k]{Are \TeX{} and friends Y2K compliant?} @@ -335,12 +338,7 @@ reasonably be distributed as a working version. system that is not itself Y2K compliant. \item[Macros:] \TeX{} macros can in principle perform calculations on the basis of the value of \csx{year}. -\begin{htmlversion} - The \Qref{LaTeX}{Q-latex} suite -\end{htmlversion} -\htmlignore - The \LaTeX{} suite (\Qref{}{Q-latex}) -\endhtmlignore + The \Qref*{LaTeX suite}{Q-latex} performs such calculations in a small number of places; the calculations performed in the current (supported) version of \LaTeX{} are known to be Y2K compliant. @@ -350,6 +348,77 @@ reasonably be distributed as a working version. needs to be individually checked. \end{description} +\Question[Q-etex]{What is \eTeX{}?} + +While Knuth has declared that \TeX{} will never % !line break +\Qref*{change in any substantial way}{Q-TeXfuture}, there remain +things that one might wish had been done differently, or indeed +implemented at all. + +The \acro{NTS} project set out to produce an advanced replacement for +\TeX{}, to provide a basis for developing such modifications: this +``New Typesetting System'' would share Knuth's aims, but would +implement the work in a modern way taking account of the lessons +learned with \TeX{}. While a first demonstrator \acro{NTS} did +appear, it wasn't practically useful, and the project seems no longer +active. + +In parallel with its work on \acro{NTS} itself, the project developed +a set of extensions that can be used with a (``true'') \TeX{} system. +Such a modified system is known as an \eTeX{} system, and the concept +has proved widely successful. Indeed, current \TeX{} distributions +are delivered with most formats built with an \eTeX{} system (for +those who don't want them, \eTeX{}'s extensions can be disabled, leaving +a functionally standard \TeX{} system). + +The extensions range from the simple (increasing the number of +available registers from 256 to 65536) through to extremely subtle +programming support. + +\Qref*{\CONTeXT{}}{Q-context} has required \eTeX{} for its operation +for some time. + +Some \LaTeX{} packages already specify the use of \eTeX{}. Some such +packages may not work at all on a non-\eTeX{} system; others will +work, but not as well as on an \eTeX{} system. The % ! line break +\Qref*{\LaTeX{} team}{Q-LaTeX3} has announced that future \LaTeX{} +packages (specifically those from the team, as opposed to those +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{}? + +\PDFTeX{} is a development of \TeX{} that is capable of generating +typeset \acro{PDF} output in place of \acro{DVI}. \PDFTeX{} has +other capabilities, most notably in the area of fine typographic +detail (for example, its support for % ! line break +\begin{wideversion} + \Qref{optimising line breaks}{Q-overfull}), +\end{wideversion} +\begin{narrowversion} + % ( <- dummy for paren balancing + optimising line breaks~--- \Qref{}{Q-overfull}), +\end{narrowversion} +but its greatest impact to date has been in the area of +\acro{PDF} output. + +\PDFTeX{} started as a topic for +\latexhtml{H\`an \The{} Th\`anh's}{Han The Thanh's} Master's~thesis, +and seems first to have been published in \TUGboat{} 18(4), in 1997 +(though it was certainly discussed at the \acro{TUG}'96 conference in +Russia). + +While the world was making good use of ``pre-releases'' of \PDFTeX{}, +Th\`anh used it as a test-bed for the micro-typography which was the +prime subject of his Ph.D. research. Since Th\`anh was finally +awarded his Ph.D., day-to-day maintenance and development of +\PDFTeX{}~1.0 (and later) has been in the hands of a group of +\PDFTeX{} maintainers (which includes Th\`anh); the group has managed +to maintain a stable platform for general use. \Question[Q-latex]{What is \LaTeX{}?} @@ -462,9 +531,9 @@ are provided, at present). \CONTeXT{} is well integrated, in all of its structure, with the needs of hypertext markup, and in particular with the -facilities offered by \Qref*{\PDFTeX{}}{Q-pdftex}. +facilities offered by \Qref*{\PDFTeX{}}{Q-whatpdftex}. The default installation employs a version of \PDFTeX{} built with the -\Qref*{\eTeX{} extensions}{Q-NTS}, which allows further flexibility. +\Qref*{\eTeX{} extensions}{Q-etex}, which allows further flexibility. \CONTeXT{} doesn't yet have quite such a large developer community as does \LaTeX{}, but those developers who are active seem to have @@ -506,12 +575,10 @@ its users to use \AMSLaTeX{} instead. \Question[Q-eplain]{What is \Eplain{}?} -The -\href{http://www.ccs.neu.edu/~dorai/eplain/index.html}{\Eplain{}} +The \href{http://tug.org/eplain}{\Eplain{}} macro package expands on and extends the definitions in Plain \TeX{}. \Eplain{} is not intended to provide ``generic typesetting -capabilities'', as do \LaTeX{} or % beware line break -\nothtml{Texinfo (}\Qref{Texinfo}{Q-texinfo}\nothtml{)}. Instead, it +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. @@ -526,13 +593,32 @@ 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. Karl Berry, the author of \Eplain{}, says -he is not aware of any generally available macro packages that do -not force their typographic style on an author, and yet provide -such capabilities. - -\Eplain{} documentation is % ! line break -\href{http://tug.org/docs/html/eplain}{available online}, and there's +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. + +Another useful feature of \Eplain{} is the ability to create PDF files +with hyperlinks. The cross-referencing macros can implicitly generate +hyperlinks for the cross-references, but you can also create explicit +hyperlinks, both internal (pointing to a destination within the +current document) and external (pointing to another local document or +a URL). + +Several \LaTeX{} packages provide capabilities which Plain \TeX{} +users are lacking, most notably text colouring and rotation provided by +the \Package{graphics} bundle (packages \Package{color} and +\Package{graphics}). Although the \Package{graphics} bundle provides +a Plain \TeX{} ``loader'' for some of the packages, it is not a +trivial job to pass options to those packages under Plain \TeX{}, and +much of the functionality of the packages is accessed through package +options. \Eplain{} extends the loader so that options can be passed +to the packages just as they are in \LaTeX{}. The following packages are +known to work with \Eplain{}: \Package{graphics}, \Package{graphicx}, +\Package{color}, \Package{autopict} (\LaTeX{} picture environment), +\Package{psfrag}, and \Package{url}. + +\href{http://tug.org/docs/html/eplain}{\Eplain{} documentation} is +available online, and there's also a mailing list~--- sign up, or browse the list archives, via \URL{http://tug.org/mailman/listinfo/tex-eplain} \begin{ctanrefs} @@ -543,7 +629,7 @@ also a mailing list~--- sign up, or browse the list archives, via Lollipop is a macro package written by Victor Eijkhout; it was used in the production of his book ``\emph{\TeX{} by Topic}'' (see -\Qref[question]{\AllTeX{} Tutorials}{Q-tutorials}). The manual says of +\Qref[question]{\AllTeX{} Tutorials}{Q-ol-books}). The manual says of it: \begin{quote} Lollipop is `\TeX{} made easy'. Lollipop is a macro package that @@ -579,17 +665,29 @@ Texinfo is a documentation system that uses one source file to produce both on-line information and printed output. So instead of writing two different documents, one for the on-line help and the other for a typeset manual, you need write only one document source file. When -the work is revised, you need only revise one document. You can read -the on-line information, known as an ``Info file'', with an Info -documentation-reading program. By convention, Texinfo source file -names end with a |.texi| or |.texinfo| extension. You can write and -format Texinfo files into Info files within \acro{GNU} +the work is revised, you need only revise one document. By +convention, Texinfo source file names end with a \texttt{.texi} or +\texttt{.texinfo} extension. + +Texinfo is a macro language, somewhat similar to \LaTeX{}, but with +slightly less expressive power. Its appearance is of course rather +similar to any \TeX{}-based macro language, except that its macros +start with \texttt{@} rather than the |\| that's more commonly used in +\TeX{} systems. + +You can write and format Texinfo files into Info files within \acro{GNU} \ProgName{emacs}, and read them using the \ProgName{emacs} Info reader. You can also format Texinfo files into Info files using \ProgName{makeinfo} and read them using \ProgName{info}, so you're not dependent on \ProgName{emacs}. The distribution includes a \ProgName{Perl} script, \ProgName{texi2html}, that will convert -Texinfo sources into \acro{HTML}. +Texinfo sources into \acro{HTML}: the language is a far better fit to +\acro{HTML} than is \LaTeX{}, so that the breast-beating agonies of +\Qref*{converting \LaTeX{} to \acro{HTML}}{Q-LaTeX2HTML} are largely +avoided. + +Finally, of course, you can also print the files, or convert them to +\acro{PDF} using \PDFTeX{}. \begin{ctanrefs} \item[\nothtml{\rmfamily}Texinfo distribution]\CTANref{texinfo} \end{ctanrefs} @@ -624,30 +722,43 @@ limit~\ensuremath{\pi} (at the time of writing, Knuth's latest release is versio 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.718.) +limit~\ensuremath{e}, and currently stands at 2.71828.) 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}). - There are projects (some of them long-term projects: see, for example, \Qref[question]{the LaTeX3 project}{Q-LaTeX3}) %\Qref[and]{and the SGML work}{Q-SGML}) to build substantial new macro packages based on \TeX{}. For the even longer term, there -are various projects to build a \emph{successor} to \TeX{}; see -\Qref[questions]{the Omega project}{Q-omega} and \Qref[]{NTS}{Q-NTS}. +are various projects to build a \emph{successor} to \TeX{}; see, for example, +the +\begin{wideversion} + \Qref{Omega/Aleph}{Q-omegaleph} and \Qref{\ExTeX{}}{Q-extex} + projects. +\end{wideversion} +\begin{narrowversion} + Omega/Aleph and \ExTeX{} projects (questions + \Qref[\nothtml]{}{Q-omegaleph} \Qref[and]{}{Q-extex}). +\end{narrowversion} \Question[Q-readtex]{Reading \AllTeX{} files} So you've been sent a \TeX{} file: what are you going to do with it? -Well, the good news is that \TeX{} systems are available, free, for -most sorts of computer; the bad news is that you need a pretty -complete \TeX{} system even to read a single file, and complete \TeX{} -systems are pretty large. + +You can, of course, ``just read it'', since it's a plain text file, +but the markup tags in the document may prove distracting. Most of +the time, even \TeX{} experts will typeset a \TeX{} file before +attempting to read it. + +So, you need to typeset the document. The good news is that \TeX{} +systems are available, free, for most sorts of computer; the bad news +is that you need a pretty complete \TeX{} system even to read a single +file, and complete \TeX{} systems are pretty large. \TeX{} is a typesetting system that arose from a publishing project (see \htmlonly{``}\Qref[question]{what is \TeX{}}{Q-whatTeX}\htmlonly{''}), @@ -828,13 +939,13 @@ 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]{\AllTeX{} tutorials}{Q-tutorials}) + \Qref[question]{online books}{Q-ol-books}) \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 Kathryn A.~Hargreaves (Addison-Wesley, 1990, \ISBN{0-201-51375-7}~--- now out of print, but see - \Qref[question]{\AllTeX{} tutorials}{Q-tutorials}) + \Qref[question]{online books}{Q-ol-books}) \item[\TeX{} in Practice]by Stephan von Bechtolsheim (Springer Verlag, 1993, 4 volumes, \ISBN{3-540-97296-X} for the set, or % nos in brackets are for German distribution (Springer Verlag, Berlin) @@ -896,6 +1007,10 @@ For \LaTeX{}, see: \checked{RF}{2001/01/16} %% gr\"atzer's home page %% http://www.maths.umanitoba.ca/homepages/gratzer.html/LaTeXBooks.html +\item[Digital Typography Using \LaTeX{}]Incorporating some + multilingual aspects, and use of \Qref*{Omega}{Q-omegaleph}, by + Apostolos Syropoulos, Antonis Tsolomitis and Nick Sofroniou + (Springer, 2003, \ISBN{0-387-95217-9}). A list of errata for the first printing is available from: \URL{http://www.springer-ny.com/catalog/np/jan99np/0-387-98708-8.html} @@ -935,7 +1050,7 @@ maintenance) is: \end{booklist} The book is decidedly dated, and is now out of print, but a copy is available via |sourceforge| and on \acro{CTAN}, -and we list it under ``\Qref*{tutorials}{Q-tutorials}''. +and we list it under ``\Qref*{online books}{Q-ol-books}''. This list only covers books in English: notices of new books, or @@ -964,7 +1079,7 @@ Of these, Bringhurst seems to be the one most often recommended. \item[The Form of the Book]by Jan Tschichold (Lund Humphries, 1991, \ISBN{0-85331-623-6}) \item[Type \& Layout]by Colin Wheildon - (Strathmore Press, 1995, \ISBN{0-9624891-5-8}) + (Strathmore Press, 2006, \ISBN{1-875750-22-3}) \item[The Design of Books]by Adrian Wilson (Chronicle Books, 1993, \ISBN{0-8118-0304-X}) \item[Optical Letter Spacing]by David Kindersley and Lida Cardozo Kindersley @@ -1008,7 +1123,6 @@ to be posted (nominally monthly) to newsgroup obsolete) last posted copy of that article is kept on \acro{CTAN} for auld lang syne. -\htmlignore \begin{pdfversion} A version of the \href{http://www.tex.ac.uk/faq}{present \acro{FAQ}} may be browsed via the World-Wide Web, and its sources @@ -1017,12 +1131,23 @@ may be browsed via the World-Wide Web, and its sources A version of the present \acro{FAQ} may be browsed via the World-Wide Web, at \acro{URL} \URL{http://www.tex.ac.uk/faq}, and its sources \end{dviversion} -\endhtmlignore \begin{htmlversion} The sources of the present \acro{FAQ} \end{htmlversion} are available from \acro{CTAN}. +This \acro{FAQ} and others are regularly mentioned, on +\Newsgroup{comp.text.tex} and elsewhere, in a ``pointer \acro{FAQ}'' +which is also saved at \URL{http://tug.org/tex-ptr-faq} + +A 2006 innovation from Scott Pakin is the ``visual'' \LaTeX{} \acro{FAQ}. +This is a document with (mostly rubbish) text formatted so as to +highlight things we discuss here, and providing Acrobat hyper-links to +the relevant answers in this \acro{FAQ} on the Web. The visual +\acro{FAQ} is provided in \acro{PDF} format, on \acro{CTAN}; it works +best using Adobe Acrobat Reader 7 (or later); some features are +missing with other readers, or with earlier versions of Acrobat Reader + Another excellent information source, available in English, is the \href{http://tex.loria.fr}{\AllTeX{} navigator}. @@ -1040,105 +1165,106 @@ The Open Directory Project (\acro{ODP}) maintains a list of sources of \AllTeX{} help, including \acro{FAQ}s. View the \TeX{} area at \URL{http://dmoz.org/Computers/Software/Typesetting/TeX/} -Other non-English \acro{FAQ}s are available: +Other non-English \acro{FAQ}s are available (off-\acro{CTAN}): \begin{booklist} \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]Posted regularly to \Newsgroup{fr.comp.text.tex}, and - archived on \acro{CTAN}. +\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[Czech]See \URL{http://www.fi.muni.cz/cstug/csfaq/} \end{booklist} + +Resources available on \acro{CTAN} are: \begin{ctanrefs} \item[\nothtml{\rmfamily}Dante \acro{FAQ}]\CTANref{dante-faq} \item[\nothtml{\rmfamily}French \acro{FAQ}]\CTANref{french-faq} \item[\nothtml{\rmfamily}Sources of this \acro{FAQ}]\CTANref{faq} \item[\nothtml{\rmfamily}Obsolete \texttt{comp.text.tex} \acro{FAQ}]% \CTANref{TeX-FAQ} +\item[\nothtml{\rmfamily}The visual \acro{FAQ}]\CTANref{visualFAQ} \end{ctanrefs} -\Question[Q-maillists]{Where to get help} +\Question[Q-gethelp]{How to get help} -First~\dots{} read any \acro{FAQ} you can find. (Which is what you're -doing now, isn't it?) - -An ambitious \acro{FAQ}-like project to collect all \TeX{}-related -information into one place is under way at -\URL{http://algaba.sdf-eu.org/TeEncontreX/TeEncontreX.html}; as with any -\acro{FAQ}, this project needs the support and help of all users~--- -as yet, it carries an incomplete set of answers to potential -questions. The sources of the package (including a complete set of -\texttt{html} files) are available on \acro{CTAN} - -The tutorials and other on-line documentation (see -\Qref[question]{\AllTeX{} Tutorials}{Q-tutorials}) can get you started but -for more in-depth understanding you should get and read at least one of the -many good books on the subject -(see \Qref[question]{\TeX{}-related books}{Q-books}). The definitive source for -\AllTeX{} is the source code itself, but that is not something to be -approached lightly (if at all). +So you've looked at all relevant \Qref*{\acro{FAQ}s}{Q-whereFAQ} you +can find, you've looked in any \Qref*{books}{Q-books} you have, and +scanned relevant \Qref*{tutorials}{Q-tutorials*}\dots{} and still you +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. - - If you have access to the internet, and in particular newsgroups, -then \AllTeX{} discussions, including \MF{} and \MP{}, are on -\Newsgroup{comp.text.tex}. -It is best to -spend a little time familiarising yourself with the current threads before -asking a question. The group is normally very responsive but asking a question -that has just been answered is likely to dampen people's enthusiasm to help -you. - -\URL{http://groups.google.com/} archives Usenet news discussions, and -\Newsgroup{comp.text.tex} may be found there. Google's archive now -goes impressively far back in time (before \Newsgroup{comp.text.tex} -even existed), and it is a powerful resource for tracking down that -recommendation that no-one can now remember. Google also allows -you to post your own questions or followups. - -The few people who can't use the World Wide Web, can't access Usenet -news, but can use electronic mail can seek help through mailing lists. - -The \TeX{}hax digest is nowadays operated as a -``\ProgName{MailMan}'' mailing list: its members now have the option -of receiving messages in `real time', and answers are more quickly -forthcoming than ever they were in the past. Subscribe via -\URL{http://www.tug.org/mailman/listinfo/texhax}; archives back to -April 2000 are available via the same link, and earlier -digests are available on \acro{CTAN}. - -Many mailing lists exist that cover some small part of the \TeX{} -arena. A good source of pointers is \URL{http://www.tug.org/} +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 +\begin{htmlversion} +``\href{http://www.tex.ac.uk/tex-archive/help/Catalogue/bytopic.html}{by topic}''. +\end{htmlversion} +\htmlignore +``by topic'' (see +\URL{http://www.tex.ac.uk/tex-archive/help/Catalogue/bytopic.html}). +\endhtmlignore +A catalogue entry has a description of the package, and links to any +documentation known on the net. \dots{} when the entry is up-to-date. + +Failing all that, look to see if anyone else has had the problem +before; there are two places where people ask: browse or search the +newsgroup \Newsgroup{comp.text.tex} via +\href{http://groups.google.com/group/comp.text.tex}{Google groups}, +and the mailing list \texttt{texhax} via its +\href{http://tug.org/pipermail/texhax/}{archive} + +If those ``back question'' searches fail, you'll have to ask the world +at large. To ask a question on \Newsgroup{comp.text.tex}, you can use +your own news client (if you have one), or use the ``start a new +topic'' button on \URL{http://groups.google.com/group/comp.text.tex}. +To ask a question on \texttt{texhax}, you may simply send mail to +\mailto{texhax@tug.org}, but it's probably better to subscribe to the +list (via \URL{http://tug.org/mailman/listinfo/texhax}) % ! no ~ on this line +first~--- not everyone will answer to you as well as to the list. + +\Question[Q-maillists*]{Specialist mailing lists} + +The previous question, ``\Qref*{getting help}{Q-gethelp}'', talked of +the two major forums in which \AllTeX{}, \MF{} and \MP{} are +discussed; however, these aren't the only ones available. + +The \acro{TUG} web site offers many mailing lists other than just +\texttt{texhax} via its % ! line break +\href{http://tug.org/mailman/listinfo}{mail list management page}. + +The French national \TeX{} user group, Gutenberg, offers a \MF{} (and, +de facto, \MP{}) mailing list, \mailto{metafont@ens.fr}: subscribe to +it by sending a message +\begin{quote} +\begin{verbatim} +subscribe metafont +\end{verbatim} +\end{quote} +to \mailto{sympa@ens.fr} + +Note that there's also a \MP{}-specific mailing list available via the +\acro{TUG} lists; in fact there's little danger of becoming confused +by subscribing to both. Announcements of \TeX{}-related installations on the \acro{CTAN} archives are sent to the mailing list \texttt{ctan-ann}. Subscribe to the list via its \ProgName{MailMan} web-site -\URL{https://sun.dante.de/mailman/listinfo/ctan-ann}; list archives +\URL{https://lists.dante.de/mailman/listinfo/ctan-ann}; list archives are available at the same address. The list archives may also be browsed via \URL{http://www.mail-archive.com/ctan-ann@dante.de/}, and an \acro{RSS} feed is also available: \URL{http://www.mail-archive.com/ctan-ann@dante.de/maillist.xml} -Issues related to \MF{} (and, increasingly, \MP{}) are discussed on -the \texttt{metafont} mailing list; subscribe by sending a message -`\texttt{subscribe metafont <\emph{your name}>}' to \mailto{listserv@ens.fr} - -A few other \TeX{}-related lists may be accessed via -\mailto{listserv@urz.uni-heidelberg.de}. Send a message containing -the line `\texttt{help}' to this address, or browse -\URL{http://listserv.uni-heidelberg.de/cgi-bin/wa} -\begin{ctanrefs} -\item[\nothtml{\rmfamily}TeEncontreX sources, etc.]\CTANref{teencontrex} -\item[\nothtml{\rmfamily}\TeX{}hax digests]Browse \CTANref{texhax} -\end{ctanrefs} - \Question[Q-askquestion]{How to ask a question} You want help from the community at large; you've decided where you're -going to \Qref*{ask your question}{Q-maillists}, but how do you +going to \Qref*{ask your question}{Q-gethelp}, but how do you phrase it? Excellent ``general'' advice (how to ask questions of anyone) is @@ -1199,7 +1325,8 @@ application of your own common sense. \Question[Q-minxampl]{How to make a ``minimum example''} \Qref[Question]{Our advice on asking questions}{Q-askquestion} -suggests that you prepare a ``minimum example'' of failing behaviour, +suggests that you prepare a ``minimum example'' (also commonly known +as a ``\emph{minimal} example'') of failing behaviour, as a sample to post with your question. If you have a problem in a two hundred page document, it may be unclear how to proceed from this problem to a succinct demonstration of your problem. @@ -1212,8 +1339,8 @@ The ``building up'' process starts with a basic document structure \cmdinvoke{begin}{document}, \cmdinvoke{end}{document}) and adds things. First to add is a paragraph or so around the actual point where the problem occurrs. (It may prove difficult to find the actual -line that's provoking the -problem. If the original problem is an error, reviewing % ! line break +line that's provoking the problem. If the original problem is an +error, reviewing % ! line break \Qref[question]{the structure of \TeX{} errors}{Q-errstruct} may help.) @@ -1235,13 +1362,14 @@ another package). The ``hacking down'' route starts with your entire document, and removes bits until the file no longer fails (and then of course restores the last thing removed). Don't forget to hack out any -unneccessary packages, but mostly, the difficulty is choosing what to +unnecessary packages, but mostly, the difficulty is choosing what to hack out of the body of the document; this is the mirror of the problem above, in the ``building up'' route. -If you've added a package (or more than one), run your minimum file -with \csx{listfiles} enabled, so as to report which versions of packages -you're using. +If you've added a package (or more than one), add \csx{listfiles} to +the preamble too: that way, \LaTeX{} will produce a list of the +packages you've used and their version numbers. This information may +be useful evidence for people trying to help you. What if your document simply doesn't fail in any of these cut-down scenarios? Whatever you do, don't post the whole of the document: if @@ -1270,23 +1398,60 @@ All things considered, a good example file can save you a day, for perhaps half an hour's effort invested. The above advice, differently phrased, may also be read on the web at -\URL{http://www.latex-einfuehrung.de/mini-en.html}; source of the +\URL{http://www.latex-einfuehrung.de/mini-en.html}; source of that article may be found at \URL{http://www.latex-einfuehrung.de/}, in both German and English. -\Question[Q-tutorials]{\AllTeX{} Tutorials, etc.} +\Question[Q-tutorials*]{\AllTeX{} Tutorials, etc.} -Some very fine tutorials have been written, over the years. Michael -Doob's splendid `Gentle Introduction' to Plain \TeX{} (available on -\acro{CTAN}) has been stable for a very long time. Another contender -in the same game is from one D. R.~Wilkins, available on the web at -\URL{http://www.ntg.nl/doc/wilkins/pllong.pdf} +From a situation where every \AllTeX{} user \emph{had} to buy a book +if she was not to find herself groping blindly along, we now have what +almost amounts to an embarrassment of riches of online documentation. +The following answers attempt to create lists of sources ``by topic''. + +First we have introductory manuals, for +\Qref*{Plain \TeX{}}{Q-man-tex} and \Qref*{\LaTeX{}}{Q-man-latex}. + +Next comes a selection of +\Qref*{``specialised'' \AllTeX{} tutorials}{Q-tutbitslatex}, +each of which concentrates on a single \LaTeX{} topic. + +A couple of reference documents (it would be good to have more) are +listed in an \Qref*{answer of their own}{Q-ref-doc}. + +Next comes the (rather new) field of % ! line break +\Qref*{\TeX{}-related WIKIs}{Q-doc-wiki}. + +A rather short list gives us a % ! line break +\Qref*{Typography style tutorial}{Q-typo-style}. + +Finally, we have a set of links to +\Qref*{Directories of \AllTeX{} information}{Q-doc-dirs}, and details +of some ``\Qref*{books}{Q-ol-books}'' that were once published +conventionally, but are now available on-line. + +\Question[Q-man-tex]{Online introductions: Plain \TeX{}} + +Michael Doob's splendid `Gentle Introduction' to Plain \TeX{} +(available on \acro{CTAN}) has been stable for a very long time. + +Another recommendable document is D. R.~Wilkins `Getting started with \TeX{}', +available on the web at \URL{http://www.ntg.nl/doc/wilkins/pllong.pdf} +\begin{ctanrefs} +\item[\nothtml{\rmfamily}Gentle Introduction]\CTANref{gentle} +\end{ctanrefs} + +\Question[Q-man-latex]{Online introductions: \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 -versions in the some of the many languages it has been translated -into. +translations into a rather large set of languages. + +Peter Flynn's ``Beginner's \LaTeX{}'' (which also started 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/}). Harvey Greenberg's `Simplified Introduction to \LaTeX{}' was written for a lecture course, and is also available on \acro{CTAN} (in \PS{} @@ -1300,43 +1465,89 @@ Its parent site, David Friggens' % ! line break \href{http://www.mcs.vuw.ac.nz/~david/latex/}{documentation page} is a useful collection of links in itself. -Peter Flynn's ``Beginner's \LaTeX{}'' (which also started 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/}). +% ! line break +\href{http://www.andy-roberts.net/misc/latex/}{Andy Roberts' introductory material} +is a pleasing short introduction to the use of \AllTeX{}; some of the +slides for \emph{actual} tutorials are to be found on the page, as +well. -T\acro{UG} India is developing a series of online \LaTeX{} tutorials -which can be strongly recommended: select single chapters at a time -from \URL{http://www.tug.org.in/tutorials.html}\nobreakspace--- the -set comprises two parts, ``Text'' and ``Graphics'', so far. +Chris Harrison's % ! line break +\href{http://www.chrisharrison.co.uk/xophbook/mybooks/tex/index.html}{TeX book} +presents basic \LaTeX{} with useful hints for extensions -\href{http://www.comp.leeds.ac.uk/andyr/misc/latex/index.html}{Andy Roberts' introductory material} -is a pleasing short introduction to the use of \AllTeX{}; some of the -slides for \emph{actual} tutorials are to be found on the page, as well. +Nicola Talbot's % ! line break +\href{http://theoval.cmp.uea.ac.uk/~nlct/latex/novices/novices.html}{\LaTeX{} for complete novices} +does what it claims: the author teaches \LaTeX{} at the University of +East Anglia. -Another item, not quite \acro{FAQ}, not quite tutorial, is Herbert -Vo\ss{}'s excellent % beware line break -\href{http://texnik.de/}{\LaTeX{} tips and tricks}. +Nicola Talbot also provides a set of % ! line break +\href{http://theoval.cmp.uea.ac.uk/~nlct/latex/}{introductory tutorials}, +which include exercises (with solutions). The page was developed as +an extension to the \LaTeX{} course Nicola teaches at the University +of East Anglia. An interesting (and practical) tutorial about what \emph{not} to do is \Package{l2tabu}, or ``A list of sins of \LaTeXe{} users'' by Mark Trettin, translated into English by J\"urgen Fenn. The 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}Not so Short Introduction]\CTANref{lshort} + (in English, you may browse for sources and other language versions at + \CTANref{lshort-parent}) +\item[\nothtml{\rmfamily}Simplified \LaTeX{}]\CTANref{simpl-latex} +% ! line break +\item[\nothtml{\rmfamily}The sins of \LaTeX{} users]\CTANref{l2tabuen}; + source also available: \CTANref{l2tabuen.src} +\end{ctanrefs} + +\Question[Q-tutbitslatex]{Specialised \AllTeX{} tutorials} 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 ``tips and tricks'' mentioned above and is -also available on \acro{CTAN}. +useful; it's 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} +Two documents written more than ten years apart about font usage in +\TeX{} are worth reading: % ! line breaks, next 3 lines +\href{href='http://www.tug.org/TUGboat/Articles/tb14-2/tb39rahtz-nfss.pdf}{Essential NFSS} +by Sebastian Rahtz, and +\href{http://tug.org/pracjourn/2006-1/schmidt/schmidt.pdf}{Font selection in LaTeX}, +cast in the form of an \acro{FAQ}, by Walter Schmidt. A general +compendium of font information (including the two above) may be found +on the \href{http://www.tug.org/fonts/}{TUG web site}. + +Peter Smith's +\begin{narrowversion} + ``\LaTeX{} for Logicians'' + (\URL{http://www.phil.cam.ac.uk/teaching_staff/Smith/LaTeX/}) +\end{narrowversion} +\begin{wideversion} + % ! line break + ``\href{http://www.phil.cam.ac.uk/teaching_staff/Smith/LaTeX/}{\LaTeX{} for Logicians}'' +\end{wideversion} +covers a rather smaller subject area, but is similarly comprehensive +(mostly by links to documents on relevant topics, rather than as a +monolithic document). + Keith Reckdahl's ``Using Imported Graphics in \LaTeXe{}'' is an -excellent introduction to graphics use, though it's slightly dated in -not discussing anything other than the \ProgName{dvips} route. -Available on \acro{CTAN}, but again without sources. +excellent introduction to graphics use. It's available on +\acro{CTAN}, but the sources aren't available (promised ``some time +soon''). + +Vincent Zoonekynd provides a set of excellent (and graphic) tutorials +on the programming of % !line breaks, ... +\href{http://zoonek.free.fr/LaTeX/LaTeX_samples_title/0.html}{title page styles}, +\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}. +In each file, there is a selection of graphics representing an output +style, and for each style, the code that produces it is shown. An invaluable step-by-step setup guide for establishing a ``work flow'' through your \AllTeX{} system, so that output appears at the @@ -1347,21 +1558,27 @@ supporting \LaTeX{} file together with correct output, both in \PS{} and \acro{PDF}, for each of \acro{A}4 and ``letter'' paper sizes. The complete kit is available on \acro{CTAN} (distributed with the author's macros for papers submitted for \acro{IEEE} publications). +The issues are also covered in a later % ! line break +\Qref{\acro{FAQ} answer}{Q-dvips-pdf}. -%% Reference material is somewhat more difficult to come by. A sterling -%% example is set by David Bausum's -%% \href{http://www.tug.org/utilities/plain/cseq.html}{list of \TeX{} primitives}. -For Plain~\TeX{} commands a rather nice % ! line break -\href{http://www.nmt.edu/tcc/help/pubs/texcrib.pdf}{quick reference booklet}, -by John W.~Shipman, is available. - -Special-purpose tutorials are always useful, and an example is set by +Documentation of Japanese \TeX{} use appears at least twice on the web: Haruhiko Okumura's page on -% beware line break +% ! line break \href{http://oku.edu.mie-u.ac.jp/~okumura/texfaq/japanese/}{typesetting Japanese with Omega} (the parent page is in Japanese, so out of the scope of this \acro{FAQ}). +One ``Tim'' documents p\TeX{} (a \TeX{} system widely used in Japan) +in his +\begin{narrowversion} + ``English notes on p\TeX{}'' (see + \url{http://www.users.waitrose.com/~nihilist/English_Notes_on_pTex.pdf}). +\end{narrowversion} +\begin{wideversion} + % ! line break + ``\href{http://www.users.waitrose.com/~nihilist/English_Notes_on_pTex.pdf}{English notes on p\TeX{}}''. +\end{wideversion} + Some university departments make their local documentation available on the web. Most straightforwardly, there's the simple translation of existing documentation into \acro{HTML}, for example the \acro{INFO} @@ -1374,51 +1591,62 @@ documenters who make public record of their \AllTeX{} support. For example, Tim Love (of Cambridge University Engineering Department) maintains his deparment's pages at -\URL{http://www-h.eng.cam.ac.uk/help/tpl/textprocessing/}, and Mimi -Burbank (of the School of Computer Science \& Information Technology -at the University of Florida) manages her department's at -\URL{http://www.csit.fsu.edu/~mimi/tex/}\nobreakspace--- both sets are fine -examples of good practice. - -%% Another summary by command (somewhat akin to David Basum's work for -%% Plain \TeX{}) is to be found at -%% \URL{http://www.giss.nasa.gov/latex/ltx-2.html}; sadly this stuff is -%% woefully out of date, and only covers \LaTeXo{}. - -People have long argued for \AllTeX{} books to be made available on -the web, and -Victor Eijkhout's excellent ``\TeX{} by Topic'' (previously published -by Addison-Wesley, but long out of print) was offered in this way at -Christmas 2001. The book is currently -available at \URL{http://www.eijkhout.net/tbt/}; -it's not a beginner's tutorial but it's a fine reference -(contributions are invited, and the book is well -worth the suggested contribution). +\URL{http://www-h.eng.cam.ac.uk/help/tpl/textprocessing/} +%% and Mimi +%% Burbank (of the School of Computer Science \& Information Technology +%% at the University of Florida) manages her department's at +%% \URL{http://www.csit.fsu.edu/~mimi/tex/}\nobreakspace--- both sets are fine +%% examples of good practice. +\begin{ctanrefs} +\item[\nothtml{\rmfamily}Graphics in \LaTeXe{}]the + document is available in \PS{} and \acro{PDF} formats as + \CTANref{epslatex_ps} and \CTANref{epslatex_pdf} respectively +\item[testflow]\CTANref{testflow} +\item[\nothtml{\rmfamily}Herbert Vo\ss{}'s Maths tutorial]\CTANref{voss-mathmode} +\end{ctanrefs} -Addison-Wesley have also released the copyright of ``\TeX{} for the -Impatient'' by Paul W.~Abrahams, Karl Berry and Kathryn A.~Hargreaves, -another book whose unavailability many have lamented. The authors -have re-released the book under the \acro{GNU} general documentation -licence, and it is available from \acro{CTAN}. +\Question[Q-ref-doc]{Reference documents} -Norm Walsh's ``Making \TeX{} Work'' is also available (free) on the -Web, at \URL{http://makingtexwork.sourceforge.net/mtw/}; the sources -of the Web page are on \acro{CTAN}. - -The book was an excellent resource in its day, but is now somewhat -dated; nevertheless, it still has its uses, and is a welcome addition -to the list of on-line resources. A project to update it is believed -to be under way. - -Jim Hefferon maintains a web page % ! line break -%\stopheretrue -``\href{http://www.ctan.org/installationadvice/}{Managing a one-person TeX system}'' -which provides a useful introduction to those who find they need to -manage a \TeX{} system on a personal machine. It covers much of the -matters discussed in answers such as % ! line break -\htmlonly{``}\Qref[number]{Where to put new files}{Q-wherefiles}\latexhtml{, below}{''}, -and thereby covers the gap left by the (possibly temporary) lack of -``\emph{Making \TeX{} work}''. +For \TeX{} primitive commands a rather nice % ! line break +\href{http://www.nmt.edu/tcc/help/pubs/texcrib.pdf}{quick reference booklet}, +by John W.~Shipman, is available; it's arranged in the same way as the +\TeX{}book. By contrast, you can view David Bausum's % ! line break +\href{http://www.tug.org/utilities/plain/cseq.html}{list of \TeX{} primitives} +alphabetically or arranged by ``family''. Either way, the list has a +link for each control sequence, that leads you to a detailed +description, which includes page references to the \TeX{}book. + +There doesn't seem to be a reference that takes in Plain \TeX{} as +well as the primitive commands. + +Similarly, there's no completely reliable command-organised reference +to \LaTeX{}, but the 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 +mirrors of the site, and it may be worth choosing a ``local'' one if +you're going to use it a lot. + +\Question[Q-doc-wiki]{WIKI pages for \TeX{} and friends} + +The \emph{WIKI} concept can be a boon to everyone, if used sensibly. +The ``general'' WIKI allows \emph{anyone} to add stuff, or to edit +stuff that someone else has added: while there is obvious potential +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. + +\Question[Q-typo-style]{Typography tutorials} There's also (at least one) typographic style tutorial available on the Web, the excellent % ! line break @@ -1432,20 +1660,53 @@ 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} + +\Question[Q-doc-dirs]{Directories of \AllTeX{} information} + +T\acro{UG} India is developing a series of online \LaTeX{} tutorials +which can be strongly recommended: select single chapters at a time +from \URL{http://www.tug.org.in/tutorials.html}\nobreakspace--- the +set comprises two parts, ``Text'' and ``Graphics'', so far. + +Herbert Vo\ss{}'s excellent % beware line break +\href{http://texnik.de/}{\LaTeX{} tips and tricks} is an excellent +source of small articles on the use of \LaTeX{}. + +\Question[Q-ol-books]{Freely available \AllTeX{} books} + +People have long argued for \AllTeX{} books to be made available on +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 currently available at +\URL{http://www.eijkhout.net/tbt/}; it's not a beginner's tutorial but +it's a fine reference. + +Addison-Wesley have also released the copyright of ``\TeX{} for the +Impatient'' by Paul W.~Abrahams, Karl Berry and Kathryn A.~Hargreaves, +another book whose unavailability many have lamented. The authors +have re-released the book under the \acro{GNU} general documentation +licence, and it is available from \acro{CTAN}. + +Norm Walsh's ``Making \TeX{} Work'' (originally published by O'Reilly) +is also available (free) on the Web, at +\URL{http://makingtexwork.sourceforge.net/mtw/}; the sources of the +Web page are on \acro{CTAN}. The book was an excellent resource in +its day, but while it is now somewhat dated, it still has its uses, +and is a welcome addition to the list of on-line resources. A project +to update it is believed to be under way. \begin{ctanrefs} -\item[\nothtml{\rmfamily}Beginner's \LaTeX{}]\CTANref{beginlatex-pdf} -\item[\nothtml{\rmfamily}Gentle Introduction]\CTANref{gentle} -\item[l2tabu]\CTANref{l2tabuen}; source also available: \CTANref{l2tabuen.src} -\item[\nothtml{\rmfamily}Graphics in \LaTeXe{}]\CTANref{epslatex}; the - document is also available in \PS{} format as \CTANref{epslatex_ps} \item[\nothtml{\rmfamily}Making \TeX{} Work]\CTANref{mtw} -\item[\nothtml{\rmfamily}Not so Short Introduction]\CTANref{lshort} - (in English, or browse for sources and other language versions at - \CTANref{lshort-parent}) -\item[\nothtml{\rmfamily}Simplified \LaTeX{}]\CTANref{simpl-latex} \item[\nothtml{\rmfamily}\TeX{} for the Impatient]\CTANref{TftI} -\item[testflow]\CTANref{testflow} -\item[\nothtml{\rmfamily}Herbert Vo\ss{}' Maths tutorial]\CTANref{voss-mathmode} \end{ctanrefs} \Question[Q-pkgdoc]{Documentation of packages} @@ -1535,7 +1796,7 @@ be found in `\LaTeXe{} for class and package writers' (\File{clsguide}, part of the \LaTeX{} documentation distribution). Beyond this, a good knowledge of \TeX{} itself is valuable: thus books such as the \Qref*{\TeX{}book}{Q-books} or % ! line break -\Qref*{\TeX{} by topic}{Q-tutorials} are relevant. With good \TeX{} +\Qref*{\TeX{} by topic}{Q-ol-books} are relevant. With good \TeX{} 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 @@ -1563,7 +1824,7 @@ technique may be seen in \Package{ltxguide.cls} Apart from Knuth's book, there seems to be only one publicly-available \href{http://metafont.tutorial.free.fr/}{tutorial for \MF{}}, by Christophe Grandsire (a copy in \acro{PDF} form may be downloaded). -Geoffrey Tobin's \textit{\MF{} for Beginners} % !! line break +Geoffrey Tobin's \textit{\MF{} for Beginners} % !! line break (see \Qref[question]{using \MF{}}{Q-useMF}) describes how the \MF{} system works and how to avoid some of the potential pitfalls. @@ -1578,16 +1839,22 @@ section describes how to use \MP{} illustrations in \LaTeX{} and fonts for any text or mathematics. Hans Hagen (of \CONTeXT{} fame) offers a \MP{} tutorial called -MetaFun (which admittedly concentrates on the use of \MP{} within \CONTeXT{}). It may be found on his company's +MetaFun (which admittedly concentrates on the use of \MP{} within +\CONTeXT{}). It may be found on his company's % ! line break \href{http://www.pragma-ade.com/metapost.htm}{\MP{} page}. -Other \MP{} tutorials that have appeared are one in English by % ! line breaks -\href{http://remote.science.uva.nl/~heck/Courses/mptut.pdf}{Andr\'e Heck}, +Other \MP{} tutorials that have appeared are two in English by % ! line breaks +\href{http://remote.science.uva.nl/~heck/Courses/mptut.pdf}{Andr\'e Heck} +and \href{http://www.tlhiv.org/MetaPost/tutorial/}{Urs Oswald}, and one in French (listed here because it's clearly enough written that this author understands it), by \href{http://pauillac.inria.fr/~cheno/metapost/metapost.pdf}{Laurent Ch\'eno}; both have been recommended for inclusion in the \acro{FAQ} +Urs Oswald's tutorial is accompanied by a super tool for testing +little bits of \MP{}, which is an invaluable aid to the learner: +\URL{http://www.tlhiv.org/cgi-bin/MetaPostPreviewer/index.cgi} + Vincent Zoonekynd's massive set of example \MP{} files is available on \acro{CTAN}; the set includes a \ProgName{Perl} script to convert the set to html, and the set may be % beware line break @@ -1598,8 +1865,8 @@ most certainly valuable learning material. Urs Oswald presents a 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-ps} - (\PS{}) or \CTANref{metafp-pdf} (\acro{PDF} format) +\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} @@ -1621,10 +1888,15 @@ for the four standard styles (|plain|, |abbrv|, |alpha|, |unsrt|). It also contains their documentation. The complete \BibTeX{} documentation set (including the files above) is available on \acro{CTAN}. + +A useful tutorial of the whole process of using \BibTeX{} is Nicolas +Markey's ``\emph{Tame the BeaST (The B to X of \BibTeX{})}'', which +may also be found on \acro{CTAN}. \begin{ctanrefs} \item[\nothtml{\rmfamily}\BibTeX{} documentation]\CTANref{bibtex-doc} \item[\nothtml{\rmfamily}\BibTeX{} documentation, in \acro{PDF}]% \CTANref{bibtex-doc-pdf} +\item[\nothtml{\rmfamily}Tame the BeaST]\CTANref{ttb-pdf} \end{ctanrefs} \Question[Q-symbols]{Where can I find the symbol for\,\dots{}} @@ -1674,7 +1946,7 @@ manual is \emph{not} available electronically. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\section{Bits and pieces of \TeX{}} +\section{Bits and pieces of \AllTeX{}} \Question[Q-dvi]{What is a \acro{DVI} file?} @@ -1719,9 +1991,9 @@ Font information may be held as bitmaps or as outlines, or simply as a set of pointers into the fonts that the printer itself `has'. Each driver will expect the font information in a particular form. For more information on the forms of fonts, -see \Qref[questions]{|pk| files}{Q-pk}, +see \Qref[questions]{\acro{PK} files}{Q-pk}, % beware of fill-paragraph here!!!! -\Qref[]{|tfm| files}{Q-tfm}, +\Qref[]{\acro{TFM} files}{Q-tfm}, \Qref[]{virtual fonts}{Q-virtualfonts} and \Qref[]{Using \PS{} fonts with \TeX{}}{Q-usepsfont}. @@ -1765,39 +2037,60 @@ printer driver. Virtual fonts for \TeX{} were first implemented by David Fuchs in the early days of \TeX{}, but for most people they date from when Knuth redefined the format, and wrote some support software, in 1989 (he -published an article in \textsl{TUGboat} at the time, and a copy is -available on \acro{CTAN}). +published an article in \textsl{TUGboat} at the time, and a plain text +copy is available on \acro{CTAN}). + Virtual fonts provide a way of telling \TeX{} about something more complicated than just a one-to-one character mapping. The entities you define in a virtual font look like characters to \TeX{} (they appear with their sizes in a font metric file), but the \acro{DVI} processor may -expand them to something quite different. You can use this facility -just to remap characters, to make a composite font with glyphs drawn -from several sources, or to build up an effect in arbitrarily -complicated ways~--- a virtual font may contain anything which is -legal in a \acro{DVI} file. A ``how to'', describing how to generate -virtual fonts from scratch, is available. - -In practice, however, the most common use of virtual fonts is to remap -\PS{} fonts (see \Qref[question]{font metrics}{Q-metrics}). Other -interesting uses have been to build `fake' maths fonts (by bundling -glyphs from several fonts together), and (utilising the facility to -use bits of \acro{DVI}) to build useful subsets of the \acro{T}1 fonts -using nothing but the \PS{} Type~1 versions of Knuth's Computer Modern fonts. - -It is important to realise that \TeX{} itself does \emph{not} see -virtual fonts; for every virtual font read by the \acro{DVI} driver there -is a corresponding \acro{TFM} file read by \TeX{}. Virtual fonts are normally -created in a single \acro{ASCII} \texttt{vpl} (Virtual Property List) -file, which -includes both sets of information. The \ProgName{vptovf} program is -then used to the create the binary \acro{TFM} and \acro{VF} files. The -commonest way (nowadays) of generating \texttt{vpl} files is to use the +expand them to something quite different. + +Specifically, \TeX{} itself only looks at a \acro{TFM} file that +contains details of how the virtual font will appear: but of course, +\TeX{} only cares about the metrics of a character, so its demands are +pretty small. The acro{DVI} processor, however, has to understand the +details of what is in the virtual font, so as to know ``what to draw, +where''. So, for every virtual font read by a \acro{DVI} driver, +there has to be a \acro{TFM} file to be read by \TeX{}. +(\PDFTeX{}, of course, needs both the \acro{TFM} and the +translation of the virtual font, since it does the whole job in the +one program.) + +You can use a virtual font: +\begin{itemize} +\item simply just to remap the glyphs of a single font, +\item to make a composite font with glyphs drawn from several + different onts, or +\item to build up an effect in arbitrarily complicated ways (since a + virtual font may contain anything which is legal in a \acro{DVI} + file). +\end{itemize} + +In practice, the most common use of virtual fonts is to remap +Adobe Type 1 fonts (see \Qref[question]{font metrics}{Q-metrics}), +though there has also been useful useful work building `fake' maths +fonts (by bundling glyphs from several fonts into a single virtual +font). Virtual Computer Modern fonts, making a % ! line break +\Qref*{Cork encoded}{Q-ECfonts} font from Knuth's originals by using +remapping and fragments of \acro{DVI} for single-glyph `accented +characters', were the first ``Type~1 format'' versions available. + +Virtual fonts are normally created in a single \acro{ASCII} +\acro{VPL} (Virtual Property List) file, which includes both sets of +information. The \ProgName{vptovf} program is then used to the create +the binary \acro{TFM} and \acro{VF} files. + +A ``how-to'' document, explaining how to generate a \acro{VPL}, +describes the endless hours of fun that may be had, doing the job by +hand. Despite the pleasures to be had of the manual method, the +commonest way (nowadays) of generating \acro{VPL} files is to use the \ProgName{fontinst} package, which is described in detail -\htmlonly{together with the discussion of}% +\htmlonly{together with the discussion of} \Qref[in answer]{\PS{} font metrics}{Q-metrics}. -\Package{qdtexvpl} is another utility for creating ad-hoc virtual -fonts. +\Package{Qdtexvpl} is another utility for creating ad-hoc virtual +fonts (it uses \TeX{} to parse a description of the virtual font, and +\ProgName{qdtexvpl} itself processes the resulting \acro{DVI} file). \begin{ctanrefs} \item[fontinst]\CTANref{fontinst} \item[\nothtml{\rmfamily}Knuth on virtual fonts]\CTANref{vf-knuth} @@ -1831,6 +2124,79 @@ commands in the em\TeX{} drivers (e.g., \ProgName{dvihplj}, \ProgName{dviscr}, commands in \ProgName{dvitoln03} that permit the page to be set in landscape orientation. +\Question[Q-hyphen]{How does hyphenation work in \TeX{}?} + +Everyone knows what hyphenation is: we see it in most books we read, +and (if we're alert) often spot ridiculous mis-hyphenation from time +to time (at one time, British newspapers were a fertile source). + +Hyphenation styles are culturally-determined, and the same language +may be hyphenated differently in different countries~--- for example, +British and American styles of hyphenation of English are very +different. As a result, a typesetting system that is not restricted +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 +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 +persuaded to think of as letters)~--- things such as \TeX{}'s +\csx{accent} primitive interrupt hyphenation. + +Sets of hyphenation patterns are usually derived from analysis of +a list of valid hyphenations (the process of derivation, using a tool +called \Package{patgen}, is not ordinarily a participatory sport). + +The patterns for the languages a \TeX{} system is going to deal with +may only be loaded when the system is installed. To change the set of +languages, a \Qref*{partial reinstallation}{Q-newlang} is necessary. + +\TeX{} provides two ``user-level'' commands for control of +hyphenation: \csx{language} (which selects a hyphenation style), and +\csx{hyphenation} (which gives explicit instructions to the hyphenation +engine, overriding the effect of the patterns). + +The ordinary \LaTeX{} user need not worry about \csx{language}, since +it is very thoroughly managed by the \Package{babel} package; use of +\csx{hyphenation} is discussed in +% beware line wrap +\Qref[question]{hyphenation failure}{Q-nohyph}. + +\Question[Q-clsvpkg]{What are \LaTeX{} classes and packages?} + +Current \LaTeX{} makes a distinction between the macros that define the +overall layout of a document, and the macros that tweak that layout +(to one extent or another) to provide what the author \emph{really} +wants. + +The distinction was not very clear in \LaTeXo{}, and after some +discussion (in the later stages of development of current \LaTeX{}) +the names ``class'' and ``package'' were applied to the two concepts. + +The idea is that a document's \emph{class} tells \LaTeX{} what sort of +document it's dealing with, while the \emph{packages} the document +loads ``refine'' that overall specification. + +On the disc, the files only appear different by virtue of their name +``extension''~--- class files are called \texttt{*.cls} while package +files are called \texttt{*.sty}. Thus we find that the \LaTeX{} +standard \Class{article} class is represented on disc by a file called +\File{article.cls}, while the \Package{footmisc} package (which +refines \Class{article}'s definition of footnotes) is represented on +disc by a file called \File{footmisc.sty}. + +The user defines the class of his document with the +\csx{documentclass} command (typically the first command in a +document), and loads packages with the \csx{usepackage} command. A +document may have several \csx{usepackage} commands, but it may have +only one \csx{documentclass} command. (Note that there are +programming-interface versions of both commands, since a class may +choose to load another class to refine its capabilities, and both +classes and packages may choose to load other packages.) + \Question[Q-dtx]{Documented \LaTeX{} sources (\texttt{.dtx} files)} \LaTeXe{}, and many support macro packages, are now written in a @@ -1922,7 +2288,7 @@ something regular. Nowadays, the operating system translates keystrokes into a code appropriate for the user's language: the encoding used is often a national or international standard, though many operating systems use ``code -pages'' defined by MicroSoft. These standards and code pages often +pages'' defined by Microsoft. These standards and code pages often contain characters that can't appear in the \TeX{} system's input stream. Somehow, these characters have to be dealt with~--- so an input character like ``\'e'' needs to be interpreted by \TeX{} in @@ -1970,58 +2336,16 @@ most font encodings can't match the corresponding input encoding nearly so well, and the two packages provide the sort of symmetry the \LaTeX{} system needs. -\Question[Q-hyphen]{How does hyphenation work in \TeX{}?} - -Everyone knows what hyphenation is: we see it in most books we read, -and (if we're alert) often spot ridiculous mis-hyphenation from time -to time (at one time, British newspapers were a fertile source). - -Hyphenation styles are culturally-determined, and the same language -may be hyphenated differently in different countries~--- for example, -British and American styles of hyphenation of English are very -different. As a result, a typesetting system that is not restricted -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 -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 -persuaded to think of as letters)~--- things such as \TeX{}'s -\csx{accent} primitive interrupt hyphenation. - -Sets of hyphenation patterns are usually derived from analysis of -a list of valid hyphenations (the process of derivation, using a tool -called \Package{patgen}, is not ordinarily a participatory sport). - -The patterns for the languages a \TeX{} system is going to deal with -may only be loaded when the system is installed. To change the set of -languages, a \Qref*{partial reinstallation}{Q-newlang} is necessary. - -\TeX{} provides two ``user-level'' commands for control of -hyphenation: \csx{language} (which selects a hyphenation style), and -\csx{hyphenation} (which gives explicit instructions to the hyphenation -engine, overriding the effect of the patterns). - -The ordinary \LaTeX{} user need not worry about \csx{language}, since -it is very thoroughly managed by the \Package{babel} package; use of -\csx{hyphenation} is discussed in -% beware line wrap -\Qref[question]{hyphenation failure}{Q-nohyph}. - \Question[Q-ECfonts]{What are the \acro{EC} fonts?} A font consists of a number of \emph{glyphs}. In order that the -glyphs may be printed, they are \nothtml{\emph{encoded} (see} -\Qref[question]{\emph{encoded}}{Q-whatenc}\nothtml{)}, and the -encoding is used as an index into tables within the font. For +glyphs may be printed, they are \Qref*{\emph{encoded}}{Q-whatenc}, and +the encoding is used as an index into tables within the font. For various reasons, Knuth chose deeply eccentric encodings for his -Computer Modern family of fonts; in -particular, he chose different encodings for different fonts, so that -the application using the fonts has to remember which font of the -family it's using before selecting a particular glyph. +Computer Modern family of fonts; in particular, he chose different +encodings for different fonts, so that the application using the fonts +has to remember which font of the family it's using before selecting a +particular glyph. When \TeX{} version 3 arrived, most of the excuses for the eccentricity of Knuth's encodings went away, and at \acro{TUG}'s Cork @@ -2050,16 +2374,26 @@ disadvantages for the casual user are their size (each \acro{EC} font is roughly twice the size of the corresponding \acro{CM} font), and there are far more of them than there are \acro{CM} fonts. The simple number of fonts has acted as a disincentive to the production of Adobe -Type~1 versions of the fonts,, but several commercial suppliers offer +Type~1 versions of the fonts, but several commercial suppliers offer \acro{EC} or \acro{EC}-equivalent fonts in type~1 or TrueType form~--- see % beware line fill -\Qref[question]{commercial suppliers}{Q-commercial}, and free -\htmlonly{\Qref{auto-traced versions}{Q-textrace}} are -available\nothtml{ (\Qref{ }{Q-textrace})}. -What's more, until corresponding fonts for mathematics are produced, -the \acro{CM} fonts must be retained because some mathematical symbols -are drawn from text fonts in the \acro{CM} encodings. +\Qref[question]{commercial suppliers}{Q-commercial}. Free +\Qref{auto-traced versions}{Q-textrace} (the \acro{CM}-super +and the \acro{LGC} fonts), and the Latin Modern series (rather +directly generated from \MF{} sources), are available. + +%% Unfortunately, until corresponding fonts for mathematics are produced, +%% the \acro{CM} fonts must be retained, since some mathematical symbols +%% are drawn from text fonts in the \acro{CM} encodings. +Note that the Cork encoding doesn't cover mathematics (and neither do +``\acro{T}1-encoded'' font families, of course). If you're using +Computer-Modern-alike fonts, this doesn't actually matter: your system +will have the original Computer Modern fonts, which cover `basic' +\TeX{} mathematics; more advanced mathematics are likely to need +separate fonts anyway. Suitable mathematics fonts for use with other +font families are discussed in % ! line break +``\Qref{choice of scalable fonts}{Q-psfchoice}''. The \acro{EC} fonts are distributed with a set of `Text Companion' (\acro{TC}) fonts that provide glyphs for @@ -2079,7 +2413,10 @@ for \PS{} fonts, and also by the \Package{txfonts} and % beware line wrap (see \Qref[question]{``choice of scalable fonts''}{Q-psfchoice}). \begin{ctanrefs} +\item[CM-super fonts]\CTANref{cm-super} +\item[CM-LGC fonts]\CTANref{cm-lgc} \item[EC and TC fonts]\CTANref{ec} +\item[Latin Modern fonts]\CTANref{lm} \end{ctanrefs} \Question[Q-tds]{What is the \acro{TDS}?} @@ -2118,7 +2455,7 @@ available on \acro{CTAN}. \item[\nothtml{\rmfamily}\acro{TDS} specification]\CTANref{tds} \end{ctanrefs} -\Question[Q-eps]{What is ``Encapsulated \PS{}''} +\Question[Q-eps]{What is ``Encapsulated \PS{}'' (``\acro{EPS}'')} \PS{} has over the years become a \emph{lingua franca} of powerful printers; since \PS{} is also a powerful graphical @@ -2148,7 +2485,7 @@ be used as figures in this way. The important features are: program may choose to ignore it. \end{itemize} A \PS{} figure that conforms to these rules is said to be in -``Encapsulated \PS{}'' format. Most \AllTeX{} packages for +``Encapsulated \PS{}'' (\acro{EPS}) format. Most \AllTeX{} packages for including \PS{} are structured to use Encapsulated \PS{}; which of course leads to much hilarity as exasperated \AllTeX{} users struggle to cope with the output of drawing software whose authors @@ -2442,10 +2779,10 @@ retrieve it without too much fuss. Otherwise, the \acro{CTAN} sites provide searching facilities, via the web. The simplest search, locating files by name, is to be found on the Dante \acro{CTAN} -at \URL{http://www.dante.de/cgi-bin/ctan-index}; the script returns -the same data as does \texttt{quote site index}, but not truncated and -arranged very neatly as a series of links to directories and -individual files. +at \URL{http://www.dante.de/cgi-bin/ctan-index}; the script scans a +list of files (\File{FILES.byname}~--- see below) and returns a list +of matches, arranged very neatly as a series of links to directories +and to individual files. The \href{http://www.tex.ac.uk/search}{\acro{UK}} and \href{http://www.ctan.org/search}{\acro{USA}} \acro{CTAN}s offer a @@ -2460,6 +2797,12 @@ search page that provides \acro{CTAN}. \end{itemize} +An alternative way to scan the catalogue is to use the catalogue's +% ! line break +\href{http://www.tex.ac.uk/tex-archive/help/Catalogue/bytopic.html}{``by topic'' index}; +this lists a series of topics, and \AllTeX{} projects that are worth +considering if you're working on matters related to the topic. + In fact, \ProgName{Google}, and other search engines, can be useful tools. Enter your search keywords, and you may pick up a package that the author hasn't bothered to submit to \acro{CTAN}. If you're using @@ -2473,8 +2816,8 @@ restriction using \ProgName{Google}'s ``advanced search'' mechanism; other search engines (presumably) have similar facilities. Many people avoid the need to go over the network at all, for their -searches, by downloading the file list that Dante's % ! line break -``\texttt{quote site index}'' command uses. This file, \File{FILES.byname}, +searches, by downloading the file list that the archives' web +file searches use. This file, \File{FILES.byname}, presents a unified listing of the archive (omitting directory names and cross-links). Its companion \File{FILES.last07days} is also useful, to keep an eye on the changes on the archive. Since these files are @@ -2515,7 +2858,7 @@ great convenience. The \TeX{}~Live distribution provides this, together with a ready-to-run \TeX{} system. The \TeX{}~Live installation disc offers -te\TeX{} for use on Unix-like systems, and fp\TeX{} for use on Windows +te\TeX{} for use on Unix-like systems, and Pro\TeX{}t for use on Windows systems. There is also a `demonstration' disc and an archive snapshot (all on \acro{CD}- or \acro{DVD}-\acro{ROM}s). \TeX{}-Live was originally developed under the auspices of a consortium of User @@ -2602,69 +2945,43 @@ see \Qref{}{Q-commercial} for details of commercial packages. \item[vtex]\CTANref{vtex-linux} \item[vtex \nothtml{\rmfamily}required common files]\CTANref{vtex-common} \end{ctanrefs} -\item[\acro{PC}; \MSDOS{} or \acro{OS/}2] Em\TeX{}, by Eberhard Mattes, - includes \LaTeX{}, \BibTeX{}, previewers, and drivers, and is - available as a series of zip archives. Documentation is - available in both German and English. Appropriate memory managers - for using em\TeX{} with 386 (and better) processors and under - Windows, are included in the distribution. Em\TeX{} will operate - under Windows, but Windows users are better advised to use a - distribution tailored for the Windows environment. - - A version of em\TeX{}, packaged to use a - % beware line break - \Qref*{TDS directory structure}{Q-tds}, is separately available as - an em\TeX{} `contribution'. Note that neither em\TeX{} itself, nor - em\TeX{}\acro{TDS}, is maintained. Most users of Microsoft - operating systems, who want an up-to-date \AllTeX{} system, need to - migrate to Win32-based systems. - \begin{ctanrefs} - \item[emtex]\CTANref{emtex} - \item[emtexTDS]\CTANref{emtextds} - \end{ctanrefs} -\item[\acro{PC}; \MSDOS{}] The most recent \MSDOS{} offering is a - port of the Web2C~7.0 implementation, using the \acro{GNU} - \ProgName{djgpp} compiler. While this package is more recent than - em\TeX{}, it still implements a rather old instance of \AllTeX{}. - \begin{ctanrefs} - \item[djgpp]\CTANref{djgpp} - \end{ctanrefs} -\item[\acro{PC}; \acro{OS/}2] \acro{OS/}2 may also use a free version of the - commercial \nothtml{V\TeX{} (see }% - \Qref[question]{V\TeX{}}{Q-commercial}\nothtml{)}, which specialises - in direct production of \acro{PDF} from \AllTeX{} input. - \begin{ctanrefs} - \item[vtex]\CTANref{vtex-os2} - \item[vtex \nothtml{\rmfamily}required common files]\CTANref{vtex-common} - \end{ctanrefs} \item[\acro{PC}: Win32] - fp\TeX{}, by Fabrice Popineau, is a version of te\TeX{} for Windows - systems. As such, it is particularly attractive to those who need - to switch back and forth between Windows and Unix environments, and - to administrators who need to maintain both (fp\TeX{} can use the - same \texttt{texmf} tree as a te\TeX{} installation). fp\TeX{}'s - previewer (\ProgName{Windvi}) is based on \ProgName{xdvi}, and takes - advantage of extra facilities in the Win32 environment. - \ProgName{Windvi} is capable of printing directly, and a version of - \ProgName{dvips} is also available. - - MiK\TeX{}, by Christian Schenk, is also a comprehensive + \miktex{}, by Christian Schenk, is also a comprehensive distribution, developed separately from the te\TeX{} work. 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 MiK\TeX{} developers provide a + on what you need to get going). The \miktex{} developers provide a ready-to-run copy of the distribution, on \CDROM{} (for purchase) via the - \href{http://www.miktex.org/cd/}{MiK\TeX{} web site}. + \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. \href{http://tug.org/protext/}{Pro\TeX{}t}, by Thomas Feuerstack, is - a further option for installing MiK\TeX{}. It bundles a MiK\TeX{} + a further option for installing \miktex{}. It bundles a \miktex{} setup with some further useful utilities, together with a \acro{PDF} file which contains clickable links for the various installation steps, along with explanations. It again it is freeware, and copies are distributed with the \Qref*{\TeX{}-live \acro{CD} set}{Q-CD}. + \href{https://xemtex.groups.foundry.supelec.fr/}{XEm\TeX{}}, by + Fabrice Popineau (he who created the excellent, but now defunct, + fp\TeX{} distribution), is an integrated distribution of \TeX{}, \LaTeX{}, + \CONTeXT{}, \ProgName{XEmacs} and friends for Windows. All programs + have been compiled natively to take the best advantage of the + Windows environment. Configuration is provided so that the + resulting set of programs runs out-of-the-box. + + The (Japanese) \acro{W}32\acro{TEX} distribution was motivated by + the needs of Japanese users (Japanese won't fit in a ``simple'' + character set like \acro{ASCII}, but \TeX{} is based on a version of + \acro{ASCII}). Despite its origins, \acro{W}32\acro{TEX} is said to + be a good bet for Western users, notably those whose disks are short + of space: the minimum documented download is as small as + 95\,MBytes. Investigate the distribution at + \URL{http://www.fsci.fuk.kindai.ac.jp/kakuto/win32-ptex/web2c75-e.html} + A further (free) option arises from the \href{http://www.cygwin.com}{``CygWin'' bundle}, which presents a Unix-like environment over the Win32 interface; an X-windows server @@ -2673,7 +2990,7 @@ see \Qref{}{Q-commercial} for details of commercial packages. run \ProgName{xdvi}). Of course, te\TeX{} components will look like Unix applications (but that's presumably what you wanted), but it's also reputedly somewhat slower than native Win32 implementations - such as MiK\TeX{} or fp\TeX{}. Te\TeX{} is available as part of the + such as \miktex{} or XEm\TeX{}. Te\TeX{} is available as part of the CygWin distribution (in the same way that a version is available with most Linux distributions, nowadays), and you may also build your own copy from the current sources. @@ -2684,16 +3001,52 @@ see \Qref{}{Q-commercial} for details of commercial packages. \TeX{}, which further the focus. \begin{ctanrefs} \item[bakoma]\CTANref{bakoma-tex} - \item[fptex]\CTANref{fptex} - \item[miktex]Acquire \CTANref{miktex-setup}, and read - \CTANref{miktex-install} + \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} \item[protext.exe]\CTANref{protext} \item[tetex]\CTANref{tetex} \end{ctanrefs} -\item[Windows \acro{NT}, other platforms] Ports of MiK\TeX{} for +\item[\acro{PC}: \MSDOS{} or \acro{OS/}2] Em\TeX{}, by Eberhard Mattes, + includes \LaTeX{}, \BibTeX{}, previewers, and drivers, and is + available as a series of zip archives. Documentation is + available in both German and English. Appropriate memory managers + for using em\TeX{} with 386 (and better) processors and under + Windows, are included in the distribution. Em\TeX{} will operate + under Windows, but Windows users are better advised to use a + distribution tailored for the Windows environment. + + A version of em\TeX{}, packaged to use a + % beware line break + \Qref*{TDS directory structure}{Q-tds}, is separately available as + an em\TeX{} `contribution'. Note that neither em\TeX{} itself, nor + em\TeX{}\acro{TDS}, is maintained. Most users of Microsoft + operating systems, who want an up-to-date \AllTeX{} system, need to + migrate to Win32-based systems. + \begin{ctanrefs} + \item[emtex]\CTANref{emtex} + \item[emtexTDS]\CTANref{emtextds} + \end{ctanrefs} +\item[\acro{PC}: \MSDOS{}] The most recent \MSDOS{} offering is a + port of the Web2C~7.0 implementation, using the \acro{GNU} + \ProgName{djgpp} compiler. While this package is more recent than + em\TeX{}, it still implements a rather old instance of \AllTeX{}. + \begin{ctanrefs} + \item[djgpp]\CTANref{djgpp} + \end{ctanrefs} +\item[\acro{PC}: \acro{OS/}2] \acro{OS/}2 may also use a free version of the + commercial \nothtml{V\TeX{} (see }% + \Qref[question]{V\TeX{}}{Q-commercial}\nothtml{)}, which specialises + in direct production of \acro{PDF} from \AllTeX{} input. + \begin{ctanrefs} + \item[vtex]\CTANref{vtex-os2} + \item[vtex \nothtml{\rmfamily}required common files]\CTANref{vtex-common} + \end{ctanrefs} +\item[Windows \acro{NT}, other platforms] Ports of \miktex{} for \acro{NT} on Power \acro{PC} and \acro{AXP} are available. Neither version has been updated for version~1.2 (or later) of - MiK\TeX{}~--- they may not be satisfactory. + \miktex{}~--- they may not be satisfactory. \begin{ctanrefs} \item[miktex for AXP]\CTANref{miktex-AXP} \item[miktex for Power PC]\CTANref{miktexppc} @@ -2704,15 +3057,16 @@ see \Qref{}{Q-commercial} for details of commercial packages. % It should run on any Macintosh Plus, SE, II, or newer model, but % will not work on a 128K or 512K Mac - \acro{UK}~\acro{TUG} prepays the shareware fee, so that its members may + \acro{UK}~\acro{TUG} prepays the shareware fee for its members, so + that they may acquire the software without further payment. Questions about Oz\TeX{} may be directed to \mailto{oztex@midway.uchicago.edu} Another partly shareware program is \acro{CM}ac\TeX{}, put together by Tom Kiffe. This is much closer to the Unix \TeX{} setup (it uses \ProgName{dvips}, for instance). - \acro{CM}ac\TeX{} includes a port of the latest version of - \nothtml{Omega (}\Qref{Omega}{Q-omega}\nothtml{)}. + \acro{CM}ac\TeX{} includes a port of a version of + \Qref*{Omega}{Q-omegaleph}. Both Oz\TeX{} and \acro{CM}ac\TeX{} run on either Mac\acro{OS} \acro{X} or on a sufficiently recent Mac\acro{OS} with CarbonLib @@ -2726,6 +3080,14 @@ see \Qref{}{Q-commercial} for details of commercial packages. \href{http://www.uoregon.edu/~koch/texshop/texshop.html}{TeXShop}, which is an integrated \TeX{} editor and previewer. + From its 2005 release, the \Qref*{\TeX{}-Live disc set}{Q-CD} + includes ``Mac\TeX{}'', a \CDROM{} image that contains + Mac\acro{OS}~\acro{X} te\TeX{} (the Gerben Wierda set mentioned + above), TeXshop, and \Qref*{XeTeX}{Q-xetex}. Details (and a + downloadable distribution set) may be found on the + \href{http://tug.org/mactex}{\acro{TUG} web site}; the distribution + is also on \acro{CTAN}. + \begin{narrowversion} % really, non-hyper version A useful resource for Mac users is to be found at \URL{http://www.esm.psu.edu/mac-tex/}; it has a news and `help' @@ -2739,6 +3101,7 @@ see \Qref{}{Q-commercial} for details of commercial packages. \end{wideversion} \begin{ctanrefs} \item[cmactex]\CTANref{cmactex} + \item[mactex]\CTANref{mactex} \item[oztex]\CTANref{oztex} \item[MacOS X teTeX]\URL{ftp://ftp.nluug.nl/pub/comp/macosx/tex-gs/} \item[TeXShop]\URL{http://darkwing.uoregon.edu/~koch/texshop/texshop.html} @@ -2812,7 +3175,7 @@ personal selection: The \ProgName{Kile} editor that is provided with the \acro{KDE} window manager provides \acro{GUI} ``shell-like'' facilities, in a - similar way to the the widely-praised \ProgName{Winedt} (see below); + similar way to the widely-praised \ProgName{Winedt} (see below); details (and downloads) are available from the project's \href{http://kile.sourceforge.net/}{home on SourceForge}. A newer system (by \ProgName{Kile}'s original author), @@ -3002,8 +3365,9 @@ also have email, and normal telephone and fax support. Note that the company \YandY{} has gone out of business, and \YandY{} \TeX{} (and support for it) is therefore no longer available. Users of \YandY{} systems may care to use the self-help -\href*{http://lists.ucc.ie/lists/archives/yandytex.html}{mailing list} -that was established in 2003. +\href*{http://tug.org/pipermail/yandytex/}{mailing list} +that was established in 2003; the remaining usable content of +\YandY{}'s web site is available at \URL{http://www.tug.org/yandy/} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -3015,24 +3379,17 @@ The best public domain \acro{DVI} to \PS{} conversion program, which runs under many operating systems, is Tom Rokicki's \ProgName{dvips}. \ProgName{dvips} is written in \acro{C} and ports easily. All current development is in the context of Karl Berry's \ProgName{kpathsea} -library, and sources are available from the \TeX{}~live repository. +library, and sources are available from the \TeX{}~live repository, +and versions are available in all \TeX{} distributions that recognise +the use of \PS{}. An \acro{VMS} versions is available as part of the \acro{CTAN} distribution of \TeX{} for \acro{VMS}. A precompiled version to work with em\TeX{} is available on \acro{CTAN}. - -%Another good portable program is \ProgName{dvitops} by James Clark, -%which is also written in C and will compile under Unix, \MSDOS{}, \acro{VMS}, -%and Primos; however, it does not support virtual fonts. It is -%available from -%\CTANref{dvitops} - -Macintosh users can use either the excellent drivers built into Oz\TeX{} -or Textures, or a port of \ProgName{dvips} in the \acro{CM}ac\TeX{} -package. \begin{ctanrefs} -\item[\nothtml{\rmfamily}\MSDOS{} and \nothtml{\acro}{OS/}2]\CTANref{dvips-pc} +\item[\nothtml{\rmfamily}\MSDOS{} and \latexhtml{\acro{OS/}}{OS/}2]% + \CTANref{dvips-pc} \item[\nothtml{\rmfamily}VMS distribution]\CTANref{OpenVMSTeX} \end{ctanrefs} @@ -3064,24 +3421,23 @@ through \PS{}, and \ProgName{ghostscript} is \emph{so} good, and has \emph{such} a wide range of printer drivers (perhaps this is where the \acro{DVI} output driver writers have all gone?). -The general advice, then, is to \nothtml{generate \PS{} (}% -\Qref{generate \PS{}}{Q-dvips}\nothtml{)}, and to process -that with \ProgName{ghostscript} set to generate the format for the -printer you actually have. If you are using a Unix system of some -sort, it's generally quite easy to insert \ProgName{ghostscript} into -the print spooling process. +The general advice, then, is to \Qref*{generate \PS{}}{Q-dvips}, and +to process that with \ProgName{ghostscript} set to generate the format +for the printer you actually have. If you are using a Unix system of +some sort, it's generally quite easy to insert \ProgName{ghostscript} +into the print spooling process. \begin{ctanrefs} \item[ghostscript]Browse \CTANref{ghostscript} \end{ctanrefs} \Question[Q-previewers]{\acro{DVI} previewers} -Em\TeX{} for \acro{PC}s running \MSDOS{} or \acro{OS/}2, MiK\TeX{} and -fp\TeX{} for \acro{PC}s running Windows and Oz\TeX{} for the Macintosh, all +Em\TeX{} for \acro{PC}s running \MSDOS{} or \acro{OS/}2, \miktex{} and +XEm\TeX{} for \acro{PC}s running Windows and Oz\TeX{} for the Macintosh, all come with previewers that can be used on those platforms. Em\TeX{}'s previewer can also be run under Windows~3.1. -Commercial \acro{PC} \TeX{} packages (see +Commercial \acro{PC} \TeX{} packages (see % ! line break \Qref[question]{commercial vendors}{Q-commercial}) have good previewers for \acro{PC}s running Windows, or for Macintoshes. @@ -3366,7 +3722,7 @@ is written in \acro{ANSI} \acro{C}). \section{Format conversions} -\Question[Q-toascii]{Conversion from \AllTeX{} to plain \acro{ASCII}} +\Question[Q-toascii]{Conversion from \AllTeX{} to plain text} The aim here is to emulate the Unix \ProgName{nroff}, which formats text as best it can for the screen, from the same @@ -3376,13 +3732,17 @@ Converting \acro{DVI} to plain text is the basis of many of these techniques; sometimes the simple conversion provides a good enough response. Options are: \begin{itemize} -\item \ProgName{dvi2tty} (one of the earliest) -\item \ProgName{crudetype} -\item \ProgName{catdvi}, which is also capable of generating Latin-1 - or \acro{UTF}-8 encoded output. \ProgName{Catdvi} was conceived as - a replacement for \ProgName{dvi2tty}, but can't (quite) be - recommended as a complete replacement yet. +\item \ProgName{dvi2tty} (one of the earliest), +\item \ProgName{crudetype} and +\item \ProgName{catdvi}, which is capable of generating Latin-1 + (ISO~8859-1) or \acro{UTF}-8 encoded output. \ProgName{Catdvi} was + conceived as a replacement for \ProgName{dvi2tty}, but can't (quite) + be recommended as a complete replacement yet. \end{itemize} +A common problem is the hyphenation that \TeX{} inserts when +typesetting something: since the output is inevitably viewed using +fonts that don't match the original, the hyphenation usually looks +silly. Ralph Droms provides a \Package{txt} bundle of things in support of \acro{ASCII} generation, @@ -3466,20 +3826,17 @@ translator: \href{http://www.perl.com/CPAN/modules/by-module/SGMLS}{\ProgName{sgmlspm}}, written in \ProgName{Perl} 5. \end{wideversion} -%or |home.sprynet.com/sprynet/dmeggins/SGMLSpm-1.03ii.tar.gz| -%was |www.uottawa.ca/~dmeggins/SGMLSpm/sgmlspm.html| \item \begin{narrowversion} % really non-hyper - Joachim Schrod and Christine Detig's \ProgName{stil}, written - in Common Lisp, which is available from - \URL{ftp://ftp.th-darmstadt.de/pub/text/sgml/stil} + Joachim Schrod and Christine Detig's \ProgName{STIL} + (`\acro{SGML} Transformations in Lisp'), which is available from + \URL{ftp://ftp.tu-darmstadt.de/pub/text/sgml/stil} \end{narrowversion} \begin{wideversion} Joachim Schrod and Christine Detig's - \href{ftp://ftp.th-darmstadt.de/pub/text/sgml/stil}{\ProgName{stil}}, - written in Common Lisp. + \href{ftp://ftp.tu-darmstadt.de/pub/text/sgml/stil}{\ProgName{STIL}}, + (`\acro{SGML} Transformations in Lisp'). \end{wideversion} -% checked RF 2001/03/19 \end{itemize} Both of these allow the user to write `handlers' for every \acro{SGML} element, with plenty of access to attributes, entities, and @@ -3546,13 +3903,13 @@ For today, possible packages are: A mailing list for users may be found via \URL{http://tug.org/mailman/listinfo/latex2html} \item[\ProgName{TtH}]a compiled program that supports either \LaTeX{} - or plain \TeX{}, and uses the font/table technique for representing + or Plain \TeX{}, and uses the font/table technique for representing mathematics. It is written by Ian Hutchinson, using \ProgName{flex}. The distribution consists of a single \acro{C} source (or a compiled executable), which is easy to install and very fast-running. \item[\ProgName{Tex4ht}]a compiled program that supports either - \LaTeX{} or plain \TeX{}, by processing a \acro{DVI} file; it uses + \LaTeX{} or Plain \TeX{}, by processing a \acro{DVI} file; it uses bitmaps for mathematics, but can also use other technologies where appropriate. Written by Eitan Gurari, it parses the \acro{DVI} file generated when you run \AllTeX{} over your file with @@ -3589,16 +3946,14 @@ The World Wide Web Consortium maintains a list of ``filters'' to \Question[Q-fmtconv]{Other conversions to and from \AllTeX{}} \begin{description} -\item[troff]\ProgName{troff-to-latex}, written by Kamal Al-Yahya at Stanford - University (California, \acro{USA}), assists in the translation of a - \ProgName{troff} document into \LaTeX{} format. It recognises most +\item[troff]\ProgName{Tr2latex}, assists in the translation of a + \ProgName{troff} document into \LaTeXo{} format. It recognises most |-ms| and |-man| macros, plus most \ProgName{eqn} and some \ProgName{tbl} preprocessor commands. Anything fancier needs to be done by hand. Two style files are provided. There is also a man page - (which converts very well to \LaTeX{}\dots{}). The program is - copyrighted but free. - \ProgName{tr2latex} is an enhanced version of this - \ProgName{troff-to-latex}. + (which converts very well to \LaTeX{}\dots{}). + \ProgName{Tr2latex} is an enhanced version of the earlier + \ProgName{troff-to-latex} (which is no longer available). % The \acro{DECUS} \TeX{} distribution (see % \Qref[question]{sources of software}{Q-archives}) @@ -3682,7 +4037,6 @@ translated to or from this one. \ProgName{FrameMaker} provides \item[rtf2tex]\CTANref{rtf2tex} \item[tex2rtf]\CTANref{tex2rtf} \item[tr2latex]\CTANref{tr2latex} -\item[troff-to-latex]\CTANref{troff-to-latex} \item[wd2latex]\CTANref{wd2latex} \item[wp2latex]\CTANref{wp2latex} \item[\nothtml{\rmfamily}Word processor \acro{FAQ} (source)]% @@ -3782,7 +4136,7 @@ beyond the provisions of Plain \TeX{}, which the document uses. The first step in installing a new package for your \LaTeX{} system is usually to \Qref*{find where it is}{Q-findfiles} -and then to get it, usually from \acro{CTAN}. However MiK\TeX{}, +and then to get it, usually from \acro{CTAN}. However \miktex{}, since version 2.1, offers a \Qref*{simpler procedure}{Q-miktexinst} than that described here, for packages it knows about. @@ -3794,7 +4148,7 @@ single files, which are supposedly complete in themselves. A small package \meta{smallpack} might be just a single \texttt{.sty} file (typically \File{smallpack.sty}) with the usage instructions either -included as comments in the file or in a seperate user manual or +included as comments in the file or in a separate user manual or \File{README} file. More often a package \meta{pack} will come as a pair of files, \File{pack.ins} and \File{pack.dtx}, written to be used with the \LaTeX{} \Package{doc} system. The package code must be @@ -3813,14 +4167,16 @@ unpack a \Package{doc} package \meta{pack}, do the following: manual and possibly a commented version of the package code. \item Run latex again on \Package{pack.dtx}, which should resolve any references and generate a Table of Contents if it was called for. -\item \LaTeX{} may have said ``|No file pack.ind|''; this is the +\item \LaTeX{} may have said ``\texttt{No file pack.ind}''; this is the source for the command index; if you want the index, process the raw - material with:\\ - | makeindex -s gind.ist pack|\\ + material with: + \begin{quote} + \texttt{makeindex -s gind.ist pack} + \end{quote} and run \LaTeX{} again. \item Print and read \File{pack.dvi} \end{itemize} -Sometimes a user manual is supplied seperately from the \File{.dtx} +Sometimes a user manual is supplied separately from the \File{.dtx} file. Process this \emph{after} doing the above, just in case the user manual uses the package it is describing. @@ -3844,18 +4200,11 @@ for this purpose. \texttt{texhash} \item[web2c] On a current \Package{web2c} distribution, \texttt{texhash} ought to work; if it doesn't, run \texttt{mktexlsr} - \item[fp\TeX{}] Click - \texttt{Start}\arrowhyph{}% - \texttt{Programs}\arrowhyph{}% - \texttt{Texlive}\arrowhyph{}% - \texttt{Maintenance}\arrowhyph{}% - \texttt{Rebuild ls-R filenames databases}, or open a ``command'' - window and run \texttt{texhash} -\item[MiK\TeX{}] On a \Package{MikTeX} distribution earlier than v2.0, +\item[\miktex{}] On a \Package{\miktex{}} distribution earlier than v2.0, click \texttt{Start}\arrowhyph{}% \texttt{Programs}\arrowhyph{}% - \texttt{MikTeX}\arrowhyph{}% + \texttt{\miktex{}}\arrowhyph{}% \texttt{Maintenance}\arrowhyph{}% \texttt{Refresh filename database} % this sequence confirmed ok for miktex 1.20, 2000/09/14, by Michael @@ -3864,14 +4213,14 @@ for this purpose. or get a DOS window and run:\\ \texttt{initexmf -\relax-update-fndb} - On a \Package{MikTeX} distribution v2.0 or later, do:\\ + On a \Package{\miktex{}} distribution v2.0 or later, do:\\ \texttt{Start}\arrowhyph{}% \texttt{Programs}\arrowhyph{}% - \texttt{MikTeX 2}\arrowhyph{}% - \texttt{MikTeX Options}, and press the + \texttt{\miktex{} 2}\arrowhyph{}% + \texttt{\miktex{} Options}, and press the % beware line break \texttt{Refresh now} button (\texttt{Update filename database} in - earlier versions of MiK\TeX{}). + earlier versions of \miktex{}). \end{description} Remember that a |\usepackage{pack}| command must be put in the preamble @@ -3882,7 +4231,7 @@ of each document in which you want to use the \Package{pack} package. Where precisely you put files that you have downloaded does depend on what \TeX{} distribution you have. However, assuming that you have one of the modern \acro{TDS}-compliant -distributions (such as te\TeX{}, fp\TeX{} or mik\TeX{}) there are +distributions (such as te\TeX{} or \miktex{}) there are some general rules that you can follow: % we're sort-of emulating an enumerated list here, but avoiding the @@ -3898,7 +4247,7 @@ tree. The root directory will be named something like: teTeX: /usr/share/texmf-local/ or /usr/local/share/texmf/ fpTeX: c:\Programs\TeXLive\texmf-local\ - mikTeX: c:\localtexmf\ + MiKTeX: c:\localtexmf\ \end{verbatim} (In fact, a te\TeX{} system can be asked to tell you what its local root is; on a Unix system, the command to use is: @@ -3927,9 +4276,10 @@ should go: .afm: $TEXMF/fonts/afm/<supplier>/<font>/ .pfb: $TEXMF/fonts/type1/<supplier>/<font>/ .ttf: $TEXMF/fonts/truetype/<supplier>/<font>/ +.pool, .fmt, .base or .mem: $TEXMF/web2c \end{verbatim} -and for modern systems (te\TeX{}~3.0, and the like, using \acro{TDS} -v1.1 format): +and for modern systems (distributed in 2005 or later, such as +te\TeX{}~3.0, using \acro{TDS} v1.1 layouts): \begin{verbatim} .map: $TEXMF/fonts/map/<syntax>/<bundle>/ .enc: $TEXMF/fonts/enc/<syntax>/<bundle>/ @@ -3962,37 +4312,47 @@ packages as part of the documentation building process; this is a hang-over from the pre-\LaTeXe{} predecessor of the package documentation process. -\Question[Q-miktexinst]{Installing MiK\TeX{} ``known packages''} +\Question[Q-miktexinst]{Installing \miktex{} ``known packages''} -MiK\TeX{} 2.1 (and later) maintains a database of packages it ``knows about'', +\miktex{} 2.1 (and later) maintains a database of packages it ``knows about'', together with (coded) installation instructions that enable it to install the packages with minimal user intervention. -If MiK\TeX{} does know about a package you need installed, it's worth +If \miktex{} does know about a package you need installed, it's worth using the system. -First, open the MiK\TeX{} packages window: click on +First, open the \miktex{} packages window: click on \texttt{Start}\arrowhyph{}% \texttt{Programs}\arrowhyph{}% - \texttt{MikTeX}\arrowhyph{}% - \texttt{MikTeX Options}, and select the + \texttt{\miktex{}}\arrowhyph{}% + \texttt{\miktex{} Options}, and select the \texttt{Packages} tab. On the tab, there is an Explorer-style display of packages. -Right-click on the root of the tree, ``\texttt{MikTeX Packages}'', +Right-click on the root of the tree, ``\texttt{\miktex{} Packages}'', and select ``\texttt{Search}'': enter the name of the package you're interested in, and press the ``\texttt{Search}'' button. If -MiK\TeX{} knows about your package, it will open up the tree to show +\miktex{} knows about your package, it will open up the tree to show you a tick box for your package: check that box. -If MiK\TeX{} \emph{doesn't} know about the package you're interested +If you prefer a command-line utility, there's \ProgName{mpm}. Open a +command shell, and type: +\begin{quote} +\begin{verbatim} +mpm --install=<package> +\end{verbatim} +\end{quote} +(which of course assumes you know the name by which \miktex{} refers to +your package). + +If \miktex{} \emph{doesn't} know about the package you're interested in, you have to use the \Qref*{long-winded procedure}{Q-instpackages} outlined elsewhere in this \acro{FAQ}. If necessary, repeat to select other packages, and then press -``\texttt{OK}''; MiK\TeX{} tells you how many packages you have +``\texttt{OK}''; \miktex{} tells you how many packages you have selected~--- if you're happy, press ``\texttt{OK}'' again. -MiK\TeX{} will go off, download the package (as a +\miktex{} will go off, download the package (as a \texttt{.cab} file), if necessary, install the files of the package, and then refresh the filename database so that the files will be found. @@ -4380,28 +4740,30 @@ it may be separated into a modest set of stages. default: if the files are not available, you are unlikely to be able to use the font with \AllTeX{}. \item Rename the \acro{AFM} files and the Type~1 files to match the - \latexhtml{``Berry font naming scheme'' (}{``}% beware line wraps - \Qref{Berry font naming scheme}{Q-fontname}\latexhtml{)}{''}. + \Qref*{Berry font naming scheme}{Q-fontname}. \item Generate \TeX{} metric files from the \acro{AFM} files. The commonest tool for this task is \Package{fontinst}; the package documentation helps, but other guides are available (see below). The simplest possible script to pass to \Package{fontinst} is: \begin{quote} - |\latinfamily{xyz}{}|\\ - |\bye| +\begin{verbatim} +\latinfamily{xyz}{} +\bye +\end{verbatim} \end{quote} where \texttt{xyz} is the Berry name of the font family. This simple script is adequate for most purposes: its output covers the - font family in both |T1| and |OT1| font encodings. Nevertheless, + font family in both \acro{T}1 and \acro{OT}1 font encodings. Nevertheless, with fancier fonts, more elaborate things are possible with \Package{fontinst}: see the documentation for details. \Package{Fontinst} also generates map files, and \LaTeX{} font - definition (|.fd|) files. + definition (\texttt{.fd}) files. \item Install the files, in your \texttt{texmf} tree. All the strictures about installing non-standard things apply here: be sure - to put the files in the local tree. Reasonable destinations for the - various files are: + to put the files in the local tree. The list gives reasonable + destinations for the various files related to a font whose Berry + name is \meta{bname}: \begin{narrowversion} \begin{verbatim} .pfb, @@ -4410,7 +4772,6 @@ it may be separated into a modest set of stages. .vf .../fonts/vf/<foundry>/<bname> .fd .../tex/latex/fontinst/ \ <foundry>/<bname> -.map .../dvips/fontinst/<foundry> \end{verbatim} {% \small Note: the split line is only to fit into the column: in @@ -4424,9 +4785,17 @@ it may be separated into a modest set of stages. .tfm .../fonts/tfm/<foundry>/<bname> .vf .../fonts/vf/<foundry>/<bname> .fd .../tex/latex/fontinst/<foundry>/<bname> -.map .../dvips/fontinst/<foundry> \end{verbatim} \end{wideversion} + The irregular things being \texttt{.map} files: in te\TeX{} 3.0 and + later, these should be placed according to the revised \acro{TDS} as +\begin{verbatim} +.map .../fonts/map/dvips/<foundry> +\end{verbatim} +and in other (earlier) systems as +\begin{verbatim} +.map .../dvips/fontinst/<foundry> +\end{verbatim} \item Regenerate the file indexes (as described in \Qref[question]{package installation}{Q-instpackages}). \item Update the \ProgName{dvips} and other maps: @@ -4439,12 +4808,12 @@ it may be separated into a modest set of stages. \begin{verbatim} updmap --enable Map <xyz>.map \end{verbatim} - \item On a MiK\TeX{} system earlier than version~2.2, the ``Refresh + \item On a \miktex{} system earlier than version~2.2, the ``Refresh filename database'' operation, which you performed after installing files, also updates the system's ``\PS{} resources database''. - \item On a MiK\TeX{} system, version~2.2 or later, update - \File{updmap.cfg} which is described in MiK\TeX{} % beware line break - \href{http://www.miktex.org/manual/psfonts.html}{online documentation}. + \item On a \miktex{} system, version~2.2 or later, update + \File{updmap.cfg} which is described in \miktex{} % beware line break + \href{http://docs.miktex.org/manual/psfonts.html#chgupdmapcfg}{online documentation}. Then execute the command \texttt{initexmf -\relax-mkmaps}, and the job is done. \end{itemize} @@ -4713,7 +5082,7 @@ roman, sans-serif and typewriter fonts; \emph{e.g}., the \FontName{Roman} as the main text font (and introduces mechanisms to typeset mathematics using \FontName{Times} and various more-or-less matching fonts), while package \Package{avant} changes the sans-serif -family to \FontName{AvantGarde}, and \Package{Courier} changes the +family to \FontName{AvantGarde}, and \Package{courier} changes the typewriter font to \FontName{Courier}. To go with these packages, you need the font metric files and font description (\File{.fd}) files for each font family you @@ -5058,25 +5427,32 @@ commercially, include: For further details (including samples) see\\ \URL{http://www.micropress-inc.com/fonts/ifmath/ifmain.htm} \nothtml{\par\egroup} -%% \item[Lucida Bright \emph{with} Lucida New Math](25 fonts) Chuck Bigelow and -%% Kris Holmes\\ -%% Lucida is a family of related fonts including seriffed, sans serif, -%% sans serif fixed width, calligraphic, blackletter, fax, Kris Holmes' -%% connected handwriting font, \emph{etc}; they're not as `spindly' as -%% Computer Modern, with a large x-height, and include a larger set of -%% maths symbols, operators, relations and delimiters than \acro{CM} -%% (over 800 instead of 384: among others, it also includes the -%% \acro{AMS} |msam| and |msbm| symbol sets). `Lucida Bright Expert' -%% (14 fonts) adds seriffed fixed width, another handwriting font, -%% smallcaps, bold maths, upright `maths italic', \emph{etc}., to the -%% set. The distribution includes support for use with Plain \TeX{} -%% and \LaTeXo{}. Support under \LaTeXe{} is provided in -%% \Qref*{\acro{PSNFSS}}{Q-usepsfont} -%% thanks to Sebastian Rahtz and David Carlisle. -%% \par -%% \nothtml{\bgroup\raggedwithindent} -%% For a sample, see \URL{http://www.YandY.com/download/chironlb.pdf} -%% \nothtml{\par\egroup} +\item[Lucida Bright \emph{with} Lucida New Math](25 fonts) Chuck Bigelow and + Kris Holmes\\ + Lucida is a family of related fonts including seriffed, sans serif, + sans serif fixed width, calligraphic, blackletter, fax, Kris Holmes' + connected handwriting font, \emph{etc}; they're not as `spindly' as + Computer Modern, with a large x-height, and include a larger set of + maths symbols, operators, relations and delimiters than \acro{CM} + (over 800 instead of 384: among others, it also includes the + \acro{AMS} \texttt{msam} and \texttt{msbm} symbol sets). `Lucida + Bright Expert' + (14 fonts) adds seriffed fixed width, another handwriting font, + smallcaps, bold maths, upright `maths italic', \emph{etc}., to the + set. Support under \LaTeX{} is available under the auspices of the + \acro{PSNFSS}, and pre-built metrics are also provided. + + \nothtml{\bgroup\raggedwithindent} + \acro{TUG} has recently (November 2005) acquired the right to distribute + these fonts; the web site +\begin{narrowversion} + \href{http://tug.org/lucida/}{``Lucida and TUG''} +\end{narrowversion} +\begin{wideversion} + ``\href{http://tug.org/lucida/}{Lucida and TUG}'' +\end{wideversion} + has details. + \nothtml{\par\egroup} \item[Adobe Lucida, LucidaSans \emph{and} LucidaMath](12 fonts)\\ Lucida and LucidaMath are generally considered to be a bit heavy. The three maths fonts contain only the glyphs in the \acro{CM} maths @@ -5272,6 +5648,8 @@ print file (\PS{} or \acro{PDF}) for their output device. \item[hfbright \nothtml{\normalfont}collection]\CTANref{hfbright} \item[hvmath \nothtml{\normalfont\itshape}(free bitmapped version)]% \CTANref{hvmath} +\item[Lucida Bright/Math metrics]\CTANref{lucida} +\item[Lucida PSNFSS support]\CTANref{lucida-psnfss} \item[MathDesign \nothtml{\normalfont}collection]\CTANref{mathdesign} \item[pxfonts]\CTANref{pxfonts} \item[tmmath \nothtml{\normalfont\itshape}(free bitmapped version)]% @@ -5300,6 +5678,100 @@ suppress the implicit switch in the pseudo-printer file. The problem has been corrected in \ProgName{dvips} v~5.90 (and later versions), which should be available in any recent \TeX{} distribution. +\subsection{Macros for using fonts} + +\Question[Q-fonts-pln]{Using non-standard fonts in Plain \TeX{}} + +Plain \TeX{} (in accordance with its description) doesn't do anything +fancy with fonts: it sets up the fonts that Knuth found he needed when +writing the package, and leaves you to do the rest. + +To use something other than Knuth's default, the default mechanism is +to use the \csx{font} primitive: +\begin{quote} +\begin{verbatim} +\font\foo=nonstdfont +... +\foo +Text set using nonstdfont ... +\end{verbatim} +\end{quote} +The name you use (\texttt{nonstdfont}, above) is the name of the +\texttt{.tfm} file for the font you want. + +If you want to use an italic version of \csx{foo}, you need to use +\csx{font} again: +\begin{quote} +\begin{verbatim} +\font\fooi=nonstdfont-italic +... +\fooi +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 +have appeared recently simply don't come in versions using Knuth's +eccentric font encodings~--- but those encodings are built into Plain +\TeX{}, so that some macros of Plain \TeX{} need to be changed to use +the fonts. \LaTeX{} gets around all these problems by using a ``font +selection scheme''~--- this `\acro{NFSS}' (`\acro{N}' for `new', as +opposed to what \LaTeXo{} had) carries around with it separate +information about the fonts you use, so the changes to +encoding-specific commands happen automagically. + +If you only want to use the \Qref*{\acro{EC} fonts}{Q-ECfonts}, you +can in principle use the \Package{ec-plain} bundle, which gives you a version +of Plain \TeX{} which you can run in the same way that you run +Plain \TeX{} using the original \acro{CM} fonts, by invoking +\ProgName{tex}. (\Package{Ec-plain} also extends the \acro{EC} fonts, +for reasons which aren't immediately clear, but which might cause +problems if you're hoping to use Type 1 versions of the fonts.) + +The \Package{font_selection} package provides a sort of halfway house: +it provides font face and size, but not family selection. This gives +you considerable freedom, but leaves you stuck with the original +\acro{CM} fonts. It's a compact solution, within its restrictions. + +Other Plain \TeX{} approaches to the problem (packages +\Package{plnfss}, \Package{fontch} and \Package{ofs}) break out of the +Plain \TeX{} model, towards the sort of font selection provided by +\CONTeXT{} and \LaTeX{}~--- font selection that allows you to change +family, as well as size and face. The remaining packages all make +provision for using encodings other than Knuth's \acro{OT}1. + +\Package{Plnfss} has a rather basic set of font family details; +however, it is capable of using font description (\texttt{.fd}) files +created for \LaTeX{}. (This is useful, since most modern mechanisms +for integrating outline fonts with \TeX{} generate \texttt{.fd} files +in their process.) + +\Package{Fontch} has special provision for \acro{T}1 and \acro{TS}1 +encodings, which you select by arcane commands, such as: +\begin{quote} +\begin{verbatim} +\let\LMTone\relax +\input fontch.tex +\end{verbatim} +\end{quote} +for \acro{T}1. + +\Package{Ofs} seems to be the most thoroughly thought-through of the +alternatives, and can select more than one encoding: as well as +\acro{T}1 it covers the encoding \acro{IL}2, which is favoured in the +Czech Republic and Slovakia. \Package{Ofs} also covers mathematical fonts, +allowing you the dubious pleasure of using fonts such as the % ! line break +\Qref*{\FontName{pxfonts} and \FontName{txfonts}}{Q-psfchoice}. +\begin{ctanrefs} +\item[ec-plain]\CTANref{ec-plain} +\item[fontch]\CTANref{fontch} +\item[font_selection]\CTANref{font_selection} +\item[ofs]\CTANref{ofs} +\item[plnfss]\CTANref{plnfss} +\end{ctanrefs} + \subsection{Particular font families} \Question[Q-concrete]{Using the ``Concrete'' fonts} @@ -5349,12 +5821,10 @@ add \end{quote} to the preamble of your document. -Type~1 versions of the fonts are available. For the OT1 encoding, -they are available from \nothtml{MicroPress (}% beware line break -\Qref{MicroPress}{Q-psfchoice}\nothtml{)}. The -\nothtml{CM-Super fonts (}% beware line break -\Qref{CM-Super fonts}{Q-textrace}\nothtml{)} contain Type~1 versions -of the Concrete fonts in the T1 encoding. +Type~1 versions of the fonts are available. For \acro{OT}1 encoding, +they are available from \Qref*{MicroPress}{Q-psfchoice}. The +\Qref*{CM-Super fonts}{Q-textrace} contain Type~1 versions +of the Concrete fonts in \acro{T}1 encoding. \begin{ctanrefs} \item[beton.sty]\CTANref{beton} \item[ccfonts.sty]\CTANref{ccfonts} @@ -5379,7 +5849,7 @@ fill in the requirements: the job is really not terribly difficult. Note that te\TeX{} distributions, from version~3.0, already have the \Package{lm} fonts: all you need do is use them. The fonts may also -be installed via the package manager, in a current MiK\TeX{} system. +be installed via the package manager, in a current \miktex{} system. The remainder of this answer, then, is for people who don't use such systems. @@ -5404,12 +5874,12 @@ Type~1-to-\acro{PK} conversion programs, by \begin{verbatim} updmap --enable Map lm.map \end{verbatim} -\item On a MiK\TeX{} system earlier than version~2.2, the ``Refresh +\item On a \miktex{} system earlier than version~2.2, the ``Refresh filename database'' operation, which you performed after installing files, also updates the system's ``\PS{} resources database''. -\item On a MiK\TeX{} system, version~2.2 or later, update - \File{updmap.cfg} as described in the MiK\TeX{} % beware line break - \href{http://www.miktex.org/manual/psfonts.html}{online documentation}. +\item On a \miktex{} system, version~2.2 or later, update + \File{updmap.cfg} as described in the \miktex{} % beware line break + \href{http://docs.miktex.org/manual/psfonts.html#chgupdmapcfg}{online documentation}. Then execute the command \texttt{initexmf -\relax-mkmaps}, and the job is done. \end{itemize} @@ -5484,15 +5954,15 @@ modified \ProgName{xdvi} and (recent releases of) \ProgName{dvips}. Output from the latter may be used in recent releases of \ProgName{ghostscript} or Acrobat Distiller. -\Question[Q-acrobat]{Making Acrobat documents from \LaTeX{}} +\Question[Q-acrobat]{Making Acrobat \acro{PDF} documents from \AllTeX{}} There are three general routes to Acrobat output: Adobe's original `distillation' route (via \PS{} output), conversion of a \acro{DVI} file, and the use of a direct \acro{PDF} generator such as -\PDFTeX{} (see \Qref[question]{the \PDFTeX{} project}{Q-pdftex}) or -MicroPress's V\TeX{} (see % beware line breaks -\Qref[questions]{commercial \TeX{} implementations}{Q-commercial} -and \Qref[\htmlonly]{`free' \TeX{} implementations)}{Q-TeXsystems}). +\PDFTeX{} (see \Qref[question]{\PDFTeX{}}{Q-whatpdftex}) or +MicroPress's V\TeX{} (which comes both as a % ! line break +\Qref*{commercial version}{Q-commercial} for Windows PCs, and as a +\Qref*{`free' version)}{Q-TeXsystems} for Linux systems). For simple documents (with no hyper-references), you can either \begin{itemize} @@ -5517,8 +5987,8 @@ links, you need a \LaTeX{} package to suitably redefine the internal commands. There are two of these for \LaTeX{}, both capable of conforming to the Hyper\TeX{} specification (see \Qref[question]{Making hypertext documents from \TeX{}}{Q-hyper}): -Sebastian Rahtz's \Package{hyperref}, and Michael Mehlich's -\Package{hyper}. \Package{Hyperref} +Heiko Oberdiek's \Package{hyperref}, and Michael Mehlich's +\Package{hyper}. uses a configuration file to determine how it will generate hypertext; it can operate using \PDFTeX{} primitives, the hyper\TeX{} \csx{special}s, or \acro{DVI} driver-specific \csx{special} commands. @@ -5528,9 +5998,18 @@ translates the \acro{DVI} with these \csx{special} commands into \PS{} acceptable to Distiller, and \ProgName{dvipdfm} has \csx{special} commands of its own. +(In practice, almost everyone uses \Package{hyperref}; \Package{hyper} +hasn't been updated since 2000.) + +If you use Plain \TeX{}, \Eplain{} macro package can help you create +Acrobat documents with hyper-references (see +\htmlonly{``}\Qref[question]{what is \Eplain{}}{Q-eplain}\htmlonly{''}). +It can operate using \PDFTeX{} primitives, or \csx{special} commands +for the \ProgName{dvipdfm} \acro{DVI} driver. + There is no free implementation of all of \ProgName{Adobe} \ProgName{Distiller}'s -functionality, but recent versions of \ProgName{ghostscript} +functionality, any but the very oldest versions of \ProgName{ghostscript} provide pretty reliable distillation (but beware of the problems discussed in % beware line break @@ -5586,25 +6065,30 @@ Issues covered are: \item \nothtml{\ProgName{ghostscript} too old (}% \Qref{\ProgName{ghostscript} too old}{Q-fuzzy-gs}\nothtml{)}, which can also result in fuzzy text. -\item \nothtml{Switching to font encoding T1 (}% - \Qref{Switching to font encoding T1}{Q-fuzzy-T1}\nothtml{)}, which +\item \Qref*{Switching to font encoding \acro{T}1}{Q-fuzzy-T1}, which is yet another possible cause of fuzzy text. \item Another problem~--- missing characters~--- arises from an % beware line breaks - \nothtml{aged version of \ProgName{Adobe}~\ProgName{Distiller} (}% - \Qref{aged version of \ProgName{Adobe}~\ProgName{Distiller}}{Q-distill-prob}\nothtml{)}. + \Qref*{aged version of \ProgName{Adobe}~\ProgName{Distiller}}{Q-distill-prob}. \item Finally, there's the common confusion that arises from using the - \ProgName{dvips} configuration file \texttt{-Ppdf}, the - \nothtml{weird characters (}% - \Qref{weird characters}{Q-charshift}\nothtml{)}. + \ProgName{dvips} configuration file \texttt{-Ppdf}, the % ! line br + \Qref*{weird characters}{Q-charshift}. \end{itemize} It should be noted that \ProgName{Adobe} % \ProgName{Acrobat} no longer % part of the name -\ProgName{Reader}~6 (released in mid-2003) does not exhibit the -``fuzziness'' that so many of the answers below address. This is of -course good news: however, it will inevitably be a long time before -every user in the world has this (or later) versions, so the remedies -below are going to remain for some time to come. +\ProgName{Reader}~6 (released in mid-2003, and later versions) does +not exhibit the ``fuzziness'' that so many of the answers below +address. This is of course good news: however, it will inevitably be +a long time before every user in the world has this (or later) +versions, so the remedies below are going to remain for some time to +come. + +The problems are also discussed, with practical examples, in Mike +Shell's \Package{testflow} package, which these FAQs recommend as a +``\Qref*{specialised tutorial}{Q-tutbitslatex}. +\begin{ctanrefs} +\item[testflow]\CTANref{testflow} +\end{ctanrefs} \Question[Q-fuzzy-type3]{The wrong type of fonts in \acro{PDF}} \keywords{crippled blurry} @@ -5707,7 +6191,7 @@ should be at least version~6.50, of course, but it's usually good policy to go to the most recent version (version~8.12 at the time of writing~--- 2003). -\Question[Q-fuzzy-T1]{Fonts go fuzzy when you switch to T1} +\Question[Q-fuzzy-T1]{Fonts go fuzzy when you switch to \acro{T}1} \keywords{crippled blurry} You've been having problems with hyphenation, and someone has @@ -5724,21 +6208,22 @@ your previous setup using Type~1 versions of the \acro{CM} fonts, and \ProgName{dvips} has inserted Type~3 versions of the \acro{EC} fonts into your document output. (See % beware line break \htmlonly{``}\Qref[question]{Adobe font types}{Q-adobetypen}\htmlonly{''} -for details of these font types; also, note that the font \emph{encoding}~T1 -has nothing directly to do with the font \emph{type}~Type~1). +for details of these font types; also, note that the font +\emph{encoding}~\acro{T}1 +has nothing directly to do with the font \emph{format}~Type~1). However, as noted in % beware line break \htmlonly{``}\Qref[question]{8-bit Type~1 fonts}{Q-type1T1}\htmlonly{''}, -Type~1 versions of \acro{CM}-like fonts in T1 (or equivalent) encoding +Type~1 versions of \acro{CM}-like fonts in \acro{T}1 (or equivalent) encoding are now available, both as ``real'' fonts, and as virtual font sets. One solution, therefore, is to use one of these alternatives. The alternative is to switch font family altogether, to something like \FontName{Times} (as a no-thought default) or one of the many more pleasing Adobe-encoded fonts. The default action of \Package{fontinst}, when -creating metrics for such a font, is to create settings for both OT1 -and T1 encodings, so there's little change in what goes on (at the -user level) even if you have switched to T1~encoding when using the +creating metrics for such a font, is to create settings for both \acro{OT}1 +and \acro{T}1 encodings, so there's little change in what goes on (at the +user level) even if you have switched to \acro{T}1~encoding when using the fonts. \Question[Q-distill-prob]{Characters missing from \acro{PDF} output} @@ -5850,9 +6335,10 @@ fonts~--- the \Package{ae} (``almost \acro{EC}'') and \Package{zefonts} sets; the \Package{zefonts} set has wider coverage (though the \Package{ae} set may be extended to offer guillemets by use of the \Package{aeguill} package). Neither offers characters such -as |eth| and |thorn| (used in, for example, in Icelandic), but the -\Package{aecompl} package works with the \Package{ae} fonts to provide -the missing characters from the \acro{EC} fonts (i.e., as bitmaps). +as \texttt{eth} and \texttt{thorn} (used in, for example, in +Icelandic), but the \Package{aecompl} package works with the +\Package{ae} fonts to provide the missing characters from the +\acro{EC} fonts (i.e., as bitmaps). The sole remaining commercial \acro{CM}-like 8-bit font comes from Micropress, who offer the complete \acro{EC} set @@ -5960,6 +6446,40 @@ will happen in this case, regardless of the options. \item[hyperref.sty]\CTANref{hyperref} \end{ctanrefs} +\Question[Q-srchpdf]{Searching \acro{PDF} files} + +In principle, you can search a \acro{PDF} file: the text of the file +is available to the viewer, and at least some viewers provide a search +facility. (It's not the fastest thing in the world, but it does help +in some circumstances.) + +However, there is a problem: the viewer wants to look at Unicode text, +but no ordinary \TeX{}-based system deals in Unicode text. +Fortunately for us Anglophones, this is is hardly ever a problem for +our text, since even Knuth's ``\acro{OT}1'' encoding matches ASCII (and hence +the lowest 128 characters of Unicode) for most things printable. +However, using the inflected characters of Continental European +languages, or anything that doesn't use a Latin alphabet, there is +potential for problems, since \TeX{}'s view of what a font is doesn't +map \acro{PDF}'s and the reader won't understand\dots{} + +\dots{} Unless you use the \Package{cmap} package with \PDFLaTeX{}, +that is. The package will instruct \PDFTeX{} to load character +maps into your \acro{PDF} for output fonts encoded according to the \acro{T}1 +(Western European Languages), T2A, T2B, or T2C (Cyrillic Languages), +or T5 (Vietnamese) encodings. If your document uses such encodings, +viewers that can search will use the maps to interpret what they find +in the file. + +Unfortunately, the package only works with fonts that are directly +encoded, such as the \FontName{cm-super} distribution. Fonts like Adobe +Times Roman (which are encoded for \AllTeX{} use via virtual fonts) +are not amenable to this treatment. +\begin{ctanrefs} +\item[cmap.sty]\CTANref{cmap} +\item[cm-super \nothtml{\rmfamily}fonts]\CTANref{cm-super} +\end{ctanrefs} + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Graphics} @@ -6064,7 +6584,7 @@ but may also be \begin{ctanrefs} \item[epsf.tex]\CTANref{epsf} \item[epsfig.sty]Part of the \CTANref{graphics} bundle -\item[epslatex.pdf]\CTANref{epslatex}; the document is also available +\item[epslatex.pdf]\CTANref{epslatex_pdf}; the document is also available in \PS{} format as \CTANref{epslatex_ps} \item[graphics.sty]\CTANref{graphics} \item[graphicx.sty]Part of the \CTANref{graphics} bundle @@ -6087,20 +6607,28 @@ this is pretty satisfactory for vector graphics work. To include bitmap graphics, you need some means of converting them to \PS{}; in fact many standard image manipulators (such as \ProgName{ImageMagick}'s \ProgName{convert}) make a good job of -creating \acro{EPS} files. (Though \ProgName{Unix} users should -beware of \ProgName{xv}'s claims: it has a tendency to downsample your -bitmap to your screen resolution.) +creating \acro{EPS} files (but be sure to ask for output at \PS{} +level~2 or higher). (\ProgName{Unix} users should beware of +\ProgName{xv}'s claims: it has a tendency to downsample your bitmap to +your screen resolution.) Special purpose applications \ProgName{jpeg2ps} (which converts \acro{JPEG} files using \PS{} level 2 functionality) and \ProgName{bmeps} (which converts both \acro{JPEG} and \acro{PNG} -files) are also considered ``good bets''. \ProgName{Bmeps} comes with -patches to produce your own version of \ProgName{dvips} that can cope -with \acro{JPEG} and \acro{PNG} direct, using \ProgName{bmeps}'s -conversion library. +files), and \ProgName{a2ping}/\ProgName{sam2p} (which convert a +bewildering array of bitmap formats to \acro{EPS} or \acro{PDF} files; +\ProgName{sam2p} is one of the engines that \ProgName{a2ping} uses) +are also considered ``good bets''. + +\ProgName{Bmeps} comes with patches to produce your own version of +\ProgName{dvips} that can cope with \acro{JPEG} and \acro{PNG} direct, +using \ProgName{bmeps}'s conversion library. \ProgName{Dvips}, as +distributed by \miktex{}, comes with those patches built-in. \begin{ctanrefs} +\item[a2ping]\CTANref{a2ping} \item[bmeps]\CTANref{bmeps} \item[jpeg2ps]\CTANref{jpeg2ps} +\item[sam2p]\CTANref{sam2p} \end{ctanrefs} \Question[Q-pdftexgraphics]{Imported graphics in \PDFLaTeX{}} @@ -6132,13 +6660,16 @@ available either as a Windows executable or as a \ProgName{Perl} script to run on Unix and other similar systems. A \LaTeX{} package, \Package{epstopdf}, can be used to generate the requisite \acro{PDF} files ``on the fly''; this is convenient, but requires that you -suppress one of \TeX{}'s security checks: don't use it in files from -sources you don't entirely trust. +suppress one of \TeX{}'s security checks: don't allow its use in files +from sources you don't entirely trust. -A similar package, \Package{ps4pdf}, permits other things than `mere' -graphics files in its argument. (Documentation is scarce: see the -\href{http://www.perce.de/LaTeX/ps4pdf/Examples/}{distribution page} -for some examples.) +A similar package, \Package{pst-pdf}, permits other things than `mere' +graphics files in its argument. \Package{Pst-pdf} operates (the +authors suggest) ``like \BibTeX{}''~--- you process your file using +\PDFLaTeX{}, then use \LaTeX{}, \ProgName{dvips} and \ProgName{ps2pdf} +in succession, to produce a secondary file to input to your next +\PDFLaTeX{} run. (Scripts are provided to ease the production of the +secondary file.) An alternative solution is to use \ProgName{purifyeps}, a \ProgName{Perl} script which uses the good offices of @@ -6148,8 +6679,8 @@ included directly. Sadly, \ProgName{purifyeps} doesn't work for all \texttt{.eps} files. Good coverage of the problem is to be found in Herbert Vo\ss{}' -\href{http://pstricks.de/pdf/pdfoutput.phtml#pdftricks}{\acro{PDF}tricks support page}, -which is, in fact, targeted at the use of \Package{pstricks} in +\href{http://pstricks.tug.org/main.cgi?file=pdf/pdfoutput}{\acro{PDF} support page}, +which is targeted at the use of \Package{pstricks} in \PDFLaTeX{}, and also covers the \Package{pstricks}-specific package \Package{pdftricks}. \begin{ctanrefs} @@ -6157,7 +6688,7 @@ which is, in fact, targeted at the use of \Package{pstricks} in \item[epstopdf.sty]Distributed with Heiko Oberdiek's packages \CTANref{oberdiek} \item[pdftricks.sty]\CTANref{pdftricks} -\item[ps4pdf.sty]\CTANref{ps4pdf} +\item[pst-pdf.sty]\CTANref{pst-pdf} \item[pstoedit]\CTANref{pstoedit} \item[purifyeps]\CTANref{purifyeps} \end{ctanrefs} @@ -6237,15 +6768,18 @@ sources. The simplest solution is to patch \TeX{}'s path, by changing the default path. On most systems, the default path is taken from the -environment variable |TEXINPUTS|, if it's present; you can adapt that +environment variable \texttt{TEXINPUTS}, if it's present; you can adapt that to take in the path it already has, by setting the variable to +\begin{quote} \begin{verbatim} - TEXINPUTS=.:<graphics path(s)>: +TEXINPUTS=.:<graphics path(s)>: \end{verbatim} -on a Unix system; on a Windows system the separator will be ``|;|'' -rather than ``|:|''. The ``|.|'' is there to ensure that the current -directory is searched first; the trailing ``|:|'' says ``patch in the -value of |TEXINPUTS| from your configuration file, here''. +\end{quote} +on a Unix system; on a Windows system the separator will be ``\texttt{;}'' +rather than ``\texttt{:}''. The ``\texttt{.}'' is there to ensure +that the current directory is searched first; the trailing +``\texttt{:}'' says ``patch in the value of \texttt{TEXINPUTS} from +your configuration file, here''. This method has the merit of efficiency (\AllTeX{} does \emph{all} of the searches, which is quick), but it's always clumsy and may prove @@ -6258,12 +6792,14 @@ syntax of \csx{graphicspath}'s one argument is slightly odd: it's a sequence of paths (typically relative paths), each of which is enclosed in braces. A slightly odd sample, given in the \Package{graphics} bundle documentation, is: +\begin{quote} \begin{verbatim} - \graphicspath{{eps/}{tiff/}} +\graphicspath{{eps/}{tiff/}} \end{verbatim} +\end{quote} however, if the security checks on your \AllTeX{} system allow, the path may be anything you choose (rather than strictly relative, like -those above). +those above); note that the trailing ``\texttt{/}'' \emph{is} required. Be aware that \csx{graphicspath} does not affect the operations of graphics macros other than those from the graphics bundle~--- in @@ -6305,12 +6841,13 @@ case. but the aspirant \acro{PDF}-maker may be using it for his output, before switching to the scheme). \item Use \cmdinvoke{includegraphics}[...]{filename} without - specifying the extension (i.e., neither |.eps| nor |.pdf|). -\item For every |.eps| file you will be including, produce a |.pdf| - version, as described in % beware line break + specifying the extension (i.e., neither \texttt{.eps} nor + \texttt{.pdf}). +\item For every \texttt{.eps} file you will be including, produce a + \texttt{.pdf} version, as described in % beware line break \Qref[question]{Graphics in \PDFLaTeX{}}{Q-pdftexgraphics}. Having - done this, you will have two copies of each graphic (a |.eps| and a - |.pdf| file) in your directory. + done this, you will have two copies of each graphic (a \texttt{.eps} + and a \texttt{.pdf} file) in your directory. \item Use \PDFLaTeX{} (rather than \LaTeX{}--\ProgName{dvips}--distillation or \LaTeX{}--\ProgName{dvipdfm}) to produce your \acro{PDF} output. @@ -6319,6 +6856,75 @@ case. document itself needs to be altered from its default (\ProgName{dvips}) state, before \ProgName{dvipdfm} will process it. +\Question[Q-repeatgrf]{Repeated graphics in a document} + +A logo or ``watermark'' image, or any other image that is repeated in +your document, has the potential to make the processed version of the +document unmanageably large. The problem is, that the default +mechanisms of graphics usage add the image at every point it's to be +used, and when processed, the image appears in the output file at each +such point. + +Huge \PS{} files are embarrassing; explaining \emph{why} such a file +is huge, is more embarrassing still. + +The \Qref*{\File{epslatex} graphics tutorial}{Q-tutbitslatex} +describes a technique for avoiding the problem: basically, one +converts the image that's to be repeated into a \PS{} subroutine, and +load that as a \ProgName{dvips} prologue file. In place of the image, +you load a file (with the same bounding box as the image) containing +no more than an invocation of the subroutine defined in the prologue. + +The \File{epslatex} technique is tricky, but does the job. Trickier +still is the neat scheme of converting the figure to a one-character +Adobe Type~3 outline font. While this technique is for the ``real +experts'' only (the author of this answer has never even tried it), it has +potential for the same sort of space saving as the \File{epslatex} +technique, with greater flexibility in actual use. + +More practical is Hendri Adriaens' \Package{graphicx-psmin}; you load +this \emph{in place} of \Package{graphicx}, so rather than: +\begin{quote} +\begin{verbatim} +\usepackage[<options>]{graphicx} +\end{verbatim} +\end{quote} +you will write: +\begin{quote} +\begin{verbatim} +\usepackage[<options>]{graphicx-psmin} +\end{verbatim} +\end{quote} +and at the start of your document, you write: +\begin{quote} +\begin{verbatim} +\loadgraphics[<bb>]{<list of graphics>} +\end{verbatim} +\end{quote} +and each of the graphics in the list is converted to an ``object'' for +use within the resulting \PS{} output. (This is, in essence, an +automated version of the \File{epslatex} technique described above.) + +Having loaded the package as above, whenever you use +\csx{includegraphics}, the command checks if the file you've asked for +is one of the graphics in \csx{loadgraphics}' list. If so, the +operation is converted into a call to the ``object'' rather than a new +copy of the file; the resulting \PS{} can of course be \emph{much} smaller. + +Note that the package requires a recent \ProgName{dvips}, version +5.95b (this version isn't~--- yet~--- widely distributed). + +If your \PS{} is destined for conversion to \acro{PDF}, either by a +\ProgName{ghostscript}-based mechanism such as \ProgName{ps2pdf} or by +(for example) \ProgName{Acrobat} \ProgName{Distiller}, the issue isn't +so pressing, since the distillation mechanism will amalgamate graphics +objects whether or not the \PS{} has them amalgamated. \PDFTeX{} does +the same job with graphics, automatically converting multiple uses +into references to graphics objects. +\begin{ctanrefs} +\item[graphicx-psmin.sty]\CTANref{graphicx-psmin} +\end{ctanrefs} + \Question[Q-grmaxwidth]{Limit the width of imported graphics} Suppose you have graphics which may or may not be able to fit within @@ -6351,6 +6957,7 @@ Use the command as follows: \includegraphics[width=\maxwidth]{figure} \end{verbatim} \end{quote} + \Question[Q-topgraph]{Top-aligning imported graphics} When \TeX{} sets a line of anything, it ensures that the base-line of @@ -6389,10 +6996,21 @@ as in: } \end{verbatim} \end{quote} +A more \LaTeX{}-y way of doing the job (somewhat innefficiently) uses +the \Package{calc} package: +\begin{quote} +\begin{verbatim} +\usepackage{calc} +... +\raisebox{1ex-\height}{\includegraphics{figure}} +\end{verbatim} +\end{quote} +(this has the same effect as the text-align version, above). + The fact is, \emph{you} may choose where the base-line ends up. This answer merely shows you sensible choices you might make. -\Question[Q-mpprologues]{Making \MP{} output display in \ProgName{ghostscript}} +\Question[Q-mpprologues]{Displaying \MP{} output in \ProgName{ghostscript}} \MP{} ordinarily expects its output to be included in some context where the `standard' \MF{} fonts (that you've specified) are already @@ -6408,12 +7026,12 @@ Error: /undefined in cmmi10 \end{verbatim} \end{quote} There is provision in \MP{} for avoiding this problem: issue the -command |prologues := 2;| at the start of the |.mp| file. +command \texttt{prologues := 2;} at the start of the \texttt{.mp} file. Unfortunately, the \PS{} that \MP{} inserts in its output, following this command, is incompatible with ordinary use of the \PS{} in inclusions into \AllTeX{} documents, so it's best to -make the |prologues| command optional. Furthermore, \MP{} takes a +make the \texttt{prologues} command optional. Furthermore, \MP{} takes a very simple-minded approach to font encoding: since \TeX{} font encodings regularly confuse sophisticated minds, this can prove troublesome. If you're suffering such problems (the symptom is that @@ -6508,18 +7126,16 @@ of drawing, and setup, here are a few systems you may consider: \Qref[question]{\PDFLaTeX{} graphics}{Q-pdftexgraphics}) generates \acro{PDF} files on the fly from \Package{pstricks} commands. The documentation is good (you may browse it via the % ! line break - \href{http://www.tug.org/applications/PSTricks/}{\Package{pstricks} page} - on the \acro{TUG} web site), and another extremely valuable - \href{http://www.pstricks.de}{web site} lists supporting - packages (for various specialised drawing operations) and many - enticing examples. There is also a mailing list + \href{http://pstricks.tug.org/}{\Package{pstricks} page} + on the \acro{TUG} web site). There is also a mailing list (\mailto{pstricks@tug.org}) which you may \href{http://tug.org/mailman/listinfo/pstricks}{join}, or you may just browse the \href{http://tug.org/pipermail/pstricks/}{list archives}. \item \Package{pgf}: while \Package{pstricks} is very powerful and convenient, using it with \PDFLaTeX{} is an awful fidget: if you - simply want the graphical capabilities, \Package{pgf} may be a good + simply want the graphical capabilities, \Package{pgf}, together with + its rather pleasing ``user-oriented'' interface \Package{tikz}, may be a good bet for you. While \acro{PDF} has (in essence) the same graphical capabilities as \PS{}, it isn't programmable; \Package{pgf} provides common \LaTeX{} commands that will utilise the graphical @@ -6549,6 +7165,7 @@ of drawing, and setup, here are a few systems you may consider: \item[pgf.sty]\CTANref{pgf} \item[pict2e.sty]\CTANref{pict2e} \item[pstricks]\CTANref{pstricks} +\item[tikz.sty]Distributed with \CTANref{pgf} \end{ctanrefs} \Question[Q-drawFeyn]{Drawing Feynman diagrams in \LaTeX{}} @@ -6606,8 +7223,31 @@ details may be found in \File{pfgguide} in the distribution. (Unfortunately, \Package{psfrag} can't be used with \PDFLaTeX{}, though one might hope that it would be susceptible to the same sort of treatment as is used in the \Package{pdftricks} package. On the other -hand, \Qref*{V\TeX{}}{Q-commercial}'s GeX processor explicitly deals -with \Package{psfrag}, both in its free and commercial instances.) +hand, +\begin{narrowversion} + V\TeX{}'s GeX processor (\Qref{}{Q-commercial}) +\end{narrowversion} +\begin{wideversion} + \Qref*{V\TeX{}}{Q-commercial}'s GeX processor +\end{wideversion} +explicitly deals with \Package{psfrag}, both in its free and +commercial instances.) + +The \Package{psfragx} package goes one step further than +\Package{psfrag}: it provides a means whereby you can put the +\Package{psfrag} commands into the preamble of your \acro{EPS} file +itself. \Package{Psfrag} has such a command itself, but deprecates +it; \Package{psfragx} has cleaned up the facility, and provides a +script \ProgName{laprint} for use with \ProgName{Matlab} to produce +appropriately tagged output. (In principle, other graphics +applications could provide a similar facility, but apparently none does.) + +\ProgName{Emacs} users may find the embedded editor \ProgName{iTe} a +useful tool for placing labels: it's a \AllTeX{}-oriented graphical +editor written in \ProgName{Emacs Lisp}. You create +\environment{iteblock} environments containing graphics and text, and +may then invoke \ProgName{iTe} to arrange the elements relative to one +another. Another useful approach is \Package{overpic}, which overlays a \environment{picture} environment on a graphic included by use of @@ -6617,9 +7257,9 @@ grid for planning your ``attack''; the distribution comes with simple examples. \Package{Pstricks} can of course do everything that \Package{overpic} -can, with all the flexibility of \PS{} programming that it offers. -The \Package{pstricks} web site has a page of % ! line break -\href{http://pstricks.de/Examples/overlay.phtml}{examples of labelling} +can, with all the flexibility of \PS{} programming that it offers +The \Package{pstricks} web site has a page with several % ! line break +\href{http://pstricks.tug.org/main.cgi?file=Examples/overlay}{examples of labelling} which will get you started; if \Package{pstricks} is % ! line break \Qref*{an option for you}{Q-drawing}, this route is worth a try. @@ -6629,8 +7269,11 @@ environment which itself includes the graphic. I would recommend are plainly little more than a convenience over what is achievable with the do-it-yourself approach. \begin{ctanrefs} +\item[iTe]\CTANref{ite} +\item[laprint]Distributed with \CTANref{psfragx} \item[overpic.sty]\CTANref{overpic} \item[psfrag.sty]\CTANref{psfrag} +\item[psfragx.sty]\CTANref{psfragx} \item[pstricks.sty]\CTANref{pstricks} \end{ctanrefs} @@ -6674,8 +7317,7 @@ in this endeavour: have ``\BibTeX{} modes''. \item If you have an existing \environment{thebibliography} environment, the \ProgName{Perl} script \ProgName{tex2bib} will - probably help (there's no documentation other than the oddly-named - \File{tex2bib.readme}). + probably help. \item There are a number of \BibTeX{} bibliography management systems available, some of which permit a graphical user interface to the task. Sadly, none seems to be available with the ordinary \TeX{} @@ -6705,9 +7347,12 @@ in this endeavour: \BibTeX{} format by utilities to be found on \acro{CTAN}. For example, the \ProgName{Perl} script \ProgName{isi2bibtex} will translate citations from \acro{ISI} ``Web of knowledge'' (a - subscription service, available to \acro{UK} academics as \acro{BIDS}). + subscription service, available to \acro{UK} academics via + \acro{BIDS}). UK academics may translate \acro{BIDS} downloads + using \ProgName{bids.to.bibtex} \end{itemize} \begin{ctanrefs} +\item[bids.to.bibtex]\CTANref{bidstobibtex} \item[btOOL]\CTANref{btOOL} \item[ebib]\CTANref{ebib} \item[isi2bibtex]\CTANref{isi2bibtex} @@ -6802,33 +7447,39 @@ example. \Question[Q-bibstrtl]{`String too long' in \BibTeX{}} The \BibTeX{} diagnostic ``Warning--you've exceeded 1000, the -|global-string-size|, for entry |foo|'' usually arises from a very -large abstract or annotation included in the database. The diagnostic -usually arises because of an infelicity in the coding of +\texttt{global-string-size}, for entry \texttt{foo}'' usually arises +from a very large abstract or annotation included in the database. +The diagnostic usually arises because of an infelicity in the coding of \File{abstract.bst}, or styles derived from it. (One doesn't ordinarily output annotations in other styles.) The solution is to make a copy of the style file (or get a clean copy from \acro{CTAN}~--- \CTANref{abstract-bst}), and rename it (e.g., on a -long file-name system to \File{abstract-long.bst}). Now edit it: find -function |output.nonnull| and +long file-name system, to \File{abstract-long.bst}). Now edit it: find +function \texttt{output.nonnull} and \begin{itemize} \item change its first line (line 60 in the version on \acro{CTAN}) - from |"{ 's :="| to |"{ swap$"|, and -\item delete its last line, which just says |"s"| (line 84 in the - version on \acro{CTAN}). + from + \begin{quote} +\begin{verbatim} +{ 's := +\end{verbatim} + \end{quote} +to + \begin{quote} +\begin{verbatim} +{ swap$ +\end{verbatim} + \end{quote} + Finally, +\item delete the function's last line, which just says ``\texttt{s} + (line 84 in the version on \acro{CTAN}). \end{itemize} Finally, change your \csx{bibliographystyle} command to refer to the name of the new file. This technique applies equally to any bibliography style: the same -change can be made to any similar |output.nonnull| function. - -%is not one that you can hope -%to avoid by altering the \BibTeX{} style in a simple way~--- \BibTeX{} -%itself needs recompiling to increase its limit on string sizes (which is -%often not practical, and is never desirable). You must therefore -%address the problem by changing your bibliography database. +change can be made to any similar \texttt{output.nonnull} function. If you're reluctant to make this sort of change, the only way forward is to take the entry out of the database, so that you don't encounter @@ -6869,7 +7520,7 @@ For example: \begin{quote} \begin{verbatim} AUTHOR = {Fred Q. Bloggs, John P. Doe \& - Robin Fairbairns} + Another Idiot} \end{verbatim} \end{quote} falls foul of two of the above rules: a syntactically significant @@ -6878,17 +7529,17 @@ name separator. The output of the above might be something like: \begin{quote} \begin{wideversion} \begin{verbatim} -John P. Doe \& Robin Fairbairns Fred Q. Bloggs +John P. Doe \& Another Idiot Fred Q. Bloggs \end{verbatim} \end{wideversion} \begin{narrowversion} \begin{verbatim} -John P. Doe \& Robin Fairbairns +John P. Doe \& Another Idiot Fred Q. Bloggs \end{verbatim} \end{narrowversion} \end{quote} -because ``John P. Doe \& Robin Fairbairns'' has become the `first name', +because ``John P. Doe \& Another Idiot has become the `first name', while ``Fred Q. Bloggs'' has become the `last name' of a single person. The example should have been written: \begin{quote} @@ -6896,13 +7547,13 @@ person. The example should have been written: \begin{verbatim} AUTHOR = {Fred Q. Bloggs and John P. Doe and - Robin Fairbairns} + Another Idiot} \end{verbatim} \end{narrowversion} \begin{wideversion} \begin{verbatim} AUTHOR = {Fred Q. Bloggs and John P. Doe and - Robin Fairbairns} + Another Idiot} \end{verbatim} \end{wideversion} \end{quote} @@ -7172,7 +7823,6 @@ Like the solution by generating extra commands, this involves tedious extra typing; which of the two techniques is preferable for a given bibliography will be determined by the names in it. - \subsection{Creating citations} \Question[Q-usebibtex]{``Normal'' use of \BibTeX{} from \LaTeX{}} @@ -7266,6 +7916,71 @@ resolve labels. To summarise: processing to resolve citations requires: \LaTeX{}; \BibTeX{}; \LaTeX{}; \LaTeX{}. +\Question[Q-whatbst]{Choosing a bibliography style} + +A large proportion of people are satisfied with one of Patashnik's +original ``standard'' styles, \Package{plain}, \Package{unsrt}, +\Package{abbrv} and \Package{alpha}. However, no style in that set +supports the ``author-date'' citation style that is popular in many +fields; but there are a very large number of contributed styles +available, that \emph{do} support the format. + +(Note that author-date styles arose because the simple and clear +citation style that \Package{plain} produces is so awkward in a +traditional manuscript preparation scenario. However, \TeX{}-based +document production does away with all those difficulties, leaving us +free once again to use the simple option.) + +Fortunately, help is at hand, on the Web, with this problem: +\begin{itemize} +\item a sample text, showing the sorts of style choices available, can + be found on +\begin{narrowversion} + Ken Turner's web site: + \URL{http://www.cs.stir.ac.uk/~kjt/software/latex/showbst.html}; +\end{narrowversion} +\begin{wideversion} + % ! line break + \href{http://www.cs.stir.ac.uk/~kjt/software/latex/showbst.html}{Ken Turner's web site}; +\end{wideversion} +\item an excellent survey, that lists a huge variety of styles, + sorted into their nominal topics as well as providing a good range + of examples, is the Reed College % ! line break +\begin{narrowversion} + ``Bibliographies in \LaTeX{}'' + (\URL{http://web.reed.edu/cis/help/BibTeXstandard.html}). +\end{narrowversion} +\begin{wideversion} + % ! line break + ``\href{http://web.reed.edu/cis/help/BibTeXstandard.html}{Bibliographies in \LaTeX{}}''. +\end{wideversion} +\end{itemize} + +Of course, these pages don't cover everything; the problem the +inquisitive user faces, in fact, is to find what the various available +styles actually do. This is best achieved (if the links above don't +help) by using \Package{xampl.bib} from the \BibTeX{} documentation +distribution: one can get a pretty good feel for any style one has to +hand using this ``standard'' bibliography. For style +\Package{my-style.bst}, the simple \LaTeX{} document: +\begin{quote} +\begin{verbatim} +\documentclass{article} +\begin{document} +\bibliographystyle{my-style} +\nocite{*} +\bibliography{xampl} +\end{document} +\end{verbatim} +\end{quote} +will produce a representative sample of the citations the style will +produce. (Because \Package{xampl.bib} is so extreme in some of its +``examples'', the \BibTeX{} run will also give you an interesting +selection of \BibTeX{}'s error messages\dots) +\begin{ctanrefs} +\item[xampl.bib]\CTANref{xampl-bib} +\end{ctanrefs} + \Question[Q-chapbib]{Separate bibliographies per chapter?} A separate bibliography for each `chapter' of a document can be provided @@ -7475,8 +8190,10 @@ Options for entries in running text are on the format of entry that your \texttt{.bst} file generates, but is otherwise undemanding of the bibliography style. \item The package \Package{inlinebib}, which requires that you use its - \File{inlinebib.bst} -\item The package \Package{jurabib}, which was originally targetted at + \File{inlinebib.bst}. \Package{Inlinebib} was actually designed for + footnote citations: its \emph{expected} use is that you place a + citation inline as the argument of a \csx{footnote} command. +\item The package \Package{jurabib}, which was originally designed for German law documents, and has comprehensive facilities for the manipulation of citations. The package comes with four bibliography styles that you may use: \File{jurabib.bst}, \File{jhuman.bst} and @@ -7486,13 +8203,13 @@ Options for entries in running text are Options for entries in footnotes are \begin{itemize} \item The package \Package{footbib}, and -\item The package \Package{jurabib}, again. +\item Packages \Package{jurabib} and \Package{inlinebib}, again. \end{itemize} Note that \Package{jurabib} does the job using \LaTeX{}'s standard footnotes, whereas \Package{footbib} creates its own sequence of -footnotes. Therefore, in a document which has other footnotes, it's -best to use \Package{jurabib}, to avoid confusion of footnotes and -foot-citations. +footnotes. Therefore, in a document which has other footnotes, it may +be advisable to use \Package{jurabib} (or of course +\Package{inlinebib}), to avoid confusion of footnotes and foot-citations. \begin{ctanrefs} \item[bibentry.sty]\emph{Distributed with} \CTANref{natbib} \item[footbib.sty]\CTANref{footbib} @@ -7750,6 +8467,39 @@ freedom via the extensibility of \Package{babelbib} \item[swebib \nothtml{\rmfamily\upshape}bundle]\CTANref{swebib} \end{ctanrefs} +\Question[Q-formbiblabel]{Format of numbers in the bibliography} + +By default, \LaTeX{} makes entries in the bibliography look like: +\begin{quote} + [1] Doe, Joe et al. Some journal. 2004.\\ {} + [2] Doe, Jane et al. Some journal. 2003. +\end{quote} +while many documents need something like: +\begin{quote} + 1. Doe, Joe et al. Some journal. 2004.\\ + 2. Doe, Jane et al. Some journal. 2003. +\end{quote} + +This sort of change may be achieved by many of the ``general'' +citation packages; for example, in \Package{natbib}, it's as simple as: +\begin{quote} +\begin{verbatim} +\renewcommand{\bibnumfmt}[1]{#1.} +\end{verbatim} +\end{quote} +but if you're not using such a package, the following internal +\LaTeX{} commands, in the preamble of your document, will do the job: +\begin{quote} +\begin{verbatim} +\makeatletter +\renewcommand*{\@biblabel}[1]{\hfill#1.} +\makeatother +\end{verbatim} +\end{quote} +\begin{ctanrefs} +\item[natbib.sty]\CTANref{natbib} +\end{ctanrefs} + \subsection{Manipulating whole bibliographies} \Question[Q-nocite*]{Listing all your \BibTeX{} entries} @@ -7856,7 +8606,7 @@ produce output on acetate foils, though subsequent work has provided environments in which they can be used with screen projectors (see below). -The advent of MicroSoft \ProgName{PowerPoint} (feeble though early +The advent of Microsoft \ProgName{PowerPoint} (feeble though early versions of it were) has created a demand for ``dynamic'' slides~--- images that develop their content in a more elaborate fashion than by merely replacing one foil with the next in the way that was the norm @@ -7869,6 +8619,9 @@ presentation. The add-on package \Package{ppr-prv} adds ``preview'' facilities (that which is commonly called ``hand-out printing''). The \Package{HA-prosper} package, which you load with \Class{prosper}, mends a few bugs, and adds several facilities and slide design styles. +The (relatively new) \Class{powerdot} class is designed as a +replacement for \Class{prosper} and \Package{HA-prosper}, co-authored +by the author of \Package{HA-prosper}. \Class{Beamer} is a relatively easy-to-learn, yet powerful, class that (as its name implies) was designed for use with projection displays. @@ -7878,6 +8631,15 @@ installing \Class{beamer} ``from scratch'', both are good additions to a modern \LaTeX{} installation. \Class{Beamer} has reasonable facilities for producing printed copies of slides. +\Class{Talk} is another highly functional, yet easy-to-learn class +which claims to differ from the systems mentioned above, such as +\Class{beamer}, in that it doesn't impose a slide style on you. You +get to specify a bunch of slide styles, and you can switch from one to +the other between slides, as you need. (The class itself provides +just the one style, in the package \Package{greybars}: the author +hopes users will contribute their own styles, based on +\Package{greybars}.) + \ProgName{Ppower4} (commonly known as \ProgName{pp4}) is a \ProgName{Java}-based support program that will postprocess \acro{PDF}, to `animate' the file at places you've marked with @@ -7901,17 +8663,76 @@ of code using many of them) may be found at Michael Wiedmann's fine \begin{ctanrefs} \item[beamer.cls]Download all of \CTANref{beamer} \item[foils.cls]\CTANref{foiltex} +\item[greybars.sty]distributed with \CTANref{talk} \item[HA-prosper.sty]\CTANref{ha-prosper} %\item[ifmslide.sty]\CTANref{ifmslide} \item[seminar.cls]\CTANref{seminar} \item[pgf.sty]\CTANref{pgf} +\item[powerdot.cls]\CTANref{powerdot} \item[pp4]\CTANref{ppower4} \item[ppr-prv.sty]\CTANref{ppr-prv} \item[prosper.cls]\CTANref{prosper} +\item[talk.cls]\CTANref{talk} \item[texpower]\CTANref{texpower} \item[xcolor.sty]\CTANref{xcolor} \end{ctanrefs} +\Question[Q-poster]{Creating posters with \LaTeX{}} + +There is no complete ``canned solution'' to creating a poster (as, for +example, classes like \Class{seminar}, \Class{powerdot} and +\Class{beamer} serve for creating presentations in a variety of +styles). + +The nearest approach to the complete solution is the \Class{sciposter} +class, which provides the means to produce really rather good posters +according to the author's required style. A complete worked example +is provided with the distribution + +Otherwise, there is a range of tools, most of which are based on the +\Class{a0poster} class, which sets up an appropriately-sized piece of +paper, sets font sizes appropriately, and leaves you to your own +devices. + +Having used \Class{a0poster}, you can of course slog it out, and write +all your poster as an unadorned \LaTeX{} document (presumably in +multiple columns, using the \Package{multicol} package), but it's not really +necessary: the (straightforward) \Package{textpos} package provides a +simple way of positioning chunks of text, or tables or figures, on the +poster page. + +More sophisticated is the \Package{flowfram} package, whose basic aim +in life is flowing text from one box on the page to the next. One of +the package's design aims seems to have been the production of +posters, and a worked example is provided. The author of +\Package{flowfram} has an experimental tool called +\href{http://theoval.cmp.uea.ac.uk/~nlct/jpgfdraw/}{JpgfDraw}, which +allows you to construct the outline of frames for use with +\Package{flowfram}. + +Despite the relative shortage of tools, there are a fair few web pages +that explain the process (mostly in terms of the \Class{a0poster} +route): +\begin{itemize} +\item from Norman Gray, \URL{http://purl.org/nxg/note/posters}; +\item from ``\emph{awf}'' and ``\emph{capes}'' + \URL{http://www.robots.ox.ac.uk/~awf/latex-posters/}; +\item from Brian Wolven, + \URL{http://fuse.pha.jhu.edu/~wolven/posters.html} (this page also + provides macros and other support suggestions); and +\item from ``\emph{pjh}'', + \URL{http://www.phys.ufl.edu/~pjh/posters/poster_howto_UF.html}, + which covers the specific issue of dealing with University of + Florida styled poster, but has hints which are generally useful. +\end{itemize} +\begin{ctanrefs} +\item[a0poster.cls]\CTANref{a0poster} +\item[flowfram.sty]\CTANref{flowfram} +\item[multicol.sty]Distributed as part of \CTANref{2etools} +\item[sciposter.cls]\CTANref{sciposter} +\item[textpos.sty]\CTANref{textpos} +\end{ctanrefs} + \Question[Q-thesis]{Formatting a thesis in \LaTeX{}} Thesis styles are usually very specific to your University, so it's @@ -7975,15 +8796,22 @@ be typeset using different page format, etc., parameters than those used when they are typeset as a part of the main file. A more `raw' toolkit is offered by Matt Swift's \Package{includex} and -\Package{moredefs} packages, both part of the \Package{frankenstein} -bundle) offer a possible way forward. - -\Package{Includex} enables you to `\csx{includedoc}' complete articles -(in the way that you `\csx{include}' chapter files in an ordinary -report). It doesn't do the whole job for you, though. You need to +\Package{newclude} packages, both part of the \Package{frankenstein} +bundle. Note that Matt believes \Package{includex} is obsolete +(though it continues to work for this author); furthermore, its +replacement, \Package{newclude} remains ``in development'', as it has +been since 1999. + +Both \Package{includex} and \Package{newclude} enable you to +`\csx{includedoc}' complete articles (in the way that you +`\csx{include}' chapter files in an ordinary report). The preamble +(everything up to \cmdinvoke{begin}{document}), and everything after +\cmdinvoke{end}{document}, is ignored by both packages. Thus the +packages don't ``do the whole job'' for you, though: you need to analyse the package use of the individual papers, and ensure that a -consistent set is loaded in the preamble of the main report. - +consistent set is loaded in the preamble of the main report. (Both +packages require \Package{moredefs}, which is also part of the bundle.) + A completely different approach is to use the \Package{pdfpages} package, and to include articles submitted in \acro{PDF} format into a a \acro{PDF} document produced by \PDFLaTeX{}. The package @@ -7998,6 +8826,7 @@ of the included pages. \item[includex.sty]Distributed in the ``unsupported'' part of \CTANref{frankenstein} \item[moredefs.sty]Distributed as part of \CTANref{frankenstein} +\item[newclude.sty]Distributed as part of \CTANref{frankenstein} \item[pdfpages.sty]\CTANref{pdfpages} \item[subfiles.cls, etc.]\CTANref{subfiles} \end{ctanrefs} @@ -8018,13 +8847,17 @@ with a major item that you want to discuss, such as `education', `work experience', etc). The class's documentation is supported by a couple of example files, and an emacs mode is provided. +Xavier Danaux offers a class \Class{moderncv} which supports +typesetting modern \emph{curricula vitarum}, both in a classic and in a +casual style. It is fairly customizable, allowing you to define your +own style by changing the colours, the fonts, etc. + The European Commission has recommended a format for % ! line break \emph{curricula vitarum} within Europe, and Nicola Vitacolonna has developed a class \Class{europecv} to produce it. While (by his own admission) the class doesn't solve all problems, it seems well-thought -out and supports many EU languages (it omits Dutch and Greek, and all -the languages of the 2004 accessions; instructions for creating new -language options are, however, there for the energetic). +out and supports all current official EU languages (together with a +few non-official languages, such as Catalan, Galician and Serbian). The alternative to using a separate class is to impose a package on one of the standard classes. An example, @@ -8037,6 +8870,7 @@ little but advice \emph{against} trying to use it. \item[currvita.sty]\CTANref{currvita} \item[curve.cls]\CTANref{curve} \item[europecv.cls]\CTANref{europecv} +\item[moderncv.cls]\CTANref{moderncv} \item[resume.sty]\CTANref{resume} \item[vita.cls]\CTANref{vita} \end{ctanrefs} @@ -8160,12 +8994,24 @@ programming described in section 2.2 of \emph{The \LaTeX{} Companion} The following hack will probably satisfy your editor. Define yourself new commands \begin{quote} +\begin{wideversion} +\begin{verbatim} +\newcommand{\ssection}[1]{% + \section[#1]{\centering\normalfont\scshape #1}} +\newcommand{\ssubsection}[1]{% + \subsection[#1]{\raggedright\normalfont\itshape #1}} +\end{verbatim} +\end{wideversion} +\begin{narrowversion} % really non-hyper \begin{verbatim} \newcommand{\ssection}[1]{% - \section[#1]{\centering\sc #1}} + \section[#1]{\centering + \normalfont\scshape #1}} \newcommand{\ssubsection}[1]{% - \subsection[#1]{\raggedright\it #1}} + \subsection[#1]{\raggedright + \normalfont\itshape #1}} \end{verbatim} +\end{narrowversion} \end{quote} and then use \csx{ssection} and \csx{ssubsection} in place of \csx{section} and \csx{subsection}. This isn't perfect: section numbers @@ -8444,11 +9290,13 @@ now been overtaken again by \Package{caption}; however, \Question[Q-fancyhdr]{Alternative head- and footlines in \LaTeX{}} The standard \LaTeX{} document classes define a small set of `page -styles' which (in effect) specify head- and footlines for your -document. The set defined is very restricted, but \LaTeX{} is capable -of much more; people occasionally set about employing \LaTeX{} -facilities to do the job, but that's quite unnecessary~--- Piet van -Oostrum has already done the work. +styles' which specify head- and footlines for your document (though +they can be used for other purposes, too). The standard set is very +limited, but \LaTeX{} is capable of much more. The internal +\LaTeX{} coding needed to change page styles is not particularly +challenging, but there's no need~--- there are packages that provide +useful abstractions that match the way we typically think about these +things. The \Package{fancyhdr} package provides simple mechanisms for defining pretty much every head- or footline @@ -8476,7 +9324,6 @@ the \Class{KOMA-script} classes. \item[fancyhdr.sty]\CTANref{fancyhdr} \item[\nothtml{\rmfamily}KOMA script bundle]\CTANref{koma-script} \item[memoir.cls]\CTANref{memoir} -\item[scrpage2.sty]Distributed as part of \CTANref{koma-script} \end{ctanrefs} \Question[Q-widefigs]{Wide figures in two-column documents} @@ -8680,9 +9527,9 @@ optional argument: \end{verbatim} \end{quote} If the \meta{short title} is present, it is used both for the table of -contents and for the page heading: the usual answer to people who -complain about the size of the title that's gone in to the running -head, is to suggest that they the optional argument. +contents and for the page heading. The usual answer to people who +complain that their title is too big for the running head is to +suggest that they the optional argument. However, using the same text for the table of contents as for the running head may also be unsatisfactory: if your chapter titles are @@ -8691,12 +9538,12 @@ scheme is to have a shortened table of contents entry, and a really terse entry in the running head. One of the problems is the tendency of page headings to be set in -capitals; so why not set headings as written for ``ordinary'' reading? -It's not possible to do so with unmodified \LaTeX{}, but the -\Package{fancyhdr} package provides a command \csx{nouppercase} for use -in its header (and footer) lines to suppress \LaTeX{}'s uppercasing -tendencies. Classes in the \Class{KOMA-script} bundle don't uppercase -in the first place. +capitals (which take up more space); so why not set headings as written +for ``ordinary'' reading? It's not possible to do so with unmodified +\LaTeX{}, but the \Package{fancyhdr} package provides a command +\csx{nouppercase} for use in its header (and footer) lines to suppress +\LaTeX{}'s uppercasing tendencies. Classes in the \Class{KOMA-script} +bundle don't uppercase in the first place. In fact, the sectioning commands use `mark' commands to pass information to the page headers. For example, \csx{chapter} uses @@ -8856,9 +9703,11 @@ which instruct \Package{geometry} which \csx{special} commands to use. or V\TeX{}.) So, the resolution of the problem is to add +\begin{quote} \begin{verbatim} - \usepackage[dvixxx,...]{geometry} +\usepackage[dvixxx,...]{geometry} \end{verbatim} +\end{quote} (where \pkgoption{dvixxx} is your current favourite \acro{DVI} driver), and the document will run correctly with any of \LaTeX{} (whether or not run on V\TeX{}) or \PDFLaTeX{}. @@ -8881,13 +9730,35 @@ mean that any change must be very carefully considered, both to ensure that it ``works'' and to ensure that the result is pleasing to the eye. -Lamport's warning to beginners in his section on `Customizing the -Style'~--- ``don't do it''~--- needs to be taken seriously. One-inch -margins on A4 paper are fine for 10- or 12-pitch typewriters, but not -for 10pt (or even 11pt or 12pt) type because readers find such wide, -dense, lines difficult to read: there should ideally be no more than -75 characters per line (though the constraints change for two-column -text). +\LaTeX{}'s defaults sometimes seem excessively conservative, +but there are sound reasons behind how Lamport designed the layouts +themselves, whatever one may feel about his overall design. For +example, the common request for ``one-inch margins all round on A4 +paper'' is fine for 10- or 12-pitch typewriters, but not for 10pt (or +even 11pt or 12pt) type because readers find such wide, dense, lines +difficult to read. There should ideally be no more than 75 characters +per line (though the constraints change for two-column text). + +So Lamport's warning to beginners in his section on `Customizing the +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 + +The following answers deal with the ways one may choose to proceed: +\begin{itemize} +\item \Qref*{Choose which package to use}{Q-marginpkgs}. +\item \Qref*{Find advice on setting up page layout by hand}{Q-marginmanual}. +\end{itemize} +There is a related question~--- how to change the layout +temporarily~--- and there's an answer that covers that, too: +\begin{itemize} +\item \Qref*{Change the margins on the fly}{Q-chngmargonfly}. +\end{itemize} + +\Question[Q-marginpkgs]{Packages to set up page designs} The `ultimate' tool for adjusting the dimensions and position of the printed material on the page is the \Package{geometry} package; a very @@ -8895,10 +9766,41 @@ wide range of adjustments of the layout may be relatively straightforwardly programmed, and package documentation is good and comprehensive. +As is usual, users of the \Class{memoir} class have built-in +facilities for this task, and users of the \Class{KOMA-script} classes +are recommended to use an alternative package, \Package{typearea}. In +either case it is difficult to argue that users should go for +\Package{geometry}: both alternatives are good. + +The documentation of \Package{geometry} is a bit overwhelming, and +learning all its capabilities may be more than you ever need. Somewhat simpler to use is the \Package{vmargin} package, which has a canned set of paper sizes (a superset of that provided in \LaTeXe{}), provision for custom paper, margin adjustments and provision for two-sided printing. +\begin{ctanrefs} +\item[geometry.sty]\CTANref{geometry} +\item[\nothtml{\rmfamily}KOMA script bundle]\CTANref{koma-script} +\item[layout.sty]Distributed as part of \CTANref{2etools} +\item[memoir.cls]\CTANref{memoir} +\item[typearea.sty]Distributed as part of \CTANref{koma-script} +\item[vmargin.sty]\CTANref{vmargin} +\end{ctanrefs} + +\Question[Q-marginmanual]{How to set up page layout ``by hand''} + +So you're eager to do it yourself, notwithstanding the cautions +\begin{narrowversion} + outlined above (\Qref{}{Q-changemargin}). +\end{narrowversion} +\begin{wideversion} + outlined in ``\Qref{changing margins}{Q-changemargin}''. +\end{wideversion} + +It's important that you first start by familiarising yourself +with LaTeX's page layout parameters. For example, see section C.5.3 of the +\LaTeX{} manual (pp.~181-182), or corresponding sections in many of the other +good \LaTeX{} manuals (see \Qref[question]{\LaTeX{} books}{Q-books}). \LaTeX{} controls the page layout with a number of parameters, which allow you to change the distance from the edges of a page to the left @@ -8908,43 +9810,49 @@ somewhat complex, and it is easy to get their interrelationships wrong when redefining the page layout. The layout package defines a \csx{layout} command which draws a diagram of your existing page layout, with the dimensions (but not their interrelationships) shown. -This \acro{FAQ} 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. -If you're still eager to ``do it yourself'', start by familiarising yourself -with LaTeX's page layout parameters. For example, see section C.5.3 of the -\LaTeX{} manual (pp.~181-182), or corresponding sections in many of the other -good \LaTeX{} manuals (see \Qref[question]{\LaTeX{} books}{Q-books}). +Even changing the text height and width, \csx{textheight} and +\csx{textwidth}, requires more care than you might expect: the height +should be set to fit a whole number of text lines (in terms of +multiples of \csx{baselinskip}), and the width should be constrained +by the number of characters per line, as mentioned in % ! line break +``\Qref*{changing margins}{Q-changemargin}''. + +Margins are controlled by two parameters: \csx{oddsidemargin} and +\csx{evensidemargin}, whose names come from the convention that +odd-numbered pages appear on the right-hand side (`recto') of a +two-page spread and even-numbered pages on the left-hand side +(`verso'). Both parameters actually refer to the left-hand margin of +the relevant pages; in each case the right-hand margin is specified by +implication, from the value of \csx{textwidth} and the width of the +paper. (In a one-sided document, which is the default in many +classes, including the standard \Class{article} and \Class{report} +classes, \csx{oddsidemargin} stands for both.) -The text height and width, \csx{textheight} and \csx{textwidth}, -require more care than you might expect: the height should be set to -fit an integral number of text lines, and the width should be -constrained by the number of characters per line, as mentioned above. - -Margins are controlled by three parameters. The pair -\csx{oddsidemargin} and \csx{evensidemargin} are so-called because it -is conventionally taken that odd-numbered pages appear on the -right-hand side of a two-page spread (`recto') and even-numbered pages -on the left-hand side (`verso'). Both parameters refer to the -left-hand margin; the right-hand margin is specified by implication, -from the size of \csx{textwidth} and the width of the paper. The +The ``origin'' (the zero position) on the page is one inch from the top of the paper and one inch from the left side; positive horizontal measurements extend right across the page, and positive vertical measurements extend down the page. Thus, the parameters \csx{evensidemargin}, \csx{oddsidemargin} and \csx{topmargin}, should be set to be 1~inch less than the true margin; for margins closer to -the left and top edges of the page than 1 inch, the margin parameters +the left and top edges of the page than 1~inch, the margin parameters must be set to negative values. -Another surprise is that you cannot change the width or height of the -text within the document, simply by modifying the text size -parameters. The simple rule is that the parameters should only be +\Question[Q-chngmargonfly]{Changing margins ``on the fly''} + +One of the surprises characteristic of \TeX{} use is that you cannot +change the width or height of the text within the document, simply by +modifying the text size parameters; \TeX{} can't change the text width +on the fly, and \LaTeX{} only ever looks at text height when starting +a new page. + +So the simple rule is that the parameters should only be changed in the preamble of the document, i.e., before the -\cmdinvoke{begin}{document} statement. To adjust text width within a -document we define an environment: +\cmdinvoke{begin}{document} statement (so before any typesetting has +happened. + +To adjust text width within a document we define an environment: \begin{quote} \begin{verbatim} \newenvironment{changemargin}[2]{% @@ -8959,11 +9867,17 @@ document we define an environment: \item[]}{\end{list}} \end{verbatim} \end{quote} -This environment takes two arguments, and will indent the left and +The environment takes two arguments, and will indent the left and right margins, respectively, by the parameters' values. Negative values will cause the margins to be narrowed, so \cmdinvoke{begin}{changemargin}{-1cm}{-1cm} narrows the left and right -margins by 1cm. +margins by 1 centimetre. + +Given that \TeX{} can't do this, how does it work?~--- well, the +environment (which is a close relation of the \LaTeX{} +\environment{quote} environment) \emph{doesn't} change the text width +as far as \TeX{} is concerned: it merely moves text around inside the +width that \TeX{} believes in. The \Package{chngpage} package provides ready-built commands to do the above; it includes provision for changing the shifts applied to your @@ -8972,11 +9886,24 @@ two-sided document. The package's documentation (in the file itself) suggests a strategy for changing text dimensions between pages~--- as mentioned above, changing the text dimensions within the body of a page may lead to unpredictable results. + +Changing the vertical dimensions of a page is clunkier still: the +\LaTeX{} command \csx{enlargethispage} adjusts the size of the current +page by the size of its argument. Common uses are +\begin{quote} +\begin{verbatim} +\enlargethispage{\baselineskip} +\end{verbatim} +\end{quote} +to make the page one line longer, or +\begin{quote} +\begin{verbatim} +\enlargethispage{-\baselineskip} +\end{verbatim} +\end{quote} +to make the page one line shorter. \begin{ctanrefs} \item[chngpage.sty]\CTANref{chngpage} -\item[geometry.sty]\CTANref{geometry} -\item[layout.sty]Distributed as part of \CTANref{2etools} -\item[vmargin.sty]\CTANref{vmargin} \end{ctanrefs} \Question[Q-nopageno]{How to get rid of page numbers} @@ -9132,9 +10059,16 @@ of landscape typesetting: \begin{itemize} \item If you have a single floating object that is wider than it is deep, and will only fit on the page in landscape orientation, use - the \Package{rotating} package; this defines |sidewaysfigure| and - \environment{sidewaystable} environments which create floats that - occupy a whole page. + the \Package{rotating} package; this defines + \environment{sidewaysfigure} and \environment{sidewaystable} + environments which create floats that occupy a whole page. + + Note that \Package{rotating} has problems in a document that also + loads the \Package{float} package, which recommended in other + answers in these \acro{FAQ}s, for example that on + \Qref*{float placement}{Q-floats}. The \Package{rotfloat} package + loads \Package{rotating} for you, and smooths the interaction with + \Package{float}. \item If you have a long sequence of things that need to be typeset in landscape (perhaps a code listing, a wide \environment{tabbing} environment, or a huge table typeset using \Package{longtable} or @@ -9149,7 +10083,7 @@ of landscape typesetting: No currently available package makes direct provision for typesetting in both portrait and landscape orientation on the same page (it's not the sort of thing that \TeX{} is well set-up to do). If such -behaviour was an absolute necessity, one would use the techniques +behaviour was an absolute necessity, one might use the techniques described in % beware line-wrap \Qref[question]{"flowing text around figures"}{Q-textflow}, and would @@ -9168,7 +10102,8 @@ output to be properly oriented. The \Class{memoir} class has the same facilities, in this respect, as does \Package{geometry}. A word of warning: most current \TeX{} previewers do not honour -rotation requests in |.dvi| files (the exception is +rotation requests in \acro{DVI} files. +%% (the exception is %% (the exceptions are the %% \begin{htmlversion} %% (\Qref{commercial}{Q-commercial}) \YandY{} previewer @@ -9179,10 +10114,10 @@ rotation requests in |.dvi| files (the exception is %% (\Qref{}{Q-commercial}), %% \endhtmlignore %% and -the fp\TeX{} previewer Win\acro{DVI}). If your previewer is not -capable of rotation, your best bet is to convert your output to \PS{} -or to \acro{PDF}, and to view these `final' forms with an appropriate -viewer. +%% the fp\TeX{} previewer Win\acro{DVI}). If your previewer is not +%% capable of rotation, +Your best bet is to convert your output to \PS{} or to \acro{PDF}, and +to view these `final' forms with an appropriate viewer. \begin{ctanrefs} \item[geometry.sty]\CTANref{geometry} \item[graphics.sty]Distributed as part of \CTANref{graphics} @@ -9192,6 +10127,7 @@ viewer. \item[pdflscape.sty]Distributed with Heiko Oberdiek's packages \CTANref{oberdiek} \item[rotating.sty]\CTANref{rotating} +\item[rotfloat.sty]\CTANref{rotfloat} \item[supertabular.sty]\CTANref{supertabular} \end{ctanrefs} @@ -9286,7 +10222,7 @@ out by the stretchability introduced by \csx{raggedbottom}; however, it could well have an effect if \csx{flushbottom} was in effect.) An alternative (which derives from a suggestion by Knuth in the -\TeX{}book) is the package \Package{needspace} or the \Class{memoir}, +\TeX{}book) is the package \Package{needspace} or the \Class{memoir} class, which both define a command \csx{needspace} whose argument tells it what space is needed. If the space isn't available, the current page is cleared, and the matter that needs to be kept together will be @@ -9351,7 +10287,46 @@ needs some sort of alignment between the two texts. The \Package{parallel} package satisfies the need, permitting typesetting in two columns (not necessarily of the same width) on one -page, or on the two opposing pages of a two-page spread. +page, or on the two opposing pages of a two-page spread. Use can be +as simple as +\begin{quote} +\begin{verbatim} +\usepackage{parallel} +... +\begin{Parallel}{<left-width>}{<right-width} + \ParallelLText{left-text} + \ParallelRText{right-text} + \ParallelPar + ... +\end{Parallel} +\end{verbatim} +\end{quote} + +The \Package{parcolumns} package can (in principle) deal with any +number of columns: the documentation shows its use with three +columns. Usage is rather similar to that of \Package{parallel}, +though there is of course a ``number of columns to specify'': +\begin{quote} +\begin{verbatim} +\usepackage{parcolumns} +... +\begin{parcolumns}[<options>]{3} + \colchunk{<Column 1 text>} + \colchunk{<Column 2 text>} + \colchunk{<Column 3 text>} + \colplacechunks + ... +\end{parcolumns} +\end{verbatim} +\end{quote} +The \meta{options} can specify the widths of the columns, whether to +place rules between the columns, whether to set the columns sloppy, etc. + +The \Package{ledpar} package is distributed with (and integrated with) +the \Qref{\Package{ledmac} package}{Q-linenos}. It provides parallel +setting carefully integrated with the needs of a scholarly text, +permitting translation, or notes, or both, to be set in parallel with +the `base' text of the document. \begin{ctanrefs} \item[ledpar.sty]Distributed with \CTANref{ledmac} \item[parallel.sty]\CTANref{parallel} @@ -9365,10 +10340,12 @@ chapters (or even at the end of chapters: Knuth puts things at the ends of chapters of the \TeX{}book). Typesetting them is a bit of a fiddle, but not impossible to do for -yourself. However, the \Package{epigraph} package will do the job for -you, even in situations where it's particularly nasty to get right. +yourself. Fortunately, there are two packages that do the job, to +some extent; there are also facilities in the two ``big'' classes +(\Class{memoir} and \Class{koma-script}. -The package defines an \csx{epigraph} command, for creating a single +The \Package{epigraph} package defines an \csx{epigraph} command, for +creating a single epigraph (as at the top of a chapter): \begin{quote} \begin{verbatim} @@ -9413,6 +10390,12 @@ an \csx{epigraphhead}), for patching the bibliography, for patching \csx{part} pages, and so on. (Some of these suggested patches lead you through writing your own package\dots{}) +The \Package{quotchap} package redefines chapter headings (in a +moderately striking way), and provides an environment +\environment{savequotes} in which you can provide one (or more) +quotations to use as epigraphs. The facilities seem not as flexible +as those of \Package{epigraph}, but it's probably easier to use. + The \Class{memoir} class offers all the facilities of the \Package{epigraph} package. The \Class{Koma-script} classes have commands \csx{setchapterpreamble} and \csx{dictum} to provide these @@ -9421,6 +10404,7 @@ facilities. \item[epigraph.sty]\CTANref{epigraph} \item[\nothtml{\rmfamily}KOMA script bundle]\CTANref{koma-script} \item[memoir.cls]\CTANref{memoir} +\item[quotchap.sty]\CTANref{quotchap} \end{ctanrefs} \Question[Q-outszwrng]{\AllTeX{} \acro{PDF} output prints at wrong size} @@ -9775,7 +10759,7 @@ Documentation is available on the % ! line break The \ProgName{lgrind} system is another well-established pre-compiler, with all the facilities one might need and a wide repertoire of languages; it is derived from the very long-established -\ProgName{tgrind}, whose output is based on plain \TeX{} +\ProgName{tgrind}, whose output is based on Plain \TeX{} The \ProgName{tiny_c2l} system is more recent: users are encouraged to generate their own driver files for languages it doesn't already deal @@ -9833,7 +10817,7 @@ conditional constructs. These primitives can easily be redefined to produce different text in the output. However, there is no support for adding new primitives. Typesetting the pseudocode itself is performed in \Package{algorithmic}; the \Package{algorithms} package -uses the facilities of the the \Package{float} package to number +uses the facilities of the \Package{float} package to number algorithms sequentially, enable algorithms to float like figures or tables, and support including a List of Algorithms in a document's front matter. @@ -10048,10 +11032,10 @@ package files. \Question[Q-music]{Typesetting music in \TeX{}} -In the early days, a simple music package called \Package{mutex} was +In the early days, a simple music package called Mu\TeX{} was written by Angelika Schofer and Andrea Steinbach, which demonstrated -that music typesetting was possible; the package was very limited, and -is no longer available. Daniel Taupin took up the baton, and +that music typesetting was possible; the package was very limited, and is +hardly ever used nowadays. Daniel Taupin took up the baton, and developed Music\TeX{}, which allows the typesetting of polyphonic and other multiple-stave music; Music\TeX{} remains available, but is most definitely no longer recommended. @@ -10084,12 +11068,21 @@ creates input intended for Music\TeX{}. However, it should be extendable to many other types of music. Digital music fans can typeset notation for their efforts by using -\ProgName{midi2tex}, which translates MIDI data files into Music\TeX{} -source code. +\ProgName{midi2tex}, which translates \acro{MIDI} data files into +Music\TeX{} source code. There is a mailing list (\Email{TeX-music@icking-music-archive.org}) -for discussion of typesetting music in \TeX{}. To subscribe, use +for discussion of typesetting music in \TeX{}; it mostly covers +Musix\TeX{} and related systems. To subscribe, use \URL{http://icking-music-archive.org/mailman/listinfo/tex-music/} + +An alternative (free) means of embedding music examples into \AllTeX{} +documents is \href{http://www.lilypond.org}{Lilypond}. Lilypond is +(at heart) a batch music typesetting system with plain text input that +does most of its work without TeX. Lilypond's input syntax is far +less cryptic than is Musix\TeX{}'s, and it handles much more stuff +automatically, yielding the same or better quality with less effort. +Lilypond can also produce basic \acro{MIDI} oputput. \begin{ctanrefs} \item[abc2mtex]\CTANref{abc2mtex} \item[M-Tx]\CTANref{mtx} @@ -10099,6 +11092,7 @@ for discussion of typesetting music in \TeX{}. To subscribe, use version)]\CTANref{musixtex-taupin} \item[musixtex \nothtml{\rmfamily}(Egler's version)]\CTANref{musixtex-egler} +\item[mutex]\CTANref{mutex} \item[pmx]\CTANref{pmx} \end{ctanrefs} @@ -10258,7 +11252,7 @@ Documentation of \Package{ulem} is in the package file. The \texttt{cmtt} font has ``curly'' quotes\nothtml{ (\texttt{`thus'})}, which are pleasing on the eye, but don't really tally with what one sees on a modern % beware line break -\ProgName{xterm}\nothtml{ (which look like \texttt{\char18 this\char13})}. +\ProgName{xterm}\nothtml{ (which look like \texttt{\textasciigrave this\textquotesingle})}. The appearance of these quotes is critical in program listings, particularly in those of Unix-like shell scripts. The @@ -10345,7 +11339,7 @@ controlled by a number of internal commands (discussed in section~2.3 of \Qref*{\emph{The \LaTeX{} Companion}}{Q-books}. The commands \csx{@pnumwidth}, \csx{@tocrmarg} and \csx{@dotsep} control the space for page numbers, the indentation of the right-hand margin, and the -seperation of the dots in the dotted leaders, respectively. The +separation of the dots in the dotted leaders, respectively. The series of commands named \csx{l@\emph{xxx}}, where \texttt{\emph{xxx}} is the name of a sectional heading (such as \texttt{chapter} or \texttt{section}, \dots{}\@) control the layout of the corresponding @@ -10361,7 +11355,7 @@ controlled in the same way. The \Class{KOMA-Script} classes provides an optional variant structure for the table of contents, and calculates the space needed for the -numbers automatically. The \Class{memoir} includes the functionality +numbers automatically. The \Class{memoir} class includes the functionality of \Package{tocloft}. \begin{ctanrefs} \item[\nothtml{\rmfamily}KOMA script bundle]\CTANref{koma-script} @@ -10490,7 +11484,7 @@ but, as the documentation observes, mini-bibliographies are a different problem~--- see \Qref[question]{bibliographies per chapter}{Q-chapbib}. -The package's basic scheme is to generate a little |.aux| file for +The package's basic scheme is to generate a little \texttt{.aux} file for each chapter, and to process that within the chapter. Simple usage would be: \begin{quote} @@ -10499,10 +11493,12 @@ would be: ... \begin{document} ... -\tableofcontents -\dominitoc \listoffigures \dominilof ... +\dominitoc \tableofcontents +\dominilof \listoffigures +... \chapter{blah blah} -\minitoc \mtcskip \minilof ... +\minitoc \mtcskip \minilof +... \end{verbatim} \end{quote} though a lot of elaborations are possible (for example, you don't need @@ -10510,12 +11506,10 @@ a \csx{minitoc} for every chapter). \Package{Babel} doesn't know about \Package{minitoc}, but \Package{minitoc} makes provision for other document languages than -English~--- a wide variety is available. However, current versions of -the \Package{hyperref} package will treat \csx{minitoc} tables in the +English~--- a wide variety is available. Fortunately, the current +version of the \Package{hyperref} package does know about +\Package{minitoc} and treats \csx{minitoc} tables in the same way as ``real'' tables of contents. - -The documentation is pretty extensive and readable: process the file -\File{minitoc.tex} in the distribution \begin{ctanrefs} \item[babel.sty]\CTANref{babel} \item[hyperref.sty]\CTANref{hyperref} @@ -10546,7 +11540,7 @@ To create a ``general'' and an ``authors'' index, one might write: \makeindex{general} \makeindex{authors} ... -\index{authors}{Robin Fairbairns} +\index{authors}{Another Idiot} ... \index{general}{FAQs} ... @@ -10591,7 +11585,7 @@ then define an author index. Then, in the body of the document, we might find commands like: \begin{quote} \begin{verbatim} -\index[aut]{Robin Fairbairns} +\index[aut]{Another Idiot} ... \index{FAQs} \end{verbatim} @@ -10867,11 +11861,14 @@ The \Package{ntheorem} package provides roman theorems directly. \Question[Q-newfunction]{Defining a new log-like function in \LaTeX{}} Use the \csx{mathop} command, as in: +\begin{quote} \begin{verbatim} - \newcommand{\diag}{\mathop{\mathrm{diag}}} +\newcommand{\diag}{\mathop{\mathrm{diag}}} \end{verbatim} +\end{quote} -Subscripts and superscripts on \csx{diag} will be placed as they are on +Subscripts and superscripts on \csx{diag} will be placed below and +above the function name, as they are on \csx{lim}. If you want your subscripts and superscripts always placed to the right, do: \begin{quote} @@ -10888,17 +11885,25 @@ to the right, do: \end{wideversion} \end{quote} -\AMSLaTeX{} (in its \Package{amsopn} package) provides a command +\AMSLaTeX{} (in its \Package{amsopn} package, which is automatically +loaded by \Package{amsmath}) provides a command \csx{DeclareMathOperator} that takes does the same job as the first definition above. To create our original \csx{diag} command, one would say: +\begin{quote} \begin{verbatim} - \DeclareMathOperator{\diag}{diag} +\DeclareMathOperator{\diag}{diag} \end{verbatim} +\end{quote} \csx{DeclareMathOperator*} declares the operator always to have its sub- and superscripts in the % ! line break ``\Qref*{\csx{limits} position}{Q-limits}''. +The \Package{amsopn} command \csx{operatorname} allows you to +introduce \emph{ad hoc} operators into your mathematics; as with +\csx{DeclareMathOperator} there's a starred version +\csx{operatorname*} for sub- and superscripts in the limits position. + (It should be noted that ``log-like'' was reportedly a \emph{joke} on Lamport's part; it is of course clear what was meant.) \begin{ctanrefs} @@ -10932,7 +11937,7 @@ needing a \csx{middle} command, to be used in expressions like \end{narrowversion} \end{quote} to specify the set of even natural numbers. The % ! line break -\Qref*{\eTeX{} system}{Q-NTS} +\Qref*{\eTeX{} system}{Q-etex} defines just such a command, but users of Knuth's original need some support. Donald Arseneau's \Package{braket} package provides commands for set specifications (as above) and for Dirac brackets (and bras and @@ -10963,7 +11968,7 @@ is done by declaring \csx{textfont}, \csx{scriptfont} and \csx{scriptscriptfont} for the maths families you're using; all such things are described in chapter~17 of the % line wrap! \Qref*{\TeX{}book}{Q-books} and in other books and -\Qref*{tutorials}{Q-tutorials} that discuss Plain~\TeX{} in sufficient +\Qref*{tutorials}{Q-man-tex} that discuss Plain~\TeX{} in sufficient detail. In \LaTeX{}, of course, all this stuff is automated: there is a scheme @@ -11077,20 +12082,43 @@ to place the limits as one would sub- and superscripts of variables. This is not universally satisfactory, so the primitive \csx{limits} is provided: +\begin{quote} \begin{verbatim} - $\sum\limits_{n=1}^{m} ...$ +$\sum\limits_{n=1}^{m} ...$ \end{verbatim} +\end{quote} which will place the limits right above and below the symbol (and be blowed to the typography\dots{}). Contrariwise, you may wish to change the arrangement of the limits when in \csx{displaystyle}. For this purpose, there's a corresponding \csx{nolimits}: +\begin{quote} \begin{verbatim} - \[\sum\nolimits_{n=1}^{m} ...\] +\[\sum\nolimits_{n=1}^{m} ...\] \end{verbatim} +\end{quote} which will place the limits as they would be in \csx{textstyle}. +Alternatively, one can manipulate the +\csx{textstyle}/\csx{displaystyle} state of the mathematics. To get +``\csx{limits} placement'' in inline maths, +\begin{quote} +\begin{verbatim} +$\displaystyle\sum_{n=1}^{m} ...$ +\end{verbatim} +\end{quote} +and for ``\csx{nolimits} placement'' in display maths, +\csx{nolimits}: +\begin{quote} +\begin{verbatim} +\[\textstyle\sum_{n=1}^{m} ...\] +\end{verbatim} +\end{quote} +will serve. Either of these forms may have effects other than on the +operator you're considering, but there are still those who prefer this +formulation. + (Note that the macro \csx{int} normally has \csx{nolimits} built in to its definition. There is an example in the \TeX{}book to show how odd \csx{int}\csx{limits} looks when typeset.) @@ -11211,7 +12239,7 @@ command from the \Package{mathtools} package: \end{verbatim} \end{quote} To have the text on the same line as the second equation, one can use -the the \environment{flalign} environment (from \Package{amsmath}) +the \environment{flalign} environment (from \Package{amsmath}) with lots of dummy equations (represented by the double \texttt{\&} signs): \begin{quote} @@ -11272,6 +12300,59 @@ at \URL{ftp://ftp.ams.org/pub/tex/doc/amsmath/amsldoc.pdf} \CTANref{amslatex} \end{ctanrefs} +\Question[Q-brkinline]{Line-breaking in in-line maths} + +\TeX{}, by default, allows you to split a mathematical expression at +the end of the line; it allows breaks at relational operators (like +``='', ``\textless'', etc.) and at binary operators (like ``+'', +``-'', etc.). In the case of large expressions, this can sometimes be +a life-saver. + +However, in the case of simple expressions like \ensuremath{a=b+c}, a +break can be really disturbing to the reader, and one would like to +avoid it. + +Fortunately, these breaks are controllable: there are ``penalties'' +associated with each type of operator: the penalty + says how +undesirable a break at each point is. Default values are: +\begin{quote} +\begin{verbatim} +\relpenalty = 500 +\binoppenalty = 700 +\end{verbatim} +\end{quote} +You make the break progressively less attractive by increasing these +values. You can actually forbid all breaks, everywhere, by: +\begin{quote} +\begin{verbatim} +\relpenalty = 10000 +\binoppenalty = 10000 +\end{verbatim} +\end{quote} +If you want just to prevent breaks in a single expression, write: +\begin{quote} +\begin{verbatim} +{% + \relpenalty = 10000 + \binoppenalty = 10000 + $a=b+c$ +} +\end{verbatim} +\end{quote} +and the original values will remain undisturbed outside the braces. +This is tedious: there is often value in an alternative approach, +in which you say which parts of the expression may not break whatever +happens, and fortunately this is surprisingly easy. Suppose we want +to defer a break until after the equality, we could write: +\begin{quote} +\begin{verbatim} +${a+b+c+d} = z+y+x+w$ +\end{verbatim} +\end{quote} +The braces say ``treat this subformula as one atom'' and (in \TeX{} at +least) atoms don't get split: not a \csx{binoppenalty} change in sight. + \subsection{Lists} \Question[Q-enumerate]{Fancy enumeration lists} @@ -11282,7 +12363,7 @@ the \environment{enumerate} environment, which is used to specify the layout of the labels. The layout parameter contains an enumeration type (`\texttt{1}' for arabic numerals, `\texttt{a}' or `\texttt{A}' for alphabetic enumeration, and `\texttt{i}' or `\texttt{I}' for Roman -numberals), and things to act as decoration of the enumeration. So, +numerals), and things to act as decoration of the enumeration. So, for example \begin{quote} \begin{verbatim} @@ -11379,11 +12460,12 @@ The \Class{memoir} class includes functions that match those in the \Qref*{Lamport's book}{Q-books} lists various parameters for the layout of list (things like \csx{topsep}, \csx{itemsep} and \csx{parsep}), but fails to mention that they're set -automatically within the list itself. It works by each list executes -a command \csx{@list}\texttt{\meta{depth}} (the depth appearing as a -lower-case roman numeral); what's more, \csx{@listi} is usually reset -when the font size is changed. As a result, it's rather tricky for -the user to control list spacing; of course, the real answer is to use +automatically within the list itself. This happens because each list +executes a command \csx{@list}\texttt{\meta{depth}} (the depth +appearing as a lower-case roman numeral); what's more, the top-level +\csx{@listi} is usually reset when the font size is changed. As a +result, it's rather tricky for +the user to control list spacing. Of course, the real answer is to use a document class designed with more modest list spacing, but we all know such things are hard to come by. The \Class{memoir} class wasn't designed for more compact lists \emph{per se}, but offers the user @@ -11429,6 +12511,13 @@ does. (\environment{asparaitem}, etc.), and \environment{description} equivalents (\environment{asparadesc}, etc.). +The \Package{multenum} package offers a more regular form of +\Package{paralist}'s \environment{inparaenum}; you define a notional +grid on which list entries are to appear, and list items will always +appear at positions on that grid. The effect is somewhat like that of +the `tab' keys on traditional typewriters; the package was designed +for example sheets, or lists of answers in the appendices of a book. + The ultimate in compaction (of every sort) is offered by the \Package{savetrees} package; compaction of lists is included. The package's prime purpose is to save space at every touch and turn: @@ -11456,28 +12545,13 @@ for example, one might write to suppress all spacing above and below your list. \Package{Enumitem} also permits manipulation of the label format in a more ``basic'' manner than the \Qref*{\Package{enumerate} package}{Q-enumerate} does. -%% If you want to adjust \csx{topsep}, the most sensible approach (at -%% present) is to define your list `from first principles' using the -%% \csx{list} command; its invocation is -%% % beware line break -%% \cmdinvoke{list}{\meta{item stuff}}{\meta{list stuff}}; the -%% \texttt{\meta{list stuff}} is executed \emph{after} the -%% \csx{@list}\texttt{\meta{depth}}, and can therefore be used to adjust -%% all the parameters, including \csx{topsep}. -%% -%% An alternative is to redefine \csx{@list}\texttt{\meta{depth}} (and the -%% size-changing commands that alter \csx{@listi}), but this is not -%% recommended unless you're building your own class or package, in which -%% case one hopes you're capable of analysing the way in which the -%% standard classes do things (as recommended in -%% % beware line wrap -%% \Qref[question]{writing your own package}{Q-writecls}). \begin{ctanrefs} \item[enumerate.sty]Distributed as part of \CTANref{2etools} \item[enumitem.sty]\CTANref{enumitem} \item[expdlist.sty]\CTANref{expdlist} \item[memoir.cls]\CTANref{memoir} \item[mdwlist.sty]Distributed as part of \CTANref{mdwtools} +\item[multenum.sty]\CTANref{multenum} \item[paralist.sty]\CTANref{paralist} \item[savetrees.sty]\CTANref{savetrees} \end{ctanrefs} @@ -11724,7 +12798,68 @@ read the documentation, since usage is distinctly odd. \begin{ctanrefs} \item[ltxtable.sty]Distributed as part of \CTANref{carlisle} \item[tabularx.sty]Distributed as part of \CTANref{2etools} -\item[tabulary.sty]Distributed as part of \CTANref{carlisle} +\item[tabulary.sty]\CTANref{tabulary} +\end{ctanrefs} + +\Question[Q-varwidcol]{Variable-width columns in tables} + +This is a slightly different take on the problem addressed in +``\Qref*[question]{fixed-width tables}{Q-fixwidtab}''~--- here we have +a column whose size we can't absolutely predict when we design the +document. + +While the basic techniques (the \Package{tabularx}, \Package{tabulary} +and \Package{ltxtable} packages) are the same for this problem as for the +fixed-width \emph{table} problem, there's one extra tool that we can +call to our aid, which may be preferable in some situations. + +Suppose we have data in one column which we read from an external +source, and the source itself isn't entirely predictable. The data in +the column may end up pretty narrow in every row of the table, or it +may be wide enough that the table would run over the edge of the page; +however, we don't want to make the column as wide as possible ``just +in case'', by defining a fixed size for the table. We would like the +column to be as small as possible, but have the possibility to spread +to a maximum width and (if even that width is exceeded) turn into a +\texttt{p}-style column. + +The \Package{varwidth} package, discussed in % ! line break +``\Qref*[question]{automatic sizing of minipages}{Q-varwidth}'', provides +a solution. If you load it together with the \LaTeX{} ``required'' +\Package{array} package, i.e.: +\begin{quote} +\begin{verbatim} +\usepackage{array} +\usepackage{varwidth} +\end{verbatim} +\end{quote} +\Package{varwidth} defines a new column-type ``\texttt{V}'', which you +can use as follows: +\begin{quote} +\begin{verbatim} +\begin{tabular}{l V{3.5cm} r} + foo & blah & bar \\ + foo & blah blah & bar \\ +\end{tabular} +\end{verbatim} +\end{quote} +when the second column ends up less than 3.5cm wide; +or you can use it as follows: +\begin{quote} +\begin{verbatim} +\begin{tabular}{l V{3.5cm} r} + foo & blah & bar \\ + foo & blah blah & bar \\ + foo & blah blah blah blah blah blah + & bar \\ +\end{tabular} +\end{verbatim} +\end{quote} +where the second column will end up noticeably wider, and will wrap to +a second line in the third row. +\begin{ctanrefs} +\item[array.sty]Distributed as part of \CTANref{2etools} +\item[varwidth.sty]\CTANref{varwidth} \end{ctanrefs} \Question[Q-struttab]{Spacing lines in tables} @@ -11750,12 +12885,14 @@ may be simply translated to Plain~\TeX{} commands. If your table exhibits a systematic problem (i.e., every row is wrong by the same amount) use \csx{extrarowheight}, which is defined by the \Package{array} package: +\begin{quote} \begin{verbatim} \usepackage{array}% in the preamble ... \setlength{\extrarowheight}{length} \begin{tabular}{....} \end{verbatim} +\end{quote} To correct a single row whose maladjustment isn't corrected by a \csx{strut} command, you can define your own, using @@ -11772,6 +12909,24 @@ each row. Its disadvantages are that it's really rather slow in operation (since it gets in the way of everything within tables) and its (lack of) compatibility with other packages. +The \Package{cellspace} does a (possibly inferior) job by defining a +new table/array column type ``S'', which you apply to each column +specification. So, for example, +\begin{quote} +\begin{verbatim} +\cmdinvoke{begin}{tabular}{l l l p{3cm}} +\end{verbatim} +\end{quote} +would become +\begin{quote} +\begin{verbatim} +\cmdinvoke{begin}{tabular}{Sl Sl Sl Sp{3cm}} +\end{verbatim} +\end{quote} +and so on. This technique shows +promise of not interfering so much with other packages, but this +author has heard of no reports from the field. + The \Package{booktabs} package comes with a thought-provoking essay about how tables should be designed. Since table row-spacing problems most often appear in collisions with rules, the author's thesis, @@ -11787,6 +12942,7 @@ found as comments in the package files themselves. \item[array.sty]Distributed as part of \CTANref{2etools} \item[bigstrut.sty]Distributed as part of \CTANref{multirow} \item[booktabs.sty]\CTANref{booktabs} +\item[cellspace.sty]\CTANref{cellspace} \item[tabls.sty]\CTANref{tabls} \end{ctanrefs} @@ -11914,8 +13070,6 @@ which may be incorporated into a simple macro as: \begin{quote} \begin{verbatim} \newcommand{\RBS}{\let\\=\tabularnewline} -... -... & \centering\RBS blah ... \\ \end{verbatim} \end{quote} and used as @@ -11992,7 +13146,7 @@ define it for yourself. \begin{ctanrefs} \item[array.sty]Distributed as part of \CTANref{2etools} \item[tabularx.sty]Distributed as part of \CTANref{2etools} -\item[tabulary.sty]Distributed as part of \CTANref{carlisle} +\item[tabulary.sty]\CTANref{tabulary} \end{ctanrefs} \nothtml{\vskip 0pt plus 4ex} @@ -12010,10 +13164,11 @@ technique for making any one rule stand out, and a little experimentation shows that it is indeed pretty difficult to prevent a change ``bleeding'' out to affect other rules in the same table. -Refer to the answer on \Qref*{design of tables}{Q-destable}, elsewhere +If you look at what we have to say on the % ! line break +\Qref*{design of tables}{Q-destable}, elsewhere among these \acro{FAQ}s, and you may sense that the design of \LaTeX{} -suimply skipped the issues surrounding table design, and \emph{that's} -why there's no facilities to help you. +simply skipped the issues surrounding table design: \emph{that's} +presumably why there's no facilities to help you. Specifically, the length \csx{arrayrulewidth} affects the thickness of the rules (both horizontal and vertical) within both @@ -12070,8 +13225,9 @@ conducted a survey of the available packages; he recommends: \end{htmlversion} \htmlignore |\begin{floatingfigure}[|\emph{options}|]{|\emph{width of figure}|}|\\ - | |\emph{figure contents}\\ - |\end{floatingfigure}| \endhtmlignore +| |\emph{figure contents}\\ +|\end{floatingfigure}| +\endhtmlignore There is a (more or less similar) \environment{floatingtable} environment. @@ -12084,24 +13240,23 @@ in the neighbourhood of list environments (unless you change your \LaTeX{} document). \item[\texttt{wrapfig}] \Package{wrapfig} has syntax: -\begin{htmlversion} +\begin{wideversion} +\begin{quote} \begin{verbatim} -\begin{wrapfigure}[height of figure in lines]{l|r}[overhang]{width} +\begin{wrapfigure}[height of figure in lines]{l|r,...}[overhang]{width} figure, caption, etc. \end{wrapfigure} \end{verbatim} -\end{htmlversion} -\htmlignore \ifpdf - |\begin{wrapfigure}[|\emph{height of figure in lines}|]|% - |{l|,|r|,\emph{etc}|}|\\ - | [|\emph{overhang}|]{|\emph{width}|}|\\ - \else - |\begin{wrapfigure}[|\emph{height of figure in lines}|]|\\ - | {l|,|r|,\emph{etc}|}[|\emph{overhang}|]{|\emph{width}|}|\\ - \fi - | |\emph{figure, caption, etc.}\\ - |\end{wrapfigure}| \endhtmlignore - +\end{quote} +\end{wideversion} +\begin{narrowversion} + \begin{quote} + |\begin{wrapfigure}[|\emph{height of figure in lines}|]|\\ + | {l|,|r|,\emph{etc}|}[|\emph{overhang}|]{|\emph{width}|}|\\ + | |\emph{figure, caption, etc.}\\ + |\end{wrapfigure}| + \end{quote} +\end{narrowversion} The syntax of the \environment{wraptable} environment is similar. Height can be omitted, in which case it will be calculated by the @@ -12121,29 +13276,28 @@ in the neighbourhood of list environments (unless you change your various \MSDOS{} formats, etc.). The command is: \begin{htmlversion} - |\parpic(width,height)(x-off,y-off)[Options][Position]{Picture}|\\ + \begin{quote} + |\parpic(width,height)(x-off,y-off)[Options][Position]{Picture}|\\ + \end{quote} + \emph{Paragraph text} \end{htmlversion} -\htmlignore \ifpdf +\htmlignore +\ifpdf |\parpic(|\emph{width}|,|\emph{height}|)(|\emph{x-off}\kern-.125em|,|\emph{y-off}|)|% |[|\emph{Options}|][|\emph{Position}|]|\\ - \else +\else |\parpic(|\emph{width}|,|\emph{height}|)(|\emph{x-off}\kern-.125em|,|\emph{y-off}|)|\\ | [|\emph{Options}|][|\emph{Position}|]|\\ - \fi +\fi | {|\emph{Picture}|}|\\ - \endhtmlignore \emph{Paragraph text} + \emph{Paragraph text} +\endhtmlignore All parameters except the \emph{Picture} are optional. The picture can be positioned left or right, boxed with a rectangle, oval, shadowbox, dashed box, and a caption can be given which will be included in the list of figures. -% This is the only package that I tried that correctly works inside an -% enumerate/itemize item. It does not, however work with -% enumerate/itemize besides the picture (i.e. started after the \parpic -% command) but neither does any of the other packages as far as I could -% discern. - Unfortunately (for those of us whose understanding of German is not good), the documentation is in German. Piet van Oostrum has written an English summary. @@ -12284,7 +13438,7 @@ might write: \begin{verbatim} \begin{tabular}{|c|c|} \hline -\multirow{4}*{Common g text} +\multirow{4}{*}{Common g text} & Column g2a\\ & Column g2b \\ & Column g2c \\ @@ -12325,7 +13479,7 @@ down one or other side of a table (with the help of the \begin{verbatim} \begin{tabular}{|l|l|} \hline -\multirow{4}*{\rotatebox{90}{hi there}} +\multirow{4}{*}{\rotatebox{90}{hi there}} & Column g2a\\ & Column g2b \\ & Column g2c \\ @@ -12854,14 +14008,14 @@ The \Package{footmisc} package provides a variety of means of controlling footnote appearance, among them a package option \pkgoption{perpage} that adjusts the numbering per page. -Documentation of \Package{footnpag} comes as a |.dvi| file +Documentation of \Package{footnpag} comes as a \acro{DVI} file \File{footnpag-user} in the distribution. Documentation of \Package{perpage} appears in the package file, only: however, it amounts to no more than appears above\dots \begin{ctanrefs} \item[footmisc.sty]\CTANref{footmisc} \item[footnpag.sty]\CTANref{footnpag} -\item[perpage.sty]\CTANref{perpage} +\item[perpage.sty]Distributed as part \CTANref{bigfoot} \end{ctanrefs} \subsection{Document management} @@ -12874,9 +14028,9 @@ footer recording what file is being processed. It's not easy\dots{} \TeX{} retains what it considers the name of the \emph{job}, only, in the primitive \csx{jobname}; this is the name of the file first handed to \TeX{}, stripped of its directory name and of any extension -(such as |.tex|). If no file was passed (i.e., you're using \TeX{} -interactively), \csx{jobname} has the value |texput| (the name that's -given to |.log| files in this case). +(such as \texttt{.tex}). If no file was passed (i.e., you're using +\TeX{} interactively), \csx{jobname} has the value \texttt{texput} +(the name that's given to \texttt{.log} files in this case). This is fine, for the case of a small document, held in a single file; most significant documents will be held in a bunch of files, and @@ -12887,36 +14041,78 @@ file name. This is particularly difficult in the case of Plain \TeX{}, since the syntax of the \csx{input} command is so peculiar. In the case of \LaTeX{}, the input commands have pretty regular -syntax, and the simplest -% beware line-breaks (next two lines) -\nothtml{patching techniques (}% -\Qref{patching techniques}{Q-patch}\nothtml{)} can be used on them: -\begin{verbatim} - \def\ThisFile{\jobname} - \newcounter{FileStack} - \let\OrigInput\input - \renewcommand{\input}[1]{% - \stepcounter{FileStack} - \expandafter\let - \csname NameStack\theFileStack\endcsname - \ThisFile - \def\ThisFile{#1}% - \OrigInput{#1}% - \expandafter\let\expandafter - \ThisFile - \csname NameStack\theFileStack\endcsname - \addtocounter{FileStack}{-1}% - } +syntax, and the simplest \Qref*{patching techniques}{Q-patch} can be +used on them. + +If you're not inputting things from a file that's already been input, +the job is almost trivial: +\begin{quote} +\begin{verbatim} +\def\ThisFile{\jobname} +\let\OldInput\input +\renewcommand{\input}[1]{% + \renewcommand{\ThisFile}{#1}% + \OldInput{#1}% +} +\end{verbatim} +\end{quote} +With that, the macro \csx{ThisFile} always contains the last thing +input: it starts pointing at the base file of your document +(\csx{jobname}), and thereafter changes every time you use +\cmdinvoke*{input}{file}. + +Most ordinary users will quickly become irritated with the simplicity +of of the \csx{ThisFile} mechanism above. The following code is more +cunning: it maintains details of the files you've `come through' to +get to where you are, and it restores \csx{ThisFile} to what the +previous file was before returning. +\begin{quote} +\begin{verbatim} +\def\ThisFile{\jobname} +\newcounter{FileStack} +\let\OrigInput\input +\renewcommand{\input}[1]{% + \stackinput{#1}{\OrigInput}% +} +\newcommand{\stackinput}[2]{% + \stepcounter{FileStack}% + \expandafter\let + \csname NameStack\theFileStack\endcsname + \ThisFile + \def\ThisFile{#1}% + #2{#1}% + \expandafter\let\expandafter + \ThisFile + \csname NameStack\theFileStack\endcsname + \addtocounter{FileStack}{-1}% +} \end{verbatim} -(And similarly for \csx{include}.) The code assumes you always use -\LaTeX{} syntax for \csx{input}, i.e., always use braces around the -argument. +\end{quote} +To do the same for \csx{include}, we need the simple addition: +\begin{quote} +\begin{verbatim} +\let\OrigInclude\include +\renewcommand{\include}[1]{% + \stackinput{#1}{\OrigInclude}% +} +\end{verbatim} +\end{quote} +Both examples of patching \csx{input} assume you always use +\LaTeX{} syntax, i.e., always use braces around the argument. The \Package{FiNK} (``File Name Keeper'') package provides a regular means of keeping track of the current file name (with its -extension), in a macro \csx{finkfile}. The bundle includes a -\File{fink.el} that provides support under \ProgName{emacs} with -\acro{AUC}-\TeX{}. +extension), in a macro \csx{finkfile}. If you need the unadorned file +name (without its `\texttt{.tex}'), use the commands: +\begin{quote} +\begin{verbatim} +\def\striptexext#1.tex{#1} +... +\edef\ThisFile{\expandafter\stripext\finkfile} +\end{verbatim} +\end{quote} +The \Package{FiNK} bundle includes a \File{fink.el} that provides +support under \ProgName{emacs} with \acro{AUC}-\TeX{}. \begin{ctanrefs} \item[fink.sty]\CTANref{fink} \end{ctanrefs} @@ -12957,7 +14153,7 @@ has application in document exchange situations too. The \ProgName{bundledoc} system uses the \Package{snapshot} to produce an archive (e.g., \texttt{.tar.gz} or \texttt{.zip}) of the files needed by your document; it comes with configuration files for use with -\ProgName{teTeX} and \ProgName{mikTeX}. It's plainly useful when +\ProgName{teTeX} and \ProgName{\miktex{}}. It's plainly useful when you're sending the first copy of a document. \begin{ctanrefs} \item[bundledoc]\CTANref{bundledoc} @@ -12989,10 +14185,10 @@ which uses \csx{special} commands supplied by the driver you're using. You need therefore to tell the package which driver to generate \csx{special}s for (in the same way that you need to tell the \Package{graphics} package); the list of available drivers is pretty -restricted, but does include \ProgName{dvips}. The package comes with +wide, but does not include \ProgName{dvipdfm}. The package comes with a shell script \ProgName{chbar.sh} (for use on Unix machines) that will compare two documents and generate a third which is marked-up -with \Package{changebar} macros to highlight changes. The (excellent) +with \Package{changebar} macros to highlight changes. The shareware \ProgName{WinEDT} editor has a macro that will generate \Package{changebar} (or other) macros to show differences from an earlier version of your file, stored in an @@ -13000,9 +14196,13 @@ earlier version of your file, stored in an \URL{http://www.winedt.org/Macros/LaTeX/RCSdiff.php} The \Package{vertbars} package uses the techniques of the -\Package{lineno} package (which must be present); it's thus the -smallest of the packages for change bar marking, since it leaves all -the trickery to another package. The \Package{framed} package is +\Package{lineno} package (which it loads, so the \Package{lineno} +itself must be installed); it's thus the smallest of the packages for +change bar marking, since it leaves all the trickery to another +package. \Package{Vertbars} defines a \environment{vertbar} +environment to create changebars. + +The \Package{framed} package is another that provides bars as a side-effect of other desirable functionality: its \environment{leftbar} environment is simply a stripped-down frame (note, though, that the environment makes a @@ -13025,7 +14225,7 @@ visible. An example of the output is embedded in the documentation, \href{http://www.tex.ac.uk/tex-archive/support/latexdiff/latexdiff-man.pdf}{latexdiff-man.pdf} (part of the distribution). \end{wideversion} -A rudimentary revision facilility is provided by another +A rudimentary revision facility is provided by another \ProgName{Perl} script, \ProgName{latexrevise}, which accepts or rejects all changes. Manual editing of the difference file can be used to accept or reject selected changes only. @@ -13064,9 +14264,9 @@ use \verb|\iftrue| -- a surprise \end{quote} The \csx{iftrue} is spotted by \TeX{} as it scans, ignoring the \csx{verb} command; so the \csx{iffalse} isn't terminated by the -following \csx{fi}. Also, \csx{gobble} is pretty inefficient for any -but trivial arguments, since all the matter to be skipped is copied to -the argument stack before being ignored. +following \csx{fi}. Also, \csx{gobble} is pretty inefficient at +consuming anything non-trivial, since all the matter to be skipped is +copied to the argument stack before being ignored. If your requirement is for a document from which whole chapters (or the like) are missing, consider the \LaTeX{} @@ -13301,14 +14501,14 @@ of what you want, and some people prefer it; it is explicitly compatible with \ProgName{LaTeX2HTML}. If, however, you need a solution which works without using external -packages, or which will work in plain TeX, then you can use the +packages, or which will work in Plain \TeX{}, then you can use the following minimal solution: \begin{quote} \begin{wideversion} \begin{verbatim} \def\RCS$#1: #2 ${\expandafter\def\csname RCS#1\endcsname{#2}} -\RCS$Revision: 1.299 $ % or any RCS keyword -\RCS$Date: 2005/07/07 13:52:16 $ +\RCS$Revision: 1.409 $ % or any RCS keyword +\RCS$Date: 2006/10/05 07:24:34 $ ... \date{Revision \RCSRevision, \RCSDate} \end{verbatim} @@ -13318,8 +14518,8 @@ following minimal solution: \def\RCS$#1: #2 ${\expandafter \def\csname RCS#1\endcsname{#2}% } -\RCS$Revision: 1.299 $ % or any RCS keyword -\RCS$Date: 2005/07/07 13:52:16 $ +\RCS$Revision: 1.409 $ % or any RCS keyword +\RCS$Date: 2006/10/05 07:24:34 $ ... \date{Revision \RCSRevision, \RCSDate} \end{verbatim} @@ -13380,8 +14580,7 @@ solution (and was used in generating printable versions of these many bells and whistles that allow it to operate as if it were a poor man's \WYSIWYG{} system. -The \nothtml{\Package{texinfo} system (}% beware line breaks -\Qref{\Package{texinfo} system}{Q-texinfo}\nothtml{)} comes with a +The \Qref*{\Package{texinfo} system}{Q-texinfo} comes with a utility called \ProgName{texi2dvi}, which is capable of ``converting'' either \LaTeX{} or \Package{texinfo} files into \acro{DVI} (or into \acro{PDF}, using \PDFTeX{}). @@ -13419,7 +14618,7 @@ Package \Package{totpages} defines a label \texttt{TotPages}, but it also makes the register it uses available as a \LaTeX{} counter, \texttt{TotPages}, which you can also reference via \csx{theTotPages}. Of course, the counter |TotPages| is asynchronous in the same way that -apge numbers are, but snapshots may safely be taken in the output +page numbers are, but snapshots may safely be taken in the output routine. The \Class{memoir} class defines two counters \texttt{lastpage} and @@ -13453,11 +14652,13 @@ not practical in many circumstances, and for those occasions, the \Package{plain} package will often come to your aid. The package defines a \environment{plain} environment, in which a Plain \TeX{} document may be processed: +\begin{quote} \begin{verbatim} \begin{plain} \input{plain-doc} \end{plain} \end{verbatim} +\end{quote} The package is known to fail, for example, with documents that use \AMSTeX{}; no doubt it would also fail if asked to load \Eplain{}. All these things can be overcome (although it's not often easy), but @@ -13499,9 +14700,11 @@ So what else can go wrong? English typesetting style (it may not be correct for other languages), but if needs must, you can replace the hyphen in the name with a \csx{hyph} command, defined +\begin{quote} \begin{verbatim} - \def\hyph{\penalty0\hskip0pt\relax} +\def\hyph{-\penalty0\hskip0pt\relax} \end{verbatim} +\end{quote} This is \emph{not} the sort of thing this \acro{FAQ} would ordinarily recommend\dots{} The \Package{hyphenat} package defines a bundle of such commands (for introducing hyphenation points at @@ -13595,16 +14798,23 @@ by adding the command \usepackage[T1]{fontenc} \end{verbatim} to the preamble of their document. Other encodings (notably -\acro{LY}1, once promoted by \YandY{} inc) -%% ~--- see -%% %beware line wrap -%% \Qref[question]{commercial implementations}{Q-commercial}) -may be used +\acro{LY}1, once promoted by \YandY{} inc) may be used in place of \acro{T}1. Indeed, most current 8-bit \TeX{} font encodings will `work' with the relevant sets of hyphenation patterns. -In the future, perhaps, \Qref*{Omega}{Q-omega} will provide a rather -different solution. +One might hope that, with the many aspirant successors to \TeX{} such +as +\begin{wideversion} + \Qref{Omega}{Q-omegaleph}, \Qref{\acro{LUA}\TeX{}}{Q-luatex} and + \Qref{Ex\TeX{}}{Q-extex}, +\end{wideversion} +\begin{narrowversion} + Omega, \acro{LUA}\TeX{} and Ex\TeX{} + (\Qref[see questions]{}{Q-omegaleph}\Qref[,]{}{Q-luatex} + \Qref[and]{}{Q-extex}), +\end{narrowversion} +all of which base their operations on Unicode, that the whole basis of +encodings will change. \Question[Q-newlang]{Using a new language with Babel} @@ -13625,12 +14835,14 @@ Package babel Warning: No hyphenation patterns were loaded for \end{wideversion} \begin{narrowversion} \begin{verbatim} -Package babel Warning: No hyphenation patterns were loaded for +Package babel Warning: No hyphenation patterns + were loaded for (babel) the language `Catalan' -(babel) I will use the patterns loaded for - \language=0 instead. +(babel) I will use the patterns + loaded for \language=0 instead. \end{verbatim} -(The last line of the above has been wrapped to fit on the page.) +(The first and third lines above have been wrapped to fit in the +column.) \end{narrowversion} The problem is that your \TeX{} system doesn't know how to hyphenate @@ -13682,17 +14894,10 @@ texconfig hyphen latex \texttt{fmtutil -\relax-byhyphen \meta{hyphenfile}}\\ where \emph{\texttt{hyphenfile}} is the file specifying hyphenation to the format~--- usually \texttt{language.dat} -\item[fp\TeX{}] Click - \texttt{Start}\arrowhyph{}% - \texttt{Programs}\arrowhyph{}% - \texttt{MikTeX}\arrowhyph{}% - \texttt{Maintenance}\arrowhyph{}% - \texttt{Create all format files}, or run any of the te\TeX{} options - in a windows command window. -\item[MiK\TeX{}] On a \Package{MikTeX} distribution earlier than v2.0, do: \\ +\item[\miktex{}] On a \Package{\miktex{}} distribution earlier than v2.0, do: \\ \texttt{Start}\arrowhyph{}% \texttt{Programs}\arrowhyph{}% - \texttt{MikTeX}\arrowhyph{}% + \texttt{\miktex{}}\arrowhyph{}% \texttt{Maintenance}\arrowhyph{}% \texttt{Create all format files} % this sequence suggested for miktex 1.20e, 2000/12/22, by Giuseppe Bilotta @@ -13700,13 +14905,13 @@ texconfig hyphen latex or get a DOS window and run:\\ \texttt{initexmf -\relax-dump} - On a \Package{MikTeX} distribtution v2.0 or later, the whole + On a \Package{\miktex{}} distribtution v2.0 or later, the whole procedure can be done via the \acro{GUI}. To select the new language, do:\\ \texttt{Start}\arrowhyph{}% \texttt{Programs}\arrowhyph{}% - \texttt{MikTeX 2}\arrowhyph{}% - \texttt{MikTeX Options}, and select the \texttt{Languages} tab. + \texttt{\miktex{} 2}\arrowhyph{}% + \texttt{\miktex{} Options}, and select the \texttt{Languages} tab. Select your language from the list, press the \texttt{Apply} button, and then the \texttt{OK} button. Then select the \texttt{General} tab and press the \texttt{Update Now} button. @@ -13759,18 +14964,20 @@ hyphenation. Third, one can set \csx{left-} and/or \csx{righthyphenmin} to a sufficiently large value that no hyphenation could possibly succeed, -since the minimum is larger than the the length of the longest word +since the minimum is larger than the length of the longest word \TeX{} is willing to hyphenate (the appropriate value is 62). Fourth, one can suppress hyphenation for all text using the current font by the command +\begin{quote} \begin{verbatim} - \hyphenchar\font=-1 +\hyphenchar\font=-1 \end{verbatim} +\end{quote} This isn't a particularly practical way for users to suppress hyphenation~--- the command has to be issued for every font the document uses~--- but it's how \LaTeX{} itself suppresses hyphenation -in |tt| and other fixed-width fonts. +in \texttt{tt} and other fixed-width fonts. Which of the techniques you should use depends on what you actually want to do. If the text whose hyphenation is to be suppressed runs @@ -13794,9 +15001,7 @@ and underfull lines. To avoid this you have two options. You may use have \TeX{} stretch what would otherwise be underfull lines to fill the space offered, and wrap other lines, while prematurely wrapping overfull lines and stretching the remainder. Alternatively, you may set the -text \nothtml{ragged right (}% -% beware line wrap -\Qref{ragged right}{Q-ragright}\nothtml{)}, and at least get rid of +text \Qref*{ragged right}{Q-ragright}, and at least get rid of the overfull lines; this technique is `traditional' (in the sense that typists do it) and may be expected to appeal to the specifiers of eccentric document layouts (such as those for dissertations), but for @@ -13813,30 +15018,36 @@ to seem ``completely wrong'', so that you want to prevent it being hyphenated. If the word occurs in just one place, put it in a box: +\begin{quote} \begin{verbatim} - \mbox{oddword} +\mbox{oddword} \end{verbatim} +\end{quote} (Plain~\TeX{} users should use \csx{hbox}, and take care at the start of paragraphs.) However, boxing the word is not really advisable unless you are sure it only occurs once. If the word occurs commonly, the best choice is to assert a non-hyphenation for it: +\begin{quote} \begin{verbatim} - \hyphenation{oddword} +\hyphenation{oddword} \end{verbatim} +\end{quote} This hyphenation exception (with no break points) will be used in preference to what \TeX{}'s hyphenation algorithm may come up with. In a multilingual document, repeat the exception specification for each language the word may appear in. So: +\begin{quote} \begin{verbatim} - \usepackage[french,english]{babel} - \selectlanguage{english} - \hyphenation{oddword} - \selectlanguage{french} - \hyphenation{oddword} +\usepackage[french,english]{babel} +\selectlanguage{english} +\hyphenation{oddword} +\selectlanguage{french} +\hyphenation{oddword} \end{verbatim} +\end{quote} (note that \Package{babel} will select the default language for the document~--- English, in this case~--- at \cmdinvoke{begin}{document}.) @@ -13844,7 +15055,7 @@ document~--- English, in this case~--- at \cmdinvoke{begin}{document}.) While \TeX{}'s hyphenation rules are good, they're not infallible: you will occasionally find words \TeX{} just gets \emph{wrong}. So for -example, \TeX{}'s default hyphenation (for American English) don't +example, \TeX{}'s default hyphenation rules (for American English) don't know the word ``\emph{manuscript}'', and since it's a long word you may find you need to hyphenate it. You \emph{can} ``write the hyphenation out'' each time you use the word: @@ -13972,10 +15183,6 @@ for \PiCTeX{}, \texttt{Bib}\cmdinvoke{TeX}{} (Bib\TeX{}) \endhtmlignore for \BibTeX{}, and so on. - -While the author of this FAQ list can't quite bring himself to do away -with the bumpy-road logos herein, he regularly advises everyone else -to\dots{} \begin{ctanrefs} \item[mflogo.sty]\CTANref{mflogo} \item[texnames.sty]\CTANref{texnames} @@ -14011,14 +15218,21 @@ fonts, since there are no Type~1 versions of the \Package{mf-extra} set. There are, however, Type~1 distributions of the EC~fonts, so you can switch to EC and use them; alternatives are discussed in \Qref[question]{8-bit Type~1 fonts}{Q-type1T1}. + Of course, commercial fixed-width fonts (even the default \FontName{Courier}) almost always come with a bold variant, so that's not a problem. Furthermore \Qref*{\acro{PSNFSS}}{Q-usepsfont} will usually provide ``faked'' small caps fonts, and has no -compunctions about providing them in a bold form. +compunctions about providing them in a bold form. \FontName{Courier} +is (as we all know, to our cost) freely available; a far more +presentable monospace font is \FontName{LuxiMono}, which is also +freely available (monospace text in the typeset version of this +\acro{FAQ} uses \FontName{LuxiMono}, with the metrics and \LaTeX{} +support available on the archive. \begin{ctanrefs} \item[bold-extra.sty]\CTANref{bold-extra} \item[bold tt and small caps fonts]\CTANref{bold} +\item[\nothtml{rmfamily}LuxiMono fonts]\CTANref{luximono} \end{ctanrefs} \Question[Q-varwidth]{Automatic sizing of \environment{minipage}} @@ -14245,7 +15459,7 @@ 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 the extent that the same metrics may be used) is + font (to the extent that the same metrics may be used) is available from \acro{URW} and is distributed with \ProgName{ghostscript}. \end{description} @@ -14347,16 +15561,16 @@ double-dashed one. \Question[Q-underscore]{How to use the underscore character} -The underscore character \texttt{\symbol{95}} is ordinarily used in +The underscore character \texttt{\_} is ordinarily used in \TeX{} to indicate a subscript in maths mode; if you type -\texttt{\symbol{95}} in the course of ordinary text, \TeX{} will +\texttt{\_} in the course of ordinary text, \TeX{} will complain. If you're writing a document which will contain a large number of underscore characters, the prospect of typing -\csx{\symbol{95}} (or, worse, \csx{textunderscore}) for every one of +\csx{\_} (or, worse, \csx{textunderscore}) for every one of them will daunt most ordinary people. Moderately skilled macro programmers can readily generate a quick hack -to permit typing \texttt{\symbol{95}} to mean `text underscore'. +to permit typing \texttt{\_} to mean `text underscore'. However, the code \emph{is} somewhat tricky, and more importantly there are significant points where it's easy to get it wrong. There is therefore a package \Package{underscore} which provides a general @@ -14371,11 +15585,13 @@ in a typewriter font, or you must use a fuller encoding, such as If the requirement is only for occasional uses of underscores, it may be acceptable to use the following construct: +\begin{quote} \begin{verbatim} \def\us{\char`\_} ... \texttt{create\us process} \end{verbatim} +\end{quote} The construction isn't in the least robust (in the normal English sense of the word), but it \emph{is} robust under expansion (i.e., the \LaTeX{} sense of the word); so use it with care, but don't worry @@ -14422,7 +15638,7 @@ package has a euro character defined (character position 164, occupied in other \acro{ISO} Latin character sets by the ``currency symbol''). The encoding uses the command \csx{texteuro} for the character; at present that command is \emph{only} available from the -\Package{textcomp} package. There is a MicroSoft code page position, +\Package{textcomp} package. There is a Microsoft code page position, too, but standardisation of such things proceeds via rather different routes and the \LaTeX{} project hasn't yet been given details of the change. @@ -15080,7 +16296,7 @@ character is made definable, or ``active'', by setting its |\catcode`_=\active|. Any character could, in principle, be activated this way and defined -as a macro (|\def_{|\csx{\symbol{95}}|}|~--- the simple answer to +as a macro (\csx{def}\texttt{\_\{}\csx{\_}\texttt{\}}~--- the simple answer to % beware line break \Qref[question]{using underscores}{Q-underscore}), but you must be wary: whereas people expect an active tilde, other active characters @@ -15702,48 +16918,53 @@ find a copy of the document in your own system. \Question[Q-atsigns]{\csx{@} and \texttt{@} in macro names} Macro names containing \texttt{@} are \emph{internal} to \LaTeX{}, and -without special treatment just don't work in ordinary use. An -exemplar of the problems caused is discussed in % ! beware line break -\htmlonly{``}\Qref[question]{\csx{@} in vertical mode}{Q-atvert}\htmlonly{''}. +without special treatment just don't work in ordinary use. A nice +example of the problems caused is discussed in % ! beware line break +\Qref*{\csx{@} in vertical mode}{Q-atvert}''. -The problems users see are caused by copying bits of a class (|.cls| file) or -package (|.sty| file) into a document, or by including a class or +The problems users see are caused by copying bits of a class +(\texttt{.cls} file) or +package (\texttt{.sty} file) into a document, or by including a class or package file into a \LaTeX{} document by some means other than \csx{documentclass} or \csx{usepackage}. \LaTeX{} defines internal -commands whose names contain the character |@| to +commands whose names contain the character \texttt{@} to avoid clashes between its internal names and names that we would normally use in our documents. In order that these commands may work at all, \csx{documentclass} and \csx{usepackage} play around with the -meaning of |@|. +meaning of \texttt{@}. If you've included a file wrongly, you solve the problem by using the correct command. If you're using a fragment of a package or class, you may well feel -confused: books such as \Qref*{\emph{The \LaTeX{} Companion}}{Q-books} +confused: books such as the first edition of the % ! line break +\Qref*{The \LaTeX{} Companion}{Q-books} are full of fragments of packages as examples for you to employ. - -For example, there's a lengthy section in \emph{The Companion} about -\csx{@startsection} and how to use it to control the appearance of -section titles. Page~15 discusses the problem; and -suggests that you make such changes in the document preamble, between -\csx{makeatletter} and \csx{makeatother}. So the redefinition of -\csx{subsection} on page~26 could be: +This problem has been solved in the second edition, and in addition, +all the examples from the \emph{Companion} are now available on-line. +To see the technique in practice, look at the example below, from file +\File{2-2-7.ltx} in the \emph{Companion} examples directory: \begin{quote} \begin{verbatim} \makeatletter -\renewcommand{\subsection}{\@startsection - {subsection}% % name - ... +\renewcommand\subsection{\@startsection + {subsection}{2}{0mm}%name, level, indent + {-\baselineskip}% beforeskip + {0.5\baselineskip}% afterskip {\normalfont\normalsize\itshape}}% style \makeatother \end{verbatim} \end{quote} +(That example appears on page 29 of \emph{The \LaTeX{} Companion}, +second edition.) The alternative is to treat all these fragments as a package proper, bundling them up into a \texttt{.sty} file and including them with -\csx{usepackage}. (This approach is marginally preferable, from the -\LaTeX{} purist's point of view.) +\csx{usepackage}; this way you hide your \LaTeX{} internal code somewhere +that \LaTeX{} internal code is expected, which often looks `tidier'. +\begin{ctanrefs} +\item[\nothtml{\rmfamily}Examples from the Companion]\CTANref{tlc2} +\end{ctanrefs} \Question[Q-protect]{What's the reason for `protection'?} @@ -15814,6 +17035,7 @@ The simple answer is to try \csx{show}, in a run of \LaTeX{} that is taking commands from the terminal: \begin{quote} \begin{verbatim} +*\makeatletter *\show\protected@edef > \protected@edef=macro: ->\let \@@protect \protect @@ -15937,19 +17159,18 @@ mandatory argument, but \csx{newcommand} requires that you `know' the value of the default beforehand. The requisite trick is to use a macro in the optional argument: -\begin{wideversion} -\begin{verbatim} -\newcommand\thing[2][\DefaultOpt]{\def\DefaultOpt{#2} ...} -\end{verbatim} -\end{wideversion} -\begin{narrowversion} \begin{verbatim} +\documentclass{article} \newcommand\thing[2][\DefaultOpt]{% \def\DefaultOpt{#2}% - ...% + optional arg: #1, mandatory arg: #2% } +\begin{document} +\thing{manda}% #1=#2 + +\thing[opti]{manda}% #1="opti" +\end{document} \end{verbatim} -\end{narrowversion} \Question[Q-twooptarg]{More than one optional argument} @@ -15994,9 +17215,9 @@ programming point of view. A command with two optional arguments strains the limit of what's sensible: obviously you can extend the technique to provide as many optional arguments as your fevered imagination can summon. However, -see the comments on the use of the \Package{keyval} package, again in -``\Qref*[question]{breaking the 9-argument limit}{Q-moren9}''. -which offer an alternative way forward. +see the comments on the use of the \Package{keyval} package, in +``\Qref*[question]{breaking the 9-argument limit}{Q-moren9}'', +which offers an alternative way forward. If you must, however, consider the \Package{optparams} package; provides a \csx{optparams} command that you use as an intermediate in @@ -16058,21 +17279,33 @@ to take an argument. Of course, the \LaTeX{} kernel has something slicker than this: \begin{quote} +\begin{wideversion} \begin{verbatim} -\newcommand{\mycommand}[1]{\@ifstar - \mycommandStar% - \mycommandNoStar% +\newcommand{\mycommand}{\@ifstar + \mycommandStar% + \mycommandNoStar% } -\newcommand{\mycommandStar}{starred version} -\newcommand{\mycommandNoStar}{normal version} +\newcommand{\mycommandStar}[2]{starred version} +\newcommand{\mycommandNoStar}[1]{normal version} +\end{verbatim} +\end{wideversion} +\begin{narrowversion} +\begin{verbatim} +\newcommand{\mycommand}{\@ifstar + \mycommandStar% + \mycommandNoStar% +} +\newcommand{\mycommandStar}[2]{starred version} +\newcommand{\mycommandNoStar}[1]{normal version} \end{verbatim} +\end{narrowversion} \end{quote} -Which is all very well, is fast and efficient, but requires the -definition to be \Qref*{\csx{makeatletter} protected}{Q-atsigns}. -The technique doesn't interfere at all with the definitions of -\csx{mycommandStar} or \csx{mycommandNoStar}; they can have any -combination of optional and mandatory arguments that you could define -them to have in the ordinary way. +(Note that arguments to \csx{mycommandStar} and \csx{mycommandNoStar} +are independent~--- either can have their own arguments, unconstrained +by the technique we're using, unlike the trick described above.) +The \csx{@ifstar} trick is all very well, is fast and efficient, but +it requires the definition to be % ! line break +\Qref*{\csx{makeatletter} protected}{Q-atsigns}. A pleasing alternative is the \Package{suffix} package. This elegant piece of code allows you to define variants of your commands: @@ -16093,7 +17326,7 @@ piece of code allows you to define variants of your commands: \end{verbatim} \end{quote} \end{wideversion} -The package needs \Qref*{\elatex{}}{Q-NTS}, but any new enough +The package needs \Qref*{\elatex{}}{Q-etex}, but any new enough distribution defines \LaTeX{} as \elatex{} by default. Command arguments may be specified in the normal way, in both command definitions (after the ``\texttt{*}'' in the \csx{WithSuffix} @@ -16169,7 +17402,64 @@ Name \tbamp Type \tbamp Value \tbeol %\csx{hb@xt@} \tbamp macro \tbamp ``\csx{hbox} \texttt{to}'' \end{tabular} -\subsection{\LaTeX{} macro techniques} +\Question[Q-ltxhash]{Defining \LaTeX{} commands within other commands} + +\LaTeX{} command definition is significantly different from the \TeX{} +primitive form discussed in an % ! line break +\Qref*[\htmlonly]{earlier question}{Q-hash} about definitions within +macros. + +In most ways, the \LaTeX{} situation is simpler (at least in part +because it imposes more restrictions on the user); however, defining a +command within a command still requires some care. + +The earlier question said you have to double the |#| signs in command +definitions: in fact, the same rule holds, except that \LaTeX{} +already takes care of some of the issues, by generating argument lists +for you. + +The basic problem is that: +\begin{quote} +\begin{verbatim} +\newcommand{\abc}[1]{joy, oh #1!% + \newcommand{\ghi}[1]{gloom, oh #1!}% +} +\end{verbatim} +\end{quote} +followed by a call: +\begin{quote} +\begin{verbatim} +\cmdinvoke{abc}{joy} +\end{verbatim} +\end{quote} +typesets ``joy, oh joy!'', but defines a command \csx{ghi} that takes +one parameter, which it ignores; \cmdinvoke{ghi}{gloom} will expand to +``gloom, oh joy!'', which is presumably not what was expected. + +And (as you will probably guess, if you've read the earlier question) +the definition: +\begin{quote} +\begin{verbatim} +\newcommand{\abc}[1]{joy, oh #1!% + \newcommand{\ghi}[1]{gloom, oh ##1!}% +} +\end{verbatim} +\end{quote} +does what is required, and \cmdinvoke{ghi}{gloom} will expand to +``gloom, oh gloom!'', whatever the argument to \csx{abc}. + +The doubling is needed whether or not the enclosing command has an +argument, so: +\begin{quote} +\begin{verbatim} +\newcommand{\abc}{joy, oh joy!% + \newcommand{\ghi}[1]{gloom, oh ##1!}% +} +\end{verbatim} +\end{quote} +is needed to produce a replica of the \csx{ghi} we defined earlier. + +\subsection{\LaTeX{} macro programming} \Question[Q-fixnam]{How to change \LaTeX{}'s ``fixed names''} @@ -16387,15 +17677,22 @@ then examined (in a \Package{hyperref}-safe way) to set a conditional \Class{memoir} class has the same command setting a conditional \csx{ifoddpage}. Of course, the \csx{label} contributes to \LaTeX{}'s ``Rerun to get cross-references right'' error messages\dots{} + +The Koma-Script classes have an \environment{addmargin*} environment +that also provides the sorts of facilities that the \Package{chngpage} +offers. Koma-Script's supporting command is % !line break +\cmdinvoke{ifthispageodd}{<true>}{<false>} executes different things +depending on the page number. \begin{ctanrefs} \item[chngpage.sty]\CTANref{chngpage} +\item[\nothtml{\rmfamily}KOMA script bundle]\CTANref{koma-script} \item[memoir.cls]\CTANref{memoir} \end{ctanrefs} \Question[Q-labelformat]{How to change the format of labels} By default, when a label is created, it takes on the appearance of the -counter labelled: specifically, it is set to +counter labelled, so the label appears as \csx{the}\texttt{\meta{counter}}~--- what would be used if you asked to typeset the counter in your text. This isn't always what you need: for example, if you have nested enumerated lists with the outer @@ -16488,9 +17785,16 @@ However, people regularly want merely to change the way the section number appears in the heading, and some such people don't mind writing out a few macros. This answer is for \emph{them}. -The way the section number is typeset is determined by the +The section number is typeset using the +\begin{narrowversion} + \LaTeX{} internal +\end{narrowversion} +\begin{wideversion} + \Qref{\LaTeX{} internal}{Q-atsigns} +\end{wideversion} \csx{@seccntformat} command, which is given the ``name'' (section, -subsection, \dots{}) of the heading, as argument. Ordinarily, it +subsection, \dots{}) of the heading, as argument. Ordinarily, +\csx{@seccntformat} merely outputs the section number, and then a \csx{quad} of space. Suppose you want to put a stop after every section (subsection, subsubsection, \dots{}) number, a trivial change may be implemented by @@ -16503,25 +17807,46 @@ simple modification of the command: \end{verbatim} \end{quote} -Many people (for some reason) just want a stop after a section -number. To do this, one must make \csx{@seccntformat} switch according -to its argument. The following technique for doing the job is -slightly wasteful, but is efficient enough: +Many people (for some reason) want a stop after a section number, but +not after a subsection number, or any of the others. +To do this, one must make \csx{@seccntformat} switch according to its +argument. The following technique for doing the job is slightly +wasteful, but is efficient enough for a relatively rare operation: +\begin{wideversion} \begin{quote} \begin{verbatim} \let\@@seccntformat\@seccntformat \renewcommand*{\@seccntformat}[1]{% - \expandafter\let\expandafter\@tempa - \csname @seccntformat@#1\endcsname - \ifx\@tempa\relax + \expandafter\ifx\csname @seccntformat@#1\endcsname\relax \expandafter\@@seccntformat \else - \expandafter\@tempa + \expandafter + \csname @seccntformat@#1\expandafter\endcsname \fi {#1}% } \end{verbatim} \end{quote} +\end{wideversion} +\begin{narrowversion} +\begin{quote} +\begin{verbatim} +\let\@@seccntformat\@seccntformat +\renewcommand*{\@seccntformat}[1]{% + \expandafter\ifx + \csname @seccntformat@#1\endcsname + \relax + \expandafter\@@seccntformat + \else + \expandafter + \csname @seccntformat@#1\expandafter + \endcsname + \fi + {#1}% +} +\end{verbatim} +\end{quote} +\end{narrowversion} which looks to see if a second-level command has been defined, and uses it if so; otherwise it uses the original. The second-level command to define stops after section numbers (only) has the same @@ -16573,13 +17898,13 @@ then simply a matter of detecting if the command exists. The usual \LaTeX{} internal way of doing this is to use the command \csx{@ifundefined}: \begin{quote} - \cmdinvoke*{@ifundefined}{\texttt{r@}lab-name}{undef-cmds}{def-cmds} + \cmdinvoke*{@ifundefined}{\textup{r@}label-name}{undef-cmds}{def-cmds} \end{quote} -In which, \meta{lab-name} is exactly what you would use in +In which, \meta{label-name} is exactly what you would use in a \csx{label} command, and the remaining two arguments are command sequences to be used if the label is undefined (\meta{undef-cmds}) or if it is defined -(\texttt{\emph{def-cmds}}). +(\meta{def-cmds}). Note that any command that incorporates \csx{@ifundefined} is naturally fragile, so remember to create it with \csx{DeclareRobustCommand} or to @@ -16590,6 +17915,18 @@ warning about undefined labels at the end of the document; however, if you are, include the command \csx{G@refundefinedtrue} in \meta{\texttt{undef-cmds}}. +And of course, remember you're dealing in internal commands, and pay +attention to the \Qref*{at-signs}{Q-atsigns}. + +All the above can be avoided by using the \Package{labelcas} package: +it provides commands that enable you to switch according to the state +of a single label, or the states of a list of labels. The package's +definition is a bit complicated, but the package itself is pretty +powerful. +\begin{ctanrefs} +\item[labelcas.sty]\CTANref{labelcas} +\end{ctanrefs} + \Question[Q-addtoreset]{Master and slave counters} It's common to have things numbered ``per chapter'' (for example, in @@ -16601,7 +17938,7 @@ done automatically, when the ``master'' counter is stepped (when the to zero). How would you do that for yourself? You might want to number -algorithms per section, or corrolaries per theorem, for example. If +algorithms per section, or corrollaries per theorem, for example. If you're defining these things by hand, you declare the relationship when you define the counter in the first place: \begin{quote} @@ -16626,20 +17963,20 @@ The \Package{chngcntr} package encapsulates the \csx{@addtoreset} command into a command \csx{counterwithin}. So: \begin{quote} \begin{verbatim} -\counterwithin*{corrolary}{theorem} +\counterwithin*{corrollary}{theorem} \end{verbatim} \end{quote} -will make the corrolary counter slave to theorem counters. The +will make the corrollary counter slave to theorem counters. The command without its asterisk: \begin{quote} \begin{verbatim} -\counterwithin{corrolary}{theorem} +\counterwithin{corrollary}{theorem} \end{verbatim} \end{quote} -will do the same, and also redefine \csx{thecorrolary} as % line brk! -\meta{theorem number}.\meta{corrolary number}, which is a good scheme -if you ever want to refer to the corrolaries~--- there are potentially -many ``corrolary~1'' in any document, so it's as well to tie its number +will do the same, and also redefine \csx{thecorrollary} as % line brk! +\meta{theorem number}.\meta{corollary number}, which is a good scheme +if you ever want to refer to the corrollaries~--- there are potentially +many ``corrollary~1'' in any document, so it's as well to tie its number to the counter of the theorem it belongs to. This is true of pretty much any such counter-within-another; if you're not using the \Package{chngcntr}, refer to the answer to % line break! @@ -16663,7 +18000,7 @@ to stabilise counter values~--- \LaTeX{} will generate the usual warnings about labels changing. \begin{ctanrefs} \item[chngcntr.sty]\CTANref{chngcntr} -\item[perpage.sty]\CTANref{perpage} +\item[perpage.sty]Distributed as part \CTANref{bigfoot} \end{ctanrefs} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -16728,12 +18065,12 @@ There is nothing that can directly be done about this error: you can't extend the number of available \csx{dimen} registers without extending \TeX{} itself. \begin{wideversion} % hyper - \Qref{\eTeX{}}{Q-NTS} and \Qref{Omega}{Q-omega} both do this, as + \Qref{\eTeX{}}{Q-etex} and \Qref{Omega}{Q-omegaleph} both do this, as does \Qref{MicroPress Inc's V\TeX{}}{Q-commercial}. \end{wideversion} \begin{narrowversion} - \eTeX{} and \ensuremath{\Omega}~--- \Qref[see questions]{}{Q-NTS} - \Qref[and]{}{Q-omega} respectively~--- both do this, as does + \eTeX{} and \ensuremath{\Omega}~--- \Qref[see questions]{}{Q-etex} + \Qref[and]{}{Q-omegaleph} respectively~--- both do this, as does MicroPress Inc's V\TeX{}~--- \Qref{}{Q-commercial}. \end{narrowversion} @@ -16760,12 +18097,12 @@ into Plain \TeX{}). And how does one use \PiCTeX{} anyway, given that the manual is so \Qref*{hard to come by}{Q-docpictex}? -Fortunately for \MSDOS{} and Windows users, the \ProgName{MathsPic} +Fortunately for us all, the \ProgName{MathsPic} system may be used to translate a somewhat different language into \PiCTeX{} commands; and the \ProgName{MathsPic} manual is free (and -part of the distribution). \ProgName{MathsPic} is written in -\ProgName{Basic}; a version written in \ProgName{Perl} is under -development, and should be available soon. +part of the distribution). \ProgName{MathsPic} is available either as +a \ProgName{Basic} program for \acro{DOS}, or as a \ProgName{Perl} +program for other systems (including Windows, nowadays). \begin{ctanrefs} \item[m-pictex.sty]Distributed as part of \CTANref{context-tmf} \item[m-pictex.tex]Distributed as part of \CTANref{context-tmf} @@ -17026,7 +18363,7 @@ all know and love (or hate)% \begin{footnoteenv} The fonts acquired their label `Almost' following the realisation that their first implementation in \MF{}79 still wasn't quite right; - Knuth's original intention had been that they were the final answer + Knuth's original intention had been that they were the final answer. \end{footnoteenv}. There's not a lot one can do with these fonts; they are (as their name implies) almost (but not quite) the @@ -17138,10 +18475,10 @@ searches of this nature) may be used. From another \Newsgroup{comp.text.tex} example: \begin{quote} \begin{verbatim} -\begin{eqnarry} +\begin{eqnarray} [a] &=& b \\ \relax[a] &=& b -\end{eqnarry} +\end{eqnarray} \end{verbatim} \end{quote} which is a usage this \acro{FAQ} would not recommend, anyway: refer @@ -17151,14 +18488,15 @@ Note that the \Package{amsmath} package modifies the behaviour of \texttt{\bsbs } in maths. With \Package{amsmath}, the \environment{eqnarray} example doesn't need any special measures. -\Question[Q-verbwithin]{Why doesn't \csx{verb} work within\,\dots{}?} +\Question[Q-verbwithin]{Why doesn't verbatim work within\,\dots{}?} The \LaTeX{} verbatim commands work by changing category codes. Knuth says of this sort of thing ``Some care is needed to get the timing right\dots{}'', since once the category code has been assigned to a -character, it doesn't change. So \csx{verb} has to assume that it is -getting the first look at its parameter text; if it isn't, \TeX{} has -already assigned category codes so that \csx{verb} doesn't have a +character, it doesn't change. So \csx{verb} and +\cmdinvoke{begin}{verbatim} have to assume that they are getting the +first look at the parameter text; if they aren't, \TeX{} has already +assigned category codes so that the verbatim command doesn't have a chance. For example: \begin{quote} \begin{verbatim} @@ -17173,8 +18511,26 @@ will work (typesetting `\csx{error}'), but \end{verbatim} \end{quote} will not (it will attempt to execute \csx{error}). Other errors one -may encounter are `\csx{verb} ended by end of line', or even `\csx{verb} -illegal in command argument'. +may encounter are `\csx{verb} ended by end of line', or even the +rather more helpful `\csx{verb} illegal in command argument'. The +same sorts of thing happen with \cmdinvoke{begin}{verbatim} \dots{} +\cmdinvoke{end}{verbatim}: +\begin{quote} +\begin{quoteverbatim} +\ifthenelse{\boolean{foo}}{% +\begin{verbatim} +foobar +\end{verbatim} +}{% +\begin{verbatim} +barfoo +\end{verbatim} +} +\end{quoteverbatim} +\end{quote} +provokes errors like `File ended while scanning use of +\csx{@xverbatim}', as \cmdinvoke{begin}{verbatim} fails to see its +matching \cmdinvoke{end}{verbatim}. This is why the \LaTeX{} book insists that verbatim commands must not appear in the argument of any other command; they @@ -17192,8 +18548,8 @@ necessary?''. \csx{verb} in the first place. \item If you're using \csx{verb} to typeset a \acro{URL} or email address or the like, then the \csx{url} command from the - \Package{url} package will help: it doesn't suffer from the problems - of \csx{verb}. + \Qref{\Package{url} package}{Q-setURL} will help: it doesn't suffer + from the problems of \csx{verb}. \item If you're putting \csx{verb} into the argument of a boxing command (such as \csx{fbox}), consider using the \environment{lrbox} environment: @@ -17233,7 +18589,7 @@ Otherwise, there are three partial solutions to the problem. (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}\symbol{95}name} + \csx{string}. \cmdinvoke{texttt}{my\csx{string}\_name} typesets the same as |\verb+my_name+|, and will work in the argument of a command. It won't, however, work in a moving argument, and no amount of @@ -17243,9 +18599,9 @@ Otherwise, there are three partial solutions to the problem. A robust alternative is: \begin{quote} \begin{verbatim} -\chardef\bs=`\_ +\chardef\us=`\_ ... -\section{... \texttt{my\bs name}} +\section{... \texttt{my\us name}} \end{verbatim} \end{quote} Such a definition is `naturally' robust; the construction @@ -17355,6 +18711,8 @@ by saying: \item[mdwlist.sty]Distributed as part of \CTANref{mdwtools} \end{ctanrefs} +% other instances: \[no]linebreak in vertical mode + \Question[Q-2colfltorder]{Two-column float numbers out of order} When \LaTeX{} can't place a float immediately, it places it on one of @@ -17527,6 +18885,7 @@ discussed in % ! line break ``\Qref*{unnumbered sections in the table of contents}{Q-secnumdep}''. \Question[Q-breaklinks]{Link text doesn't break at end line} +\keywords{hyperref overfull link} When using the \Package{hyperref} package, you make a block of text ``active'' when you define a hyper-link (when the user clicks on @@ -17537,19 +18896,38 @@ The \Package{hyperref} package uses a \emph{driver} (in the same way as the \Package{graphics} package does), to determine how to implement all that hyper-stuff. -If you use the driver for \Package{dvips} output (presumably you want +If you use the driver for \ProgName{dvips} output (presumably you want to distill the resulting \PS{}), limitations in the way \ProgName{dvips} deals with the \csx{special} commands mean that \Package{hyperref} must prevent link anchors from breaking at the end of lines. Other drivers (notably those for \PDFTeX{} and for \ProgName{dvipdfm}) don't suffer from this problem. -The only known solution to this problem is to use the -\Package{breakurl} package. This package provides a very simple -solution: in place of the single link, the \csx{burl} command produces -a sequences of small pieces, between each of which a line break is -permitted. Each sequence of pieces, that ends up together in one +The problem may occur in a number of different circumstances. For a +couple of them, there are work-arounds: + +First, if you have an \acro{URL} which is active (so that clicking on +it will activate your web browser to ``go to'' the \acro{URL}). In +this case \Package{hyperref} employs the \Package{url} package to +split up the \acro{URL} (as described in % ! line break +\Qref[question]{typesetting \acro{URL}s}{Q-setURL}), but the +\ProgName{dvips} driver then suppresses the breaks. The way out is +the \Package{breakurl} package, which modifies the \csx{url} command +to produce several smaller pieces, between each of which a line break +is permitted. Each group of pieces, that ends up together in one line, is converted to a single clickable link. + +Second, if you have a table of contents, list of figure or tables, or +the like, \Package{hyperref} will ordinarily make the titles in the +table of contents, or captions in the lists, active. If the title or +caption is long, it will need to break within the table, but the +\ProgName{dvips} driver will prevent that. In this case, load +\Package{hyperref} with the option \pkgoption{linktocpage}, and only +the page number will be made active. + +Otherwise, if you have a lengthy piece of text that you want active, +you have at present no simple solution: you have to rewrite your text, +or to use a different \acro{PDF} generation mechanism. \begin{ctanrefs} \item[breakurl.sty]\CTANref{breakurl} \end{ctanrefs} @@ -17561,7 +18939,7 @@ This is a long story, whose sources are deep inside the workings of the best possible output. The page number is conventionally stored in \csx{count0}; \LaTeX{} -users see this as the counter \texttt{page}, and may set its value +users see this as the counter \texttt{page}, and may typeset its value using \csx{thepage}. The number (that is to say, \csx{count0}) is only updated when \TeX{} @@ -17593,6 +18971,64 @@ Here is page \pageref{here}\label{here}. that could potentially end up as a page-break space itself, which rather defeats the purpose of the exercise!). +\Question[Q-matchbrak]{My brackets don't match} + +\AllTeX{} has a low-level mechanism for matching braces in document +text. This means you can type something like: +\begin{quote} +\begin{verbatim} +\section{All \emph{OK} now.} +\end{verbatim} +\end{quote} +and know that the first brace (for the argument of \csx{section}) will +be matched with the last brace, and the internal pair of braces (for +the argument of \csx{emph}) will be matched with each other. It's all +very simple. + +However, \LaTeX{} has a convention of enclosing optional arguments in +brackets, as in: +\begin{quote} +\begin{verbatim} +\section[OK]{All \emph{OK} now.} +\end{verbatim} +\end{quote} +These brackets are not matched by \TeX{} mechanisms, despite the +superficial similarity of their use. As a result, +straightforward-looking usages like: +\begin{quote} +\begin{verbatim} +\section[All [OK] now]{All \emph{OK} now.} +\end{verbatim} +\end{quote} +aren't \acro{OK} at all~--- the optional argument comes to consist of +``All [OK'', and \csx{section} takes the single character ``n'' (of +the first ``now'') as its argument. + +Fortunately, \TeX{}'s scanning mechanisms helps us by accepting the +syntax ``\texttt{\{]\}}'' to `hide' the closing bracket from the +scanning mechanism that \LaTeX{} uses. In practice, the commonest way +to use this facility is: +\begin{quote} +\begin{verbatim} +\section[All {[OK]} now]{All \emph{OK} now.} +\end{verbatim} +\end{quote} +since bracing the bracket on its own ``looks odd''. + +\LaTeX{} has another argument syntax, even less regular, where the +argument is enclosed in parentheses, as in: +\begin{quote} +\begin{verbatim} +\put(1,2){foo} +\end{verbatim} +\end{quote} +(a picture environment command). + +This mechanism is also prone to problems with matching closing +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. + \subsection{Common misunderstandings} \Question[Q-include]{What's going on in my \csx{include} commands?} @@ -17692,7 +19128,7 @@ Here's text to be ranged left... In fact, there are a number of parameters for which \TeX{} only maintains one value per paragraph. A tiresome one is the set of upper case/lower case translations, which (oddly enough) constrains -hyphenation of mutlilingual texts. Another that regularly creates +hyphenation of mutilingual texts. Another that regularly creates confusion is \Qref*{\csx{baselineskip}}{Q-baselinepar}. \Question[Q-casechange]{Case-changing oddities} @@ -17759,7 +19195,7 @@ commands (\emph{not} the \TeX{} primitive commands \csx{uppercase} and \csx{lowercase}), so that section headings and the like don't produce broken page headings. \begin{ctanrefs} -\item[textcase.sty]Distributed as part of \CTANref{carlisle} +\item[textcase.sty]\CTANref{textcase} \end{ctanrefs} \Question[Q-splitfoot]{Why does \LaTeX{} split footnotes across pages?} @@ -18092,13 +19528,42 @@ parameter, so you need to ensure it's actually applied~--- see \end{quote} enclosing entire paragraphs (or set of paragraphs) in it. -\csx{emergencystretch} is a slightly trickier customer to understand. -The example above set it to |3em|; the Computer Modern fonts -ordinarily fit three space skips to the em, so the change would -allow anything up to the equivalent of nine extra spaces in each -line. In a line with lots of spaces, this could be reasonable, but -with (say) only three spaces on the line, each could stretch to four -times its natural width. +The value of \csx{emergencystretch} is added to the assumed +stretchability of each line of a paragraph, in a further run of the +paragraph formatter in case that the paragraph can't be made to look +right any other way. (The extra scan happens if +\csx{emergencystretch\textgreater0pt}~--- if it's zero or negative, no gain +could be had from rerunning the paragraph setter.) The example above +set it to \texttt{3em}; the Computer Modern fonts ordinarily fit three +space skips to the \texttt{em}, so the change would allow anything up +to the equivalent of nine extra spaces in each line. In a line with +lots of spaces, this could be reasonable, but with (say) only three +spaces on the line, each could stretch to four times its natural +width. It is therefore clear that \csx{emergencystretch} needs to be +treated with a degree of caution. + +More subtle (but more tricky to manage) are the microtypographic +extensions provided by \PDFTeX{}. Since \PDFTeX{} is the default +`engine' for \LaTeX{} and \CONTeXT{} work in all distributions, +nowadays, the extensions are available to all. There are two +extensions, margin kerning and font expansion; margin kerning only +affects the visual effect of the typeset page, and has little effect +on the ability of the paragraph setter to ``get things right''. +Font expansion works like a subtler version of the trick that +\csx{emergencystretch} plays: \PDFTeX{} `knows' that your current font +may be stretched (or shrunk) to a certain extent, and will do that +``on the fly'' to optimise the setting of a paragraph. This is a +powerful tool in the armoury of the typesetter. + +As mentioned above, the microtypographic extensions are tricky beasts +to control; however, the \Package{microtype} package relieves the user +of the tedious work of specifying how to perform margin adjustments +and how much to scale each font~\dots{}\@ for the fonts the package +knows about; it's a good tool, and users who can take on the +specification of adjustments for yet more fonts are always welcome. +\begin{ctanrefs} +\item[microtype.sty]\CTANref{microtype} +\end{ctanrefs} \Question[Q-exscale]{Maths symbols don't scale up} @@ -18252,6 +19717,57 @@ A separate answer discusses % ! line break \Qref{re-designing the tables}{Q-tocloft}\nothtml{ ---} and those techniques can be employed to make the numbers fit. +\Question[Q-gutter]{Why is the inside margin so narrow?} + +If you give the standard classes the \pkgoption{twoside} option, the +class sets the margins narrow on the left of odd-numbered pages, and +on the right of even-numbered pages. This is often thought to look +odd, but it is quite right. + +The idea is that the typographic urge for symmetry should also apply +to margins: if you lay an even numbered page to the left of an +odd-numbered one, you will see that you've three equal chunks of +un-printed paper: the left margin of the even page, the right margin +of the odd page, and the two abutting margins together. + +This is all very fine in the abstract, but in practical book(let) +production it only works ``sometimes''. + +If your booklet is produced on double-width paper and stapled, the +effect will be good; if your book(let) is produced using a so-called +``perfect'' binding, the effect will again be good. + +However, almost any ``quality'' book-binder will need some of your +paper to grab hold of, and a book bound in such a way won't exhibit +the treasured symmetry unless you've done something about the margin +settings. + +The packages recommended in % ! line break +``\Qref*{setting up margins}{Q-marginpkgs}'' mostly have provision for +a ``binding offset'' or a ``binding correction''~--- search for +``binding'' in the manuals (\Package{vmargin} doesn't help, here). + +If you're doing the job by hand (see % ! line break +\Qref[question]{manual margin setup}{Q-marginmanual}), the trick is to +calculate your page and margin dimensions as normal, and then: +\begin{itemize} +\item subtract the binding offset from \csx{evensidemargin}, and +\item add the binding offset to \csx{oddsidemargin}. +\end{itemize} +which can be achieved by: +\begin{quote} +\begin{verbatim} +\addtolength{\evensidemargin}{-offset} +\addtolength{\oddsidemargin}{offset} +\end{verbatim} +\end{quote} +(substituting something sensible like ``\texttt{5mm}'' for +``\texttt{offset}'', above). + +The above may not be the best you can do: you may well choose to +change the \csx{textwidth} in the presence of the binding offset; but +the changes do work for constant \csx{textwidth}. + \subsection{Why shouldn't I?} \Question[Q-t1enc]{Why use \Package{fontenc} rather than \Package{t1enc}?} @@ -18546,6 +20062,61 @@ needs \LaTeX{}'s simplest font selection commands: \item[smallcap.sty]\CTANref{smallcap} \end{ctanrefs} +\Question[Q-newfont]{What's wrong with \csx{newfont}?} + +If all else fails, you \emph{can} specify a font using the \LaTeX{} +\csx{newfont} command. The font so specified doesn't fit into the +\LaTeX{} font selection mechanism, but the technique can be tempting +under several circumstances. The command is merely the thinnest of +wrappers around the \csx{font} primitive, and suffers from exactly the +problems with font encodings and sizes that are outlined in +\Qref[question]{using Plain \TeX{} commands in \LaTeX}{Q-plninltx}. + +Almost all fonts, nowadays, are provided with \LaTeX{} control files +(if they're adapted to \TeX{} at all). There is therefore little gain +in using \csx{newfont}. + +One temptation arises from the way that \LaTeX{} restricts the sizes +of fonts. In fact, this restriction only significantly applies to the +default (Computer Modern) and the Cork-encoded (\acro{T}1) EC fonts, but it +is widely considered to be anomalous, nowadays. In recognition of +this problem, there is a package \Package{fix-cm} which will allow you +to use the fonts, within \LaTeX{}, at any size you choose. If you're +not using scaleable versions of the fonts, most modern distributions +will just generate an appropriate bitmap for you. + +So, suppose you want to use Computer Modern Roman at 30 points, you +might be tempted to write: +\begin{quote} +\begin{verbatim} +\newfont{\bigfont}{cmr10 at 30pt} +{\bigfont Huge text} +\end{verbatim} +\end{quote} +which will indeed work, but will actually produce a worse result than +\begin{quote} +\begin{verbatim} +\usepackage{fix-cm} +... +{% + \fontsize{30}{36}\selectfont + Huge text% +} +\end{verbatim} +\end{quote} +Note that the \Package{fix-cm} package was not distributed until the +December 2003 edition of \LaTeX{}; if you have an older distribution, +the packages \Package{type1cm} (for \acro{CM} fonts) and +\Package{type1ec} (for \acro{EC} fonts) are available. +\begin{ctanrefs} +\item[fix-cm.sty]Distributed as part of \CTANref{latex} (an unpacked + version is available at \CTANref{fix-cm}) +\item[type1cm.sty]\CTANref{type1cm} +\item[type1ec.sty]\CTANref{type1ec} (the package is actually part of + the \CTANref{cm-super} distribution, but it works happily in + the absence of the scaled fonts) +\end{ctanrefs} + %*****************************************quote environments up to here %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -18570,8 +20141,8 @@ perplexing) errors that you may encounter. There's a long list of but they often contain a straightforward clue to the problem. See \Qref[question]{the structure of errors}{Q-errstruct} for further details. -\item Read the |.log| file; it contains hints to things you may not - understand, often things that have not even presented as error +\item Read the \texttt{.log} file; it contains hints to things you may + not understand, often things that have not even presented as error messages. \item Be aware of the amount of context that \TeX{} gives you. The error messages gives you some bits of \TeX{} code (or of the @@ -18615,8 +20186,7 @@ most of the common errors are plain to the eye when you go back to the source line that \TeX{} tells you of. If that approach doesn't work, the remaining answers in this section deal with some of the odder error messages you may encounter. You should not ordinarily need to -appeal to the \nothtml{wider public (}% -\Qref[question]{wider public}{Q-maillists}\nothtml{)} +appeal to the \Qref*[question]{wider public}{Q-gethelp} for assistance, but if you do, be sure to report full backtraces (see |errorcontextlines| above) and so on. \begin{ctanrefs} @@ -18886,12 +20456,12 @@ 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-NTS} and \Qref{Omega}{Q-omega} + Of course, \Qref{\eTeX{}}{Q-etex} and \Qref{Omega}{Q-omegaleph} \end{htmlversion} \htmlignore % beware line wrap here Of course, \ensuremath{\Omega} and \eTeX{}~--- - \Qref[see questions]{}{Q-omega} \Qref[and]{}{Q-NTS} respectively~--- + \Qref[see questions]{}{Q-omegaleph} \Qref[and]{}{Q-etex} respectively~--- \endhtmlignore both do this, as does \Qref*{MicroPress Inc's V\TeX{}}{Q-commercial}. @@ -18904,7 +20474,7 @@ 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-NTS} (all modern distributions provide it). The +\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 derivative of the Plain \TeX{} macro file \Package{etex.src}, which is @@ -19546,7 +21116,7 @@ than a given length; so the solution is just to edit the file. If the problem is a ridiculous preview section, try using \ProgName{ghostscript} to reprocess the file, outputting a ``plain -|.eps|'' file. (\ProgName{Ghostscript} is distributed with a script +\texttt{.eps}'' file. (\ProgName{Ghostscript} is distributed with a script \ProgName{ps2epsi} which will regenerate the preview if necessary.) Users of the shareware program \ProgName{GSview} will find buttons to perform the required transformation of the file being displayed. @@ -19590,10 +21160,10 @@ depends on which system you are using. fmtutil --byfmt=<format name> \end{verbatim} to build only the format that you are interested in. -\item On a MiK\TeX{} system, click \texttt{Start}\arrowhyph{}% +\item On a \miktex{} system, click \texttt{Start}\arrowhyph{}% \texttt{Programs}\arrowhyph{}% -\texttt{MiKTeX \emph{version}}\arrowhyph{}% -\texttt{MiKTeX Options}, and in the options window, click +\texttt{\miktex{} \emph{version}}\arrowhyph{}% +\texttt{\miktex{} Options}, and in the options window, click \texttt{Update now}. \end{itemize} @@ -19619,7 +21189,7 @@ More amenable to correction, but more confusing, are packages (such as \Package{color}, \Package{graphics} and \Package{hyperref}) that specify a ``driver''. These packages have plug-in modules that determine what \csx{special} (or other commands) are needed to generate -any given effect: the |pdftex| driver for such packages knows not to +any given effect: the \texttt{pdftex} driver for such packages knows not to generate \csx{special} commands. In most circumstances, you can let the system itself choose which driver you need; in this case everything will act properly when you switch to using \PDFLaTeX{}. If @@ -19761,14 +21331,34 @@ The warning: the same identifier (name{page.1}) has been already used, duplicate ignored \end{verbatim} -{\small NB: message text wrapped to fit in the column} +{\small NB: message text wrapped to fit in the column\par} \end{narrowversion} \end{quote} arises because of duplicate page numbers in your document. The problem is usually soluble: see % beware line break -\Qref*[question]{\acro{PDF} page destinations}{Q-pdfpagelabels}~-- which +\Qref*[question]{\acro{PDF} page destinations}{Q-pdfpagelabels}~--- which answer also describes the problem in more detail. +If the identifier in the message is different, for example +|name{figure.1.1}|, the problem is (usually) due to a problem of +package interaction. Some packages are simply incompatible with +\Package{hyperref}, but most work simply by ignoring it. In most +cases, therefore, you should load your package before you load +\Package{hyperref}, and \Package{hyperref} will patch things up so +that they work: +\begin{quote} + \cmdinvoke{usepackage}{\emph{your package}}\\ + \dots{}\\ + \cmdinvoke{usepackage}[\emph{opts}]{hyperref} +\end{quote} +You should do this as a matter of course, unless the documentation of +a package says you \emph{must} load it after \Package{hyperref}. +(There aren't many such packages: one such is \Class{memoir}'s +``\Package{hyperref} fixup'' package \Package{memhfixc}.) + +If loading your packages in the (seemingly) ``correct'' order doesn't +solve the problem, you need to \Qref*{seek further help}{Q-gethelp}. + \Question[Q-altabcr]{Alignment tab changed to \csx{cr}} This is an error you may encounter in \LaTeX{} when a tabular @@ -20138,10 +21728,196 @@ error: \fbox{\section{Boxy section}} \end{verbatim} \end{quote} -This is a case where you've simply got to be more subtle; either you -write your own macros to replace the insides of \LaTeX{}'s sectioning -macros, or you should look for some alternative in the packages -discussed in ``\Qref*{The style of section headings}{Q-secthead}''. +This is a case where you've simply got to be more subtle; you should +either write your own macros to replace the insides of \LaTeX{}'s +sectioning macros, or look for some alternative in the packages +discussed in % ! line break +``\Qref*[question]{The style of section headings}{Q-secthead}''. + +\Question[Q-errparnum]{Illegal parameter number in definition} + +The error message means what it says. In the simple case, you've +attempted a definition like: +\begin{quote} +\begin{verbatim} +\newcommand{\abc}{joy, oh #1!} +\end{verbatim} +\end{quote} +or (using \TeX{} primitive definitions): +\begin{quote} +\begin{verbatim} +\def\abc{joy, oh #1!} +\end{verbatim} +\end{quote} +In either of the above, the definition uses an argument, but the +programmer did not tell \AllTeX{}, in advance, that she was going to. +The fix is simple~--- \cmdinvoke{newcommand}{\csx{abc}}[1], in the +\LaTeX{} case, |\def\abc#1| in the basic \TeX{} case. + +The more complicated case is exemplified by the attempted definition: +\begin{quote} +\begin{verbatim} +\newcommand{\abc}{joy, oh joy!% + \newcommand{\ghi}[1]{gloom, oh #1!}% +} +\end{verbatim} +\end{quote} +will also produce this error, as will its \TeX{} primitive equivalent: +\begin{quote} +\begin{verbatim} +\def\abc{joy, oh joy!% + \def\ghi#1{gloom, oh #1!}% +} +\end{verbatim} +\end{quote} +This is because special care is needed when defining one macro within +the code of another macro. This is explained elsewhere, separately +for \Qref*[question]{\LaTeX{} definitions}{Q-ltxhash} and for +\Qref*[question]{\TeX{} primitive definitions}{Q-hash} + +\Question[Q-fllost]{Float(s) lost} + +The error +\begin{quote} +\begin{verbatim} +! LaTeX Error: Float(s) lost. +\end{verbatim} +\end{quote} +seldom occurs, but always seems deeply cryptic when it \emph{does} +appear. + +The message means what it says: one or more figures, tables, etc., or +marginpars has not been typeset. (Marginpars are treated internally +as floats, which is how they come to be lumped into this error +message.) + +The most likely reason is that you placed a float or a \csx{marginpar} +command inside another float or marginpar, or inside a +\environment{minipage} environment, a \csx{parbox} or \csx{footnote}. +Note that the error may be detected a long way from the problematic +command(s), so the techniques of % ! line break +\Qref*{tracking down elusive errors}{Q-erroradvice} all need to be +called into play. + +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-optionclash]{Option clash for package} + +So you've innocently added: +\begin{quote} +\cmdinvoke{usepackage}[draft]{graphics} +\end{quote} +to your document, and \LaTeX{} responds with +\begin{wideversion} +\begin{quote} +\begin{verbatim} +! LaTeX Error: Option clash for package graphics. +\end{verbatim} +\end{quote} +\end{wideversion} +\begin{narrowversion} +\begin{quote} +\begin{verbatim} +! LaTeX Error: Option clash for package + graphics. +\end{verbatim} +\end{quote} +\end{narrowversion} + +The error is a complaint about loading a package % ! line break +\emph{with options}, more than once (\LaTeX{} doesn't actually examine +what options there are: it complains because it can't do anything with +the multiple sets of options). You can load a package +any number of times, with no options, and \LaTeX{} will be happy, but +you may only supply options when you first load the package. + +So perhaps you weren't entirely innocent~--- the error would have +occurred on the second line of: +\begin{quote} +\cmdinvoke{usepackage}[dvips]{graphics}\\ +\cmdinvoke{usepackage}[draft]{graphics} +\end{quote} +which could quite reasonably (and indeed correctly) have been typed: +\begin{quote} +\cmdinvoke{usepackage}[dvips,draft]{graphics} +\end{quote} + +But if you've not made that mistake (even with several lines +separating the \csx{usepackage} commands, it's pretty easy to spot), +the problem could arise from something else loading the package for +you. How do you find the culprit? Well, it's down to the log +analysis games discussed in % ! line break +``\Qref*{How to approach errors}{Q-erroradvice}''; the trick to remember +is that that the process of loading each file is parenthesised in the +log; so if package \Package{foo} loads \Package{graphics}, the log +will contain something like: +\begin{quote} +\begin{verbatim} +(<path>/foo.sty ... +... +(<path>/graphics.sty ... +...) +... +) +\end{verbatim} +\end{quote} +(the parentheses for \Package{graphics} are completely enclosed in +those for \Package{foo}; the same is of course true if \Class{bar} is +the culprit, except that the line will start with the path to +\texttt{bar.cls}). + +If we're dealing with a package that loads the package you are +interested in, you need to ask \LaTeX{} to slip in options when +\Package{foo} loads it. Instead of: +\begin{quote} +\cmdinvoke{usepackage}{foo}\\ +\cmdinvoke{usepackage}[draft]{graphics} +\end{quote} +you would write: +\begin{quote} +\cmdinvoke{PassOptionsToPackage}{draft}{graphics}\\ +\cmdinvoke{usepackage}{foo} +\end{quote} +The command \csx{PassOptionsToPackage} tells \LaTeX{} to behave as if +its options were passed, when it finally loads a package. As you would +expect from its name, \csx{PassOptionsToPackage} can deal with a list +of options, just as you would have in the the options brackets of +\csx{usepackage}. + +More trickily, instead of: +\begin{quote} +\cmdinvoke{documentclass}[...]{bar}\\ +\cmdinvoke{usepackage}[draft]{graphics} +\end{quote} +you would write: +\begin{quote} +\cmdinvoke{PassOptionsToPackage}{draft}{graphics}\\ +\cmdinvoke{documentclass}[...]{bar} +\end{quote} +with \csx{PassOptionsToPackage} \emph{before} the \csx{documentclass} +command. + +However, if the \Package{foo} package or the \Class{bar} class loads +\Package{graphics} with an option of its own that clashes with +what you need in some way, you're stymied. For example: +\begin{quote} +\cmdinvoke{PassOptionsToPackage}{draft}{graphics} +\end{quote} +where the package or class does: +\begin{quote} +\cmdinvoke{usepackage}[final]{graphics} +\end{quote} +sets \pkgoption{final} \emph{after} it's dealt with option you passed to +it, so your \pkgoption{draft} will get forgotten. In extreme cases, +the package might generate an error here (\Package{graphics} doesn't +go in for that kind of thing, and there's no indication that +\pkgoption{draft} has been forgotten). + +In such a case, you have to modify the package or class itself +(subject to the terms of its licence). It may prove useful to contact +the author: she may have a useful alternative to suggest. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -20166,10 +21942,11 @@ version of \LaTeX{}, in parallel with development of \LaTeX{}3. Some of the older discussion papers about directions for \LaTeX{}3 are to be found on \acro{CTAN}; other (published) articles are to be -found on the project web site (see -\URL{http://www.latex-project.org/articles.html}), as is some of the +found on the project web site +(\URL{http://www.latex-project.org/papers/}), as is some of the project's experimental code -(\URL{http://www.latex-project.org/experimental}). You can +(see \URL{http://www.latex-project.org/code.html}, which allows you to +read the project's source repository). 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 @@ -20178,136 +21955,7 @@ message `\texttt{subscribe latex-l <\emph{your name}>}' to \item[\nothtml{\rmfamily}\LaTeX{} project publications]\CTANref{ltx3pub} \end{ctanrefs} -\Question[Q-omega]{The Omega project} - -Omega -\htmlignore -(\ensuremath{\Omega}) -\endhtmlignore -is a program built by extension of the \TeX{} sources which works -internally with `wide' characters (it is capable of dealing with all -of Unicode version 3); this allows it to work with most scripts in the -world with few difficulties from coding schemes. -\latexhtml{\ensuremath\Omega}{Omega} also has a -powerful concept of input and output filters to allow the user to work -with existing transliteration schemes, \emph{etc}. - -A part of the project is to develop a version of \LaTeX{} to work with -\latexhtml{\ensuremath{\Omega}}{Omega}, styled -\latexhtml{``Lambda'' (\ensuremath{\Lambda})}{``Lambda''}. - -%% An email discussion list is available: subscribe by sending a message -%% `\texttt{subscribe}' to \mailto{omega-request@omega.cse.unsw.edu.au} - -\latexhtml{\ensuremath\Omega}{Omega} was first released in November 1996 -by the project originators, John Plaice and Yannis Haralambous; a -recent version is maintained on \acro{CTAN}. General project -information, as well as copies papers, are available via the -\begin{narrowversion}% i.e. non-hyper version - project's web site (\URL{http://omega.enstb.org}). -\end{narrowversion} -\begin{wideversion} - \href{http://omega.enstb.org}{project's web site}. -\end{wideversion} - -Implementations of \latexhtml{\ensuremath\Omega}{Omega} -are available as part of the te\TeX{}, -mik\TeX{}, fp\TeX{} and \acro{C}Mac\TeX{} distributions -(see \Qref[question]{\TeX{} systems}{Q-TeXsystems}), as well as -in \Qref*{\TeX{}~Live}{Q-CD}. - -A related project, \Qref*{Aleph}{Q-aleph}, has merged a version of -\latexhtml{\ensuremath\Omega}{Omega} with the facilities of -\Qref*{\eTeX{}}{Q-NTS}, as a pathfinder for potential future Omega -development. -\begin{ctanrefs} -\item[CTAN distribution]\CTANref{omega} (not up-to-date: use the - version in your \AllTeX{} distribution) -\end{ctanrefs} - -\nothtml{\begingroup\ifboldmathavail\boldmath\fi} -\Question[Q-NTS]{The \NTS{} project} -\nothtml{\afterquestion} - -The \NTS{} project was established in 1992, to produce a typesetting -system that's even better than \TeX{}. The project is not simply -enhancing \TeX{}, for two reasons: first, that \TeX{} itself has been -frozen by Knuth -(see \Qref[question]{the future of \TeX{}}{Q-TeXfuture}), and second, -even if they \emph{were} allowed to develop the program, some members -of the \NTS{} team feel that \TeX{} in its present form is simply -unsuited to further development. While all those involved in the -project are committed to \TeX{}, they recognise -that the end product may very well have little in common with \TeX{} -other than its philosophy. - -The group's first product was nevertheless a set of -extensions and enhancements to \TeX{}, implemented through the standard -medium of a change-file. The extended system is known \eTeX{}, and is -100\textpercent\ compatible with \TeX{}; furthermore, \eTeX{} can -construct a format -that \emph{is} ``\TeX{}'', with no extensions or enhancements present. - -The most recent base source of \eTeX{} (i.e., the Web change file) is -available on \acro{CTAN}. Following a suggestion from the -\Qref*{\LaTeX{} project}{Q-LaTeX3}, most \AllTeX{} distributions now -make \emph{all} their \LaTeX{} executables with the -\eTeX{} extensions (that is, \ProgName{latex} is really \elatex{}, -\ProgName{pdflatex} is really \acro{PDF}e-\LaTeX{}, and so on). In -this context, some of the newer \LaTeX{} packages are designed to -require the \eTeX{} extensions. - -The project has now produced a \ensuremath{\beta}-version of -\TeX{} written (from scratch) in Java. Since it \emph{isn't} \TeX{} -(it remains slightly incompatible in microscopic ways), it's known as -\NTS{}. As might be expected, this first re-implementation runs -rather slowly, but its operation \emph{has} been demonstrated in -public, and the \ensuremath{\beta}-release is available on -\acro{CTAN}. -\begin{ctanrefs} -\item[e-TeX]Browse \CTANref{e-TeX} -\item[NTS]\CTANref{nts} -\end{ctanrefs} - -\Question[Q-pdftex]{The \PDFTeX{} project} - -\PDFTeX{} (formerly known as \TeX{}2\acro{PDF}) arose from -\latexhtml{H\'an \The{} Th\'anh's}{Han The Thanh's} -post-graduate research at Masaryk University, Brno, Czech -Republic. The basic idea is very simple: to provide a version of -\TeX{} that can output \acro{PDF} as an alternative format to -\acro{DVI}. \PDFTeX{} implements a small number of new -primitives, to switch to \acro{PDF} output, and to control various -\acro{PDF} features. -\latexhtml{H\'an \The{} Th\'anh}{Han The Thanh} -worked on \PDFTeX{} throughout his Ph.D.\ research into -typesetting, and the latest release includes facilities he wrote to -support novel typesetting techniques that he was studying. - -Since he completed his studies, Han has had little time to work on -\PDFTeX{}, and day-to-day support is provided by a team of experts -(mostly in Europe). -The latest sources are available on \acro{CTAN}, and -implementations are available as part of Web2C, as well as in the -te\TeX{}, mik\TeX{}, fp\TeX{}, \acro{C}Mac\TeX{} and \TeX{}~live distributions -A version (by the author of \acro{C}Mac\TeX{}) for use with Oz\TeX{} is also -available on \acro{CTAN}. - -A mailing list discussing \PDFTeX{} is available; -\begin{narrowversion} % non-hyper version - subscribe via the \acro{TUG} \ProgName{mailman} interface at - \URL{http://www.tug.org/mailman/listinfo/pdftex} -\end{narrowversion} -\begin{wideversion} - subscribe via the - \href{http://www.tug.org/mailman/listinfo/pdftex}{\acro{TUG} \ProgName{mailman} interface}. -\end{wideversion} -\begin{ctanrefs} -\item[pdftex]\CTANref{pdftex} -\item[pdftex for OzTeX]\CTANref{pdftex-oztex} -\end{ctanrefs} - -\Question[Q-mathml]{Future \acro{WEB} technologies and \AllTeX{}} +\Question[Q-mathml]{Future \acro{WWW} technologies and \AllTeX{}} An earlier answer % ! line break (\Qref[number]{``converting to \acro{HTML}''}{Q-LaTeX2HTML}) @@ -20454,9 +22102,9 @@ are increasingly being used to provide Type~1 fonts to the public domain. The \ProgName{MetaType1} system aims to use \MF{} font sources, by way of \MP{} and a bunch of scripts and so on, to produce high-quality Type~1 fonts. The first results, the % ! line break -\Qref*{\Package{Latin Modern} fonts}{Q-type1T1}, are pretty -impressive, and it is known that the team that produced the system are -developing new work using the system. +\Qref*{\Package{Latin Modern} fonts}{Q-type1T1}, are now +well-established, and a bunch of existing designs have been reworked +in MetaType1 format. \begin{ctanrefs} \item[MetaType1]\CTANref{metatype1} \end{ctanrefs} @@ -20565,7 +22213,8 @@ distraction. \Question[Q-ant]{The \textsf{ANT} typesetting system} -Achim Blumensath's \textsf{ANT} project, in contrast to \NTS{}, aims +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. @@ -20580,50 +22229,22 @@ writer. This architecture holds the promise of a system that avoids a set of serious problems with \TeX{}'s user interface: those that derive from the design language being the same as the markup language. \begin{ctanrefs} -\item[\textsf{ANT} downloads]% - \URL{http://www-mgi.informatik.rwth-aachen.de/~blume/Download.html} -\end{ctanrefs} - -\Question[Q-aleph]{The Aleph project} - -The Aleph \nothtml{(\ensuremath\aleph)} project aims to build a -``usable'' version of \nothtml{Omega (\ensuremath\Omega~--- }% ! line break -\Qref{Omega}{Q-omega}\nothtml{)}, incorporating \eTeX{} extensions -from the \Qref*{\NTS{} project}{Q-NTS}. - -Two sets of concerns have provided impetus to the project: first, that -many users need the \eTeX{} extensions, and they're not on the -\latexhtml{\ensuremath\Omega}{Omega} development path; and second, -that the \latexhtml{\ensuremath\Omega}{Omega} project is currently -immersed in radical restructuring of -\latexhtml{\ensuremath\Omega}{Omega}, and is not able to be -particularly responsive to user requirements in the short term. In -the longer term, the \latexhtml{\ensuremath\aleph}{Aleph} project hope -that their work will be rendered irrelevant by the development of -\latexhtml{\ensuremath\Omega}{Omega} proper. - -The current pre-release snapshot of -\latexhtml{\ensuremath\aleph}{Aleph} resides on \acro{CTAN} with the -rather modest name of e-Omega. Follow development by subscribing -to the project mailing list via \URL{http://www.ntg.nl/mailman/listinfo/aleph} -\begin{ctanrefs} -\item[e-omega]Browse \CTANref{aleph} +\item[\textsf{ANT}]\CTANref{ant} \end{ctanrefs} \Question[Q-extex]{The \ExTeX{} project} -\href{http://www.dante.de/projects/extex/}{The \ExTeX{} project} is +\href{http://www.extex.org/}{The \ExTeX{} project} is building on the experience of the many existing \TeX{} development and extension projects, to develop a new \TeX{}-like system. The system -is to be developed in Java, but will not necessarily use the code of -\Qref*{\NTS{}}{Q-NTS}. +is to be developed in Java (like the ill-fated \NTS{} project). While \ExTeX{} will implement all of \TeX{}'s primitives, some may be marked as obsolete, and ``modern'' alternatives provided (an obvious example is the primitive \csx{input} command, whose syntax inevitably makes life difficult for users of modern operating system file -paths). Desirable extensions from \Qref*{\eTeX{}}{Q-NTS}, -\Qref*{\PDFTeX{}}{Q-pdftex} and \Qref*{\ensuremath{\Omega}}{Q-omega} +paths). Desirable extensions from \Qref*{\eTeX{}}{Q-etex}, +\Qref*{\PDFTeX{}}{Q-whatpdftex} and \Qref*{\ensuremath{\Omega}}{Q-omegaleph} have been identified. Usability will be another focus of the work: debugging support and log @@ -20633,6 +22254,60 @@ 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*{\acro{LUA}\TeX{}}{Q-luatex} project. + +\Question[Q-luatex]{\PDFTeX{} becomes \acro{LUA}\TeX{}} + +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. + +Thus arose the idea of \acro{LUA}\TeX{}. \acro{LUA} is a script +language, chosen because its interpreter has a very small +``footprint'', so it is rather easy to build it into other +applications. So \acro{LUA}\TeX{} was launched as a \PDFTeX{} +executable with a \acro{LUA} interpreter built into it. + +The \acro{LUA}\TeX{} 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}. + \Question[Q-xetex]{The XeTeX project} XeTeX (by Jonathan Kew) is a successor to the shareware \TeX{}/\acro{GX} @@ -20642,17 +22317,8 @@ is able to make use of Mac~\acro{OS}~X \acro{AAT} (Apple Advanced Typography) (which facilitates the afore-mentioned font access) to generate \acro{PDF} output. -XeTeX requires Mac~\acro{OS}~{X} 10.3 ``Panther'' or later (although -there has been some success using earlier versions). It is -especially oriented towards multi-lingual typography, taking advantage -of Apple's keyboard input systems and system font support for various -languages. - -The system is able to make use of Gerben Wierda's \TeX{} for -Mac~\acro{OS}~X setup, but a minimal set of \TeX{} support files is -also available, making an attractive proposition for those with -limited bandwidth who are inclined to use Plain \TeX{}. It can be -installed using Apple's Installer, or as an i-Installer package. +A Linux version has been announced (2006); that version of course +can't use \acro{AAT} fonts, and relies on OpenType fonts alone. 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 @@ -20673,14 +22339,24 @@ cover a set of questions that have arisen; it's always possible that they're written in a way that a novice won't understand them. Which is where you can help the community. Mail the -\href{mailto:faq@tex.ac.uk}{maintainers} to report the answer -that you find unclear. Time permitting (the team is small and all its -members are busy), we'll try and clarify the answer. This way, with a -bit of luck, we can together improve the value of this resource to the -whole community. +\begin{wideversion} + \href{mailto:faq-devel@tex.ac.uk}{maintainers} +\end{wideversion} +\begin{narrowversion} + maintainers (at \Email{faq-devel@tex.ac.uk}) +\end{narrowversion} +to report the answer that you find unclear, and (if you can) suggest +what we need to clarify. Time permitting (the team is small and all +its members are busy), we'll try and clarify the answer. This way, +with a bit of luck, we can together improve the value of this resource +to the whole community. -(We need hardly say that we look forward to hearing from none of you: -but we're not so arrogant as to be confident that we won't!) +Note that the \acro{FAQ} development email address is not for +answering questions: it's for you to suggest which questions we should +work on, or new questions we should answer in future editions. + +Those who simply ask questions at that address will be referred to +\mailto{texhax@tug.org} or to \Newsgroup{comp.text.tex}. \Question[Q-newans]{Submitting new material for the \acro{FAQ}} @@ -20689,7 +22365,13 @@ there will be people out there who know better than we do about something or other. We always need to be put right about whatever we've got wrong, and suggestions for improvements, particularly covering areas we've missed, are always needed: mail anything you have -to the \href{mailto:faq@tex.ac.uk}{maintainers}. +to the +\begin{wideversion} + \href{mailto:faq-devel@tex.ac.uk}{maintainers} +\end{wideversion} +\begin{narrowversion} + maintainers (at \Email{faq-devel@tex.ac.uk}) +\end{narrowversion} If you have actual material to submit, your contribution is more than ever welcome. Submission in plain text is entirely acceptable, but @@ -20714,14 +22396,18 @@ up to date for development purposes. The \LaTeX{} team supports \LaTeX{}, and will deal with % beware line wrap -\emph{bona fide} bug reports. However, you need to be slightly +\emph{bona fide} bug reports. Note that the \LaTeX{} team does +\emph{not} deal with contributed packages~--- just the software that +is part of the \LaTeX{} distribution itself: \LaTeX{} and the +``required'' packages. +Furthermore, you need to be slightly careful to produce a bug report that is usable by the team. The steps are: \nothtml{\noindent}\textbf{1.} Are you still using current \LaTeX{}? Maintenance is only available for sufficiently up-to-date versions of \LaTeX{}~--- if your \LaTeX{} is more than two versions out of date, the bug reporting -mechanisms will reject your report. +mechanisms may reject your report. \nothtml{\noindent}\textbf{2.} Has your bug already been reported? Browse the % beware line break @@ -20794,21 +22480,37 @@ money prizes to finders of bugs; the cheques he writes are such rare items that they are seldom cashed. If \emph{you} think you have found a genuine fault in \TeX{} itself (or \MF{}, or the \acro{CM} fonts, or the \TeX{}book), don't immediately write to Knuth, -however. He only looks at bugs once or twice a year, and even then +however. He only looks at bugs infrequently, and even then only after they are agreed as bugs by a small vetting team. In the first instance, contact Barbara Beeton at the \acro{AMS} -(\Email{bnb@math.ams.org}), or contact +(\Email{bnb@ams.org}), or contact \Qref*{\acro{TUG}}{Q-TUG*}. If you've found a bug in \LaTeXe{}, \Qref*{report it}{Q-latexbug} -using mechanisms supplied in the \LaTeX{} distribution. +using mechanisms supplied by the \LaTeX{} team. (Please be +careful to ensure you've got a \LaTeX{} bug, or a bug in one of the +``required'' packages distributed by the \LaTeX{} team.) + +If you've found a bug in a contributed \LaTeX{} package, you could try +contacting the author (if you can find a contact address). However, +it's generally best to treat any package as unsupported, in the first +instance, and only try the author \emph{after} mailing list/news group +support has failed you. If you've found a bug in \LaTeXo{}, or some other such unsupported -software, there's not a lot you can do about it. You may find help or +software, you may find help or \emph{de facto} support on a newsgroup such as \Newsgroup{comp.tex.tex} or on a mailing list such as -\mailto{texhax@tug.org}, but posting non-bugs to any of these forums -can lay you open to ridicule! Otherwise you may need to pay for +\mailto{texhax@tug.org}; be carefule to include a % ! line wrap +\Qref*{code example}{Q-minxampl} of the +failure, if relevant. + +Failing all else, you may need to pay for help~--- \acro{TUG} maintains a % ! line break \href{http://www.tug.org/consultants.html}{register of \TeX{} consultants}. + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: t +%%% End: |