NAME

       texfot - run TeX, filtering online transcript for interesting messages

SYNOPSIS

       texfot [option]... texcmd [texarg...]

DESCRIPTION

       "texfot" invokes texcmd with the given texarg arguments, filtering the online output for
       ``interesting'' messages.  Its exit value is that of texcmd.  Examples:

         # Sample basic invocation:
         texfot pdflatex file.tex

         # Ordinarily all output is copied to /tmp/fot before filtering,
         # but that can be omitted:
         texfot --tee=/dev/null lualatex file.tex

         # Example of more complex engine invocation:
         texfot xelatex --recorder '\nonstopmode\input file'

       Aside from its own options, described below, "texfot" just runs the given command with the
       given arguments (same approach to command line syntax as "env", "nice", "time", "timeout",
       etc.).  Thus, "texfot" works with any engine and any command line options.

       "texfot" 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.  "texfot" writes all accepted
       lines to its stdout.

       The messages shown are intended to be those which likely need action by the author: error
       messages, overfull and underfull boxes, undefined citations, missing characters from
       fonts, etc.

FLOW OF OPERATION

       Here is the order in which lines of output are checked:

       1.  If the ``next line'' needs to be printed (see below), print it.

       2.  Otherwise, if the line matches the built-in list of regexps to ignore, or any user-
           supplied list of regexps to ignore (given with "--ignore", see below), in that order,
           ignore it.

       3.  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 common "!" and "filename:lineno:" error
           messages, which are generally followed by a line with specific detail about the error.

       4.  Otherwise, if the line matches the list of regexps to show, show it.

       5.  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 because TeX engines write
           relatively few messages to stderr, and it's likely that any such should be considered.

           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).

       Once a particular check matches, the program moves on to process the next line.

       Don't hesitate to peruse the source to the script, which is essentially a straightforward
       loop matching against the different lists as above.  You can see the exact regexps being
       matched in the different categories in the source.

       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 anything else as verbose as TeX to make that useful).

OPTIONS

       The following are the options to "texfot" itself (not the TeX engine being invoked;
       consult the TeX documentation or the engine's "--help" output for that).

       The first non-option terminates "texfot"'s option parsing, and the remainder of the
       command line is invoked as the TeX command, without further parsing.  For example, "texfot
       --debug tex --debug" will output debugging information from both "texfot" and "tex".

       Options may start with either - or --, and may be unambiguously abbreviated.  It is best
       to use the full option name in scripts, though, to avoid possible collisions with new
       options in the future.

       "--debug"
       "--no-debug"
           Output (or not) what is being done on standard error.  Off by default.

       "--ignore" regexp
           Ignore lines in the TeX output matching (Perl) regexp.  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.

       "--interactive"
       "--no-interactive"
           By default, standard input to the TeX process is closed so that TeX's interactive mode
           (waiting for input upon error, the "*" prompt, etc.)  is never entered.  Giving
           "--interactive" allows interaction to happen.

       "--quiet"
       "--no-quiet"
           By default, the TeX command being invoked is reported on standard output.  "--quiet"
           omits that reporting. To get a completely silent run, redirect standard output:
           "texfot ... >/dev/null". (The only messages to standard error should be errors from
           "texfot" itself, so it shouldn't be necessary to redirect that, but of course that can
           be done as well.)

       "--stderr"
       "--no-stderr"
           The default is for "texfot" to report everything written to stderr by the TeX command
           (on stdout).  "--no-stderr" omits that reporting.  (Some programs, "dvisvgm" is one,
           can be rather verbose on stderr.)

       "--tee" file
           By default, the output being filtered is "tee"-ed, before filtering, to "$TMPDIR/fot"
           (or "$TMP/fot" if "TMP" is set, or "/tmp/fot" if neither environment variable is set),
           to make it easy to check the full output when the filtering seems suspect. This option
           allows specifying a different file. Use "--tee /dev/null" if you don't want the
           original output at all.

       "--version"
           Output version information and exit successfully.

       "--help"
           Display this help and exit successfully.

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 too
       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.

       I found some other programs of a similar nature, the LaTeX package "silence", 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.

       Here are some keywords if you want to explore other options: texloganalyser, pydflatex,
       logfilter, latexmk, rubber, arara, and searching for "log" at <https://ctan.org/search>.

       "texfot" is written in Perl, and runs on Unix. It may work on Windows if Perl and other
       software is installed, but I don't use Windows and don't support C,texfot> there.

       The name comes from the "trip.fot" and "trap.fot" 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
       "fot" stands for in trip and trap, but I can pretend that it stands for "filter online
       transcript" in the present case :).

AUTHORS AND COPYRIGHT

       This script and its documentation were written by Karl Berry and both are released to the
       public domain.  Email "karl@freefriends.org" with bug reports.  It has no home page beyond
       the package on CTAN: <https://ctan.org/pkg/texfot>.