From a1e6a7b727e6acf25eeacbacc20345b721b416c4 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Thu, 16 Dec 2021 21:25:06 +0000 Subject: texlogsieve (16dec21) git-svn-id: svn://tug.org/texlive/trunk@61328 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/man/man1/texlogsieve.1 | 229 +++++++++++++++++++++ .../texmf-dist/doc/man/man1/texlogsieve.man1.pdf | Bin 0 -> 38464 bytes 2 files changed, 229 insertions(+) create mode 100644 Master/texmf-dist/doc/man/man1/texlogsieve.1 create mode 100644 Master/texmf-dist/doc/man/man1/texlogsieve.man1.pdf (limited to 'Master/texmf-dist/doc/man/man1') 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 +.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 Binary files /dev/null and b/Master/texmf-dist/doc/man/man1/texlogsieve.man1.pdf differ -- cgit v1.2.3