diff options
Diffstat (limited to 'Master/texmf-dist/doc/man/man1/texfot.1')
| -rw-r--r-- | Master/texmf-dist/doc/man/man1/texfot.1 | 310 |
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>. |