summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/man
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2022-09-25 20:14:15 +0000
committerKarl Berry <karl@freefriends.org>2022-09-25 20:14:15 +0000
commitf3c78998bab94f2f9c38a885340e3b4e6271b2aa (patch)
treee5069e3186131f52db2f55626646d82d01d005f2 /Master/texmf-dist/doc/man
parent4a55596dd3edcf25f37acc637407db73c2b31949 (diff)
texfot (25sep22)
git-svn-id: svn://tug.org/texlive/trunk@64507 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/man')
-rw-r--r--Master/texmf-dist/doc/man/man1/texfot.1105
-rw-r--r--Master/texmf-dist/doc/man/man1/texfot.man1.pdfbin32546 -> 32355 bytes
2 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
diff --git a/Master/texmf-dist/doc/man/man1/texfot.man1.pdf b/Master/texmf-dist/doc/man/man1/texfot.man1.pdf
index 07a865f745e..4e3d43c5836 100644
--- a/Master/texmf-dist/doc/man/man1/texfot.man1.pdf
+++ b/Master/texmf-dist/doc/man/man1/texfot.man1.pdf
Binary files differ