\typeout{inputtrc.tex 2010/10/08b documenting inputtrc.sty} \title{\textsf{inputtrc.sty}\\---\\Tracing Which File Loads Which} % \thanks{This % manual describes package version % version 0.2 as of April 09, 2009%%%\fileversion\ as of \filedate\ % .}}%%%of the package.}% % \listfiles \RequirePackage{inputtrc}\dotracinginputs % \setinputindentunit{\space\space\space} { \RequirePackage{makedoc} \ProcessLineMessage{} \MakeJobDoc{17}{\SectionLevelTwoParseInput} } \documentclass{article}%% TODO paper dimensions!? \notracinginputs \input{makedoc.cfg} %% shared formatting settings \sloppy \begin{document} \maketitle \begin{abstract}\noindent 'inputtrc.sty' produces screen/log messages \qtd{\texttt{~INPUTTING~}} on \LaTeX\ input commands, and being file names. The message indents reflect the input nesting level. This can be turned on and off, and the ``indent unit" can be chosen. The implementation somewhat resembles packages \ctanpkgref{fink} and \ctanpkgref{inputfile}. \end{abstract} \tableofcontents \newpage %% 2010/10/08b \section{Features and Usage} The file 'inputtrc.sty' is provided ready, installation only requires putting it somewhere where \TeX\ finds it (which may need updating the filename data base).\footnote{\url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=inst-wlcf}} \emph{After} `\documentclass', you load 'inputtrc' (as usually) by \begin{verbatim} \usepackage{inputtrc} \end{verbatim} However, you may want to see what `\documentclass' loads; then precede `\documentclass' with \begin{verbatim} \RequirePackage{inputtrc}\dotracinginputs \end{verbatim} Indeed, the feature messages appear after the command |\dotracinginputs| only. The command |\notracinginputs| turns the feature off again. |\setinputindentunit{}| globally sets the ``indent unit," whose default is set by \begin{verbatim} \setinputindentunit{\space\space} \end{verbatim} in 'inputtrc.sty'. By default, the indent for what the main file (to whose name `\jobname' expands---TODO: extension is not yet dealt with) loads is two spaces; each nesting level increases the indent by two more spaces, and the indent is reduced again when a loaded file is left. (TODO: not dealt with `\dotracinginputs' in other files yet, may need 'fink'.) The first indent and the indent difference will be, e.g., \emph{three} spaces if you insert \begin{verbatim} \setinputindentunit{\space\space\space} \end{verbatim} \textbf{Note} that only \emph{\LaTeX} input commands are recognized by 'inputtrc.sty' (at present, TODO). This means that `\input' \emph{without braces} is not recognized: it neither produces a message nor changes the indent, and with \begin{quote} `\input ' \end{quote} where loads other files, files that loads directly produce \emph{wrong} messages. \section{What it is Good for} \TeX's primitive `\input' (that \LaTeX\ represents as \cs{@@input}) sends a left round bracket to screen, followed by the path of the loaded file. When \TeX\ stops reading the file, a right round bracket is sent to screen. This screen log suffices to trace which files load which other files (directly). However, this has a quite little visual effect and hardly reflects input nesting in an intuitive way. And when an inputted file produces many messages, it becomes quite impossible to trace input nesting by eyes and mind only. This may be very painful in debugging. Sometimes you get a warning or error message and you are unable to tell which file produced the message (if the file is not a \LaTeX\ package issuing the proper \emph{package} warnings and errors)\footnote{\cs{PackageWarning} etc.}---typically the \emph{number of the line} that caused the warning is shown, but not the \emph{file name}. % \pagebreak %% 2010/10/08b Indeed on the 'texhax' mailing list, \emph{Karl Berry} posted the following:\footnote{\url{http://tug.org/mailman/htdig/texhax/2010-February/014305.html}} \begin{quote}\itshape Sometimes it would be helpful for tex debugging to get a \dqtd{backtrace} of the files that tex is executing. It could be something static, that reads a .log file (or maybe .fls file from -recorder) and reports on which files were opened and closed in some way that is readable for deep nesting. I seem to recall that auctex and presumably front ends have dealt with extracting the filenames, at least, out of the mess of garbage printed to the terminal on a typical run, parsing all the open/close parens, but I've been unable to find anything that works as a separate utility. Does anyone know of something to do this? Failing anything else, I wonder about adding a new primitive to pdftex to dump the input stack at any point. Then we could get line numbers too, I expect. \end{quote} The subject line was \textit{\dqtd{tex filename backtrace utility}}.---\emph{Ronald Fehd} joined:\footnote{\url{http://tug.org/mailman/htdig/texhax/2010-February/014311.html}} \begin{quote}\itshape I am glad to see this suggestion as I have occasional problems identifying from which of my included files the error message is coming from. \end{quote} and suggested using the programming language SAS. Karl's suggestion to filter the .log file would have the advantage over the present approach that information not relevant for input tracing would be stripped off. However, more in the direction addressed by Ronald Fehd, any message from a file may be wanted to be attributed to that file. The present approach should be helpful then, you just must read the log back to the last line containing `INPUTTING'. The present approach was inspired by Karl's idea to provide a new \TeX\ primitive. This first triggered my reply\footnote{\url{http://tug.org/mailman/htdig/texhax/2010-February/014309.html}} claiming one could just redefine the primitive `\input' as a macro---a %% <- typo and wording 2010/10/08b -> little too optimistic. In the documentation for his 'FiNK' package,\footnote{\url{http://ctan.org/pkg/fink}} Didier Verna remarks that this primitive parses the file name in a way that is somewhat difficult to imitate by %%% with %% 2010/10/08b macros: \begin{quote}\itshape (one would have to parse the characters one by one, and I'm not ready to do so\dots) \end{quote} Instead, I here change two \LaTeX\ macros that use the primitive. \pagebreak %% 2010/10/08b \section{Example} It is especially nice to watch 'hyperref' loading quite a bunch from Heiko's 'oberdiek' bundle:\footnote{\url{http://ctan.org/pkg/oberdiek}} \begingroup \hfuzz=10pc \begin{verbatim} hyperref.sty INPUTTING ltxcmds.sty (/usr/share/texmf/tex/latex/oberdiek/ltxcmds.sty Package: ltxcmds 2010/04/26 v1.7 LaTeX kernel commands for general use (HO) ) hyperref.sty INPUTTING keyval.sty (/usr/share/texmf/tex/latex/graphics/keyval.sty Package: keyval 1999/03/16 v1.13 key=value parser (DPC) \KV@toks@=\toks14 ) hyperref.sty INPUTTING kvsetkeys.sty (/usr/share/texmf/tex/generic/oberdiek/kvsetkeys.sty Package: kvsetkeys 2007/09/29 v1.3 Key value parser with default handler suppor t (HO) kvsetkeys.sty INPUTTING infwarerr.sty (/usr/share/texmf/tex/generic/oberdiek/infwarerr.sty Package: infwarerr 2007/09/09 v1.2 Providing info/warning/message (HO) ) kvsetkeys.sty INPUTTING etexcmds.sty (/usr/share/texmf/tex/generic/oberdiek/etexcmds.sty Package: etexcmds 2007/12/12 v1.2 Prefix for e-TeX command names (HO) Package etexcmds Info: Could not find \expanded. (etexcmds) That can mean that you are not using pdfTeX 1.50 or (etexcmds) that some package has redefined \expanded. (etexcmds) In the latter case, load this package earlier. )) hyperref.sty INPUTTING pdfescape.sty (/usr/share/texmf/tex/generic/oberdiek/pdfescape.sty Package: pdfescape 2007/11/11 v1.8 Provides hex, PDF name and string conversion s (HO) pdfescape.sty INPUTTING pdftexcmds.sty (/usr/share/texmf/tex/generic/oberdiek/pdftexcmds.sty Package: pdftexcmds 2009/04/10 v0.4 LuaTeX support for pdfTeX utility functions (HO) pdftexcmds.sty INPUTTING ifluatex.sty (/usr/share/texmf/tex/generic/oberdiek/ifluatex.sty Package: ifluatex 2009/04/10 v1.1 Provides the ifluatex switch (HO) Package ifluatex Info: LuaTeX not detected. ) Package pdftexcmds Info: LuaTeX not detected on input line 145. )) hyperref.sty INPUTTING ifvtex.sty (/usr/share/texmf/tex/generic/oberdiek/ifvtex.sty Package: ifvtex 2008/11/04 v1.4 Switches for detecting VTeX and its modes (HO) Package ifvtex Info: VTeX not detected. ) hyperref.sty INPUTTING ifxetex.sty (/usr/share/texmf/tex/generic/ifxetex/ifxetex.sty Package: ifxetex 2010/09/12 v0.6 Provides ifxetex conditional ) hyperref.sty INPUTTING hycolor.sty (/usr/share/texmf/tex/latex/oberdiek/hycolor.sty Package: hycolor 2008/09/08 v1.4 Code for color options of hyperref/bookmark (H O) hycolor.sty INPUTTING xcolor-patch.sty (/usr/share/texmf/tex/latex/oberdiek/xcolor-patch.sty Package: xcolor-patch 2008/09/08 xcolor patch )) hyperref.sty INPUTTING letltxmacro.sty (/usr/share/texmf/tex/latex/oberdiek/letltxmacro.sty Package: letltxmacro 2008/06/24 v1.3 Let assignment for LaTeX macros (HO) ) \@linkdim=\dimen103 \Hy@linkcounter=\count88 \Hy@pagecounter=\count89 hyperref.sty INPUTTING pd1enc.def (/usr/share/texmf/tex/latex/hyperref/pd1enc.def File: pd1enc.def 2010/06/18 v6.81g Hyperref: PDFDocEncoding definition (HO) ) hyperref.sty INPUTTING intcalc.sty (/usr/share/texmf/tex/generic/oberdiek/intcalc.sty Package: intcalc 2007/09/27 v1.1 Expandable integer calculations (HO) ) hyperref.sty INPUTTING hyperref.cfg (/usr/share/texmf/tex/latex/config/hyperref.cfg File: hyperref.cfg 2002/06/06 v1.2 hyperref configuration of TeXLive ) hyperref.sty INPUTTING kvoptions.sty (/usr/share/texmf/tex/latex/oberdiek/kvoptions.sty Package: kvoptions 2010/02/22 v3.7 Keyval support for LaTeX options (HO) ) Package hyperref Info: Option `bookmarksnumbered' set `true' on input line 3577 . Package hyperref Info: Hyper figures OFF on input line 3658. Package hyperref Info: Link nesting OFF on input line 3663. Package hyperref Info: Hyper index ON on input line 3666. Package hyperref Info: Plain pages OFF on input line 3673. Package hyperref Info: Backreferencing OFF on input line 3678. Implicit mode ON; LaTeX internals redefined Package hyperref Info: Bookmarks ON on input line 3874. hyperref.sty INPUTTING url.sty (/usr/share/texmf/tex/latex/ltxmisc/url.sty \Urlmuskip=\muskip10 Package: url 2005/06/27 ver 3.2 Verb mode for urls, etc. ) LaTeX Info: Redefining \url on input line 4159. hyperref.sty INPUTTING bitset.sty (/usr/share/texmf/tex/generic/oberdiek/bitset.sty Package: bitset 2007/09/28 v1.0 Data type bit set (HO) bitset.sty INPUTTING bigintcalc.sty (/usr/share/texmf/tex/generic/oberdiek/bigintcalc.sty Package: bigintcalc 2007/11/11 v1.1 Expandable big integer calculations (HO) )) \Fld@menulength=\count90 \Field@Width=\dimen104 \Fld@charsize=\dimen105 \Field@toks=\toks15 Package hyperref Info: Hyper figures OFF on input line 5137. Package hyperref Info: Link nesting OFF on input line 5142. Package hyperref Info: Hyper index ON on input line 5145. Package hyperref Info: backreferencing OFF on input line 5152. Package hyperref Info: Link coloring OFF on input line 5157. Package hyperref Info: Link coloring with OCG OFF on input line 5162. Package hyperref Info: PDF/A mode OFF on input line 5167. LaTeX Info: Redefining \ref on input line 5207. LaTeX Info: Redefining \pageref on input line 5211. hyperref.sty INPUTTING atbegshi.sty (/usr/share/texmf/tex/generic/oberdiek/atbegshi.sty Package: atbegshi 2008/07/31 v1.9 At begin shipout hook (HO) ) \Hy@abspage=\count91 \c@Item=\count92 \c@Hfootnote=\count93 ) * hyperref using default driver hpdftex * makedoc.cfg INPUTTING hpdftex.def (/usr/share/texmf/tex/latex/hyperref/hpdftex.def File: hpdftex.def 2010/06/18 v6.81g Hyperref driver for pdfTeX hpdftex.def INPUTTING atveryend.sty (/usr/share/texmf/tex/latex/oberdiek/atveryend.sty Package: atveryend 2010/03/24 v1.5 Hooks at very end of document (HO) Package atveryend Info: \enddocument detected (standard). ) \Fld@listcount=\count94 \c@bookmark@seq@number=\count95 hpdftex.def INPUTTING rerunfilecheck.sty (/usr/share/texmf/tex/latex/oberdiek/rerunfilecheck.sty Package: rerunfilecheck 2010/03/16 v1.6 Rerun checks for auxiliary files (HO) rerunfilecheck.sty INPUTTING uniquecounter.sty (/usr/share/texmf/tex/latex/oberdiek/uniquecounter.sty Package: uniquecounter 2009/12/18 v1.1 Provides unlimited unique counter (HO) ) Package uniquecounter Info: New unique counter `rerunfilecheck' on input line 2 71. ) \Hy@SectionHShift=\skip43 ) \end{verbatim} \endgroup \pagebreak %% 2010/10/08b \section{Implementation} \subsection{Package File Header (Legalize)} \input{inputtrc.doc} \end{document} HISTORY 2010/10/08 for v0.1 very first, sent to CTAN 2010/10/08b for v0.1a some wordings, even contentually