diff options
Diffstat (limited to 'help/uk-tex-faq/faq-docs.tex')
-rw-r--r-- | help/uk-tex-faq/faq-docs.tex | 1305 |
1 files changed, 0 insertions, 1305 deletions
diff --git a/help/uk-tex-faq/faq-docs.tex b/help/uk-tex-faq/faq-docs.tex deleted file mode 100644 index dbbdeb37c5..0000000000 --- a/help/uk-tex-faq/faq-docs.tex +++ /dev/null @@ -1,1305 +0,0 @@ -% $Id: faq-docs.tex,v 1.46 2014/03/04 15:42:45 rf10 Exp rf10 $ - -\section{Documentation and Help} - -\Question[Q-book-lists]{Books relevant to \tex{} and friends} - -There are too many books for them all to appear in a single list, so -the following answers aim to cover ``related'' books, with subject -matter as follows: -\begin{itemize} -\item \Qref*{\tex{} itself and \plaintex{}}{Q-tex-books} -\item \Qref*{\latex{}}{Q-latex-books} -\item \Qref*{Books on other \tex{}-related matters}{Q-other-books} -\item \Qref*{Books on Type}{Q-type-books} -\end{itemize} - -These lists only cover books in English: notices of new books, or -warnings that books are now out of print are always welcome. However, -these \acro{FAQ}s do \emph{not} carry reviews of current published -material. -\LastEdit*{2011-06-01} - -\Question[Q-tex-books]{Books on \TeX{}, \plaintex{} and relations} -\AliasQuestion{Q-books} - -While Knuth's book is the definitive reference for both \TeX{} and -\plaintex{}, there are many books covering these topics: -\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 also 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 comments 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) -\begin{typesetversion} -\item[\TeX{}: Starting from \sqfbox{1}\,\footnotemark]% -\footnotetext{That's `Starting from Square One'}% -\end{typesetversion} -\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} -\LastEdit*{2011-06-01} - -\Question[Q-latex-books]{Books on \latex{}} - -\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[\latex{} Beginner's Guide]by Stefan Kottwitz (Packt Publishing, - 2011, \ISBN*{1847199860}{978-1847199867}) -\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}); the - book as also available as a digital download (in \acro{EPUB}, - \acro{MOBI} and \acro{PDF} formats) from - \url{http://www.informit.com/store/latex-companion-9780133387667} -\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} -\item[More Math into \latex{}:]\emph{An Introduction to} \LaTeX{} - \emph{and} \AMSLaTeX{} by George Gr\"atzer (fourth edition Springer Verlag, - 2007, \ISBN{978-0-387-32289-6} -%% 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 of Digital Typography Using -% \LaTeX{} is available from: -% \URL{http://www.springer-ny.com/catalog/np/jan99np/0-387-98708-8.html} -% (not any longer) -\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) -\item[Typesetting Mathematics with \latex{}]by Herbert Vo\ss {} (UIT - Cambridge, 2010, \ISBN{978-1-906-86017-2}) -% checked 2011-09-09 http://www.uit.co.uk/BK-TMWL/HomePage -\item[Typesetting Tables with \latex{}]by Herbert Vo\ss {}, (UIT - Cambridge, 2011, \ISBN{978-1-906-86025-7}) -% checked 2011-09-09 http://www.uit.co.uk/BK-TTWL/HomePage -\item[PSTricks: Graphics and PostScript for \tex{} and \latex{}]by - Herbert Vo\ss {}, (UIT Cambridge, 2011, \ISBN{978-1-906-86013-4}) -\end{booklist} -A sample of George Gr\"atzer's ``Math into \LaTeX{}'', in Adobe -Acrobat format, and example files -for the three \LaTeX{} Companions, and for -Gr\"atzer's ``First Steps in \LaTeX{}'', are all available on -\acro{CTAN}. -\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} -\LastEdit{2014-03-14} - -\Question[Q-other-books]{Books on other \tex{}-related matters} - -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}''. -\LastEdit*{2011-06-01} - -\Question[Q-type-books]{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. -\LastEdit{2011-06-01} - -\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} -\LastEdit{2013-07-02} - -\Question[Q-gethelp]{Getting help online} - -We assume, here, that you have looked at all relevant -\Qref*{\acro{FAQ} answers}{Q-whereFAQ} you can find, you've looked in -any \Qref*{books}{Q-book-lists} you have, and scanned relevant -\Qref*{tutorials}{Q-tutorials*}\dots{} and still you don't know what -to do. - -There are two more steps you can take before formulating a question to -the \tex{} world at large. - -First, (if you are seeking a particular package or program), start by -looking on your own system: you might already have what you seek~--- -the better \TeX{} distributions provide a wide range of supporting -material. The \Qref*{\acro{CTAN} Catalogue}{Q-catalogue} can also -identify packages that might help: you can % ! line break -\href{http://www.tex.ac.uk/search}{search it}, or you can browse it -\begin{hyperversion} -% !!!! line break -``\href{http://mirrors.ctan.org/help/Catalogue/bytopic.html}{by topic}''. -\end{hyperversion} -\begin{flatversion} -``by topic'' at -\url{http://mirrors.ctan.org/help/Catalogue/bytopic.html} -\end{flatversion} -Each catalogue entry has a brief description of the package, and links to -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 (where possible, each package link in the main body of these -\acro{FAQ}s \hyperflat{has a link to}{shows the \acro{URL} of} -the relevant catalogue entry). - -Failing that, look to see if anyone has solved the problem before; -places where people ask are: -\begin{enumerate} -\item newsgroup \Newsgroup{comp.text.tex}, whose ``historical posts'' - are accessible via - \href{http://groups.google.com/group/comp.text.tex}{Google groups}, - and -\item the mailing list \texttt{texhax} via its - \href{http://tug.org/pipermail/texhax/}{archive}, or via the `Gmane' - newsgroup \Newsgroup{gmane.comp.tex.texhax}, which holds a - \emph{very} long history of the list. A long shot would be to - search the archives of the mailing list's ancient posts on - \acro{CTAN}, which go back to the days when it was a digest: in - those days, a question asked in one issue would only ever be - answered in the next one. -\end{enumerate} -If the ``back question'' searches fail, you must ask the world at -large. - -So, how do you like to ask questions?~--- the three available -mechanisms are: -\begin{enumerate} -\item Mailing lists: there are various specialist mailing lists, but - the place for `general' \alltex{} queries is the \texttt{texhax} - mailing list. Mail to \mailto{texhax@tug.org} to ask a question, - but it's probably better to subscribe to the list - (via \URL{http://tug.org/mailman/listinfo/texhax}) % ! no ~ allowed - first~--- not everyone will answer to you as well as to the list. -\item Newsgroup: to ask a question on \Newsgroup{comp.text.tex}, you - can use your own news client (if you have one), or use the ``+ new - post'' button on - \URL{http://groups.google.com/group/comp.text.tex}. -\item Web forum: alternatives are: the % ! line break - \href{http://www.latex-community.org/}{``\LaTeX{} community'' site}, - which offers a variety of `categories' to place your query, and the - % the next line will tend to break if you add _anything_ to it! - \href{http://tex.stackexchange.com/}{\TeX{}, \LaTeX{} and friends Q\&A site} - (``StackExchange''). - - StackExchange has a scheme for voting on the quality of answers (and - hence of those who offer support). This arrangement is supposed to - enable you to rank any answers that are posted. - - StackExchange offers - \href{http://meta.tex.stackexchange.com/questions/1436/welcome-to-tex-sx}{hints about ``good behaviour''}, - which any user should at least scan before asking for help there. - (The hints' principal aim is to maximise the chance that you get useful - advice from the first answer; for example, it suggests that you supply a - \Qref*{minimal example of your problem}{Q-askquestion}, just as - these \acro{FAQ}s do. There are people on the site who can be abrasive - to those asking questions, who seem not to be following the - guidelines for good behaviour) -\end{enumerate} -Do \textbf{not} try mailing the \LaTeX{} project team, 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 and forums -are a far better bet. -\begin{ctanrefs} -\item[texhax \nothtml{\rmfamily}`back copies']\CTANref{texhax} -\end{ctanrefs} -\LastEdit{2014-01-28} - -\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. - -The process of `building up', and to some extent that of `hacking -down', can be helped by stuff available on \acro{CTAN}: -\begin{itemize} -\item the \Class{minimal} class (part of the \latex{} distribution) - does what its name says: it provides nothing more than what is - needed to get \latex{} code going, and -\item the \Package{mwe} bundle provides a number of images in formats - that \alltex{} documents can use, and a small package \Package{mwe} - which loads other useful packages (such as \Package{blindtext} and - \Package{lipsum}, both capable of producing dummy text in a - document). -\end{itemize} - -What if none of of these cut-down derivatives of your document will -show your error? 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 indeed necessary, it could be that your -error is 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. - -Much of 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. -\begin{ctanrefs} -\item[blindtext.sty]\CTANref{blindtext} -\item[lipsum.sty]\CTANref{lipsum} -\item[minimal.cls]Distributed as part of \CTANref{latex} -\item[mwe.sty]\CTANref{mwe} -\end{ctanrefs} -\LastEdit{2013-01-09} - -\Question[Q-tutorials*]{Tutorials, etc., for \tex{}-based systems} - -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 small selection 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 (somewhat newer) 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}. -\LastEdit{2011-09-26} - -\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 thence 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://mirrors.ctan.org/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. - -D. R.~Wilkins' % ! line break -\href{http://www.maths.tcd.ie/~dwilkins/LaTeXPrimer/}{`Getting started with \latex{}'} -also looks good (it appears shorter~--- more of a primer~--- than some -of the other offerings). - -Chris Harrison's % ! line break -\href{http://xoph.co/20111024/latex-tutorial/}{LaTeX tutorial} -presents basic \LaTeX{} in a rather pleasing and straightforward way. - -Nicola Talbot's % ! line break -\href{http://www.dickimaw-books.com/latex/novices/}{\LaTeX{} for complete novices} -does what it claims: the author teaches \LaTeX{} at the University of -East Anglia. The ``Novices'' tutorial is one of several % ! line break -\href{http://www.dickimaw-books.com/latex/}{introductory tutorials}, -which include exercises (with solutions). Other tutorials include -those for % ! line break -\href{http://www.dickimaw-books.com/latex/thesis/}{writing theses/dissertations with \LaTeX{}}, and for % ! line break -\href{http://www.dickimaw-books.com/latex/admin/}{using \LaTeX{} in administrative work} - -Engelbert Buxbaum provides the `slides' for his \latex{} course `The -\latex{} document preparation system'; this seems to be a departmental -course at his university. - -Mark van Dongen's % line break -\href{"http://csweb.ucc.ie/~dongen/LaTeX-and-Friends.pdf}{`\latex and friends'} -appeared as he was writing his book on the subject (soon to be published). - -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} -% ! line break -\item[\nothtml{\rmfamily}Getting something out of \latex{}]\CTANref{first-latex-doc} -% ! line break -\item[\nothtml{\rmfamily}Getting up and running with \AMSLaTeX{}]\CTANref{amslatex-primer} -\item[\nothtml{\rmfamily}Slides for \latex{} course]\CTANref{latex-course} -\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]Browse - \CTANref{l2tabu} for a copy of the document in a language that is - convenient for you -\end{ctanrefs} -\LastEdit{2012-11-29} - -\Question[Q-tutbitslatex]{\AllTeX{} tutorials} -\AliasQuestion{Q-doc-dirs} - -The \acro{AMS} publishes a ``Short Math Guide for \LaTeX{}'', which is -available (in several formats) via -\URL{http://www.ams.org/tex/amslatex.html} (the ``Additional -Documentation'' about half-way down the page. - -Herbert Vo\ss {} has written an extensive guide to mathematics in -\LaTeX{}, and a development of it has been % ! line break -\Qref*{published as a book}{Q-latex-books}. - -Two documents written more than ten years apart about font usage in -\TeX{} are worth reading: % ! line break -\href{http://www.tug.org/TUGboat/Articles/tb14-2/tb39rahtz-nfss.pdf}{Essential NFSS} -by Sebastian Rahtz, and % ! line break -\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}. - -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/tutorials/tugindia}\nobreakspace--- there -are 17~chapters in the series, two of which are mostly introductory. - -Peter Smith's -\begin{narrowversion} - ``\LaTeX{} for Logicians'' - (\URL{http://www.logicmatters.net/latex-for-logicians/}) -\end{narrowversion} -\begin{wideversion} - % ! line break - ``\href{http://www.logicmatters.net/latex-for-logicians/}{\LaTeX{} for Logicians}'' -\end{wideversion} -page 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{}'' -(\Package{epslatex}) is an -excellent introduction to graphics use. It's available on -\acro{CTAN}, but not in the \texlive{} or miktex{} distributions, for -lack of sources. - -Stefan Kottwitz manages a web site devoted to the use of the drawing -packages % ! line break -\Qref*{\acro{PGF} and \acro{T}ik\acro{Z}}{Q-drawing}, % ! line break -\url{http://www.texample.net/} - -Included is % ! 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 original site maintainer (Kjell Magne Fauske) -and others. - -The compendious \acro{PGF}/\acro{T}ik\acro{Z} manual is clear, but is -bewildering for some beginners. The % ! line break -\href{http://cremeronline.com/LaTeX/minimaltikz.pdf}{`minimal' introduction} -has helped at least the present author. - -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 \ensuremath{\Omega{}} use appears in -Haruhiko Okumura's page -% ! 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} list). - -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 -department'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{}]\CTANref{epslatex} -\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. % line break -(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{}) - -For command organised references to \LaTeX{}, Karl Berry (et -al)'s % !line break -\href{http://home.gna.org/latexrefman}{LaTeX reference manual} is (to -an extent) work in progress, but is generally reliable (source is -available on the.archive as well). - -Martin Scharrer's ``List of internal \latex{} macros'' is a help to -those aiming to write a class or package. - -The reference provided by the Emerson Center of Emory -University), % ! line break -\href{http://www.emerson.emory.edu/services/latex/latex2e/latex2e_toc.html}{LaTeXe help} -also looks good. -\begin{ctanrefs} -\item[\nothtml{\rmfamily}Cheat sheet]\CTANref{latexcheat} -\item[\nothtml{\rmfamily}LaTeX reference manual]\CTANref{latex2e-help-texinfo} -\item[\nothtml{\rmfamily}LaTeX internal macros]\CTANref{macros2e} -\end{ctanrefs} -\LastEdit{2012-02-16} - -\Question[Q-doc-wiki]{\acro{WIKI} books for \TeX{} and friends} - -The \emph{\acro{WIKI}} concept can be a boon to everyone, if used sensibly. -The ``general'' \acro{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 -\acro{WIKI} under control. - -Following the encouraging performance of the % ! line break -\href{http://contextgarden.net/}{\CONTeXT{} \acro{WIKI}}, valiant -efforts have been made generating ``\acro{WIKI} books'' for \AllTeX{} -users. Thus we have % ! line break -\href{http://en.wikibooks.org/wiki/TeX}{(Plain) \TeX{} \acro{WIKI} book} and -\href{http://en.wikibooks.org/wiki/LaTeX}{\LaTeX{} \acro{WIKI} book}~--- -both well established. Both are highly rated as reference sources, -and even as introductory texts. -\LastEdit{2012-07-25} - -\Question[Q-typo-style]{Typography tutorials} - -Peter Wilson's article \Package{memdesign} 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. (\Package{Memdesign} now distributed separately from -the manual for his \Class{memoir} class, but was originally part of -that manual) - -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-type-books}, 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[memdesign]\CTANref{memdesign} -\end{ctanrefs} - -\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} -\LastEdit{2011-06-29} - -\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. - -On \texlive{}-based distributions, help should be available from the -\ProgName{texdoc} command, as in: -\begin{quote} -\begin{verbatim} -texdoc footmisc -\end{verbatim} -\end{quote} -which opens a window showing documentation of the \Package{footmisc} -package. (The window is tailored to the file type, in the way normal -for the system.) - -If \ProgName{texdoc} can't find any documentation, it may launch a Web -browser to look at the package's entry in the \acro{CTAN} catalogue. -The catalogue has an entry for package documentation, and most authors -respond to the \acro{CTAN} team's request for documentation of -packages, you will more often than not find documentation that way. - -On \miktex{} systems, the same function is provided by the -\ProgName{mthelp}. - -Note that the site \url{texdoc.net} provides access to the -documentation you \emph{would} have if you had a \emph{full} -installation of \texlive{}; on the site you can simply ask for a -package (as you would ask \ProgName{texdoc}, or you can use the site's -index of documentation to find what you want. (This is helpful for -some of us: many people don't have a full \alltex{} installation on -their mobile phone~\dots{} yet.) - -If your luck (as defined above) doesn't hold out, you've got to find -documentation by other means. That is, you have to find the -documentation for yourself. The rest of this answer 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, the \Class{KOMA-script} bundle -(whose developers take the trouble to produce detailed documentation -in both German and English), the \Package{pgf} documentation (which -would make a substantial book in its own right) -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. -\LastEdit{2012-11-09} - -\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-tex-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, is a good guide to -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} -\LastEdit{2011-07-19} - -\Question[Q-latex3-prog]{\latex{}3 programming} -As yet, there is no book ``Programming in \latex{}3'', and even if -such a thing existed there would be lots of gaps. So there is no -\emph{comprehensive} support. - -However, there are some `resources': -\begin{itemize} -\item The ``introduction to \latex{}3 ideas'' in the \Package{expl3} - documentation gives a broad-brush overview of the concepts. -\item Joseph Wright has written a short series of % !line break - \href{http://www.texdev.net/index.php?s=programming+latex3}{blog posts}, - which may help. -\item There is also a complete command reference in the - \Package{interface3} document. -\end{itemize} - -The documents are still subject to development; some of the broader -design issues are discussed on the \latex{} mailing list -\texttt{latex-l}~--- you may subscribe to that list by sending a -message by sending a message -\begin{quote} - `\texttt{subscribe latex-l <\emph{your name}>}' -\end{quote} -to \mailto{listserv@urz.Uni-Heidelberg.de} -\begin{ctanrefs} -\item[expl3.pdf]\CTANref{expl3-doc} -\item[interface3.pdf]\CTANref{interface3-doc} -\end{ctanrefs} -\LastEdit*{2012-11-29} - -\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. - -Peter Wilson's experience of running both \MF{} and \MP{} (the -programs), \textit{Some Experiences in Running \MF{} and \MP{}} -(available on \ctan{}) 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/general/manuals/metafun-p.pdf}{`manuals' page}. - -Another \MP{} tutorial in English is: % ! line breaks -\url{http://www.tlhiv.org/MetaPost/tutorial/} by Urs Oswald. -One in French (listed here because it's clearly enough written -that even this author understands it), -\url{http://pauillac.inria.fr/~cheno/metapost/metapost.pdf} -by Laurent Ch\'eno. - -Urs Oswald's tutorial uses Troy Henderson's tool -(\URL{http://www.tlhiv.org/mppreview}) for testing little bits of -\MP{}; it is an invaluable aid to the learner: -\URL{http://www.tlhiv.org/mppreview} - -A three-part introduction, by Mari Voipio, was published in -\href{http://tug.org/TUGboat/intromp/tb106voipio-grid.pdf}{\TUGboat34(1) (Entry-level \MP{}: On the grid)}, -\TUGboat34(2) -\href{http://tug.org/TUGboat/intromp/tb107voipio-moveit.pdf}{(Entry-level \MP{}: Move it!\@)}, and -\href{http://tug.org/TUGboat/intromp/tb108voipio-color.pdf}{\TUGboat34(2) (Entry-level \MP{}: Color)}. - -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} -\LastEdit{2014-02-18} - -\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'', in the \bibtex{} distribution (look for -\File{btxdoc}), -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]{\latex{} books}{Q-latex-books} for details of both -books.) - -The web site ``\href{http://www.bibtex.org}{Your \bibtex{} resource}'' -offers a solid introduction, but doesn't go into very great detail. - -The document ``Designing \bibtex{} Styles'', also in the \bibtex{} -distribution (look for -\File{btxhak}), explains the postfix stack-based language used to -write \bibtex{} styles (\File{.bst} files). The file\File{btxbst.doc}, -also in the \bibtex{} distribution, -is the template for the four standard styles (\Package{plain}, -\Package{abbrv}, \Package{alpha}, and \Package{unsrt}); it also -contains their documentation. - -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} by Michael -Shell and David Hoadley, is also to be recommended. -\begin{ctanrefs} -\item[\nothtml{\rmfamily}\bibtex{} distribution]\CTANref{bibtex} -\item[\nothtml{\rmfamily}Shell and Hoadley's FAQ]\CTANref{bibtex-faq} -\item[\nothtml{\rmfamily}Tame the BeaST]\CTANref{ttb-pdf} -\end{ctanrefs} -\LastEdit{2013-10-15} - -\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. - -However, while the symbol list is a wonderful resource, it is never -easy to find a particular symbol there. A graphical % ! line break -\href{http://detexify.kirelabs.org/classify.html}{symbol search} is -available on the web. The site 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 (such as the present -author), and it's often worth trying more than once. `Detexify apps' -are available for both Android and iPhone devices, you can use them to -draw the symbol with your fingertip~--- a less challenging procedure -than using your workstation's mouse, by all accounts! - -If you are using Unicode maths in \xetex{} or \luatex{}, your own -distribution ought to provide the Unicode maths symbol table -\File{unimath-symbols.pdf}; this lists the things available in the -commonly-used mathematics fonts. (If the file isn't already available -on your system, you can download it from \acro{CTAN}, where it live -with the \Package{unicode-math} package. - -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} -\begin{ctanrefs} -\item[\nothtml{\rmfamily}Symbol List]Browse \CTANref{symbols}; there - are processed versions \acro{PDF} form for both A4 and letter paper. -\item[\nothtml{\rmfamily}Unicode maths symbols]Distributed as part of - \CTANref{unicode-math} -\end{ctanrefs} -\LastEdit{2012-09-03} - -\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} |