summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc
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
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')
-rw-r--r--Master/texmf-dist/doc/man/man1/texlogsieve.1149
-rw-r--r--Master/texmf-dist/doc/man/man1/texlogsieve.man1.pdfbin38464 -> 40761 bytes
-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
5 files changed, 241 insertions, 215 deletions
diff --git a/Master/texmf-dist/doc/man/man1/texlogsieve.1 b/Master/texmf-dist/doc/man/man1/texlogsieve.1
index 79cdbc68d1c..41095e2374e 100644
--- a/Master/texmf-dist/doc/man/man1/texlogsieve.1
+++ b/Master/texmf-dist/doc/man/man1/texlogsieve.1
@@ -1,4 +1,4 @@
-.TH TEXLOGSIEVE "1" "December 2021" "texlogsieve 1.0.0-beta-1" "User Commands"
+.TH TEXLOGSIEVE "1" "January 2022" "texlogsieve 1.0.0-beta-2" "User Commands"
.SH NAME
@@ -16,7 +16,9 @@ report.
texlogsieve \fBmust\fR 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 \einput etc.).
+from the current directory, files included with \einput etc.). Also, since
+it cannot detect if LaTeX stops for user input, you should \fBreally\fR run
+LaTeX in \fI\,nonstopmode\/\fR when texlogsieve is reading from a pipe.
The program goes to great lengths to correctly handle TeX line wrapping. It
understands the \fI\,max_print_line\/\fR TeX configuration variable and reads
@@ -27,7 +29,15 @@ The defaults are reasonable; hopefully, you can just do
.RS 3
.EX
-[pdf|lua|xe]latex myfile.tex | texlogsieve
+[pdf|lua|xe]latex \-interaction nonstopmode myfile.tex | texlogsieve
+.EE
+.RE
+
+or
+
+.RS 3
+.EX
+texlogsieve myfile.log
.EE
.RE
@@ -61,6 +71,19 @@ Allow/prevent repeated messages (default disabled, i.e., repeated messages
are supressed).
.TP
+\fB\-\-be\-redundant\fR, \fB\-\-no\-be\-redundant\fR
+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 \-\-no\-be\-redundant (the default),
+these messages are filtered out and only appear in the final summary.
+
+.TP
+\fB\-\-box\-detail\fR, \fB\-\-no\-box\-detail\fR
+Include/exclude detailed information on under/overfull boxes in the final
+summary. With \-\-no\-box\-detail, the summary presents only a list of
+pages and files that had under/overfull boxes (default enabled).
+
+.TP
\fB\-\-heartbeat\fR, \fB\-\-no\-heartbeat\fR
Enable/disable progress gauge in page-delay mode (default enabled).
@@ -75,13 +98,14 @@ WARNING).
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 \-l debug,
-\-\-no\-summary, \-\-no\-page\-delay, \-\-repetitions, and \-\-shipouts, and
-also supresses the verbose \[lq]open/close file\[rq] and \[lq]shipout\[rq]
-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).
+\-\-no\-summary, \-\-no\-page\-delay, \-\-repetitions, \-\-be\-redundant,
+and \-\-shipouts, and also supresses the verbose \[lq]open/close file\[rq]
+and \[lq]shipout\[rq] 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).
.TP
\fB\-\-silence\-package\fR=\fI\,PKGNAME\/\fR
@@ -107,8 +131,11 @@ enclose it in quotes nor escape special characters such as \[lq]\e\[rq].
\fB\-\-silence\-file\fR=\fI\,FILENAME OR FILE GLOB\/\fR
Filter out messages that have been generated while the given file was being
processed. Do \fBnot\fR use absolute or relative paths, only filenames. Simple
-file globs, such as \[lq]*.cls\[rq], work as expected. Use this option multiple
-times to suppress messages from several different files.
+file globs, such as \[lq]*.cls\[rq], work as expected. If you are only using
+packages you already know, silencing \[lq]*.sty\[rq] 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.
.TP
\fB\-\-semisilence\-file\fR=\fI\,FILENAME OR FILE GLOB\/\fR
@@ -123,24 +150,63 @@ messages generated by chapters.tex will be suppressed, but messages generated
by chapter1.tex or chapter2.tex will not.
.TP
-\fB\-\-add\-[debug|info|warning]\-message\fR=\fI\,MESSAGE\/\fR
+\fB\-\-add\-[debug|info|warning|critical]\-message\fR=\fI\,MESSAGE\/\fR
Add MESSAGE to the list of messages known to the program with the given
severity level; see Section UNRECOGNIZED MESSAGES below for more information
about this. Like \-\-silence\-string, these should be a single line; unlike
\-\-silence\-string, you need to embed \en explicitly to indicate line
-breaks. You may precede the string with \[lq]////\[rq] to use lua-style
-pattern matching, but embedding \en to indicate line breaks is unavoidable.
-Use these options multiple times to add many different messages.
+breaks (this is literally a backslash character followed by the letter
+\[lq]n\[rq], \fBnot\fR a linefeed character). You may precede the string
+with \[lq]////\[rq] to use lua-style pattern matching, but embedding \en
+to indicate line breaks is unavoidable. Use these options multiple times
+to add many different messages.
+
+.TP
+\fB\-\-set\-to\-level\-[debug|info|warning|critical]\fR=\fI\,EXCERPT OF MESSAGE\/\fR
+Redefine the severity level of messages that contain the provided string
+to the given level. Check the explanation for \-\-silence\-string, as this
+works in a similar way. Use these options multiple times to change the
+severity level of many different messages.
.TP
\fB\-c\fR \fI\,CFGFILE\/\fR, \fB\-\-config\-file\fR=\fI\,CFGFILE\/\fR
-Read options from the given configuration file. Options are exactly the
-same as the long command-line options, but without the preceding \[lq]\-\-\[rq]
-characters. Lines starting with a \[lq]#\[rq] sign are comments. An example
-configuration file:
+Read options from the given configuration file in addition to
+\fI\,texlogsieverc\/\fR.
+
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Show concise options description.
+
+.TP
+\fB\-\-version\fR
+Print program version.
+
+.SH UNRECOGNIZED MESSAGES
+
+texlogsieve automatically handles messages such as \[lq]Package blah
+Info:...\[rq] or \[lq]LaTeX Warning:...\[rq]. However, many messages do not
+follow this pattern. To do its thing, texlogsieve should know about these
+other messages beforehand.
+
+.PP
+While 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 \[lq]\-l unknown\[rq]). If that is the case, you can use
+the \-\-add\-[debug|info|warning|critical]\-message options to add it to the
+list of messages known to the program.
+
+.SH CONFIGURATION FILE
+
+texlogsieve always searches automatically for the (optional)
+\fI\,texlogsieverc\/\fR configuration file in the TeX path (i.e., it searches
+using 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 above, but without the
+preceding \[lq]\-\-\[rq] characters. Lines starting with a \[lq]#\[rq] sign
+are comments. An example configuration file:
.RS
-.RS 3
.EX
no\-page\-delay
.br
@@ -158,48 +224,17 @@ silence\-string = Using \eoverbracket and \eunderbracket from \[ga]mathtools\[aq
.br
silence\-string = ////luaotfload | aux : font no %d+ %(.\-%)
.br
-silence\-files = *.cls
+silence\-files = *.sty
.EE
.RE
-.RE
-
-.TP
-\fB\-h\fR, \fB\-\-help\fR
-Show concise options description.
-
-.TP
-\fB\-\-version\fR
-Print program version.
-
-.SH UNRECOGNIZED MESSAGES
-
-texlogsieve automatically handles messages such as \[lq]Package blah
-Info:...\[rq] or \[lq]LaTeX Warning:...\[rq]. However, many messages do not
-follow this pattern. To do its thing, texlogsieve should know about these
-other messages beforehand. This is important for three reasons:
-
-.IP 1. 3
-Unknown messages are given maximum priority; if you do not want to see them,
-you have to use \-\-silence\-string;
-.IP 2. 3
-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;
-.IP 3. 3
-In some rare cases, the line unwrapping algorithm may fail near an
-unrecognized message.
-
-.PP
-While 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 \[lq]\-l unknown\[rq]). If that is the case, you can use
-the \-\-add\-[debug|info|warning]\-message options to add it to the list of
-messages known to the program.
.SH LIMITATIONS
texlogsieve 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.
+at the log file anyway. It also cannot detect if LaTeX stops for user input,
+so you should \fBreally\fR run LaTeX in \fI\,nonstopmode\/\fR when texlogsieve
+is reading from a pipe.
Since it needs to know what messages to expect, texlogsieve is currently
geared towards LaTeX; I have no idea how it would work with ConTeXt or plain
@@ -219,7 +254,7 @@ program, check the initial comments in the code.
.SH COPYRIGHT
-Copyright \[co] 2021 Nelson Lago <lago@ime.usp.br>
+Copyright \[co] 2021, 2022 Nelson Lago <lago@ime.usp.br>
.br
License GPLv3+: GNU GPL version 3 or later
.UR https://gnu.org/licenses/gpl.html
diff --git a/Master/texmf-dist/doc/man/man1/texlogsieve.man1.pdf b/Master/texmf-dist/doc/man/man1/texlogsieve.man1.pdf
index 06f5b53d0da..12059aaf046 100644
--- a/Master/texmf-dist/doc/man/man1/texlogsieve.man1.pdf
+++ b/Master/texmf-dist/doc/man/man1/texlogsieve.man1.pdf
Binary files differ
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.\\