path: root/Master/texmf-dist/source/latex/inputtrc/inputtrc.tex

\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 
`<current> INPUTTING <next>'
on \LaTeX\ input commands, <current> and <next> 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 <current>' may be 
added. These messages should help especially 
when you otherwise get a screen message about `l.<digits>' 
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[<ir>]{inputtrc}|\]
where <ir> is `i', `r', or `ir' (---or `i,r').
However, you may want to see what `\documentclass' loads; 
then precede `\documentclass' with 
\[|\RequirePackage[<ir>]{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{<cmds>}| 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 <file>'\]
where <file> loads other files, files that <file> loads directly 
produce \emph{wrong} messages. 

\subsection{After Input}
|\dotracingreturns| adds a message 
\[`RETURNING TO <current>' \quad \mbox{after} \quad 
  `<current> INPUTTING <next>'\]
meaning that processing file <next> 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