diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/inputtrc/inputtrc.tex')
| -rw-r--r-- | Master/texmf-dist/doc/latex/inputtrc/inputtrc.tex | 332 |
1 files changed, 332 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/inputtrc/inputtrc.tex b/Master/texmf-dist/doc/latex/inputtrc/inputtrc.tex new file mode 100644 index 00000000000..21308958583 --- /dev/null +++ b/Master/texmf-dist/doc/latex/inputtrc/inputtrc.tex @@ -0,0 +1,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 |