summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/man
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/man
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/man')
-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
2 files changed, 92 insertions, 57 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