texfot

git-svn-id: svn://tug.org/texlive/trunk@33155 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 310 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/man/man1/texfot.1 b/Master/texmf-dist/doc/man/man1/texfot.1
new file mode 100644
index 00000000000..b0b18cd683d
--- /dev/null
+++ b/Master/texmf-dist/doc/man/man1/texfot.1
@@ -0,0 +1,310 @@
+.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{
+.    if \nF \{
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "TEXFOT 1"
+.TH TEXFOT 1 "2014-03-10" "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
+.nh
+.SH "NAME"
+texfot \- run TeX, filtering online transcript for interesting messages
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+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:
+.PP
+.Vb 2
+\&  # Basic invocation:
+\&  texfot pdflatex file.tex
+\&  
+\&  # Ordinarily the output is copied to /tmp/fot before filtering;
+\&  # omit that:
+\&  texfot \-\-tee=/dev/null file.tex
+\&  
+\&  # Example with more complex engine invocation:
+\&  texfot lualatex \-\-recorder \*(Aq\enonstopmode\einput file\*(Aq
+.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`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.
+.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 standard output from the command.
+.PP
+The messages shown are intended to be those which probably deserve some
+action by the author: error messages, overfull and underfull boxes,
+undefined citations, missing characters from fonts, etc.
+.SH "FLOW OF OPERATION"
+.IX Header "FLOW OF OPERATION"
+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 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
+Otherwise, if the line matches the list of regexps for which the next
+line (two lines in all) should be shown, set the ``next line'' flag for
+the next time around the loop and show this line.  Examples are the
+usual \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, ignore this line.
+.PP
+Once a particular check matches, the program moves on process the next
+line.
+.PP
+Don't hesitate to peruse the source to the script, which is essentially
+a straightforward loop matching against the different regexp lists as
+above.  You can see all the messages in the different categories 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
+anything else as verbose as TeX to make that useful).
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+The following are the options to \f(CW\*(C`texfot\*(C'\fR itself (not the TeX engine
+being invoked; consult the TeX documentation or the engine's \f(CW\*(C`\-\-help\*(C'\fR
+output for that).  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
+\&\-\-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,
+to avoid possible collisions with new options in the future.
+.ie n .IP """\-\-debug""" 4
+.el .IP "\f(CW\-\-debug\fR" 4
+.IX Item "--debug"
+.PD 0
+.ie n .IP """\-\-no\-debug""" 4
+.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.
+.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), just used as-is.
+.ie n .IP """\-\-interactive""" 4
+.el .IP "\f(CW\-\-interactive\fR" 4
+.IX Item "--interactive"
+.PD 0
+.ie n .IP """\-\-no\-interactive""" 4
+.el .IP "\f(CW\-\-no\-interactive\fR" 4
+.IX Item "--no-interactive"
+.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.)
+never happens.  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"
+.PD 0
+.ie n .IP """\-\-no\-quiet""" 4
+.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.
+.ie n .IP """\-\-tee"" \fIfile\fR" 4
+.el .IP "\f(CW\-\-tee\fR \fIfile\fR" 4
+.IX Item "--tee file"
+By default, the output being filtered is \f(CW\*(C`tee\*(C'\fR\-ed, before filtering, to
+\&\f(CW\*(C`$TMPDIR/fot\*(C'\fR (\f(CW\*(C`/tmp/fot\*(C'\fR if \f(CW\*(C`TMPDIR\*(C'\fR is not set), to make it easy to
+check the full output when the filtering seems suspect.  This option
+allows specifying a different file.  Use \f(CW\*(C`\-\-tee\ /dev/null\*(C'\fR if you don't
+want the original output at all.
+.ie n .IP """\-\-version""" 4
+.el .IP "\f(CW\-\-version\fR" 4
+.IX Item "--version"
+Output version information and exit successfully.
+.ie n .IP """\-\-help""" 4
+.el .IP "\f(CW\-\-help\fR" 4
+.IX Item "--help"
+Display this help and exit successfully.
+.SH "RATIONALE"
+.IX Header "RATIONALE"
+I wrote this because, in my work as a TUGboat editor
+(<http://tug.org/TUGboat>, submissions welcome), I end up running and
+rerunning many papers, many times.  It was too easy to lose warnings I
+needed to see in the mass of unvarying and uninteresting output from
+TeX, such as all the style files being read and all the fonts being
+used.  I wanted to see all and only those messages which actually needed
+some action by me.
+.PP
+I found some other programs of a similar nature, the \f(CW\*(C`silence\*(C'\fR LaTeX
+package, 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, definitely including the TeX invocation, which can get
+complicated).  Hence I finally went ahead and wrote this.
+.PP
+Here are some keywords if you want to explore other options:
+texloganalyser, pydflatex, logfilter, latexmk, rubber, arara, and
+searching for \f(CW\*(C`log\*(C'\fR at <http://ctan.org/search>.
+.PP
+\&\f(CW\*(C`texfot\*(C'\fR is written in Perl, and runs on Unix, and does not work on
+Windows.  (If by some chance anyone wants to run this on Windows, please
+make your own fork; I'm not interested in supporting it.)
+.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\ :).
+.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.  There is no home page beyond the package on \s-1CTAN:
+\&\s0<http://www.ctan.org/pkg/texfot>.