% $Id: faq-the-end.tex,v 1.1 2009/06/13 20:56:49 rf10 Exp $ \section{You're still stuck?} \Question[Q-noans]{You don't understand the answer} While the \acro{FAQ} maintainers don't offer a `help' service, they're very keen that you understand the answers they've already written. They're (almost) written ``in a vacuum'', to provide something to cover a set of questions that have arisen; it's always possible that they're written in a way that a novice won't understand them. Which is where you can help the community. Mail the \begin{wideversion} \href{mailto:faq-devel@tex.ac.uk}{maintainers} \end{wideversion} \begin{narrowversion} maintainers (at \Email{faq-devel@tex.ac.uk}) \end{narrowversion} to report the answer that you find unclear, and (if you can) suggest what we need to clarify. Time permitting (the team is small and all its members are busy), we'll try and clarify the answer. This way, with a bit of luck, we can together improve the value of this resource to the whole community. Note that the \acro{FAQ} development email address is not for answering questions: it's for you to suggest which questions we should work on, or new questions we should answer in future editions. Those who simply ask questions at that address will be referred to \mailto{texhax@tug.org} or to \Newsgroup{comp.text.tex}. \Question[Q-newans]{Submitting new material for the \acro{FAQ}} The \acro{FAQ} will never be complete, and we always expect that there will be people out there who know better than we do about something or other. We always need to be put right about whatever we've got wrong, and suggestions for improvements, particularly covering areas we've missed, are always needed: mail anything you have to the \begin{wideversion} \href{mailto:faq-devel@tex.ac.uk}{maintainers} \end{wideversion} \begin{narrowversion} maintainers (at \Email{faq-devel@tex.ac.uk}) \end{narrowversion} If you have actual material to submit, your contribution is more than ever welcome. Submission in plain text is entirely acceptable, but if you're really willing, you may feel free to mark up your submission in the form needed for the \acro{FAQ} itself. The markup is a strongly-constrained version of \LaTeX{}~--- the constraints come from the need to translate the marked-up text to \acro{HTML} on the fly (and hence pretty efficiently). There is a file \File{markup-syntax} in the \acro{FAQ} distribution that describes the structure of the markup, but there's no real substitute for reading at least some of the source (\File{faqbody.tex}) of the \acro{FAQ} itself. If you understand \ProgName{Perl}, you may also care to look at the translation code in \File{texfaq2file} and \File{sanitize.pl} in the distribution: this isn't the code actually used on the Web site, but it's a close relation and is kept up to date for development purposes. \begin{ctanrefs} \item[\nothtml{\rmfamily}\acro{FAQ} distribution]\CTANref{faq} \end{ctanrefs} \Question[Q-latexbug]{Reporting a \LaTeX{} bug} The \LaTeX{} team supports \LaTeX{}, and will deal with % beware line wrap \emph{bona fide} bug reports. Note that the \LaTeX{} team does \emph{not} deal with contributed packages~--- just the software that is part of the \LaTeX{} distribution itself: \LaTeX{} and the ``required'' packages. Furthermore, you need to be slightly careful to produce a bug report that is usable by the team. The steps are: \nothtml{\noindent}\textbf{1.} Are you still using current \LaTeX{}? Maintenance is only available for sufficiently up-to-date versions of \LaTeX{}~--- if your \LaTeX{} is more than two versions out of date, the bug reporting mechanisms may reject your report. \nothtml{\noindent}\textbf{2.} Has your bug already been reported? Browse the % beware line break \href{http://www.latex-project.org/cgi-bin/ltxbugs2html?introduction=yes}{\LaTeX{} bugs database}, to find any earlier instance of your bug. In many cases, the database will list a work-around. \nothtml{\noindent}\textbf{3.} Prepare a % ! line break \Qref*{``minimum'' file}{Q-minxampl} that exhibits the problem. Ideally, such a file should contain no contributed packages~--- the \LaTeX{} team as a whole takes no responsibility for such packages (if they're supported at all, they're supported by their authors). The ``minimum'' file should be self-sufficient: if a member of the team should run it in a clean directory, on a system with no contributed packages, it should replicate your problem. \nothtml{\noindent}\textbf{4.} Run your file through \LaTeX{}: the bug system needs the \extension{log} file that this process creates. You now have two possible ways to proceed: either create a mail report to send to the bug processing mechanism (5, below), or submit your bug report via the web (7, below). \nothtml{\noindent}\textbf{5.} Process the bug-report creation file, using \LaTeX{} itself: \begin{verbatim} latex latexbug \end{verbatim} \File{latexbug} asks you some questions, and then lets you describe the bug you've found. It produces an output file \File{latexbug.msg}, which includes the details you've supplied, your ``minimum'' example file, and the log file you got after running the example. (I always need to edit the result before submitting it: typing text into \File{latexbug} isn't much fun.) \nothtml{\noindent}\textbf{6.} Mail the resulting file to \Email{latex-bugs@latex-project.org}; the subject line of your email should be the same as the bug title you gave to \File{latexbug}. The file \File{latexbug.msg} should be included into your message in-line: attachments are likely to be rejected by the bug processor. \nothtml{\noindent}\textbf{7.} Connect to the % beware line break \href{http://www.latex-project.org/bugs-upload.html}{latex bugs processing web page} and enter details of your bug~--- category, summary and full description, and the two important files (source and log file); note that members of the \LaTeX{} team \emph{need} your name and email address, as they may need to discuss the bug with you, or to advise you of a work-around. \htmlignore \par \endhtmlignore \Question[Q-bug]{What to do if you find a bug} \htmlignore \par \endhtmlignore % % This here isn't a reference to a question... \label{lastquestion} For a start, make entirely sure you \emph{have} found a bug. Double-check with books about \TeX{}, \LaTeX{}, or whatever you're using; compare what you're seeing against the other answers above; ask every possible person you know who has any \TeX{}-related expertise. The reasons for all this caution are various. If you've found a bug in \TeX{} itself, you're a rare animal indeed. Don Knuth is so sure of the quality of his code that he offers real money prizes to finders of bugs; the cheques he writes are such rare items that they are seldom cashed. If \emph{you} think you have found a genuine fault in \TeX{} itself (or \MF{}, or the \acro{CM} fonts, or the \TeX{}book), don't immediately write to Knuth, however. He only looks at bugs infrequently, and even then only after they are agreed as bugs by a small vetting team. In the first instance, contact Barbara Beeton at the \acro{AMS} (\Email{bnb@ams.org}), or contact \Qref*{\acro{TUG}}{Q-TUG*}. If you've found a bug in \LaTeXe{}, \Qref*{report it}{Q-latexbug} using mechanisms supplied by the \LaTeX{} team. (Please be careful to ensure you've got a \LaTeX{} bug, or a bug in one of the ``required'' packages distributed by the \LaTeX{} team.) If you've found a bug in a contributed \LaTeX{} package, you could try contacting the author (if you can find a contact address). However, it's generally best to treat any package as unsupported, in the first instance, and only try the author \emph{after} mailing list/news group support has failed you. If you've found a bug in \LaTeXo{}, or some other such unsupported software, you may find help or \emph{de facto} support on a newsgroup such as \Newsgroup{comp.tex.tex} or on a mailing list such as \mailto{texhax@tug.org}; be careful to include a % ! line wrap \Qref*{code example}{Q-minxampl} of the failure, if relevant. Failing all else, you may need to pay for help~--- \acro{TUG} maintains a % ! line break \href{http://www.tug.org/consultants.html}{register of \TeX{} consultants}. %%% Local Variables: %%% mode: latex %%% TeX-master: t %%% End: