summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/inputtrc/inputtrc.tex
blob: 21308958583f538df0353c023e8deca3d2a4a51b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
\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{<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. 
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{<cmds>}| 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 <file>'
\end{quote}
where <file> loads other files, files that <file> 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