summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2022-01-04 22:29:24 +0000
committerKarl Berry <karl@freefriends.org>2022-01-04 22:29:24 +0000
commit3886457c768d0a6fd86ca3aa7139026e39ef5724 (patch)
tree283767d038c865ce69717b6ee246896b1ff75f0a /Master/texmf-dist/doc/support
parent7a4b2dbccb7935c20880c89d10fd42100bafeb24 (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')
-rw-r--r--Master/texmf-dist/doc/support/texlogsieve/README.md97
-rw-r--r--Master/texmf-dist/doc/support/texlogsieve/texlogsieve.pdfbin46978 -> 51179 bytes
-rw-r--r--Master/texmf-dist/doc/support/texlogsieve/texlogsieve.tex210
3 files changed, 149 insertions, 158 deletions
diff --git a/Master/texmf-dist/doc/support/texlogsieve/README.md b/Master/texmf-dist/doc/support/texlogsieve/README.md
index acc3204d907..e7e92339978 100644
--- a/Master/texmf-dist/doc/support/texlogsieve/README.md
+++ b/Master/texmf-dist/doc/support/texlogsieve/README.md
@@ -22,12 +22,20 @@ report. It is a `texlua` script, similar in spirit to tools such as
`texlogsieve` **must** be run from the same directory as `[pdf|lua|xe]latex`,
because it searches for the files used during compilation (packages loaded
-from the current directory, files included with `\input` etc.).
+from the current directory, files included with `\input` etc.). Also, since
+it cannot detect if LaTeX stops for user input, you should **really** run
+LaTeX in `nonstopmode` when `texlogsieve` is reading from a pipe.
The defaults are reasonable; hopefully, you can just do
```
-[pdf|lua|xe]latex myfile.tex | texlogsieve
+[pdf|lua|xe]latex -interaction nonstopmode myfile.tex | texlogsieve
+```
+
+or
+
+```
+texlogsieve myfile.log
```
and be satisfied with the result.
@@ -40,94 +48,11 @@ 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.
-## Short-term improvements
-
- * Create tests
-
- - Synthetic unit tests: these should systematically test the code and the
- features it implements with small "fake" log files
-
- - Real-world files (for example, the docs for some packages or some papers
- from arXiv): these should help us detect important log messages and
- changes in messages whenever new versions of LaTeX and its packages are
- released
-
- * Include the line number in the summary for messages that have it
-
- * Consider messages that only differ by "on line XXX" to be repetitions
-
- * Implement option `--collapse-lines` (show multiline messages as a single
- line)
-
- * Implement option `--no-redundant` (makes messages that are going to be
- summarized, such as `undefined reference blah`, not appear in the filtered
- report, only in the summary)
-
-## Other improvements
-
- * Improve the final summary format - we should look at other tools for
- inspiration
-
- * Filter the summary report too; look at `texloganalyser` for inspiration
-
- * Consider indicating filenames more prominently in the filtered report;
- something like
-
- Messages for file ./somefile.tex:
- LaTeX Warning: File `blah.txt' already exists on the system.
- Messages for file ./someotherfile.tex:
- Warning: Missing character: There is no " (U+0022) in font...
- but only when there is actually something to report for the given file
-
- * Do something smart about LaTeX errors (maybe just detecting them and saying
- "there was an error here" is enough) - maybe get some inspiration from
- <https://github.com/overleaf/latex-log-parser> (the parser from overleaf).
- This can get complicated if we account for the possibility that the user
- interactively solved whatever was the problem, but do we really want to or
- need to handle that?
-
- * Add colors (see `texlog_extract`)
-
- * Improve error handling if/where possible
-
- * Better aggregation in the summary:
-
- - `under/overfull boxes: p.5 (chap1.tex, L27); p.7 (chap2.tex, L37); p.19
- (chap2.tex, L176)`
-
- - `missing characters X, Y, Z in font blah`
-
- * Try to figure out a way to automatically extract possible messages from
- LaTeX packages
-
- * Stuff like
- `LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right`
- should trigger a specific "please rerun" message in the summary
-
- * Maybe grep the .fls file first before trying to do `kpse.find_file()`; this
- is probably more reliable and works even if the environment has changed,
- but can we be sure it works correctly when reading the logfile from a pipe?
-
-## Refactorings to consider:
-
- * Modify `heartbeat` to use `os.difftime()`
-
- * Improve Lines:
-
- - Eliminate `Lines.current` and instead always use `Lines.get(0)`,
- `Lines.get(1)` etc. We might store stuff in indexes 1, 2, 3 etc. and
- make something like `Lines:get(val) => return Lines[val +1]` (this is
- better than actually using index 0 because the lua standard library
- counts from one, so adhering to this convention makes using it easier)
-
- - Reimplement the logic using <https://www.lua.org/pil/11.4.html> for a
- small performance increase
-
---
Code etc: <https://gitlab.com/lago/texlogsieve>
-Copyright 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
diff --git a/Master/texmf-dist/doc/support/texlogsieve/texlogsieve.pdf b/Master/texmf-dist/doc/support/texlogsieve/texlogsieve.pdf
index 80c47a30378..35a729df5de 100644
--- a/Master/texmf-dist/doc/support/texlogsieve/texlogsieve.pdf
+++ b/Master/texmf-dist/doc/support/texlogsieve/texlogsieve.pdf
Binary files differ
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.\\