diff options
author | Karl Berry <karl@freefriends.org> | 2009-10-09 22:55:11 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2009-10-09 22:55:11 +0000 |
commit | 4be9896a3192173699de340a9f0475654efedb3a (patch) | |
tree | da0e954012cd781f875c761c42f6a76e50e2f272 /Master/texmf-dist/doc/generic/FAQ-en/faq-docs.tex | |
parent | bd1227ad4919d2fbe17d63213bf48542f9c36f38 (diff) |
faq 3.19a update (9oct09)
git-svn-id: svn://tug.org/texlive/trunk@15725 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/generic/FAQ-en/faq-docs.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/FAQ-en/faq-docs.tex | 1115 |
1 files changed, 1115 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/FAQ-en/faq-docs.tex b/Master/texmf-dist/doc/generic/FAQ-en/faq-docs.tex new file mode 100644 index 00000000000..cecf4d3e1bb --- /dev/null +++ b/Master/texmf-dist/doc/generic/FAQ-en/faq-docs.tex @@ -0,0 +1,1115 @@ +% $id:$ + +\section{Documentation and Help} + +\Question[Q-books]{Books on \TeX{} and its relations} + +While Knuth's book is the definitive reference for \TeX{}, there are +other books covering \TeX{}: +\begin{booklist} +\item[The \TeX{}book]by Donald Knuth (Addison-Wesley, 1984, + \ISBN{0-201-13447-0}, paperback \ISBN{0-201-13448-9}) +\item[A Beginner's Book of \TeX{}]by Raymond Seroul and Silvio Levy, + (Springer Verlag, 1992, \ISBN{0-387-97562-4}) +\item[\TeX{} by Example: A Beginner's Guide]by Arvind Borde + (Academic Press, 1992, \ISBN{0-12-117650-9}~--- now out of print) +\item[Introduction to \TeX{}]by Norbert Schwarz (Addison-Wesley, + 1989, \ISBN{0-201-51141-X}~--- now out of print) +\item[A \plaintex{} Primer]by Malcolm Clark (Oxford University + Press, 1993, ISBNs~0-198-53724-7 (hardback) and~0-198-53784-0 + (paperback)) +\item[A \TeX{} Primer for Scientists]by Stanley Sawyer and Steven + Krantz (CRC Press, 1994, \ISBN{0-849-37159-7}) +\item[\TeX{} by Topic]by Victor Eijkhout (Addison-Wesley, 1992, + \ISBN{0-201-56882-9}~--- now out of print, but see + \Qref[question]{online books}{Q-ol-books}; you can now buy a copy + printed, on demand, by Lulu~--- see + \url{http://www.lulu.com/content/2555607}) +\item[\TeX{} for the Beginner]by Wynter Snow (Addison-Wesley, 1992, + \ISBN{0-201-54799-6}) +\item[\TeX{} for the Impatient]by Paul W.~Abrahams, Karl Berry and + Kathryn A.~Hargreaves (Addison-Wesley, 1990, + \ISBN{0-201-51375-7}~--- now out of print, but see + \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) + Vol.~1: \ISBN{0-387-97595-0}, % (3-540-97595-0) + Vol.~2: \ISBN{0-387-97596-9}, % (3-540-97596-9) + Vol.~3: \ISBN{0-387-97597-7}, and % (3-540-97597-7) + Vol.~4: \ISBN{0-387-97598-5})% (3-540-97598-5) +\htmlignore +\item[\TeX{}: Starting from \sqfbox{1}\,\footnotemark]% +\footnotetext{That's `Starting from Square One'}% +\endhtmlignore +\begin{htmlversion} +\item[\TeX{}: Starting from Square One] +\end{htmlversion} + by Michael Doob (Springer + Verlag, 1993, \ISBN{3-540-56441-1}~--- now out of print) +\item[The Joy of \TeX{}]by Michael D.~Spivak (second edition, + \acro{AMS}, 1990, \ISBN{0-821-82997-1}) +\item[The Advanced \TeX{}book]by David Salomon (Springer Verlag, 1995, + \ISBN{0-387-94556-3}) +\end{booklist} +A collection of Knuth's publications about typography is also available: +\begin{booklist} +\item[Digital Typography]by Donald Knuth (CSLI and Cambridge + University Press, 1999, \ISBN{1-57586-011-2}, paperback + \ISBN{1-57586-010-4}). +\end{booklist} +\nothtml{\noindent}and in late 2000, a ``Millennium Boxed Set'' of all +5 volumes of Knuth's ``Computers and Typesetting'' series (about +\TeX{} and \MF{}) was published by Addison Wesley: +\begin{booklist} +\item[Computers \& Typesetting, Volumes A--E Boxed Set]by Donald Knuth + (Addison-Wesley, 2001, \ISBN{0-201-73416-8}). +\end{booklist} +\checked{rf}{2000/02/12 -- http://cseng.aw.com/book/0,3828,0201734168,00.html} +For \LaTeX{}, see: +\begin{booklist} +\item[\LaTeX{}, a Document Preparation System]by Leslie Lamport + (second edition, Addison Wesley, 1994, \ISBN{0-201-52983-1}) +\item[Guide to \LaTeX{}]Helmut Kopka and Patrick W.~Daly (fourth + edition, Addison-Wesley, 2004, \ISBN{0-321-17385-6}) +\item[The \LaTeX{} Companion]by Frank Mittelbach, Michel Goossens, + Johannes Braams, David Carlisle and Chris Rowley (second edition, + Addison-Wesley, 2004, \ISBN*{0-201-36299-6}{978-0-201-36299-2}) +\item[The \LaTeX{} Graphics Companion:]% + \emph{Illustrating documents with \TeX{} and \PS{}} by Michel + Goossens, Sebastian Rahtz, Frank Mittelbach, Denis Roegel and + Herbert Vo\ss{} (second edition, Addison-Wesley, 2007, + \ISBN*{0-321-50892-0}{978-0-321-50892-8}) +\item[The \LaTeX{} Web Companion:]% + \emph{Integrating \TeX{}, \acro{HTML} and \acro{XML}} by Michel + Goossens and Sebastian Rahtz (Addison-Wesley, 1999, \ISBN{0-201-43311-7}) +\item[\TeX{} Unbound:]% + \emph{\LaTeX{} and \TeX{} strategies for fonts, graphics, and more} + by Alan Hoenig (Oxford University Press, 1998, \ISBN{0-19-509685-1} + hardback, \ISBN{0-19-509686-X} paperback) +\item[Math into \LaTeX{}:]\emph{An Introduction to \LaTeX{} and \AMSLaTeX{}} + by George Gr\"atzer (third edition Birkh\"auser and Springer Verlag, + 2000, \ISBN{0-8176-4431-9}, \ISBN{3-7643-4131-9}) +\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} +\item[First Steps in \LaTeX{}]by George Gr\"atzer (Birkh\"auser, 1999, + \ISBN{0-8176-4132-7}) +\item[\LaTeX{}: Line by Line:]% + \emph{Tips and Techniques for Document Processing} + by Antoni Diller (second edition, John Wiley \& Sons, + 1999, \ISBN{0-471-97918-X}) +\item[\LaTeX{} for Linux:]\emph{A Vade Mecum} + by Bernice Sacks Lipkin (Springer-Verlag, 1999, + \ISBN{0-387-98708-8}, second printing) +\end{booklist} +A sample of George Gr\"atzer's ``Math into \LaTeX{}'', in Adobe +Acrobat format, and example files +%for von Bechtolsheim's ``\TeX{} in Practice'', +for the three \LaTeX{} Companions, and for +Gr\"atzer's ``First Steps in \LaTeX{}'', are all available on +\acro{CTAN}. + +There's a nicely-presented list of of ``recommended books'' to be had +on the web: \URL{http://www.macrotex.net/texbooks/} + +The list of \MF{} books is rather short: +\begin{booklist} +\item[The \MF{}book]by Donald Knuth (Addison Wesley, 1986, + \ISBN{0-201-13445-4}, \ISBN{0-201-52983-1} paperback) +\end{booklist} +Alan Hoenig's `\textsl{\TeX{} Unbound}' includes some discussion and +examples of using \MF{}. + +A book covering a wide range of topics (including installation and +maintenance) is: +\begin{booklist} +\item[Making \TeX{} Work]by Norman Walsh (O'Reilly and Associates, + Inc, 1994, \ISBN{1-56592-051-1}) +\end{booklist} +The book is decidedly dated, and is now out of print, but a copy is +available via \texttt{sourceforge} and on \acro{CTAN}, +and we list it under ``\Qref*{online books}{Q-ol-books}''. + + +This list only covers books in English: notices of new books, or +warnings that books are now out of print are always welcome. However, +this \acro{FAQ} does \emph{not} carry reviews of current published material. +\begin{ctanrefs} +\item[\nothtml{\rmfamily}Examples for \nothtml{\upshape}First Steps in \LaTeX{}]\CTANref{gfs} +\item[\nothtml{\rmfamily}Examples for \nothtml{\upshape}\LaTeX{} Companion]\CTANref{tlc2} +\item[\nothtml{\rmfamily}Examples for \nothtml{\upshape}\LaTeX{} Graphics Companion]\CTANref{lgc} +\item[\nothtml{\rmfamily}Examples for \nothtml{\upshape}\LaTeX{} Web Companion]\CTANref{lwc} +%\item[\nothtml{\rmfamily}Examples for \nothtml{\upshape}\TeX{} in Practice]\CTANref{tip} +\item[\nothtml{\rmfamily}Sample of \nothtml{\upshape}Math into \LaTeX{}]\CTANref{mil} +\end{ctanrefs} + +\Question[Q-typebooks]{Books on Type} + + The following is a partial listing of books on typography in general. +Of these, Bringhurst seems to be the one most often recommended. +\begin{booklist} +\item[The Elements of Typographic Style]by Robert Bringhurst + (Hartley \& Marks, 1992, \ISBN{0-88179-033-8}) +\item[Finer Points in the Spacing \& Arrangement of Type]by Geoffrey Dowding + (Hartley \& Marks, 1996, \ISBN{0-88179-119-9}) +\item[The Thames \& Hudson Manual of Typography]by Ruari McLean + (Thames \& Hudson, 1980, \ISBN{0-500-68022-1}) +\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, 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 + % ! line break + (\href{http://www.kindersleyworkshop.co.uk/}{The Cardozo Kindersley Workshop} + 2001, \ISBN{1-874426-139}) +\end{booklist} + + There are many catalogues of type specimens but the following books provide +a more interesting overall view of types in general and some of their history. +\begin{booklist} +\item[Alphabets Old \& New]by Lewis F.~Day + (Senate, 1995, \ISBN{1-85958-160-9}) +\item[An Introduction to the History of Printing Types]by Geoffrey Dowding + (British Library, 1998, UK \ISBN{0-7123-4563-9}; USA \ISBN{1-884718-44-2}) +\item[The Alphabet Abecedarium]by Richard A.~Firmage + (David R.~Godine, 1993, \ISBN{0-87923-998-0}) +\item[The Alphabet and Elements of Lettering]by Frederick Goudy + (Dover, 1963, \ISBN{0-486-20792-7}) +\item[Anatomy of a Typeface]by Alexander Lawson + (David R.~Godine, 1990, \ISBN{0-87923-338-8}) +\item[A Tally of Types]by Stanley Morison + (David R.~Godine, 1999, \ISBN{1-56792-004-7}) +\item[Counterpunch]by Fred Smeijers + (Hyphen, 1996, \ISBN{0-907259-06-5}) +\item[Treasury of Alphabets and Lettering]by Jan Tschichold + (W.~W.~Norton, 1992, \ISBN{0-393-70197-2}) +\item[A Short History of the Printed Word]by Warren Chappell and + Robert Bringhurst (Hartley \& Marks, 1999, \ISBN{0-88179-154-7}) +\end{booklist} + + The above lists are limited to books published in English. Typographic +styles are somewhat language-dependent, and similarly the `interesting' fonts +depend on the particular writing system involved. + +\Question[Q-whereFAQ]{Where to find \acro{FAQ}s} + +Bobby Bodenheimer's article, from which this \acro{FAQ} was developed, used +to be posted (nominally monthly) to newsgroup +\Newsgroup{comp.text.tex}. The (long +obsolete) last posted copy of that article is kept on \acro{CTAN} for +auld lang syne. + +\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 +\end{pdfversion} +\begin{dviversion} +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} +\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}. + +Both the Francophone \TeX{} user group Gutenberg and the Czech/Slovak +user group CS-TUG have published translations of this \acro{FAQ}, with +extensions appropriate to their languages. + +Herbert Vo\ss{}'s excellent % beware line break +\href{http://texnik.de/}{\LaTeX{} tips and tricks} +provides excellent advice on most topics one might imagine (though +it's not strictly a \acro{FAQ})~--- highly recommended for most +ordinary mortals' use. + +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 (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]% +%% 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-gethelp]{How to get help} + +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. The +\acro{CTAN} Catalogue can also identify packages that might help: you +can \href{http://www.tex.ac.uk/search}{search it}, or you can browse it +% !!!! line break +``\href{http://www.tex.ac.uk/tex-archive/help/Catalogue/bytopic.html}{by topic}''. +A catalogue entry has a brief description of the package, and links to +any known documentation on the net. In fact, a large proportion of +\acro{CTAN} package directories now include documentation, so it's +often worth looking at the catalogue entry for a package you're considering +using. + +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}, or (as a long shot) +the archives of ancient posts on \acro{CTAN}. + +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. + +Do \textbf{not} try mailing the % ! line break +\Qref*{\LaTeX{} project team}{Q-LaTeX3}, +the maintainers of the \texlive{} or \miktex{} distributions +or the maintainers of these \acro{FAQ}s +for help; while all these addresses reach experienced \AllTeX{} +users, no small group can possibly have expertise in every area of +usage so that the ``big'' lists are a far better bet. +\begin{ctanrefs} +\item[texhax \nothtml{\rmfamily}`back copies']\CTANref{texhax} +\end{ctanrefs} + +\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} list server; 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://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} + +\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-gethelp}, but how do you +phrase it? + +Excellent ``general'' advice (how to ask questions of anyone) is +contained in +%beware line break +\href{http://catb.org/~esr/faqs/smart-questions.html}{Eric Raymond's article on the topic}. +Eric's an extremely self-confident person, and this comes through in +his advice; but his guidelines are very good, even for us in the +un-self-confident majority. It's important to remember that you don't +have a right to advice from the world, but that if you express +yourself well, you will usually find someone who will be pleased to +help. + +So how do you express yourself in the \AllTeX{} world? There aren't +any comprehensive rules, but a few guidelines may help in the +application of your own common sense. +\begin{itemize} +\item Make sure you're asking the right people. Don't ask in a \TeX{} + forum about printer device drivers for the \ProgName{Foobar} + operating system. Yes, \TeX{} users need printers, but no, \TeX{} + users will typically \emph{not} be \ProgName{Foobar} systems + managers. + + Similarly, avoid posing a question in a language that the majority + of the group don't use: post in Ruritanian to + \Newsgroup{de.comp.text.tex} and you may have a long wait before a + German- and Ruritanian-speaking \TeX{} expert notices your + question. +\item If your question is (or may be) \TeX{}-system-specific, report + what system you're using, or intend to use: ``I can't install + \TeX{}'' is as good as useless, whereas ``I'm trying to install the + \ProgName{mumbleTeX} distribution on the \ProgName{Grobble} + operating system'' gives all the context a potential respondent + might need. Another common situation where this information is + important is when you're having trouble installing something new in + your system: ``I want to add the \Package{glugtheory} package to my + \ProgName{mumbleTeX v12.0} distribution on the \ProgName{Grobble 2024} + operating system''. +\item If you need to know how to do something, make clear what your + environment is: ``I want to do \emph{x} in \plaintex{}'', or ``I + want to do \emph{y} in \LaTeX{} running the \Class{boggle} + class''. If you thought you knew how, but your attempts are + failing, tell us what you've tried: ``I've already tried installing + the \Package{elephant} in the \Package{minicar} directory, and it + didn't work, even after refreshing the filename database''. +\item If something's going wrong within \AllTeX{}, pretend you're + \Qref*{submitting a \LaTeX{} bug report}{Q-latexbug}, + and try to generate a \Qref*{minimum failing example}{Q-minxampl}. + If your example + needs your local \Class{xyzthesis} class, or some other resource + not generally available, be sure to include a pointer to how the + resource can be obtained. +\item Figures are special, of course. Sometimes the figure itself is + \emph{really} needed, but most problems may be demonstrated with a + ``figure substitute'' in the form of a + \cmdinvoke*{rule}{width}{height} command, for some value of + \meta{width} and \meta{height}. If the (real) figure is needed, + don't try posting it: far better to put it on the web somewhere. +\item Be as succinct as possible. Your helpers don't usually need to + know \emph{why} you're doing something, just \emph{what} you're + doing and where the problem is. +\end{itemize} + +\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'' (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. + +There are two valid approaches to this task: building up, and hacking +down. + +% ! line break +\latexhtml{The ``building up'' process}{\textbf{\emph{Building up}}} starts +with a basic document structure +(for \LaTeX{}, this would have \csx{documentclass}, +\cmdinvoke{begin}{document}, \cmdinvoke{end}{document}) and adds +things. First to add is a paragraph or so around the actual point +where the problem occurs. (It may prove difficult to find the actual +line that's provoking the problem. If the original problem is an +error, reviewing % ! line break +\Qref[the answer to question]{``the structure of \TeX{} errors''}{Q-errstruct} +may help.) + +Note that there are things that can go wrong in one part of the +document as a result of something in another part: the commonest is +problems in the table of contents (from something in a section title, +or whatever), or the list of \meta{something} (from something in a +\csx{caption}). In such a case, include the section title or caption +(the caption probably needs the \environment{figure} or +\environment{table} environment around it, but it \emph{doesn't} need +the figure or table itself). + +If this file you've built up shows the problem already, then you're done. +Otherwise, try adding packages; the optimum is a file with only one +package in it, but you may find that the guilty package won't even load +properly unless another package has been loaded. (Another common case +is that package \Package{A} only fails when package \Package{B} has been +loaded.) + +% ! line break +\latexhtml{The ``hacking down'' route}{\textbf{\emph{Hacking down}}} 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 +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), 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 +you can, it may be useful to make a copy available on the web +somewhere: people will probably understand if it's impossible~\dots{}\ +or inadvisable, in the case of something confidential. + +If the whole document is necessary, it could be that it's an overflow +of some sort; the best you can do is to post the code ``around'' the +error, and (of course) the full text of the error. + +It may seem that all this work is rather excessive for preparing a +simple post. There are two responses to that, both based on the +relative inefficiency of asking a question on the internet. + +First, preparing a minimum document very often leads \emph{you} to the +answer, without all the fuss of posting and looking for responses. + +Second, your prime aim is to get an answer as quickly as possible; a +well-prepared example stands a good chance of attracting an answer +``in a single pass'': if the person replying to your post finds she +needs more information, you have to find that request, post again, and +wait for your benefactor to produce a second response. + +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.minimalbeispiel.de/mini-en.html}; source of that +article may be found at \URL{http://www.minimalbeispiel.de/}, in +both German and English. + +\Question[Q-tutorials*]{\AllTeX{} Tutorials, etc.} + +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*{\plaintex{}}{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: \plaintex{}} + +Michael Doob's splendid `Gentle Introduction' to \plaintex{} +(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{}} + +A pleasing little document, ``Getting something out of \LaTeX{}'' is +designed to give a feel of \LaTeX{} to someone who's never used it at +all. It's not a tutorial, merely helps the user to decide whether to +go on to a tutorial, and to `real' use of \LaTeX{}. + +Tobias Oetiker's `(Not so) Short Introduction to \LaTeXe{}', is +regularly updated, as people suggest better ways of explaining things, +etc. The introduction is available on \acro{CTAN}, together with +translations into a rather large set of languages. + +Peter Flynn's ``Beginner's \LaTeX{}'' (which started life as course +material) is a pleasing read. A complete copy may be found on +\acro{CTAN}, but it may also be browsed over the web +(\URL{http://www.tex.ac.uk/tex-archive/info/beginlatex/html/}). + +Harvey Greenberg's `Simplified Introduction to \LaTeX{}' was written +for a lecture course, and is also available on \acro{CTAN} (in \PS{} +only, unfortunately). + +The fourth edition of George Gr\"atzer's book ``Math into \LaTeX{}'' +contains a ``short course'' in \LaTeX{} itself, and that course has +been made publicly available on \acro{CTAN}. + +Philip Hirschhorn's ``Getting up and running with \AMSLaTeX{}'' has a +brief introduction to \LaTeX{} itself, followed by a substantial +introduction to the use of the \acro{AMS} classes and the +\Package{amsmath} package and other things that are potentially of +interest to those writing documents containing mathematics. + +Edith Hodgen's % beware line break +\href{http://www.mcs.vuw.ac.nz/~david/latex/notes.pdf}{\LaTeX{}, a Braindump} +starts you from the ground up~--- giving a basic tutorial in the use +of \ProgName{Linux} to get you going (rather a large file\dots{}). +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. + +% ! 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. + +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 + +Nicola Talbot's % ! line break +\href{http://theoval.cmp.uea.ac.uk/~nlct/latex/novices/}{\LaTeX{} for complete novices} +does what it claims: the author teaches \LaTeX{} at the University of +East Anglia. That is one of several of Nicola's % ! line break +\href{http://theoval.cmp.uea.ac.uk/~nlct/latex/}{introductory tutorials}, +which include exercises (with solutions). Other tutorials include +those for writing theses/dissertations with \LaTeX{}, and for using +\LaTeX{} in administrative work. (The page seems to be an adjunct to +her \LaTeX{} courses~--- fortunate people, the people of \acro{UEA}!). + +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}First \LaTeX{} document]\CTANref{first-latex-doc} +% ! line break +\item[\nothtml{\rmfamily}Getting up and running with \AMSLaTeX{}]\CTANref{amslatex-primer} +\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} +\item[\nothtml{\rmfamily}Short Course in \LaTeX{}]\CTANref{mil-short} +% ! 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{} has written an extensive guide to mathematics in +\LaTeX{} (a German version of which is published as a book). The +guide is part of his ``\Qref*{tips and tricks}{Q-doc-dirs}'' and +a copy is maintained on \acro{CTAN}. +%\URL{http://www.perce.de/LaTeX/math/Mathmode-TeX.pdf} + +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. It's available on +\acro{CTAN}, but the sources aren't available (promised ``some time +soon''). + +Kjell Magne Fauske offers a set of examples of the use of the drawing +packages % ! line break +\Qref*{\acro{PGF} and \acro{T}ik\acro{Z}}{Q-drawing}; the % ! line break +\href{http://www.texample.net/tikz/examples/}{examples catalogue} +includes examples (with output) from the package documentation as well +as code written by the author himself. + +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 +correct size and position on standard-sized paper, and that the print +quality is satisfactory, is Mike Shell's \Package{testflow}. The +tutorial consists of a large plain text document, and there is a +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}. + +Documentation of Japanese \TeX{} use appears at least twice on the web: +Haruhiko Okumura's page on +% ! 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} +documentation of the \AllTeX{} installation, of which a sample is the +\LaTeX{} documentation available at +\URL{http://www.tac.dk/cgi-bin/info2www?(latex)} + +More ambitiously, some university departments have enthusiastic +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. +\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} + +\Question[Q-ref-doc]{Reference documents} + +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 \plaintex{} as +well as the primitive commands. + +An interesting \LaTeX{} ``cheat sheet'' is available from \acro{CTAN}: +it's a list of (more or less) everything you `ought to' remember, for +basic \LaTeX{} use. (It's laid out very compactly for printing on N.\ +American `letter'; printed on \acro{ISO} \acro{A}4, using Adobe +Acrobat's ``shrink to fit'', it strains aged eyes\dots{}) + +Similarly, there's no completely reliable command-organised reference +to \LaTeX{}. The page (provided by \acro{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. + +Another \LaTeXe{} reference (provided by the Emerson Center of Emory +University) is: % ! line break +\href{http://www.emerson.emory.edu/services/latex/latex2e/latex2e_toc.html}{LaTeXe help} +\begin{ctanrefs} +\item[\nothtml{\rmfamily}Cheat sheet]\CTANref{latexcheat} +\end{ctanrefs} + +\Question[Q-doc-wiki]{WIKI pages for \TeX{} and friends} + +The \emph{WIKI} concept can be a boon to everyone, if used sensibly. +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}, valiant efforts +have been made generating ``WIKI books'' for \AllTeX{} users. Thus we +have \href{http://en.wikibooks.org/wiki/TeX}{(Plain) \TeX{} WIKI} and +\href{http://en.wikibooks.org/wiki/LaTeX}{\LaTeX{} WIKI} are well +established. Neither would seem yet to be of publication quality, but +they both seem useful reference sources. + +\Question[Q-typo-style]{Typography tutorials} + +Peter Wilson's manual for his \Class{memoir} class has a lengthy +introductory section on typographic considerations, which is a fine +tutorial, written by someone who is aware of the issues as they apply +to \AllTeX{} users. + +There's also (at least one) typographic style tutorial available on +the Web, the excellent % ! line break +``\href*{http://www.nbcs.rutgers.edu/~hedrick/typography/typography.janson-syntax.107514.pdf}{Guidelines for Typography in NBCS}''. +In fact, its % !! +\href*{http://www.nbcs.rutgers.edu/~hedrick/typography/index.html}{parent page} +is also worth a read: among other things, it provides copies of the +``guidelines'' document in a wide variety of primary fonts, for +comparison purposes. The author is careful to explain that he has no +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. +\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 now available on \acro{CTAN}; it's not a +beginner's tutorial but it's a fine reference. It's also available, +as a printed copy, via the on-line publishers +\href{http://www.lulu.com/content/2555607/}{Lulu} (not quite free, of +course, but not a \emph{bad} deal\dots{}). + +Addison-Wesley have also released the copyright of ``\TeX{} for the +Impatient'' by Paul W.~Abrahams, Karl Berry and Kathryn A.~Hargreaves, +another book whose unavailability many have lamented. The authors +have re-released the book under the \acro{GNU} Free 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}Making \TeX{} Work]\CTANref{mtw} +\item[\nothtml{\rmfamily}\TeX{} by Topic]\CTANref{texbytopic} +\item[\nothtml{\rmfamily}\TeX{} for the Impatient]\CTANref{TftI} +\end{ctanrefs} + +\Question[Q-pkgdoc]{Documentation of packages} + +These \acro{FAQ}s regularly suggest packages that will ``solve'' +particular problems. In some cases, the answer provides a recipe for +the job. In other cases, or when the solution needs elaborating, how +is the poor user to find out what to do? + +If you're lucky, the package you need is already in your installation. +If you're particularly lucky, you're using a distribution that gives +access to package documentation and the documentation is available in +a form that can easily be shown. For example, on many current +distributions, the \ProgName{texdoc} command often helps, as in: +\begin{quote} +\begin{verbatim} +texdoc footmisc +\end{verbatim} +\end{quote} +which opens a window showing documentation of the +\Package{footmisc} package. According to the type of file +\ProgName{texdoc} finds, it will launch a \acro{DVI} viewer +or a \acro{PDF} reader. + +If \ProgName{texdoc} can't find any documentation, it may launch a Web +browser to look at its copy of the \acro{CTAN} catalogue. The +catalogue has an entry for package documentation, and since the +\acro{CTAN} team asks authors documentation of their packages (and +members of the team even occasionally generate documentation that +seems useful), you will more often than not find documentation that +way. + +If your luck (as defined above) doesn't hold out, you've got to find +documentation by other means. This is where you need to exercise your +intelligence: you have to find the documentation for yourself. What +follows offers a range of possible techniques. + +The commonest form of documentation of \LaTeX{} add-ons is within the +\extension{dtx} file in which the code is distributed (see +\Qref[answer]{documented \LaTeX{} sources}{Q-dtx}). Such files +are supposedly processable by \LaTeX{} itself, but there are +occasional hiccups on the way to readable documentation. Common +problems are that the package itself is needed to process its own +documentation (so must be unpacked before processing), and that the +\extension{dtx} file will \emph{not} in fact process with \LaTeX{}. In the +latter case, the \extension{ins} file will usually produce a +\extension{drv} (or similarly-named) file, which you process with +\LaTeX{} instead. (Sometimes the package author even thinks to +mention this wrinkle in a package \texttt{README} file.) + +Another common form is the separate documentation file; particularly +if a package is ``conceptually large'' (and therefore needs a lot of +documentation), the documentation would prove a cumbersome extension +to the \extension{dtx} file. Examples of such cases are the \Class{memoir} +class (whose documentation, \File{memman}, is widely praised as an +introduction to typesetting concepts), the \Class{KOMA-script} bundle +(whose developers take the trouble to produce detailed documentation +in both German and English), and the \Package{fancyhdr} package (whose +documentation derives from a definitive tutorial in a mathematical +journal). Even if the documentation is not separately identified in a +\texttt{README} file, it should not be too difficult to recognise its +existence. + +Documentation within the package itself is the third common form. +Such documentation ordinarily appears in comments at the head of the +file, though at least one eminent author regularly places it after the +\csx{endinput} command in the package. (This is desirable, since +\csx{endinput} is a `logical' end-of-file, and \AllTeX{} doesn't read +beyond it: thus such documentation does not `cost' any package loading time.) + +The above suggestions cover most possible ways of finding +documentation. If, despite your best efforts, you can't find +it in any of the above places, there's the awful possibility that the +author didn't bother to document his package (on the ``if it was hard +to write, it should be hard to use'' philosophy). Most ordinary +mortals will seek support from some more experienced user at this +stage, though it \emph{is} possible to proceed in the way that the original +author apparently expected\dots{}by reading his code. + +\Question[Q-writecls]{Learning to write \LaTeX{} classes and packages} + +There's nothing particularly magic about the commands you use when +writing a package, so you can simply bundle up a set of \LaTeX{} +\csx{(re)newcommand} and \csx{(re)newenvironment} commands, put them in +a file \File{package.sty} and you have a package. + +However, any but the most trivial package will require rather more +sophistication. Some details of \LaTeX{} commands for the job are to +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-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 +source of \LaTeX{} may be prepared by processing the file +\File{source2e.tex} in the \LaTeX{} distribution. Such processing is +noticeably tedious, but Heiko Oberdiek has prepared a well-linked +\acro{PDF} version, which is in the file \File{base.tds.zip} of his +\ProgName{latex-tds} distribution. Individual files in the \LaTeX{} +distribution may be processed separately with \LaTeX{}, like any +well-constructed \Qref*{\extension{dtx} file}{Q-dtx}. + +Writing good classes is not easy; it's a good idea to read some +established ones (\File{classes.dtx}, for example, is the documented +source of the standard classes other than \Class{Letter}, and may +itself be formatted with \LaTeX{}). Classes that are not part of the +distribution are commonly based on ones that are, and start by loading +the standard class with \csx{LoadClass}~--- an example of this +technique may be seen in \Package{ltxguide.cls} + +An % !! line break +\href{http://tug.org/TUGboat/Articles/tb28-1/tb88flynn.pdf}{annotated version of \Class{article}}, +as it appears in \File{classes.dtx}, was published in +\TUGboat{} 28(1). The article, by Peter Flynn, which is some help in +understanding \File{classes.dtx} +\begin{ctanrefs} +\item[classes.dtx]\CTANref{latex-classes} +\item[clsguide.pdf]\CTANref{clsguide} +\item[latex-tds \nothtml{rmfamily}collection]\CTANref{latex-tds} +\item[ltxguide.cls]\CTANref{ltxguide} +\item[\nothtml{\rmfamily}\LaTeX{} documentation]\CTANref{latexdoc} +\item[source2e.tex]\CTANref{latex-source} +\end{ctanrefs} + +\Question[Q-mfptutorials]{\MF{} and \MP{} Tutorials} + +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 +(see \Qref[question]{using \MF{}}{Q-useMF}) describes how the \MF{} +system works and how to avoid some of the potential pitfalls. + +There is also an article on how to run both \MF{} and \MP{} (the +programs). Peter Wilson's % !! line break +\textit{Some Experiences in Running \MF{} and \MP{}} +offers the benefit of Peter's experience (he has designed a number of +`historical' fonts using \MF{}). For \MF{} the article is geared +towards testing and installing new \MF{} fonts, while its \MP{} +section describes how to use \MP{} illustrations in \LaTeX{} and +\PDFLaTeX{} documents, with an emphasis on how to use appropriate +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 % ! line break +% \href{http://www.pragma-ade.com/metapost.htm}{\MP{} page}. + +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 even 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 (by Troy +Henderson) for testing little bits of \MP{}, which is an invaluable +aid to the learner: \URL{http://www.tlhiv.org/mppreview} + +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 +\href{http://zoonek.free.fr/LaTeX/Metapost/metapost.html}{viewed on the web}. +While these examples don't exactly constitute a ``tutorial'', they're +most certainly valuable learning material. Urs Oswald presents a +\href{http://www.ursoswald.ch/metapost/tutorial.pdf}{similar document}, +written more as a document, and presented in \acro{PDF}. +\begin{ctanrefs} +\item[\nothtml{\rmfamily}Beginners' guide]\CTANref{mf-beginners} +\item[\nothtml{\rmfamily}Peter Wilson's ``experiences'']\CTANref{metafp-pdf} +\item[\nothtml{\rmfamily}Vincent Zoonekynd's examples]\CTANref{zoon-mp-eg} +\end{ctanrefs} + +\Question[Q-BibTeXing]{\BibTeX{} Documentation} + +\BibTeX{}, a program originally designed to produce bibliographies in +conjunction with \LaTeX{}, is explained in Section~4.3 and Appendix~B +of Leslie Lamport's \LaTeX{} manual. +The document ``\BibTeX{}ing'', contained in the file \File{btxdoc.tex}, +expands on the chapter in Lamport's book. \emph{The \LaTeX{} Companion} +also has information on \BibTeX{} and writing \BibTeX{} style files. +(See \Qref[question]{TeX-related books}{Q-books} for details of both +books.) + +The document ``Designing \BibTeX{} Styles'', contained in the file +\File{btxhak.tex}, explains the postfix stack-based language used to +write \BibTeX{} styles (\File{.bst} files). The file \File{btxbst.doc} +is the template for the four standard styles (\Package{plain}, +\Package{abbrv}, \Package{alpha}, and \Package{unsrt}). It also +contains their documentation. The complete \BibTeX{} documentation +set (including all 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}. A summary and \acro{FAQ} +(\File{btxFAQ}), by Michael Shell and David Hoadley, is also to be +recommended. +\begin{ctanrefs} +\item[\nothtml{\rmfamily}\BibTeX{} documentation]\CTANref{bibtex-doc} +\item[btxFAQ.pdf]\CTANref{bibtex-faq} +\item[\nothtml{\rmfamily}Tame the BeaST]\CTANref{ttb-pdf} +\end{ctanrefs} + +\Question[Q-symbols]{Where can I find the symbol for\,\dots{}} +\keywords{assignment circular integral degrees diagonal dots Fourier transform} +\keywords{Laplace greater less complex integer natural real} +\keywords{cent euro} + +There is a wide range of symbols available for use with \TeX{}, most +of which are not shown (or even mentioned) in \AllTeX{} books. +\emph{The Comprehensive \LaTeX{} Symbol List} (by Scott Pakin +% beware line wrap +\emph{et al.}\@) illustrates over 2000 symbols, and details the +commands and the \LaTeX{} packages needed to produce them. + +Other questions in this \acro{FAQ} offer specific help on kinds of +symbols: +\begin{itemize} +\item \Qref*{Script fonts for mathematics}{Q-scriptfonts} +\item \Qref*{Fonts for the number sets}{Q-numbersets} +\item \Qref*{Typesetting the principal value integral}{Q-prinvalint} +\end{itemize} + +A useful new % ! line break +\href{http://detexify.kirelabs.org/classify.html}{symbol search} web +site is available. It provides you a scratch area on which you draw +the symbol you're thinking of, with your mouse; when you've finished +drawing, the classifier tries to match your sketch with symbols it +knows about. The matching process is pretty good, even for the +sketches of a \emph{really} poor draughtsman, and it's often worth +trying more than once. Given the huge size of the symbol list, this +tool can be very helpful. +\begin{ctanrefs} +\item[Symbol List]Browse \CTANref{symbols}; there are processed + versions in both \PS{} and \acro{PDF} forms for both A4 and + letter paper. +\end{ctanrefs} + +\Question[Q-docpictex]{The \PiCTeX{} manual} + +\PiCTeX{} is a set of macros by Michael Wichura for drawing diagrams +and pictures. The +macros are freely available; however, the +\PiCTeX{} manual itself is not free. +Unfortunately, \acro{TUG} is no longer able to supply copies of the +manual (as it once did), and it is now available only through Personal +\TeX{} Inc, the vendors of PC\TeX{} (\URL{http://www.pctex.com/}). The +manual is \emph{not} available electronically. + +However, there \emph{is} a summary of \PiCTeX{} commands available on +\acro{CTAN}, which is a great aide-memoire for those who basically +know the package to start with. +\begin{ctanrefs} +\item[pictex]\CTANref{pictex} +\item[PiCTeX summary]\CTANref{pictex-summary} +\end{ctanrefs} |