summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/texlogsieve/texlogsieve.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/support/texlogsieve/texlogsieve.tex')
-rw-r--r--Master/texmf-dist/doc/support/texlogsieve/texlogsieve.tex312
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}