diff options
Diffstat (limited to 'Master/texmf-dist/doc/man/man1/texfot.1')
| -rw-r--r-- | Master/texmf-dist/doc/man/man1/texfot.1 | 105 |
1 files changed, 60 insertions, 45 deletions
diff --git a/Master/texmf-dist/doc/man/man1/texfot.1 b/Master/texmf-dist/doc/man/man1/texfot.1 index 85ba26172b4..bf513599252 100644 --- a/Master/texmf-dist/doc/man/man1/texfot.1 +++ b/Master/texmf-dist/doc/man/man1/texfot.1 @@ -133,7 +133,7 @@ .\" ======================================================================== .\" .IX Title "TEXFOT 1" -.TH TEXFOT 1 "2022-02-17" "texfot" "Karl Berry" +.TH TEXFOT 1 "2022-09-24" "texfot" "Karl Berry" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -146,8 +146,8 @@ texfot [\fIoption\fR]... \fItexcmd\fR [\fItexarg\fR...] .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\f(CW\*(C`texfot\*(C'\fR invokes \fItexcmd\fR with the given \fItexarg\fR arguments, -filtering the online output for ``interesting'' messages. Its exit -value is that of \fItexcmd\fR. Examples: +filtering the online output for ``interesting'' messages. Its exit +value is that of \fItexcmd\fR. Examples: .PP .Vb 2 \& # Sample basic invocation: @@ -161,15 +161,24 @@ value is that of \fItexcmd\fR. Examples: \& texfot xelatex \-\-recorder \*(Aq\enonstopmode\einput file\*(Aq .Ve .PP +Here is an example of what the output looks like (in its entirety) on an +error-free run: +.PP +.Vb 3 +\& /path/to/texfot: invoking: pdflatex hello.ltx +\& This is pdfTeX, Version 3.141592653\-2.6\-1.40.24 (TeX Live 2022) (preloaded format=pdflatex) +\& Output written on hello.pdf (1 page, 94415 bytes). +.Ve +.PP Aside from its own options, described below, \f(CW\*(C`texfot\*(C'\fR just runs the given command with the given arguments (same approach to command line -syntax as \f(CW\*(C`env\*(C'\fR, \f(CW\*(C`nice\*(C'\fR, \f(CW\*(C`time\*(C'\fR, \f(CW\*(C`timeout\*(C'\fR, etc.). Thus, \f(CW\*(C`texfot\*(C'\fR -works with any engine and any command line options. +syntax as \f(CW\*(C`env\*(C'\fR, \f(CW\*(C`nice\*(C'\fR, \f(CW\*(C`timeout\*(C'\fR, etc.). Thus, \f(CW\*(C`texfot\*(C'\fR works with +any engine and any command line options. .PP \&\f(CW\*(C`texfot\*(C'\fR does not look at the log file or any other possible output file(s); it only looks at the standard output and standard error from -the command. stdout is processed first, then stderr. Lines from stderr -have an identifying prefix. \f(CW\*(C`texfot\*(C'\fR writes all accepted lines to its +the command. stdout is processed first, then stderr. Lines from stderr +have an identifying prefix. \f(CW\*(C`texfot\*(C'\fR writes all accepted lines to its stdout. .PP The messages shown are intended to be those which likely need action by @@ -181,25 +190,25 @@ Here is the order in which lines of output are checked: .IP "1." 4 If the ``next line'' needs to be printed (see below), print it. .IP "2." 4 +Otherwise, if the line matches any user-supplied list of regexps to +accept (given with \f(CW\*(C`\-\-accept\*(C'\fR, see below), in that order, print it. +.IP "3." 4 Otherwise, if the line matches the built-in list of regexps to ignore, or any user-supplied list of regexps to ignore (given with \f(CW\*(C`\-\-ignore\*(C'\fR, see below), in that order, ignore it. -.IP "3." 4 +.IP "4." 4 Otherwise, if the line matches the list of regexps for which the next line (two lines in all) should be shown, show this line and set the -``next line'' flag for the next time around the loop. Examples are the +``next line'' flag for the next time around the loop. Examples are the common \f(CW\*(C`!\*(C'\fR and \f(CW\*(C`filename:lineno:\*(C'\fR error messages, which are generally followed by a line with specific detail about the error. -.IP "4." 4 -Otherwise, if the line matches the list of regexps to show, show it. .IP "5." 4 +Otherwise, if the line matches the list of regexps to show, show it. +.IP "6." 4 Otherwise, the default: if the line came from stdout, ignore it; if the -line came from stderr, print it (to stdout). This distinction is made +line came from stderr, print it (to stdout). This distinction is made because TeX engines write relatively few messages to stderr, and it's likely that any such should be considered. -.Sp -It would be easy to add more options to allow for user additions to the -various regex lists, if that ever seems useful. Or email me (see end). .PP Once a particular check matches, the program moves on to process the next line. @@ -211,8 +220,8 @@ in the source. .PP Incidentally, although nothing in this basic operation is specific to TeX engines, all the regular expressions included in the program are -specific to TeX. So in practice the program isn't useful except with -TeX engines, although it would be easy enough to adapt it (if there was +specific to TeX. So in practice the program isn't useful except with TeX +engines, although it would be easy enough to adapt it (if there was anything else as verbose as TeX to make that useful). .SH "OPTIONS" .IX Header "OPTIONS" @@ -222,13 +231,20 @@ output for that). .PP The first non-option terminates \f(CW\*(C`texfot\*(C'\fR's option parsing, and the remainder of the command line is invoked as the TeX command, without -further parsing. For example, \f(CW\*(C`texfot \-\-debug tex +further parsing. For example, \f(CW\*(C`texfot \-\-debug tex \&\-\-debug\*(C'\fR will output debugging information from both \f(CW\*(C`texfot\*(C'\fR and \&\f(CW\*(C`tex\*(C'\fR. .PP Options may start with either \- or \-\-, and may be unambiguously -abbreviated. It is best to use the full option name in scripts, though, +abbreviated. It is best to use the full option name in scripts, though, to avoid possible collisions with new options in the future. +.ie n .IP """\-\-accept"" \fIregexp\fR" 4 +.el .IP "\f(CW\-\-accept\fR \fIregexp\fR" 4 +.IX Item "--accept regexp" +Accept lines in the TeX output matching (Perl) \fIregexp\fR. Can be +repeated. This list is checked first, so any and all matches will be +shown, regardless of other options. These regexps are not automatically +anchored (or otherwise altered), simply used as-is. .ie n .IP """\-\-debug""" 4 .el .IP "\f(CW\-\-debug\fR" 4 .IX Item "--debug" @@ -237,14 +253,14 @@ to avoid possible collisions with new options in the future. .el .IP "\f(CW\-\-no\-debug\fR" 4 .IX Item "--no-debug" .PD -Output (or not) what is being done on standard error. Off by default. +Output (or not) what the program is doing to standard error; off by default. .ie n .IP """\-\-ignore"" \fIregexp\fR" 4 .el .IP "\f(CW\-\-ignore\fR \fIregexp\fR" 4 .IX Item "--ignore regexp" -Ignore lines in the TeX output matching (Perl) \fIregexp\fR. Can be -repeated. Adds to the default set of ignore regexps rather than -replacing. These regexps are not automatically anchored (or otherwise -altered), simply used as-is. +Ignore lines in the TeX output matching (Perl) \fIregexp\fR. Can be +repeated. Adds to the default set of ignore regexps rather than +replacing. Like the acceptance regexps, these are not automatically +anchored (or otherwise altered). .ie n .IP """\-\-interactive""" 4 .el .IP "\f(CW\-\-interactive\fR" 4 .IX Item "--interactive" @@ -255,7 +271,7 @@ altered), simply used as-is. .PD By default, standard input to the TeX process is closed so that TeX's interactive mode (waiting for input upon error, the \f(CW\*(C`*\*(C'\fR prompt, etc.) -is never entered. Giving \f(CW\*(C`\-\-interactive\*(C'\fR allows interaction to happen. +is never entered. Giving \f(CW\*(C`\-\-interactive\*(C'\fR allows interaction to happen. .ie n .IP """\-\-quiet""" 4 .el .IP "\f(CW\-\-quiet\fR" 4 .IX Item "--quiet" @@ -264,8 +280,8 @@ is never entered. Giving \f(CW\*(C`\-\-interactive\*(C'\fR allows interaction t .el .IP "\f(CW\-\-no\-quiet\fR" 4 .IX Item "--no-quiet" .PD -By default, the TeX command being invoked is reported on standard output. -\&\f(CW\*(C`\-\-quiet\*(C'\fR omits that reporting. To get a completely silent run, +By default, the TeX command being invoked is reported on standard +output. \f(CW\*(C`\-\-quiet\*(C'\fR omits that reporting. To get a completely silent run, redirect standard output: \f(CW\*(C`texfot\ ...\ >/dev/null\*(C'\fR. (The only messages to standard error should be errors from \f(CW\*(C`texfot\*(C'\fR itself, so it shouldn't be necessary to redirect that, but of course that can be done @@ -279,8 +295,8 @@ as well.) .IX Item "--no-stderr" .PD The default is for \f(CW\*(C`texfot\*(C'\fR to report everything written to stderr by -the TeX command (on stdout). \f(CW\*(C`\-\-no\-stderr\*(C'\fR omits that reporting. -(Some programs, \f(CW\*(C`dvisvgm\*(C'\fR is one, can be rather verbose on stderr.) +the TeX command (on stdout). \f(CW\*(C`\-\-no\-stderr\*(C'\fR omits that reporting. (Some +programs, \f(CW\*(C`dvisvgm\*(C'\fR is one, can be rather verbose on stderr.) .ie n .IP """\-\-tee"" \fIfile\fR" 4 .el .IP "\f(CW\-\-tee\fR \fIfile\fR" 4 .IX Item "--tee file" @@ -306,19 +322,18 @@ Display this help and exit successfully. .IX Header "RATIONALE" I wrote this because, in my work as a TUGboat editor (<https://tug.org/TUGboat>, journal submissions always welcome!), I run -and rerun many documents, many times each. It was easy to lose -warnings I needed to see in the mass of unvarying and uninteresting -output from TeX, such as style files being read and fonts being used. I -wanted to see all and only those messages which needed some action by -me. +and rerun many documents, many times each. It was easy to lose warnings +I needed to see in the mass of unvarying and uninteresting output from +TeX, such as style files being read and fonts being used. I wanted to +see all and only those messages which needed some action by me. .PP I found some other programs of a similar nature, the LaTeX package \&\f(CW\*(C`silence\*(C'\fR, and plenty of other (La)TeX wrappers, but it seemed none of -them did what I wanted. Either they read the log file (I wanted the -online output only), or they output more or less than I wanted, or they -required invoking TeX differently (I wanted to keep my build process -exactly the same, most critically the TeX invocation, which can get -complicated). Hence I wrote this. +them did what I wanted. Either they read the log file (I wanted to look +at only the online output), or they output more or less than I wanted, +or they required invoking TeX differently (I wanted to keep my build +process exactly the same, most critically the TeX invocation, which can +get complicated). Hence I wrote this little script. .PP Here are some keywords if you want to explore other options: texloganalyser, pydflatex, logfilter, latexmk, rubber, arara, and @@ -330,16 +345,16 @@ don't support \f(CW\*(C`texfot\*(C'\fR there. .PP The name comes from the \f(CW\*(C`trip.fot\*(C'\fR and \f(CW\*(C`trap.fot\*(C'\fR files that are part of Knuth's trip and trap torture tests, which record the online output -from the programs. I am not sure what \*(L"fot\*(R" stands for in trip and -trap, but I can pretend that it stands for \*(L"filter online transcript\*(R" in -the present case\ :). +from the programs. I am not sure what \*(L"fot\*(R" stands for in trip and trap, +but I can pretend that it stands for \*(L"filter online transcript\*(R" in the +present case\ :). .SH "AUTHORS AND COPYRIGHT" .IX Header "AUTHORS AND COPYRIGHT" This script and its documentation were written by Karl Berry and both -are released to the public domain. Email \f(CW\*(C`karl@freefriends.org\*(C'\fR with -bug reports. It has no home page beyond the package on \s-1CTAN:\s0 +are released to the public domain. Email \f(CW\*(C`karl@freefriends.org\*(C'\fR with +bug reports. It has no home page beyond the package page on \s-1CTAN:\s0 <https://ctan.org/pkg/texfot>. .PP .Vb 1 -\& $Id: texfot,v 1.45 2022/02/17 18:42:02 karl Exp $ +\& $Id: texfot,v 1.47 2022/09/24 16:38:13 karl Exp $ .Ve |