diff options
author | Karl Berry <karl@freefriends.org> | 2022-01-04 22:29:24 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2022-01-04 22:29:24 +0000 |
commit | 3886457c768d0a6fd86ca3aa7139026e39ef5724 (patch) | |
tree | 283767d038c865ce69717b6ee246896b1ff75f0a /Master/texmf-dist/doc/support/texlogsieve/texlogsieve.tex | |
parent | 7a4b2dbccb7935c20880c89d10fd42100bafeb24 (diff) |
texlogsieve (4jan22)
git-svn-id: svn://tug.org/texlive/trunk@61494 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/support/texlogsieve/texlogsieve.tex')
-rw-r--r-- | Master/texmf-dist/doc/support/texlogsieve/texlogsieve.tex | 210 |
1 files changed, 138 insertions, 72 deletions
diff --git a/Master/texmf-dist/doc/support/texlogsieve/texlogsieve.tex b/Master/texmf-dist/doc/support/texlogsieve/texlogsieve.tex index 4d29abf8cc5..3608343743f 100644 --- a/Master/texmf-dist/doc/support/texlogsieve/texlogsieve.tex +++ b/Master/texmf-dist/doc/support/texlogsieve/texlogsieve.tex @@ -1,6 +1,6 @@ % texlogsieve - filter and summarize LaTeX log files % -% Copyright (C) 2021 Nelson Lago <lago@ime.usp.br> +% Copyright (C) 2021, 2022 Nelson Lago <lago@ime.usp.br> % % This program is free software: you can redistribute it and/or modify % it under the terms of the GNU General Public License as published by @@ -37,13 +37,26 @@ \RecordChanges -\changes{v1.0.0-beta-1}{2021/12/16}{first public prerelease} +\changes{v1.0.0-beta-1}{2021/12/16}{First public prerelease} +\changes{v1.0.0-beta-2}{2022/01/04}{Automatically read \texttt{texlogsieverc} + if it exists} +\changes{v1.0.0-beta-2}{2022/01/04}{Add options \texttt{-\/-be-redundant} + and \texttt{-\/-box-detail}} +\changes{v1.0.0-beta-2}{2022/01/04}{Add options + \texttt{-\/-set-to-level-[levelname]}} +\changes{v1.0.0-beta-2}{2022/01/04}{Include silenced messages in summaries} +\changes{v1.0.0-beta-2}{2022/01/04}{Substitute empty citation/label keys + for ``???''} +\changes{v1.0.0-beta-2}{2022/01/04}{Fix bug that prevented + \texttt{-\/-add-[info\textbar + warning]-message} from working} +\changes{v1.0.0-beta-2}{2022/01/04}{Misc small bugfixes} \begin{document} \title{\textsf{texlogsieve}:\thanks{This document -corresponds to \textsf{texlogsieve}~1.0.0-beta-1, -dated~2021-12-16.}\\[.3\baselineskip] +corresponds to \textsf{texlogsieve}~1.0.0-beta-2, +dated~2022-01-04.}\\[.3\baselineskip] {\normalsize(yet another program to)\\[-.6\baselineskip]} {\large filter and summarize \LaTeX\ log files} } @@ -87,9 +100,13 @@ messages and outputs the rest, together with a final summary for the specially important ones. It is a \texttt{texlua} script, similar in spirit to tools such as \texttt{texfot}, \texttt{texloganalyser}, \texttt{rubber-info}, \texttt{textlog\_extract}, \texttt{texlogparser}, -and others. Note that it does not try to do anything smart about error -messages (at least for now); if there is an error, you probably want to -take a look directly at the log file anyway. +and others. + +Note that it does not try to do anything smart about error messages +(at least for now); if there is an error, you probably want to take a +look directly at the log file anyway. It also cannot detect if \LaTeX{} +stops for user input, so you should \textbf{really} run \LaTeX\ in +\texttt{nonstopmode} when \texttt{texlogsieve} is reading from a pipe. \texttt{texlogsieve} \textbf{must} be run from the same directory as \verb/[pdf|lua|xe]latex/, because it searches for the files used during @@ -99,11 +116,15 @@ with \verb|\input| etc.). \pagebreak[1] The defaults are reasonable; hopefully, you can just do -\begin{quote} -\verb/[pdf|lua|xe]latex myfile.tex | texlogsieve/ -\end{quote} +\begin{list}{}{} + \small\item + \verb/[pdf|lua|xe]latex -interaction nonstopmode myfile.tex | texlogsieve/ + \par + {\normalsize or\par} + \verb|texlogsieve myfile.log| +\end{list} -and be satisfied with the result. +\noindent and be satisfied with the result. Since it needs to know what messages to expect, \texttt{texlogsieve} is currently geared towards \LaTeX; I have no idea how it would work with @@ -113,7 +134,7 @@ too difficult. If you want to know more about the \TeX\ log file and the workings of the program, check the initial comments in the code. -\section{Unwrapping long lines} +\section{Unwrapping Long Lines} \TeX\ wraps (breaks) lines longer than \texttt{max\_print\_line} (by default, 79 characters). Most tools detect lines that are exactly 79 @@ -130,6 +151,60 @@ the \texttt{max\_print\_line} \TeX{} configuration variable and reads its value from the same places as \TeX. Setting \texttt{max\_print\_line} to a value larger than 9999 makes \texttt{texlogsieve} ignore line wrapping. +\section{Unrecognized Messages} +\label{unrecognized} + +\texttt{texlogsieve} automatically handles messages such as ``Package blah +Info:\dots'' or ``LaTeX Warning:\dots''. However, many messages do not +follow this pattern. To do its thing, \texttt{texlogsieve} should know about +these other messages beforehand. This is important for three reasons: + +\begin{enumerate} + \item Unknown messages are given maximum priority; if you do not want to + see them, you have to use \texttt{-\/-silence-string}; + \item If the message has more than one line, each line is treated as an + independent message. This means you need to use + \texttt{-\/-silence-string} multiple times; + \item In some rare cases, an unrecognized message may make + \texttt{texlogsieve} misclassify nearby wrapped lines (if it comes + right after a 79 characters long line of a specific type), close + file messages (if it includes an unmatched close parens character), + or shipout messages (if it includes an unmatched close square bracket + character or an open square bracket character followed only by + numbers). +\end{enumerate} + +While \texttt{texlogsieve} recognizes quite a few messages out of the box, +you may run into a message generated by some package that it does not know +about (you can check for this using \texttt{-l unknown}). If that is the +case, you can use the \verb/--add-[debug|info|warning|critical]-message/ +options to add it to the list of messages known to the program. + +\section{Configuration File} + +\texttt{texlogsieve} always searches automatically for the (optional) +\texttt{texlogsieverc} configuration file in the \TeX\ path (i.e., it +searches using \texttt{Kpathsea}). In the default configuration, the +current directory is in the search path, so adding a config file with that +name to the project directory is enough to make it work. Options in the +config file are exactly the same as the long command-line options described +below, but without the preceding ``\texttt{-\/-}'' characters. Lines +starting with a ``\#'' sign are comments. An example configuration file: + +\begin{quote} +\begin{verbatim} +no-page-delay +# no-page-delay enables shipouts, but we do not want that +no-shipouts +silence-string = Hyperreferences in rotated content will be misplaced +# no need to escape the "\" (or any other) character +silence-string = Using \overbracket and \underbracket from `mathtools' +# silence a string using lua pattern matching +silence-string = ////luaotfload | aux : font no %d+ %(.-%) +silence-files = *.sty +\end{verbatim} +\end{quote} + \section{Options} \begin{description} @@ -162,6 +237,22 @@ are supressed). \end{description} \begin{description} +\item[\texttt{-\/-be-redundant}, \texttt{-\/-no-be-redundant}]~\\ +Present/suppress ordinary messages that will also appear in the summary. +This affects messages that have special summaries (such as under/overfull +boxes or undefined citations). With \texttt{-\/-no-be-redundant} (the +default), these messages are filtered out and only appear in the final +summary. +\end{description} + +\begin{description} +\item[\texttt{-\/-box-detail}, \texttt{-\/-no-box-detail}]~\\ +Include/exclude detailed information on under/overfull boxes in the final +summary. With \texttt{-\/-no-box-detail}, the summary presents only a list +of pages and files that had under/overfull boxes (default enabled). +\end{description} + +\begin{description} \item[\texttt{-\/-heartbeat}, \texttt{-\/-no-heartbeat}]~\\ Enable/disable progress gauge in page-delay mode (default enabled). \end{description} @@ -177,14 +268,15 @@ levels are \texttt{DEBUG} (no filtering), \texttt{INFO}, \texttt{WARNING}, \item[\texttt{-u}, \texttt{-\/-unwrap-only}]~\\ Do not filter messages and do not output the summary, only unwrap long, wrapped lines. The output should be very similar (but not equal) to the -input file, but with wrapped lines reconstructed. This activates \texttt{-l -debug}, \texttt{-\/-no-summary}, \texttt{-\/-no-page-delay}, -\texttt{-\/-repetitions}, and \texttt{-\/-shipouts}, and also supresses the -verbose ``open/close file'' and ``shipout'' messages, simulating instead -the \TeX{} format, with parens and square brackets. This is useful if you -prefer the reports generated by some other tool but want to benefit from -texlogsieve's line unwrapping algorithm; the output generated by this option -should be parseable by other tools (but you probably need to coerce the other +input file, but with wrapped lines reconstructed. This activates +\texttt{-l debug}, \texttt{-\/-no-summary}, \texttt{-\/-no-page-delay}, +\texttt{-\/-repetitions}, \texttt{-\/-be-redundant}, and +\texttt{-\/-shipouts}, and also supresses the verbose ``open/close file'' +and ``shipout'' messages, simulating instead the \TeX{} format, with +parens and square brackets. This is useful if you prefer the reports +generated by some other tool but want to benefit from texlogsieve's line +unwrapping algorithm; the output generated by this option should be +parseable by other tools (but you probably need to coerce the other tool not to try to unwrap lines). \end{description} @@ -213,7 +305,10 @@ nor escape special characters such as ``\textbackslash''. \item[\texttt{-\/-silence-file=FILENAME OR FILE GLOB}]~\\ Filter out messages that have been generated while the given file was being processed. Do \textbf{not} use absolute or relative paths, only filenames. -Simple file globs, such as ``\texttt{*.cls}'', work as expected. Use this +Simple file globs, such as ``\texttt{*.cls}'', work as expected. If you are +only using packages you already know, silencing ``\texttt{*.sty}'' may be a +good idea (note that this does not suppress all messages from all packages, +only the messages generated while the packages are being loaded). Use this option multiple times to suppress messages from several different files. \end{description} @@ -232,37 +327,32 @@ by any of the three files from being displayed. If, however, you use \end{description} \begin{description} -\item[\texttt{-\/-add-[debug\textbar info\textbar warning]-message=MESSAGE}]~\\ -Add \texttt{MESSAGE} to the list of messages known to the program with the given -severity level; see Section \ref{unrecognized} below for more information +\item[\texttt{-\/-add-[debug\textbar info\textbar warning\textbar + critical]-message=MESSAGE}]~\\ +Add \texttt{MESSAGE} to the list of messages known to the program with the +given severity level; see Section \ref{unrecognized} for more information about this. Like \texttt{-\/-silence-string}, these should be a single line; -unlike \texttt{-\/-silence-string}, you need to embed \verb|\n| explicitly -to indicate line breaks. You may precede the string with ``////'' to use -lua-style pattern matching, but embedding \verb|\n| to indicate line breaks -is unavoidable. Use these options multiple times to add many different -messages. +unlike \texttt{-\/-silence-string}, you need to embed \verb|\n| explicitly +to indicate line breaks (this is literally a backslash character followed +by the letter ``n'', \textbf{not} a linefeed character). You may precede +the string with ``////'' to use lua-style pattern matching, but embedding +\verb|\n| to indicate line breaks is unavoidable. Use these options multiple +times to add many different messages. \end{description} \begin{description} -\item[\texttt{-c CFGFILE}, \texttt{-\/-config-file=CFGFILE}]~\\ -Read options from the given configuration file. Options are exactly the -same as the long command-line options, but without the preceding ``-\/-'' -characters. Lines starting with a ``\#'' sign are comments. An example -configuration file: +\item[\texttt{-\/-set-to-level-[debug\textbar info\textbar warning\textbar + critical]=EXCERPT OF MESSAGE}]~\\ +Redefine the severity level of messages that contain the provided string +to the given level. Check the explanation for \texttt{-\/-silence-string}, +as this works in a similar way. Use these options multiple times to change +the severity level of many different messages. +\end{description} -\begin{quote} -\begin{verbatim} -no-page-delay -# no-page-delay enables shipouts, but we do not want that -no-shipouts -silence-string = Hyperreferences in rotated content will be misplaced -# no need to escape the "\" (or any other) character -silence-string = Using \overbracket and \underbracket from `mathtools' -# silence a string using lua pattern matching -silence-string = ////luaotfload | aux : font no %d+ %(.-%) -silence-files = *.cls -\end{verbatim} -\end{quote} +\begin{description} +\item[\texttt{-c CFGFILE}, \texttt{-\/-config-file=CFGFILE}]~\\ +Read options from the given configuration file in addition to +\texttt{texlogsieverc}. \end{description} \begin{description} @@ -275,33 +365,9 @@ Show concise options description. Print program version. \end{description} -\section{Unrecognized Messages} -\label{unrecognized} - -\texttt{texlogsieve} automatically handles messages such as ``Package blah -Info:\dots'' or ``LaTeX Warning:\dots''. However, many messages do not -follow this pattern. To do its thing, \texttt{texlogsieve} should know about -these other messages beforehand. This is important for three reasons: - -\begin{enumerate} - \item Unknown messages are given maximum priority; if you do not want to - see them, you have to use -\/-silence-string; - \item If the message has more than one line, each line is treated as an - independent message. This means you need to use -\/-silence-string - multiple times; - \item In some rare cases, the line unwrapping algorithm may fail near an - unrecognized message. -\end{enumerate} - -While \texttt{texlogsieve} recognizes quite a few messages out of the box, -you may run into a message generated by some package that it does not know -about (you can check for this using \texttt{-l unknown}). If that is the -case, you can use the \verb/--add-[debug|info|warning]-message/ options to -add it to the list of messages known to the program. - \section{License} -Copyright © 2021 Nelson Lago \textless lago@ime.usp.br\textgreater\\ +Copyright © 2021, 2022 Nelson Lago \textless lago@ime.usp.br\textgreater\\ License GPLv3+: GNU GPL version 3 or later \url{https://gnu.org/licenses/gpl.html}.\\ This is free software: you are free to change and redistribute it.\\ |