diff options
Diffstat (limited to 'Master/texmf-dist/doc/support/texlogsieve/texlogsieve.tex')
| -rw-r--r-- | Master/texmf-dist/doc/support/texlogsieve/texlogsieve.tex | 312 |
1 files changed, 312 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/support/texlogsieve/texlogsieve.tex b/Master/texmf-dist/doc/support/texlogsieve/texlogsieve.tex new file mode 100644 index 00000000000..4d29abf8cc5 --- /dev/null +++ b/Master/texmf-dist/doc/support/texlogsieve/texlogsieve.tex @@ -0,0 +1,312 @@ +% texlogsieve - filter and summarize LaTeX log files +% +% Copyright (C) 2021 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 +% the Free Software Foundation, either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see <https://www.gnu.org/licenses/>. +% +% Code etc: https://gitlab.com/lago/texlogsieve + +\documentclass{ltxdoc} + +\usepackage[hyperref,svgnames,x11names,table]{xcolor} +\usepackage{url} +\urlstyle{sf} +\usepackage{hyperref} +\hypersetup{ + colorlinks=true, + citecolor=DarkGreen, + linkcolor=NavyBlue, + urlcolor=DarkRed, + filecolor=green, + anchorcolor=black, +} + +\usepackage{libertinus} +\usepackage[scale=.85]{sourcecodepro} + +\RecordChanges + +\changes{v1.0.0-beta-1}{2021/12/16}{first public prerelease} + +\begin{document} + +\title{\textsf{texlogsieve}:\thanks{This document +corresponds to \textsf{texlogsieve}~1.0.0-beta-1, +dated~2021-12-16.}\\[.3\baselineskip] +{\normalsize(yet another program to)\\[-.6\baselineskip]} +{\large filter and summarize \LaTeX\ log files} +} + +\author{ +Nelson Lago\\ +\texttt{lago@ime.usp.br}\\ +~\\ +\url{https://gitlab.com/lago/texlogsieve} +} + +\maketitle + +\begin{abstract} + +\texttt{texlogsieve} reads a \LaTeX\ log file (or the standard input if +no file is specified), filters out less relevant messages, and displays +a summary report. Highlights: + +\begin{itemize} + \item Two reports: the most important messages from the log file + followed by a summary of repeated messages, undefined + references etc.; + \item The program goes to great lengths to correctly handle \TeX\ line + wrapping and does a much better job at that than existing tools; + \item Multiline messages are treated as a single entity; + \item Several options to control which messages should be filtered out; + \item No messages are accidentally removed; + \item The summary report is currently simple, but useful. +\end{itemize} + +\end{abstract} + +\section{Introduction} + +The \LaTeX\ log file is very verbose, which is useful when debugging but +a hindrance during document preparation, as warnings such as ``missing +character'', ``undefined reference'', and others become buried among lots +of less relevant messages. This program filters out such less relevant +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. + +\texttt{texlogsieve} \textbf{must} be run from the same directory as +\verb/[pdf|lua|xe]latex/, because it searches for the files used during +compilation (packages loaded from the current directory, files included +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} + +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 +Con\TeX{}t or plain \TeX. Still, adding support to them should not be +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} + +\TeX\ wraps (breaks) lines longer than \texttt{max\_print\_line} (by +default, 79 characters). Most tools detect lines that are exactly 79 +characters long and treat the next line as a continuation, but that fails +in quite a few cases (check the comments in the \texttt{texlogsieve} code +for a discussion on that). So, if at all possible, it is a very good idea +to set \texttt{max\_print\_line} to a really large value (such as 100,000), +effectively disabling line wrapping. It was useful in the 1980s, but not +anymore (your terminal or editor wraps automatically). + +Still, \texttt{texlogsieve} goes to great lengths to correctly handle +\TeX{} line wrapping and does a pretty good job at that. It understands +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{Options} + +\begin{description} +\item[\texttt{-\/-page-delay}, \texttt{-\/-no-page-delay}]~\\ +Enable/disable grouping messages by page before display. When enabled, messages +are only output after the current page is finished (shipout). The advantage is +that the page number is included in the message (default enabled). +\end{description} + +\begin{description} +\item[\texttt{-\/-summary}, \texttt{-\/-no-summary}]~\\ +Enable/disable final summary (default enabled). +\end{description} + +\begin{description} +\item[\texttt{-\/-only-summary}]~\\ +No messages, show only the final summary (default disabled). +\end{description} + +\begin{description} +\item[\texttt{-\/-shipouts}, \texttt{-\/-no-shipouts}]~\\ +Enable/disable reporting shipouts (default disabled with page-delay, enabled +with no-page-delay). +\end{description} + +\begin{description} +\item[\texttt{-\/-repetitions}, \texttt{-\/-no-repetitions}]~\\ +Allow/prevent repeated messages (default disabled, i.e., repeated messages +are supressed). +\end{description} + +\begin{description} +\item[\texttt{-\/-heartbeat}, \texttt{-\/-no-heartbeat}]~\\ +Enable/disable progress gauge in page-delay mode (default enabled). +\end{description} + +\begin{description} +\item[\texttt{-l LEVEL}, \texttt{-\/-minlevel=LEVEL}]~\\ +Filter out messages with severity level lower than \texttt{LEVEL}. Valid +levels are \texttt{DEBUG} (no filtering), \texttt{INFO}, \texttt{WARNING}, +\texttt{CRITICAL}, and \texttt{UNKNOWN} (default \texttt{WARNING}). +\end{description} + +\begin{description} +\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 +tool not to try to unwrap lines). +\end{description} + +\begin{description} +\item[\texttt{-\/-silence-package=PKGNAME}]~\\ +Filter out messages that can be identified as coming from the given package. +Use this option multiple times to suppress messages from several different +packages. +\end{description} + +\begin{description} +\item[\texttt{-\/-silence-string=EXCERPT OF UNWANTED MESSAGE}]~\\ +Filter out messages that contain the given string (you only need to provide +part of the message text for the whole message to be suppressed). Use this +option multiple times to suppress several different messages. The string +should be a single line, but that is not a problem for multiline log +messages: space characters in the provided string match any sequence of +whitespace characters in the message, including newlines. If needed, you +may precede the string with ``////'', in which case you can use lua-style +pattern matching (\url{https://www.lua.org/pil/20.2.html}). Note that the +string is used verbatim: you need not (and should not) enclose it in quotes +nor escape special characters such as ``\textbackslash''. +\end{description} + +\begin{description} +\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 +option multiple times to suppress messages from several different files. +\end{description} + +\begin{description} +\item[\texttt{-\/-semisilence-file=FILENAME OR FILE GLOB}]~\\ +Just like the previous option, but non-recursive. This means that messages +generated while the given file was being processed are excluded, but messages +generated by some other file that was opened by it are not. For example, +if ``\texttt{chapters.tex}'' includes (with \textbackslash input) the +files ``\texttt{chapter1.tex}'' and ``\texttt{chapter2.tex}'', using +``\texttt{-\/-silence-file=chapters.tex}'' will prevent messages generated +by any of the three files from being displayed. If, however, you use +``\texttt{-\/-semisilence-file=chapters.tex}'', messages generated by +\texttt{chapters.tex} will be suppressed, but messages generated by +\texttt{chapter1.tex} or \texttt{chapter2.tex} will not. +\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 +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. +\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: + +\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} +\end{description} + +\begin{description} +\item[\texttt{-h}, \texttt{-\/-help}] +Show concise options description. +\end{description} + +\begin{description} +\item[\texttt{-\/-version}] +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\\ +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.\\ +There is NO WARRANTY, to the extent permitted by law. + +\PrintChanges + +\end{document} |