.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) .\" .\" 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 .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . 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 >0, 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 .\" ======================================================================== .\" .IX Title "TYPOG-GREP 1" .TH TYPOG-GREP 1 2024/07/08 0.4 "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .\" Turn off justification. .na .SH NAME typog\-grep \- specialized grep for typog\-inspect elements in LaTeX log files .SH SYNOPSIS .IX Header "SYNOPSIS" .IP "\fBtypog-grep\fR \-a|\-\-all|\-\-any [\fIOPTION\fR...] \fILOG-FILE\fR..." 4 .IX Item "typog-grep -a|--all|--any [OPTION...] LOG-FILE..." .PD 0 .IP "\fBtypog-grep\fR [\fIOPTION\fR...] \fIREGEXP\fR \fILOG-FILE\fR..." 4 .IX Item "typog-grep [OPTION...] REGEXP LOG-FILE..." .PD .PP The first form, ``discovery mode'', shows all \fIID\fRs of .RS .EX .EE .RE .PP elements in \fILOG-FILE\fR. .PP The second form shows the contents, \fILOG-DATA\fR, of the elements .RS .EX \fILOG-DATA\fP .EE .RE .PP whose \fIID\fRs match \fIREGEXP\fR in \fILOG-FILE\fR. .PP If no \fILOG-FILE\fR is given read from \fIstdin\fR. The filename\ \f(CW\*(C`\-\*(C'\fR is synonymous to \fIstdin\fR. .SH DESCRIPTION .IX Header "DESCRIPTION" \&\fBtypog-grep\fR is a tailored post-processor for LaTeX \fIlog\fR\ files and the \f(CW\*(C`typoginspect\*(C'\fR environment as provided by the LaTeX\ package\ typog. It shares more with the venerable \&\fBsgrep\fR than with POSIX\ \fBgrep\fR\ . .PP In the LaTeX source file the user brackets her text or code in a \f(CW\*(C`typoginspect\*(C'\fR environment: .RS .EX \ebegin{typoginspect}{\fI\,ID\/\fP} \fITEXT-OR-CODE-TO-INVESTIGATE\fP \eend{typoginspect} .EE .RE .PP where \fIID\fR is used to identify one or more bracketed snippets. \&\fIID\fR does not have to be unique. The \fIREGEXP\fR mechanism makes it easy to select groups of related \fIID\fRs if they are named accordingly. .PP In \fILOG-FILE\fR the result of the environment shows up, packed with tracing information, as .RS .EX \fILOG-DATA\fP .EE .RE .PP where all the capital-letter sequences are meta-variables and in particular \&\fIJOB-NAME\fR is the expansion of \f(CW\*(C`\ejobname\*(C'\fR, \&\fILINE-NUMBER\fR is the LaTeX source file line number of the beginning of the \f(CW\*(C`typoginspect\*(C'\fR environment, and \fIPAGE-NUMBER\fR is the page where the output of \f(CW\*(C`TEXT\-OR\-CODE\-TO\-INVESTIGATE\*(C'\fR occurs. .PP \&\fBtypog-grep\fR reveals the contents of \fILOG-FILE\fR between \f(CW\*(C`\*(C'\fR and \f(CW\*(C`\*(C'\fR excluding the XML-tags themselves. Access the \fIJOB-NAME\fR, \fILINE-NUMBER\fR, and \fIPAGE-NUMBER\fR with the commandline options \&\fB\-\-job\-name\fR, \fB\-\-line\-number\fR, and \fB\-\-page\-number\fR, respectively. Use \fB\-\-id\fR to show the name of the IDs that matched \fIREGEXP\fR. .PP \&\f(CW\*(C`typoginspect\*(C'\fR environments can be nested. \&\fBtypog-grep\fR respects the nesting, i.e., if the \fIID\fR of the nested environment does not match \fIREGEXP\fR it will not be included in the program's output. .SH OPTIONS .IX Header "OPTIONS" The list of options is sorted by the names of the long options. .IP "\fB\-a\fR, \fB\-\-all\fR, \fB\-\-any\fR" 4 .IX Item "-a, --all, --any" ID-discovery mode: Discover all \f(CW\*(C`typog\-inspect\*(C'\fR elements independent of any matching patterns and print their \fIID\fRs. The results are printed in their order of occurrence in the respective \fILOG-FILE\fRs. Pipe the output into \fBsort\fR to get alphabetically ordered \fIID\fRs. .Sp Augment with options \&\fB\-\-job\-name\fR, \fB\-\-line\-number\fR, \fB\-\-log\-line\-number\fR, or \fB\-\-page\-number\fR for more information. .IP "\fB\-\-color\fR, \fBcolour\fR \fIWHEN\fR" 4 .IX Item "--color, colour WHEN" Colorize specific log contents for the matching \fIID\fRs. The argument\ \fIWHEN\fR determines when to apply color: \&\f(CW\*(C`always\*(C'\fR, \f(CW\*(C`never\*(C'\fR, or\ \f(CW\*(C`auto\*(C'\fR. The setting \f(CW\*(C`auto\*(C'\fR checks whether standard output has been redirected. This is the default. .IP "\fB\-C\fR, \fB\-\-config\fR \fIKEY\fR=\fIVALUE\fR[:\fIKEY\fR=\fIVALUE\fR[:...]]" 4 .IX Item "-C, --config KEY=VALUE[:KEY=VALUE[:...]]" Set one or more configuration \fIKEY\fR to \fIVALUE\fR pairs. See section "CONFIGURATION" for a description of all available configuration items. Use option\ \fB\-\-show\-config\fR to display the default configuration. .IP \fB\-\-debug\fR 4 .IX Item "--debug" Turn on debug output on \fIstderr\fR. .IP "\fB\-E\fR, \fB\-\-encoding\fR \fIENCODING\fR" 4 .IX Item "-E, --encoding ENCODING" Set the \fIENCODING\fR of \fILOG-FILE\fR for the translation to UTF\-8. The default is unset. .Sp Use this option to get rid of pesky "<\fIHEX-DIGITS\fR>"\ escapes on UTF\-8 terminals. See option\ \fB\-\-show\-encodings\fR for the known encodings and Encode::Supported for a summary of all encodings. See also section\ "Some\ Common\ Encodings". .Sp Apply \fBiconv\fR (POSIX) or \fBrecode\fR (GNU) on \fILOG-FILE\fR before this tool to avoid having to use option\ \fB\-\-encoding\fR. .IP "\fB\-h\fR, \fB\-\-help\fR" 4 .IX Item "-h, --help" Display brief help then exit. .IP "\fB\-i\fR, \fB\-\-[no\-]id\fR" 4 .IX Item "-i, --[no-]id" Print the actual ID-name that matched \fIREGEXP\fR. Control the appearance of the matching \fIID\fR with configuration item\ \f(CW\*(C`id\-heading\*(C'\fR. .IP "\fB\-y\fR, \fB\-\-[no\-]ignore\-case\fR" 4 .IX Item "-y, --[no-]ignore-case" Match \fIID\fRs while ignoring case distinctions in patterns and data. .IP "\fB\-j\fR, \fB\-\-[no\-]job\-name\fR" 4 .IX Item "-j, --[no-]job-name" Print the \f(CW\*(C`\ejobname\*(C'\fR that \fBlatex\fR associated with the input file. .IP "\fB\-n\fR, \fB\-\-[no\-]line\-number\fR" 4 .IX Item "-n, --[no-]line-number" Print the line number where the \f(CW\*(C`typoginspect\*(C'\fR\ environment was encountered in the LaTeX source file. .IP "\fB\-N\fR, \fB\-\-[no\-]log\-line\-number\fR" 4 .IX Item "-N, --[no-]log-line-number" Print the line number of the \fIlog\fR\-file where the current line was encountered. .IP "\fB\-p\fR, \fB\-\-[no\-]page\-number\fR" 4 .IX Item "-p, --[no-]page-number" Print page number where the contents of the \f(CW\*(C`typoginspect\*(C'\fR\ environment starts in the typeset document. .IP "\fB\-P\fR, \fB\-\-[no\-]pager\fR" 4 .IX Item "-P, --[no-]pager" Redirect output from \fIstdout\fR to the configured pager. .IP \fB\-\-show\-config\fR 4 .IX Item "--show-config" Show the default configuration and exit. .IP \fB\-\-show\-encodings\fR 4 .IX Item "--show-encodings" Show all known encodings and exit. .IP "\fB\-V\fR, \fB\-\-version\fR" 4 .IX Item "-V, --version" Show version information and exit. .IP "\fB\-w\fR, \fB\-\-[no\-]word\-regexp\fR" 4 .IX Item "-w, --[no-]word-regexp" Match only whole words. .SH CONFIGURATION .IX Header "CONFIGURATION" .ie n .IP """id\-format""=\fIFORMAT\fR" 4 .el .IP \f(CWid\-format\fR=\fIFORMAT\fR 4 .IX Item "id-format=FORMAT" Control the \fIFORMAT\fR for printing matching ids in inline-mode, where \fIFORMAT\fR is passed to Perl's \f(CW\*(C`printf\*(C'\fR. Default:\ \f(CW%s:\fR. .ie n .IP """id\-heading""=0|1" 4 .el .IP \f(CWid\-heading\fR=\f(CW0\fR|\f(CW1\fR 4 .IX Item "id-heading=0|1" Choose between printing the matching \fIID\fRs with option\ \fB\-\-id\fR: Inline\ (\f(CW0\fR) or heading before the matching data (\f(CW1\fR). Default:\ \f(CW0\fR. .ie n .IP """id\-heading\-format""=\fIFORMAT\fR" 4 .el .IP \f(CWid\-heading\-format\fR=\fIFORMAT\fR 4 .IX Item "id-heading-format=FORMAT" Control the \fIFORMAT\fR for printing matching \fIID\fRs in heading-mode, where \fIFORMAT\fR is passed to Perl's \f(CW\*(C`printf\*(C'\fR. Default:\ \f(CW\*(C`\-\->\ %s\ <\-\-\*(C'\fR. .ie n .IP """id\-indent""=\fIINDENT\fR" 4 .el .IP \f(CWid\-indent\fR=\fIINDENT\fR 4 .IX Item "id-indent=INDENT" Indentation of nested typog-inspect tags. Only used in ``discovery mode'' (first form), i.e., if \fB\-\-all\fR is active. Default:\ 8. .ie n .IP """id\-max\-length""=\fIMAXIMUM-LENGTH\fR" 4 .el .IP \f(CWid\-max\-length\fR=\fIMAXIMUM-LENGTH\fR 4 .IX Item "id-max-length=MAXIMUM-LENGTH" Set the maximum length of a matching \fIID\fR for printing. It a matching \fIID\fR exceeds this length it will be truncated and the last three characters (short of \fIMAXIMUM-LENGTH\fR) will be replaced by dots. Default:\ 40. .ie n .IP """line\-number\-format""=\fIFORMAT\fR" 4 .el .IP \f(CWline\-number\-format\fR=\fIFORMAT\fR 4 .IX Item "line-number-format=FORMAT" Control the \fIFORMAT\fR for printing TeX source line numbers, where \fIFORMAT\fR is passed to Perl's \f(CW\*(C`printf\*(C'\fR. Default:\ \f(CW%5d\fR. .ie n .IP """log\-line\-number\-format""=\fIFORMAT\fR" 4 .el .IP \f(CWlog\-line\-number\-format\fR=\fIFORMAT\fR 4 .IX Item "log-line-number-format=FORMAT" Control the \fIFORMAT\fR for printing log line numbers, where \fIFORMAT\fR is passed to Perl's \f(CW\*(C`printf\*(C'\fR. Default:\ \f(CW%6d\fR. .ie n .IP """page\-number\-format""=\fIFORMAT\fR" 4 .el .IP \f(CWpage\-number\-format\fR=\fIFORMAT\fR 4 .IX Item "page-number-format=FORMAT" Control the \fIFORMAT\fR for printing page numbers, where \fIFORMAT\fR is passed to Perl's \f(CW\*(C`printf\*(C'\fR. Default:\ \f(CW\*(C`[%3d]\*(C'\fR. .ie n .IP """pager""=\fIPAGER\fR" 4 .el .IP \f(CWpager\fR=\fIPAGER\fR 4 .IX Item "pager=PAGER" Name of pager application to pipe output into if run with option\ \fB\-\-pager\fR. Default:\ \f(CW\*(C`less\*(C'\fR. .ie n .IP """pager\-flags""=\fIFLAGS\fR" 4 .el .IP \f(CWpager\-flags\fR=\fIFLAGS\fR 4 .IX Item "pager-flags=FLAGS" Pass \fIFLAGS\fR to \fIPAGER\fR. Default:\ \f(CW\*(C`\-\-quit\-if\-one\-screen\*(C'\fR. .IP "Color Configuration" 4 .IX Item "Color Configuration" For the syntax of the color specifications consult the manual page of Term::ANSIColor(pm). .RS 4 .ie n .IP """file\-header\-color""" 4 .el .IP \f(CWfile\-header\-color\fR 4 .IX Item "file-header-color" Color of the filename header. .ie n .IP """fill\-state\-color""" 4 .el .IP \f(CWfill\-state\-color\fR 4 .IX Item "fill-state-color" Color of the messages that report ``Underfull hbox'' or ``Overfull hbox''. .ie n .IP """first\-vbox\-color""" 4 .el .IP \f(CWfirst\-vbox\-color\fR 4 .IX Item "first-vbox-color" Color of the first vbox on a page. .ie n .IP """font\-spec\-color""" 4 .el .IP \f(CWfont\-spec\-color\fR 4 .IX Item "font-spec-color" Color of font specifications. .ie n .IP """horizontal\-break\-candidate\-color""" 4 .el .IP \f(CWhorizontal\-break\-candidate\-color\fR 4 .IX Item "horizontal-break-candidate-color" Color of lines with horizontal-breakpoint candidates\ \f(CW\*(C`@\*(C'\fR. .ie n .IP """horizontal\-breakpoint\-color""" 4 .el .IP \f(CWhorizontal\-breakpoint\-color\fR 4 .IX Item "horizontal-breakpoint-color" Color of lines with horizontal breakpoints\ \f(CW\*(C`@@\*(C'\fR. .ie n .IP """id\-color""" 4 .el .IP \f(CWid\-color\fR 4 .IX Item "id-color" Color of matching \fIID\fRs when printed inline. .ie n .IP """id\-heading\-color""" 4 .el .IP \f(CWid\-heading\-color\fR 4 .IX Item "id-heading-color" Color of matching \fIID\fRs when printed in heading form. .ie n .IP """line\-break\-pass\-color""" 4 .el .IP \f(CWline\-break\-pass\-color\fR 4 .IX Item "line-break-pass-color" Color of the lines showing which pass (e.g., \f(CW@firstpass\fR) of the line-breaking algorithm is active. .ie n .IP """line\-number\-color""" 4 .el .IP \f(CWline\-number\-color\fR 4 .IX Item "line-number-color" Color of TeX-source-file line numbers. .ie n .IP """log\-line\-number\-color""" 4 .el .IP \f(CWlog\-line\-number\-color\fR 4 .IX Item "log-line-number-color" Color of log-file line numbers. .ie n .IP """math\-color""" 4 .el .IP \f(CWmath\-color\fR 4 .IX Item "math-color" Color used for math expressions including their font specs. .ie n .IP """page\-number\-color""" 4 .el .IP \f(CWpage\-number\-color\fR 4 .IX Item "page-number-color" Color of page numbers of the final output. .ie n .IP """tightness\-color""" 4 .el .IP \f(CWtightness\-color\fR 4 .IX Item "tightness-color" Color of lines with Tight/Loose hbox reports. .ie n .IP """vertical\-breakpoint\-color""" 4 .el .IP \f(CWvertical\-breakpoint\-color\fR 4 .IX Item "vertical-breakpoint-color" Color of possible vertical breakpoints. .RE .RS 4 .RE .SS "Brief summary of colors and attributes" .IX Subsection "Brief summary of colors and attributes" .IP "Foreground Color" 4 .IX Item "Foreground Color" \&\f(CW\*(C`black\*(C'\fR, \f(CW\*(C`red\*(C'\fR, \f(CW\*(C`green\*(C'\fR, \f(CW\*(C`yellow\*(C'\fR, \&\f(CW\*(C`blue\*(C'\fR, \f(CW\*(C`magenta\*(C'\fR, \f(CW\*(C`cyan\*(C'\fR, \f(CW\*(C`white\*(C'\fR, .Sp Prefix with \f(CW\*(C`bright_\*(C'\fR for high-intensity or bold foreground. .IP "Foreground Grey" 4 .IX Item "Foreground Grey" \&\f(CW\*(C`grey0\*(C'\fR, ..., \f(CW\*(C`grey23\*(C'\fR .IP "Background Color" 4 .IX Item "Background Color" \&\f(CW\*(C`on_black\*(C'\fR, \f(CW\*(C`on_red\*(C'\fR, \f(CW\*(C`on_green\*(C'\fR, \f(CW\*(C`on_yellow\*(C'\fR, \&\f(CW\*(C`on_blue\*(C'\fR, \f(CW\*(C`on_magenta\*(C'\fR, \f(CW\*(C`on_cyan\*(C'\fR, \f(CW\*(C`on_white\*(C'\fR .Sp Replace \f(CW\*(C`on_\*(C'\fR with \f(CW\*(C`on_bright_\*(C'\fR for high-intensity or bold background. .IP "Background Grey" 4 .IX Item "Background Grey" \&\f(CW\*(C`on_grey0\*(C'\fR, ..., \f(CW\*(C`on_grey23\*(C'\fR .IP "Text Attribute" 4 .IX Item "Text Attribute" \&\f(CW\*(C`bold\*(C'\fR, \f(CW\*(C`dark\*(C'\fR, \f(CW\*(C`italic\*(C'\fR, \f(CW\*(C`underline\*(C'\fR, \f(CW\*(C`reverse\*(C'\fR .SS "Some Common Encodings" .IX Subsection "Some Common Encodings" The following list shows some encodings that are suitable for option\ \fB\-\-encoding\fR. .IP "Latin\-1, Western European" 4 .IX Item "Latin-1, Western European" \&\f(CW\*(C`iso\-8859\-1\*(C'\fR, \f(CW\*(C`cp850\*(C'\fR, \f(CW\*(C`cp860\*(C'\fR, \f(CW\*(C`cp1252\*(C'\fR .IP "Latin\-2, Central European" 4 .IX Item "Latin-2, Central European" \&\f(CW\*(C`iso\-8859\-2\*(C'\fR, \f(CW\*(C`cp852\*(C'\fR, \f(CW\*(C`cp1250\*(C'\fR .IP "Latin\-3, South European (Esperanto, Maltese)" 4 .IX Item "Latin-3, South European (Esperanto, Maltese)" \&\f(CW\*(C`iso\-8859\-3\*(C'\fR .IP "Latin\-4, North European (Baltics)" 4 .IX Item "Latin-4, North European (Baltics)" \&\f(CW\*(C`iso\-8859\-4\*(C'\fR .IP Cyrillics 4 .IX Item "Cyrillics" \&\f(CW\*(C`iso\-8859\-5\*(C'\fR, \f(CW\*(C`cp855\*(C'\fR, \f(CW\*(C`cp866\*(C'\fR (Ukrainian), \f(CW\*(C`cp1251\*(C'\fR .IP Arabic 4 .IX Item "Arabic" \&\f(CW\*(C`iso\-8859\-6\*(C'\fR, \f(CW\*(C`cp864\*(C'\fR, \f(CW\*(C`cp1006\*(C'\fR (Farsi), \f(CW\*(C`cp1256\*(C'\fR .IP Greek 4 .IX Item "Greek" \&\f(CW\*(C`iso\-8859\-7\*(C'\fR, \f(CW\*(C`cp737\*(C'\fR, \f(CW\*(C`cp1253\*(C'\fR .IP Hebrew 4 .IX Item "Hebrew" \&\f(CW\*(C`iso\-8859\-8\*(C'\fR, \f(CW\*(C`cp862\*(C'\fR, \f(CW\*(C`cp1255\*(C'\fR .IP Turkish 4 .IX Item "Turkish" \&\f(CW\*(C`iso\-8859\-9\*(C'\fR, \f(CW\*(C`cp857\*(C'\fR, \f(CW\*(C`cp1254\*(C'\fR .IP Nordic 4 .IX Item "Nordic" \&\f(CW\*(C`iso\-8859\-10\*(C'\fR, \f(CW\*(C`cp865\*(C'\fR, \f(CW\*(C`cp861\*(C'\fR (Icelandic) .IP Thai 4 .IX Item "Thai" \&\f(CW\*(C`iso\-8859\-11\*(C'\fR, \f(CW\*(C`cp874\*(C'\fR .IP Baltic 4 .IX Item "Baltic" \&\f(CW\*(C`iso\-8859\-13\*(C'\fR, \f(CW\*(C`cp775\*(C'\fR, \f(CW\*(C`cp1257\*(C'\fR .IP Celtic 4 .IX Item "Celtic" \&\f(CW\*(C`iso\-8859\-14\*(C'\fR .IP "Latin\-9 (sometimes called Latin0)" 4 .IX Item "Latin-9 (sometimes called Latin0)" \&\f(CW\*(C`iso\-8859\-15\*(C'\fR .IP Latin\-10 4 .IX Item "Latin-10" \&\f(CW\*(C`iso\-8859\-16\*(C'\fR .SH "EXIT STATUS" .IX Header "EXIT STATUS" The exit status is 0 if at least one \fIID\fR matched \fIREGEXP\fR, 1 if no \fIID\fR matched \fIREGEXP\fR, and 2 if an error occurred. .SH CAVEATS .IX Header "CAVEATS" The end tag \f(CW\*(C`\*(C'\fR sometimes gets placed too early in the output and the trace \&\fIseems\fR truncated. However, LaTeX reliably logs the requested the trace information, but the write operations for trace data and the code which is used to print the end\ tag are not synchronized. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBgrep\fR(1), \fBprintf\fR(3), \fBEncode::Supported\fR(pm), \fBTerm::ANSIColor\fR(pm)