summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/man
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2021-12-16 21:25:06 +0000
committerKarl Berry <karl@freefriends.org>2021-12-16 21:25:06 +0000
commita1e6a7b727e6acf25eeacbacc20345b721b416c4 (patch)
tree406fda5234b923567652225efec91e7aa1be6096 /Master/texmf-dist/doc/man
parentd358de4496e1833473023a9fe431880e5fa05336 (diff)
texlogsieve (16dec21)
git-svn-id: svn://tug.org/texlive/trunk@61328 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/man')
-rw-r--r--Master/texmf-dist/doc/man/man1/texlogsieve.1229
-rw-r--r--Master/texmf-dist/doc/man/man1/texlogsieve.man1.pdfbin0 -> 38464 bytes
2 files changed, 229 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/man/man1/texlogsieve.1 b/Master/texmf-dist/doc/man/man1/texlogsieve.1
new file mode 100644
index 00000000000..79cdbc68d1c
--- /dev/null
+++ b/Master/texmf-dist/doc/man/man1/texlogsieve.1
@@ -0,0 +1,229 @@
+.TH TEXLOGSIEVE "1" "December 2021" "texlogsieve 1.0.0-beta-1" "User Commands"
+
+.SH NAME
+
+texlogsieve \- filter and summarize LaTeX log files
+
+.SH SYNOPSIS
+
+\fBtexlogsieve\fR [\fI\,OPTION\/\fR]... [\fI\,INPUT FILE\/\fR]
+
+.SH DESCRIPTION
+
+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.
+
+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.).
+
+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
+its value from the same places as TeX. Setting \fI\,max_print_line\/\fR to a
+value larger than 9999 makes texlogsieve ignore line wrapping.
+
+The defaults are reasonable; hopefully, you can just do
+
+.RS 3
+.EX
+[pdf|lua|xe]latex myfile.tex | texlogsieve
+.EE
+.RE
+
+and be satisfied with the result.
+
+.SH OPTIONS
+
+.TP
+\fB\-\-page\-delay\fR, \fB\-\-no\-page\-delay\fR
+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).
+
+.TP
+\fB\-\-summary\fR, \fB\-\-no\-summary\fR
+Enable/disable final summary (default enabled).
+
+.TP
+\fB\-\-only\-summary\fR
+No messages, show only the final summary (default disabled).
+
+.TP
+\fB\-\-shipouts\fR, \fB\-\-no\-shipouts\fR
+Enable/disable reporting shipouts (default disabled with page-delay,
+enabled with no-page-delay).
+
+.TP
+\fB\-\-repetitions\fR, \fB\-\-no\-repetitions\fR
+Allow/prevent repeated messages (default disabled, i.e., repeated messages
+are supressed).
+
+.TP
+\fB\-\-heartbeat\fR, \fB\-\-no\-heartbeat\fR
+Enable/disable progress gauge in page-delay mode (default enabled).
+
+.TP
+\fB\-l\fR \fI\,LEVEL\/\fR, \fB\-\-minlevel\fR=\fI\,LEVEL\/\fR
+Filter out messages with severity level lower than LEVEL. Valid levels
+are DEBUG (no filtering), INFO, WARNING, CRITICAL, and UNKNOWN (default
+WARNING).
+
+.TP
+\fB\-u\fR, \fB\-\-unwrap\-only\fR
+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).
+
+.TP
+\fB\-\-silence\-package\fR=\fI\,PKGNAME\/\fR
+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.
+
+.TP
+\fB\-\-silence\-string\fR=\fI\,EXCERPT OF UNWANTED MESSAGE\/\fR
+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 \[lq]////\[rq], in which case you can use lua-style pattern matching
+(\c
+.UR https://www.lua.org/pil/20.2.html
+.UE ). Note that the string is used verbatim: you need not (and should not)
+enclose it in quotes nor escape special characters such as \[lq]\e\[rq].
+
+.TP
+\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.
+
+.TP
+\fB\-\-semisilence\-file\fR=\fI\,FILENAME OR FILE GLOB\/\fR
+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
+\[lq]chapters.tex\[rq] includes (with \einput) the files \[lq]chapter1.tex\[rq]
+and \[lq]chapter2.tex\[rq], using \[lq]\-\-silence\-file=chapters.tex\[rq]
+will prevent messages generated by any of the three files from being
+displayed. If, however, you use \[lq]\-\-semisilence\-file=chapters.tex\[rq],
+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
+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.
+
+.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:
+
+.RS
+.RS 3
+.EX
+no\-page\-delay
+.br
+# no\-page\-delay enables shipouts, but we do not want that
+.br
+no\-shipouts
+.br
+silence\-string = Hyperreferences in rotated content will be misplaced
+.br
+# no need to escape the \[dq]\e\[dq] (or any other) character
+.br
+silence\-string = Using \eoverbracket and \eunderbracket from \[ga]mathtools\[aq]
+.br
+# silence a string using lua pattern matching
+.br
+silence\-string = ////luaotfload | aux : font no %d+ %(.\-%)
+.br
+silence\-files = *.cls
+.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.
+
+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
+TeX. Still, adding support to them should not be too difficult.
+
+.SH SEE ALSO
+
+The pdf documentation (in TeXLive, try \fI\,texdoc texlogsieve\/\fR).
+
+If you want to know more about the TeX log file and the workings of the
+program, check the initial comments in the code.
+
+.SH BUGS AND DEVELOPMENT
+
+.UR https://gitlab.com/lago/texlogsieve
+.UE
+
+.SH COPYRIGHT
+
+Copyright \[co] 2021 Nelson Lago <lago@ime.usp.br>
+.br
+License GPLv3+: GNU GPL version 3 or later
+.UR https://gnu.org/licenses/gpl.html
+.UE .
+
+This is free software: you are free to change and redistribute it. \
+There is NO WARRANTY, to the extent permitted by law.
diff --git a/Master/texmf-dist/doc/man/man1/texlogsieve.man1.pdf b/Master/texmf-dist/doc/man/man1/texlogsieve.man1.pdf
new file mode 100644
index 00000000000..06f5b53d0da
--- /dev/null
+++ b/Master/texmf-dist/doc/man/man1/texlogsieve.man1.pdf
Binary files differ