\ProvidesFile{inputtrc.tex}[2012/10/03 documenting inputtrc.sty] \title{\pkgtitle{inputtrc.sty}{Tracing Which File Loads Which}} %% 2012/10/03 % \listfiles \RequirePackage{inputtrc} %%% \dotracinginputs %%% returns % \setinputindentunit{\space\space\space} { \RequirePackage{makedoc} \ProcessLineMessage{} \MakeJobDoc{18}{\SectionLevelTwoParseInput} } %% 18 2012/10/03 \documentclass[fleqn]{article}%% TODO paper dimensions!? % \notracinginputs \input{makedoc.cfg} %% shared formatting settings \newcommand*{\TODO}{\textcolor{blue}{\acro{TODO}}} \AddQuotes \sloppy \begin{document} \maketitle \begin{abstract}\noindent 'inputtrc.sty' produces screen/log messages ` 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. `RETURNING TO ' may be added. These messages should help especially when you otherwise get a screen message about `l.' referring to an input line while you have no idea in which \emph{file} that line is.---The implementation somewhat resembles packages \ctanpkgref{filehook}, \ctanpkgref{currfile}, %% 2010/11/28 \CtanPkgRef{fink}{FiNK} and \ctanpkgref{inputfile}. \end{abstract} \tableofcontents \newpage %% 2010/10/08b \section{Features and Usage} \subsection{Installing, Calling, and Package Options} 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).\urlfoot{ukfaqref}{inst-wlcf} % \footnote{\url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=inst-wlcf}} % \AddQuotes %% 2012/10/10 \emph{After} `\documentclass', you may load 'inputtrc' (as usually) by \[|\usepackage{inputtrc}|\] In order to use one of the package options that come with v0.3, you may type \[|\usepackage[]{inputtrc}|\] where is `i', `r', or `ir' (---or `i,r'). However, you may want to see what `\documentclass' loads; then precede `\documentclass' with \[|\RequirePackage[]{inputtrc}|\] |[i]| issues `\dotracinginputs' immediately, |[r]| issues `\dotracingreturns' immediately, and |[ir]| issues `\dotracinginputsreturns' immediately. So `[ir]' is like `[i,r]'. % \DontAddQuotes \subsection{Input} Indeed, the `INPUTTING' messages appear after command |\dotracinginputs| only, \emph{unless} you load the package with option |[i]| or |[ir]|. The command |\notracinginputs| turns the feature off again. |\setinputindentunit{}| globally sets the ``indent unit," whose default is set by \[|\setinputindentunit{\space\space}|\] 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 \[|\setinputindentunit{\space\space\space}|\] \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 \[`\input '\] where loads other files, files that loads directly produce \emph{wrong} messages. \subsection{After Input} |\dotracingreturns| adds a message \[`RETURNING TO ' \quad \mbox{after} \quad ` INPUTTING '\] meaning that processing file has been finished. The package issues this command immediately if called with option |[r]| Use |\notracingreturns| to turn this additional feature off again. %% doubled `both' before 2012/10/10: |\dotracinginputsreturns| calls both \[`\dotracinginputs' \quad \mbox{and} \quad `\dotracingreturns'\] at (about) the same time. On package option |[ir]|, this command is issued immediately. |\notracinginputsreturns| switches off both kinds of 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}. Indeed on the 'texhax' mailing list, \emph{Karl Berry} posted the following:\urlfoot{texhaxpref}{10-02-014305} %% 2011/01/28 ... \begin{quote}\itshape\small 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:\urlfoot{texhaxpref}{10-02-014311} \begin{quote}\itshape\small 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'---or to \texttt{RETURNING TO} (v0.2). The present approach was inspired by Karl's idea to provide a new \TeX\ primitive. This first triggered my reply\urlfoot{texhaxpref}{10-02-014309} 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,\urlfoot{CtanPkgRef}{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\small (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. \section{Example} It is especially nice to watch 'hyperref' loading quite a bunch from Heiko's 'oberdiek' bundle (on running the present 'inputtrc.tex'):\urlfoot{CtanPkgRef}{oberdiek} \begingroup \hfuzz=10pc \small \begin{verbatim} inputtrc.tex 2010/10/09 documenting inputtrc.sty (./inputtrc.sty Package: inputtrc 2010/10/09 v0.2 input tracing (UL) ) inputtrc INPUTTING makedoc.sty (/usr/share/texmf/tex/latex/nicetext/makedoc.sty Package: makedoc 2010/03/30 v0.4 TeX input from *.sty (UL) makedoc.sty INPUTTING fifinddo.sty (/usr/share/texmf/tex/latex/nicetext/fifinddo.sty Package: fifinddo 2010/04/15 v0.41 filtering TeX(t) files by TeX (UL) \result_file=\write3 \c@fdInputLine=\count79 ) RETURNING TO makedoc.sty ) RETURNING TO inputtrc inputtrc INPUTTING mdoccorr.cfg (/usr/share/texmf/tex/latex/nicetext/mdoccorr.cfg File: mdoccorr.cfg 2010/03/29 local typographical corrections with `makedoc.sty ' ) RETURNING TO inputtrc \openout3 = `inputtrc.doc'. `fifinddo' processing `inputtrc.sty' inputtrc INPUTTING article.cls (/usr/share/texmf/tex/latex/base/article.cls Document Class: article 2005/09/16 v1.4f Standard LaTeX document class article.cls INPUTTING size10.clo (/usr/share/texmf/tex/latex/base/size10.clo File: size10.clo 2005/09/16 v1.4f Standard LaTeX file (size option) ) RETURNING TO article.cls \c@part=\count80 \c@section=\count81 \c@subsection=\count82 \c@subsubsection=\count83 \c@paragraph=\count84 \c@subparagraph=\count85 \c@figure=\count86 \c@table=\count87 \abovecaptionskip=\skip41 \belowcaptionskip=\skip42 \bibindent=\dimen102 ) RETURNING TO inputtrc inputtrc INPUTTING makedoc.cfg (./makedoc.cfg File: makedoc.cfg 2010/10/08 doc formatting settings makedoc.cfg INPUTTING ifpdf.sty (/usr/share/texmf/tex/generic/oberdiek/ifpdf.sty Package: ifpdf 2009/04/10 v2.0 Provides the ifpdf switch (HO) Package ifpdf Info: pdfTeX in pdf mode not detected. ) RETURNING TO makedoc.cfg makedoc.cfg INPUTTING hyperref.sty (/usr/share/texmf/tex/latex/hyperref/hyperref.sty Package: hyperref 2010/06/18 v6.81g Hypertext links for LaTeX 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) ) RETURNING TO hyperref.sty 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 ) RETURNING TO hyperref.sty 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) ) RETURNING TO kvsetkeys.sty 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. ) RETURNING TO kvsetkeys.sty ) RETURNING TO hyperref.sty 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. ) RETURNING TO pdftexcmds.sty Package pdftexcmds Info: LuaTeX not detected on input line 145. ) RETURNING TO pdfescape.sty ) RETURNING TO hyperref.sty 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. ) RETURNING TO hyperref.sty hyperref.sty INPUTTING ifxetex.sty (/usr/share/texmf/tex/generic/ifxetex/ifxetex.sty Package: ifxetex 2010/09/12 v0.6 Provides ifxetex conditional ) RETURNING TO hyperref.sty 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 ) RETURNING TO hycolor.sty ) RETURNING TO hyperref.sty 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) ) RETURNING TO hyperref.sty \@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) ) RETURNING TO hyperref.sty hyperref.sty INPUTTING intcalc.sty (/usr/share/texmf/tex/generic/oberdiek/intcalc.sty Package: intcalc 2007/09/27 v1.1 Expandable integer calculations (HO) ) RETURNING TO hyperref.sty 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 ) RETURNING TO hyperref.sty 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) ) RETURNING TO hyperref.sty Package hyperref Info: Option `draft' 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. ) RETURNING TO hyperref.sty 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) ) RETURNING TO bitset.sty ) RETURNING TO hyperref.sty \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) ) RETURNING TO hyperref.sty \Hy@abspage=\count91 \c@Item=\count92 \c@Hfootnote=\count93 ) RETURNING TO makedoc.cfg * hyperref using default driver hdvips * makedoc.cfg INPUTTING hdvips.def (/usr/share/texmf/tex/latex/hyperref/hdvips.def File: hdvips.def 2010/06/18 v6.81g Hyperref driver for dvips hdvips.def INPUTTING pdfmark.def (/usr/share/texmf/tex/latex/hyperref/pdfmark.def File: pdfmark.def 2010/06/18 v6.81g Hyperref definitions for pdfmark specials \pdf@docset=\toks16 \pdf@box=\box26 \pdf@toks=\toks17 \pdf@defaulttoks=\toks18 \Fld@listcount=\count94 \c@bookmark@seq@number=\count95 pdfmark.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 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). ) RETURNING TO rerunfilecheck.sty 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) ) RETURNING TO rerunfilecheck.sty Package uniquecounter Info: New unique counter `rerunfilecheck' on input line 2 71. ) RETURNING TO pdfmark.def \Hy@SectionHShift=\skip43 ) RETURNING TO hdvips.def ) RETURNING TO makedoc.cfg makedoc.cfg INPUTTING niceverb.sty (/usr/share/texmf/tex/latex/nicetext/niceverb.sty Package: niceverb 2010/04/05 v0.41 minimize doc markup (UL) \niceverb_savebox=\box27 ) RETURNING TO makedoc.cfg ) RETURNING TO inputtrc inputtrc INPUTTING inputtrc.aux (./inputtrc.aux) RETURNING TO inputtrc \openout1 = `inputtrc.aux'. LaTeX Font Info: Checking defaults for OML/cmm/m/it on input line 13. LaTeX Font Info: ... okay on input line 13. LaTeX Font Info: Checking defaults for T1/cmr/m/n on input line 13. LaTeX Font Info: ... okay on input line 13. LaTeX Font Info: Checking defaults for OT1/cmr/m/n on input line 13. LaTeX Font Info: ... okay on input line 13. LaTeX Font Info: Checking defaults for OMS/cmsy/m/n on input line 13. LaTeX Font Info: ... okay on input line 13. LaTeX Font Info: Checking defaults for OMX/cmex/m/n on input line 13. LaTeX Font Info: ... okay on input line 13. LaTeX Font Info: Checking defaults for U/cmr/m/n on input line 13. LaTeX Font Info: ... okay on input line 13. LaTeX Font Info: Checking defaults for PD1/pdf/m/n on input line 13. LaTeX Font Info: ... okay on input line 13. inputtrc INPUTTING moreverb.sty (/usr/share/texmf/tex/latex/moreverb/moreverb.sty Package: moreverb 1997/12/07 v2.2d.2 `more' verbatim facilities moreverb.sty INPUTTING verbatim.sty (/usr/share/texmf/tex/latex/tools/verbatim.sty Package: verbatim 2003/08/22 v1.5q LaTeX2e package for verbatim enhancements \every@verbatim=\toks19 \verbatim@line=\toks20 \verbatim@in@stream=\read1 ) RETURNING TO moreverb.sty \verbatim@out=\write4 \tab@position=\count96 \tab@size=\count97 \listing@line=\count98 ) RETURNING TO inputtrc \AtBeginShipoutBox=\box28 Package hyperref Warning: draft mode on. Package hyperref Info: Link coloring OFF on input line 13. inputtrc INPUTTING nameref.sty (/usr/share/texmf/tex/latex/hyperref/nameref.sty Package: nameref 2010/04/30 v2.40 Cross-referencing by name of section nameref.sty INPUTTING refcount.sty (/usr/share/texmf/tex/latex/oberdiek/refcount.sty Package: refcount 2008/08/11 v3.1 Data extraction from references (HO) ) RETURNING TO nameref.sty nameref.sty INPUTTING gettitlestring.sty (/usr/share/texmf/tex/latex/oberdiek/gettitlestring.sty Package: gettitlestring 2009/12/18 v1.3 Cleanup title references (HO) ) RETURNING TO nameref.sty \c@section@level=\count99 ) RETURNING TO inputtrc \end{verbatim} \endgroup % \pagebreak %% 2010/10/08b %% rm. 2012/10/10 \DontAddQuotes %% 2012/10/10 \section{Implementation} \subsection{Package File Header (Legalese)} %% ize -> ese 2012/10/03 \input{inputtrc.doc} \end{document} HISTORY 2010/10/08 for v0.1 very first, installed on CTAN same day 2010/10/08b for v0.1a some wordings, even contentually (occurrences of \@@input) 2010/11/11 for v0.2a + package date 2010/11/28 for myfilist.sty; using readprov.sty; mention `filehook' 2011/01/28 use texlinks.sty (v0.2) 2012/10/03 for v0.3 ize -> ese, using \pkgtitle, corr. \HeaderLines 2012/10/10 [fleqn] for replacing verbatim/quote environments, account for [i] and [ir], use \AddQuotes instead of \qtd, abstract mentions "line number", corr. \dotracinginput|returns