Chapter 6
Parameters resp. Settings

This section describes the parameters of both the ant-task and the maven-plugin. There are also general aspects, treated in Section 6.1. As this software mainly acts by invoking other converter and checker, most parameters refer to commands and options for invocations, but there are also parameters which cannot be associated to an individual invocation. Parameters referring to the conversion process or to checking as a whole are collected in Section 6.2. A special case is Section 6.3 which collects the parameters for goals vrs and inj. All the other sections refer to one or more converters.

The parameters are listed in Tables 6.1 through 6.13 with names, default values and short explanations. Note that neither of the parameters is mandatory, as there are always valid default values.

Each of the tables is described in a separate section, only the tables 6.8 and 6.9 for pythontex and for depythontex, respectively, are collected in the single Section 5.5.

Table 6.1 shows parameters controlling the general conversion process described in detail in Section 6.2. These are directories with names xxxDirectory and further parameters not following a naming convention. The other tables show parameters after a certain naming scheme: Command names have the form xxxCommand and the parameter with the according options have the form xxxOptions. Here xxx represents a certain converter. This is one of

• The converter of fig-files into mixed latex- and PDF-files.

• The converter of gnuplot-files into mixed latex- and PDF-files.

• The converter of MetaPost-files into mixed latex- and PDF-files.

• The converter of latex-files into PDF-files.

• The creator of a bibliography from an aux-file.

• The makeindex utility creating an index.

• The makeglossaries utility creating a glossary.

• The utility to invoke python and other languages from within LaTeX and to replace the code by its results dynamically.

• The utility to replace code finally after a run of pythontex.

• The converter of latex into HTML and also into ODT, depending on the parameters.

• The converter of latex-files into RTF-files.

• The converter of ODT-files into doc(x)-files.

• The converter of PDF-files into TXT-files.

• A code-checker converting in a sense a LaTeX main file into a log-file containing errors, warnings and further messages.

• A diff tool comparing the PDF file created with an expected PDF file. This is relevant only if a PDF file has been created and if the comparison is activated, which is not true by default.

It is a little more complicated with the parameters in Section 6.10.

The command name and the list of options describes the invocation of the command. This LaTeX builder supervises also the return value frequently and the log file is supervised.

There are some parameters of the form patternXxxYyy, referring to a pattern in the log-file of the converter Xxx indicating an event Yyy which is one of the following:

• indicates that Xxx needs to be rerun.

• indicates that Xxx had an error.

• indicates that Xxx had a warning.

Besides the abovementioned patterns, describing events in log files, there are further patterns. The maybe the most prominent one, patternLatexMainFile, is devoted a separate section, Section 6.2.1. All patterns, i.e. all parameters of the form patternZZZ are interpreted as regular expressions in a variant slightly generalizing the default implementation for java. We owe description and implementation to Florian Ingerl.

Essentially, there are two kinds of parameters: Most are just passed to the converters invoked by this software. The parameters of this software are so that the choice of the converter, i.e. the name of the application can be configured, and also each converter can be almost freely configured.

Parameters not passed to an application, are either really crucial or are included to allow also development of latex files.

6.1 Generalities on parameters

As pointed out in the introduction of this chapter, this software acts mainly by invoking various converters. The converters are grouped in so-called categories. The converters of a category have the same (file-)interface, means read and write the same files and, mostly but not strictly necessarily, have the same options. For each category there is an option xxxCommand, where xxx is the name of the category in lowercase letters¹ . The value of the option is the command to invoke the converter of the category. Also, there is a default converter in each category, and sometimes there is just a single converter possible. For example, lualatex is the default converter in the category latex.

This software knows about converters and registers the ones approved for this software. Among the advantages are, that it is ensured that the converter is really in that category and that this software checks whether a converter used is in the right category, and it checks whether it is installed in an approved version. On the other hand, there are cases, where the user needs to invoke a custom converter. In this case, the command name shall be given in the form

  <categoryCommand>commandName:category</categoryCommand>

to make sure, that the user is really aware that the converter (s)he uses is in the correct category, i.e. has the required interface. Since neither of the registered converters has a : in its name, This form is identified by the occurrence of a colon. Since the categories neither have colons in their names, separation of command name and category is by the last colon occurring. That way, command names may contain colons also.

For most categories of converters, in fact at the time of this writing with a single exception, one can specify command line options, specified in the form

  <categoryOptions></categoryOptions>

In fact, only for diffPdfCommand there is no option at all, and for some converters with more complex options, the options are split over more than one setting, e.g. for converter category fig2dev converting fig-files, there are general settings given by fig2devGenOptions and settings specific for the output language: LaTeX (fig2devPtxOptions) and eps (fig2devPdfEpsOptions. In any case, options are trimmed, i.e. leading and trailing white spaces are removed before being processed. There are cases, where the options as given are not directly passed to the converter but is further processed. In this case, the processing is documented.

6.2 General parameters

This section describes the general parameters given in Table 6.1.

6.2.1 The parameter patternLatexMainFile

Before reading the details given in this section, the user is advised to at least skim through Section 3.1.1 and 3.2 for intuitive understanding.

The regular expression pattern patternLatexMainFile matches exactly the files to be compiled, the so called LaTeX main files, and for LaTeX main files it extracts the following pieces of information, all by named capturing groups which have the form (!<name>pattern) but in the pom < and > must be escaped and so capturing groups take the form (!&lt;name&gt;pattern). The capturing group named docClass extracts the document class from the command \documentclass. If patternLatexMainFile matches, also the capturing group docClass matches, so that for LaTeX main files the document class is always known. All other capturing groups are defined though magic comments. As the document class, they are directives specific to the given file on how to compile it. They override the general settings given in the pom. A magic comment may not match, which means that there is no according specific directive and so the general setting holds.

Whether a capturing group must match or not, the regular expression pattern patternLatexMainFile must contain each of the following named capturing groups, because the software asks for it. Distinguish between the pattern and the matching strings: Whereas in the pattern all groups must be mentioned, a string may match without matching the group. Whereas docClass is mandatory, i.e. the according group matches, the magic comments are all optional, i.e. they need not match any part of the string.

docClass

the document class given by the command \documentclass.

programMagic

the LaTeX engine to be used specifically for the according document. This is intended to be specified only if the required engine for the given document deviates from what is specified globally as setting latex2pdfCommand described in Table 6.4 on page 262.

targetsMagic

the targets to be built. This is intended to be specified only if the targets for the given document deviate from what is specified globally as setting targets and docClassesToTargets, both given in Table 6.1 on page 246.

latexmkMagic, latexmkMagicVal

whether for creating PDF files latexmk shall be used. This is intended to run the build process with latexmk although the global setting latexmkUsage given in Table 6.1 on page 246 may specify direct compilation without latexmk.

The magic comment can take the form % !LMP latexmkMagic=<bool> or % !LMP latexmkMagic which is just short for % !LMP latexmkMagic=true.

chkDiffMagic, chkDiffMagicVal

whether the created PDF file shall be checked against an original ensuring that it is correctly reproduced. This is intended to control a check specific for this file overwriting the general setting chkDiff given in Table 6.13 on page 286.

The magic comment can take the form % !LMP chkDiff=<bool> or % !LMP chkDiff which is just short for % !LMP chkDiff=true.

The default pattern for identifying LaTeX main files and to extract the above pieces of information is given by Listing 6.1.

1\A 
2(%\s*!\s*T[eE]X (TXS|spellcheck|encoding|root).*\R)* 
3(%\s*!\s*T[eE]X program\s*=\s*(?<programMagic>[^} ]+)\R)? 
4(%\s*!\s*T[eE]X .*\R)* 
5(%\s*!\s*LMP (?<chkDiffMagic>chkDiff)(=(?<chkDiffMagicVal>true|false))?\R)? 
6(%\s*!\s*LMP (?<latexmkMagic>latexmk)(=(?<latexmkMagicVal>true|false))?\R)? 
7(%\s*!\s*LMP targets=(?<targetsMagic>(\p{Lower}|,)+)\R)? 
8(\s*( 
9\\RequirePackage\s*(\[(\s|\w|[,=])*\])?\s*\{(\w|-)+\}\s*(\[(\d|[-./])+\])?| 
10\\PassOptionsToPackage\s*\{(\s|\w|[,=])*\}\s*\{(\w|-)+\}| 
11\\newbool\s*\{\w+\}| 
12\\setbool\s*\{\w+\}\{(true|false)\}| 
13\\DocumentMetadata(?<brace>\{(?:[^{}]|(?'brace'))*\})| 
14\\input\s*\{[^{}]*\} 
15)?\s*(%.*)?\R)* 
16\\(documentstyle|documentclass)\s*(\[[^]]*\])?\s*\{(?<docClass>[^} ]+)\}


    
Listing 6.1:
    The
    default
    pattern
    of
    the
    LaTeX
    main
    file
    in
    a
    form
    as
    in
    a
    pom
    configuration

   

Let us trace through line by line:

1

The \A indicates the start of the file.

2–4

These lines match magic comments % !TEX, which are used by other build tools also. Line 3 extracts programMagic from the first magic comment of the form % !TEX program=…. This is the behavior of the other tools also. The other lines are to skip information from magic comments % !TEX which are not needed.

5–7

These lines match magic comments of the form % !LMP… which are specific for this software. Like the above magic comments they are all optional, but their ordering is fixed:

chkDiffMagic

to activate diffing to check reproduction, or in conjunction with chkDiffMagicVal to switch reproduction check.

latexmkMagic

to delegate build to latexmk.

targetsMagic

allows to specify a list of targets. This is the sole of these magic comments not only applying to creating PDF files.

8–11

This defines material which may precede the command \documentclass, except for magic comments and is the only one without magic comments. Besides lines with specific commands, it matches empty lines and comment lines. Also, a line may start with whitespace and may contain a comand and end in a comment. The commands specified there may occur in arbitrary multiplicity and order. This section is likely to be modified by the user.

11

Matches the command \documentclass and extracts docClass.

Between magic comments and \documentclass or \documentstyle only the following material is allowed:

• the command \RequirePackage specifying packages to be loaded before \documentclass, in contrast to \usepackage which is used after,

• the command \PassOptionsToPackage allowing to pass one or more options to a package, although including with \usepackage is without options,

• \newbool and \setbool to define and set a boolean value defining variants (preceeded by \RequirePackage{etoolbox}),

• the command \DocumentMetadata allowing arbitrarily nested braces,

• the command \input, and

• whitespace, empty lines, comment lines even magic comments, although for this tool they are ignored.

This may be too restrictive and here is the point, where the use has freedom to change the pattern. On the other hand, \input offers a quick workaround to add material if a user is not familiar with regular expressions.

In the long run it must be thought of weakening the pattern: It is not necessary, that exactly the correct files are parsed, because incorrect files are detected by the LaTeX engine anyway. Instead, among the correct files the LaTeX main files shall be detected.

As a workaround for very special LaTeX main files, it is a good idea to let it indicate in a magic comment. Then the pattern as a whole must match, even not matching a \documentclass. From the point of view of this software, it makes sense to specify the document type in the magic comment then. Thinking one step further, also specifying the target or the LaTeX engine in a magic comment indicates already a LaTeX main file. Whereas the target set makes the document class superfluous, this is not the case for the magic comment specifying the LaTeX engine.

The LaTeX extension LaTeX workshop for VS Code offers two similar alternatives to identify LaTeX main files: Occurrence of \documentclass without checking preceding material and absence of first line % !TEX root= declaring a TEX file as depending on a LaTeX main file which must be given explicitly. The first alternative risks that a TEX file is recognized as main file, just because it deals with document classes, whereas the second alternative is inconvenient and does not work if a file has two potential LaTeX main files as is suggested for beamer presentations in Section 3.1 and realized in [Rei23a]. Although presence of % !TEX root= indicates that the according file is no LaTeX main file, this software ignores this magic comment.

Emacs with package AUCTeX, uses an alternative to the current technique to determine the LaTeX main files: LaTeX main files are marked with an end section as this file:

%%% Local Variables: 
%%% mode: latex 
%%% TeX-command-extra-options: "-recorder -shell-escape" 
%%% TeX-master: t 
%%% End:

The vital line in this context is %%% TeX-master: t. In contrast to this, a non-master file either has no end-section at all or has an end section declaring the according master file (if it is unique) explicitly as the following one from header.tex:

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "manualLMP"
%%% End:

Unlike the document class to be extracted from \documentclass and unlike other magic comments to be taken into account, those of AUCTeX are at the end of the file.

Although the author considers this approach charming, this software ignores AUCTeX-style magic comments, since otherwise the whole file is to be parsed. Sticking to regular expressions, the parsing engine must then keep the whole file in memory. All this would push down performance.

6.2.2 The parameter patternCreatedFromLatexMain

The files created from a LaTeX main file depend strongly on the compiler options and on packages used in the LaTeX main file and in the TEX-files inputted. The default value ‘^T$T\.[^.]*’ is appropriate for most parameters and packages: Most packages create files with names only which coincide with the name of the LaTeX main file, except the suffix. This is all sufficient even for programs doing post-processing such as bibtex, makeindex, xindy and makeglossaries.

The program splitindex requires in addition ‘^T$T-.+\.(idx|ind|ilg)’.

The utility pythontex requires ‘^T$Tḋepytx(\.tex)?’ and creates a bunch of further files all in a folder of the form ‘pythontex-files-T$T’ which must also be added to the regular expression.

Whereas typically latexmk creates only ‘^T$Tḟdb_latexmk’ which is included in the very first expression, during its run it creates ‘^(pdf|xe|lua)?latex\d+\.fls’, where the digits represent the process number. If interrupting latexmk, these files may remain, so it is appropriate to add them to the regular expression.

Package ‘srcltx’ or also synctex requires in addition ‘^T$T\.synctex(\.gz)?’ depending on the setting synctex=1 or synctex=-1. For long files the synctex may create a busy file ‘^T$T\.synctex\(busy\)?’. Even if the LaTeX process is interrupted regularly, at the end the busy file is erased, but still if interrupted from outside it may remain, so we add also the busy variant to the regular expression. Strictly speaking, ‘^T$T\.synctex(\(busy\))?(\.gz)?’ is not precisely what may occur, but is a good approximation.

The class beamer creates a lot of additional files but finally in addition to what we already have, it needs an additional ^T$T\.run\.xml and at times ^T$T\.\d+\.vrb.

Finally, package ‘tex4ht’ is for all the rest of the cases, created by packages.

The pattern is designed to match quite exactly the created files, not much more and at any case not less. In particular, it has to comprise the files matching pattern $patternT4htOutputFiles. Nevertheless, since any new package may break the pattern, and not every package is well documented, this pattern cannot be guaranteed to be final.

If the current default value is not appropriate, please overwrite it in the configuration and notify the developer of this plugin of the deficiency.

The default value for this pattern is currently:

^(
T$T                      (\.([^.]*|
                             synctex(\(busy\))?(\.gz)?|
                             out\.ps|run\.xml|\d+\.vrb|
                             depytx(\.tex)?)|
    (-|ch|se|su|ap|li)?\d+\.x?html?|
                      \d+x\.x?bb|
                     \d+x?\.png|
                      -\d+\.svg|
                       -.+\.(idx|ind|ilg))|
      pythontex-files-T$T|
      zzT$T\.e?ps|
      (cmsy)\d+(-c)?-\d+c?\.png|
      (pdf|xe|lua)?latex\d+\.fls)$

6.3 Parameters for goals vrs and inj

This section describes the parameters for the goals vrs and inj given in Table 6.2. As illustrated in Listing 2.4 of the part of the pom referring to this plugin, in general parameters are configured in a settings element contained in a general configuration element. In contrast to this, the parameters for the goals vrs and inj are given in configurations within executions specific for these goals.

6.4 Parameters for graphical preprocessing

This section describes the parameters for graphical preprocessing given in Table 6.3.

TODO: do this.

6.4.1 The parameter metapostOptions

The options of the (sole standalone) metapost compiler are given in the metapost manual [Hob24], Appendix B.2.1. The current default option line for this software is as follows:

The details are as follows:

-interaction=nonstopmode

To avoid user interaction in case of an error This seems mandatory.

-recorder

Strictly speaking not necessary at the current stage, but for later versions of this software, to allow dependencies tracking.

-s prologues=2

In general the -s assigns an internal key a value. Here it is the kind of the prologue. The value 2 is a compromise between safe quality of output and length of artifact. As described in detail in [Hob24], Section 8.2, a value of 0 is sufficient for PDF output. Also, if no LaTeX is used to typeset labels, the prologue value is irrelevant. The value 1 is deprecated, 2 yields a prologue only slightly longer than with 0, whereas the safest setting 3 yields a huge prologue. So the compromise is 2 and if 3 is needed in individual cases, this setting can be overwritten in the MP file.

outputtemplate="%j.mps"

determines the name of the output file. The default given here uses the “jobname” and the canonical ending. Unlike the default value of mpost, no number of the figure within the metapost file is given. This comes from the fact that we assume a single figure only and ignore the number of the figure.

6.4.2 The parameter svg2devOptions

The following options are mandatory:

–export-area-drawing

Export the drawing (not the page).

–export-latex

Export into PDF/PS/EPS format without text. Besides the PDF/PS/EPS files, a LaTeX-file latexfile.tex is exported, putting the text on top of the PDF/PS/EPS file, i.e. including the according pure graphic file. Include the result in LaTeX as: \input{latexfile.tex}.

Note that the latter option is necessary, to create the expected files. It is also conceivable to export text as pdf/eps

The following options are prohibited, because they are automatically added by the software or interfers with:

–export-filename=FILENAME

Export document to a file with type given by the extension. This is used both to export into PDF and into EPS format. The extension is always given explicitly.

–export-type=TYPE

Overwrites the type given by –export-filename. If no extension is given, this is to determine the export type.

6.5 Parameters for the LaTeX-to-pdf Conversion

This section describes the parameters of the LaTeX engine which are given in Table 6.4.

TODO: do this.

6.5.1 The parameter latex2pdfOptions

An overview over the options supported by the usual latex engines in distribution TeX Live is given in [Rei23b], Section 2. In particular, there is a table with the options occurring in any LaTeX engine and columns indicating for each option for which engines it is valid. Note that unlike the other engines, lualatex defines options starting with --, it works on according options starting with single dash also. To support all engines with the same parameters, the default options are among the ones common to all supported engines. Currently, default option line is as follows:

The details are as follows:

-interaction=nonstopmode

To avoid user interaction in case of an error This seems mandatory.

-synctex=1

to create .synctex.gz files needed for interaction between editor and viewer.

-recorder

Strictly speaking not necessary at the current stage, but for later versions of this software, to allows tracking dependencies.

-shell-escape

allows the TEX engine to access the shell to execute. This is needed for some reason for driver dvipdfmx which seems to be the sole one supporting PDF-pictures in DVI-mode and PDF-pictures in PDF-mode.

An alternative would be -shell-restricted. CAUTION: In MiKTeX this is –enable-write18 instead.

Note that part of the default values is mandatory, in particular nonstopmode, but there are also options which are not allowed. In most of the cases, the problem is that the latex engine does not create an output or does not create it in the expected location or in the expected form. This may apply to the main artifact, i.e. PDF or DVI or XDV, but it may also apply to log files and other files.

The following list of prohibited options is illustrative but not complete:

-draftmode

switch on draft mode (generates no output PDF which causes an error)

-output-directory=dir

to specify the output directory

-aux-directory=dir

to specify the auxiliary output directory

-job-name=name

effectively changes the output file name

-quiet

makes the log quiet and so circumvents error and warning detection

-fmt=FMTNAME

use FMTNAME instead of program name or a %& line

–luaonly

run a lua file, then exit

-output-format=FORMAT

use FORMAT for job output; FORMAT is ‘dvi’ or ‘pdf’ pdf is the only allowed …. This is not supported by xelatex.

-no-pdf

generate XDV (extended DVI) output rather than PDF. This is specific for xelatex.

-progname=STRING

set program (and fmt) name to STRING only names also without -progname are possible

-help

display this help and exit

-version

output version information and exit

Note that the default value of $patternErrLatex excludes option -file-line-error-style and its synonym –file-line-error-style. Nevertheless, these options can be used if the pattern $patternErrLatex is adapted.

Also option -halt-on-error is not strictly forbidden, but not recommended, because it prevents operation as intended for this software.

Two options deserve particular notification, both specifying the output format:

-no-pdf

which is specific to xelatex, makes xelatex create XDV files which currently cannot be further processed by this software. As soon as this software supports XDV files, this option is set by this software, not by the user.

-output-format=FORMAT

, which this software uses to set the output format, either to dvi or to pdf. Strictly speaking, this option is supported by all engines, except for xelatex. For xelatex, this software only supports pdf, which xelatex creates because -no-pdf is not given. The option -output-format=pdf does no harm, because it is ignored. As soon as this software supports XDV creation, it will no longer pass -output-format to xelatex.

In general, there are two forms of options, one starting with double dash, --, and the other form with single dash. In TeX Live, pdflatex and xelatex use single dash, whereas lualatex uses double dash according to the help text. But using the single dash always is ok, because lualatex understands single dash also.

In MiKTeX, all options of all engines are double dash. It must be clarified, whether they understand single dash. If not one has to clarify whether in TeX Live all engines understand double dash. If so all must be changed into double dash.

6.5.2 The parameter patternWarnLatex

The patterns given below are just by (unwritten) convention. As a consequence, the pattern has a comprehensive default value covering all warnings known to the author, while not detecting a warning, where there is none. To that end, the pattern requires that the warning text starts with the line of the log file. Still the pattern has to be configurable to allow the user to overwrite the default value not being forced to wait for the developer to change it.

For the current default value, we distinguish

• LaTeX-warnings emitted directly by LaTeX starting with LaTeX Warning: ,

• LaTeX-font-warnings related with fonts/font selection starting with LaTeX Font Warning: ,

• Package warnings emitted by a package. By convention, a package emitting a warning identifies itself by its name <name> emitting a warning starting with Package <name> Warning: ,

• Class warnings emitted by a package. By convention, a class emitting a warning identifies itself by its name <name> emitting a warning starting with Class <name> Warning: ,

• pdfTeX-warning starting with pdfTeX warning and being specific for the compiler pdflatex,

• Warnings on inclusion of a PDF file, e.g. inclusion of PDF files with incompatible version, starting with warning (file <filename>) (pdf inclusion),

• Font specification warnings starting with * fontspec warning² ,

• Further warnings not identifying themselves as warnings as the word “warning” does not occur. Still they are treated as warning because they all indicate some imperfection in the output.

The resulting default pattern is

^(LaTeX Warning: | 
LaTeX Font Warning: | 
(Package|Class) .+ Warning: | 
pdfTeX warning( \((\d|\w)+\))?: | 
\* fontspec warning: | 
Non-PDF special ignored!| 
Missing character: There is no .* in font .*!$| 
A space is missing\. (No warning)\.)

6.5.3 The parameter patternReRunLatex

TODO: rework based on comments in class Settings.

For the package rerunfilecheck an analysis of the code is possible, and the warnings emitted by this package indicating the need for rerun are taken into account for the pattern.

Besides this package, also other packages may require rerun, but these are not analyzes systematically. A first step would be to analyze those given in header.tex created by injection.

As a consequence, the pattern has a comprehensive default value covering all warnings known to the author, while not detecting a warning, where there is none. To that end, the pattern requires that the warning text starts with the line of the log file. Still the pattern has to be configurable to allow the user to overwrite the default value not being forced to wait for the developer to change it.

The resulting default pattern is

^(LaTeX Warning: Label\(s\) may have changed\. Rerun to get cross-references right\.$| 
Package \w+ Warning: .*Rerun( .*|\.)$| 
Package rerunfilecheck Info: Checksums for | 
Package \w+ Warning: .*$^\(\w+\) .*Rerun( .*|\.)$| 
LaTeX Warning: Etaremune labels have changed\.$| 
\(rerunfilecheck\)                Rerun to get outlines right$| 
\(rerunfilecheck\)                Rerun LaTeX)

There is one Info message in there, also indicating the need for rerun. This is inserted because another rerun warning may fail to apply because it contains the file name and if this is too long, then the required sequence “Rerun.” is cut off and is not on the current line.

Still what is good, if such a warning is not recognized as a pattern indicating the need for rerun, it occurs in the final LOG file and is recognized as a warning. So it is merely impossible to get a result with not enough reruns and without warning.

FIXME: There is a bug in this pattern. See Section 9.

6.6 Parameters for creation of the bibliography

This section describes the parameters or creation of the bibliography which are given in Table 6.5.

TODO: do this.

6.7 Parameters for creation of the indices

This section describes the parameters or creation of the indices which are given in Table 6.6.

TODO: do this.

6.8 Parameters for creation of the Glossary

This section describes the parameters or creation of the glossary which are given in Table 6.7.

TODO: do this.

Table 6.7:  The MakeGlossaries-utility

Parameter	Default
Explanation
makeGlossariesCommand	makeglossaries
The MakeGlossaries command to create a gls-file from a glo-file (invoked without file ending) also taking ist-file or xdy-file into account logging on a glg-file.
makeGlossariesOptions	the empty string
The options for the $makeGlossariesCommand. These are the options for ‘makeindex’ (not for $makeIndexCommand) and for ‘xindy’ (also hardcoded). The aux-file decides on whether program is executed and consequently which options are used. The default value is the empty option string. Nevertheless, ‘xindy’ is invoked as ‘xindy -L english -I xindy -M…’. With option ‘-L german’, this is added. Options ‘-M<’ for ‘xindy’ ‘-s’ for ‘makeindex’ and ‘-t’ and ‘-o’ for both, ‘xindy’ and ‘makeindex’.
patternErrMakeGlossaries	(^\*\*\* unable to execute: )
The pattern is applied line-wise to the ‘glg’-file and matching indicates that $makeGlossariesCommand failed. The default value ‘( unable to execute: )’ is chosen according to the makeindex documentation. If the default value is not appropriate, please modify and notify the developer of this plugin.
patternErrXindy	(^ERROR: )
The pattern in the glg-file which indicates an error when running ‘xindy’ via $makeGlossariesCommand. If the default value is not appropriate, please modify and notify the developer of this plugin.
patternWarnXindy	(^WARNING: )
The pattern is applied line-wise to the ‘glg’-file and matching indicates a warning when running ‘xindy’ via $makeGlossariesCommand. The default value ‘(^WARNING: )’ (note the space and the brackets) is chosen according to the ’xindy’ documentation. If the current default value is not appropriate, please overwrite it in the configuration and notify the developer of this plugin of the deficiency.
patternReRunMakeGlossaries
This parameter is deprecated since version 2.1. Rerun check of auxiliary programs do not read the LOG file. Details of the present algorithm are described in Section 5.6. The pattern is applied line-wise to the log file and matching triggers rerunning $makeGlossariesCommand followed by $latex2pdfCommand. This pattern only matches a warning emitted by the package ‘rerunfilecheck’ e.g. used with option ‘glossary’. The default value is chosen according to the package documentation.

6.9 Parameters for including code via pythontex

This section describes the parameters for invoking pythontex and parameters for invoking depythontex which are given in Table 6.8 and in Table 6.9, respectively.

The pattern patternErrPyTex is by default

\*_PythonTeX_error|...

substituting the dots by

(PythonTeX:__.+_-|____-_Current:_)_[1-9][0-9]*_error\(s\),_[0-9]+_warning\(s\)

Accordingly, the pattern textttpatternWarnPyTex is by default

(PythonTeX:__.+_-|____-_Current:_)_[0-9]+_error\\(s\),_[1-9][0-9]*_warning\(s\)

6.10 Parameters for conversion LaTeX to HTML

This section describes the parameters of the LaTeX-to-html converter which are given in Table 6.10.

6.10.1 The parameter patternT4htOutputFiles

The default value has the following components:

• ‘^T$T\.x?html?$’ is the main output file.

• ‘^T$Tli\d+\.x?html?$’ are lists: toc, lof, lot, indices, glossaries, NOT the bibliography.

• ’^T$T(ch|se|su|ap)\d+\.x?html?$’ are chapters, sections and subsections or below and appendices.

• ‘^T$T\d+\.x?html?$’ are footnotes.

• ‘^T$T\.css$’ are cascaded stylesheets.

• ‘^T$T-\d+\.svg$’ and ‘^T$T\d+x\.png$’ are svg/png-files representing figures.

• ‘^T$T\d+x\.x?bb’ are the bounding boxes (suffix .bb for dvipdfm and suffix .xbb for dvipdfmx).

• ‘^(cmsy)\d+(-c)?-\d+c?\.png$’ represents special symbols.

Note that the patterns for the html-files can be summarized as

^T$T((ch|se|su|ap|li)?\d+)?\.x?html?\$

This altogether constitutes the default value for this pattern:

^(T$T(((ch|se|su|ap|li)?\d+)?\.x?html?|
\.css|
\d+x\.x?bb|
\d+x\.png|
-\d+\.svg)|
(cmsy)\d+(-c)?-\d+c?\.png)$

The pattern is designed to match quite exactly the files to be copied to $targetSiteDirectory, for the goal “html”, not much more and at any case not less. since $tex2htCommand is not well documented, and still subject to development, this pattern cannot be guaranteed to be final.

6.11 Parameters for further conversions

This section describes the parameters of the converter from and to further formats which are given in Table 6.11.

These converters convert latex into RTF directly, they convert ODT into doc-like documents and pdf into pure text. A special case is the code-checker in a sense converting latex into a log-file. For each of them, the name of the command can be specified and also the options. Since neither of them, except the code checker, write a log-file, there are no further parameters necessary.

FIXME: Note that pdftotext -h prints a usage message. This is a way to obtain not the specified output. It shows that pdftotext -q does not print any messages or errors. This indicates that pdftotext normally does display error messages on the standard output. These may be led to a log file to indicate errors and warnings. Here, further research is required.

The option -htmlmeta seems not approprate. The option resolution -r seems sensible only in conjunction with the crop area defined by -x and -y which does not make sense in our context. The same holds for specification of the first and the last page via -f and -l. What does make sense is specifying the encoding via -enc with possible values given by pdftotext -listenc. What makes sense most is UTF-8.

6.12 Parameters for the code checker chktex

Among the applications used by this software, the codechecker plays a special role: it is not really a converter, unless we interprete the log file as artifact. Like for the most converters also for the codechecker we can specify the command ant its options, both given in Table 6.12.

The options of chktex are described in detail in [Thi22], Section 6.1.2.

Here is a list of options useful in this context. The first group of these are muting options:

• ’-w’, ’-e’, ’-m’, Make the message number passed as parameter a warning/an error/a message and turns it on. Messages are not counted.

• ’-n’ Turns the warning/error number passed as a parameter off.

• ’-L’ Turns off suppression of messages on a per line basis.

The next group of interesting options are for output control:

• Shuts up about copyright information.

• Specifies the output file. This is added automatically and shall thus not be specified by the user.

• If you use the -o switch, and the named output-file exists, it will be renamed to ‘filename.bak’ for option -b1 and not for -b0.

• Specifies the format of the output via a format similar to “printf()’. For details consult the manual [Thi22], Section 6.1.2. The codes are listed below.

• Verbosity level followed by a number ‘d’ specifying the format of the output according to the listing below. The verbosity number is resolved as a pattern as if given by the option ‘-f format’. Thus the option ‘-v’ is ignored if the option ‘-f format’ is specified.

The default value -q -b0 avoids verbose output and backing up the output log-file.

Code

• String to print between fields (from -s option).

• Column position of error.

• Length of error (digit).

• Current file-name.

• Turn on inverse printing mode.

• Turn off inverse printing mode.

• kind of error (warning, error, message).

• line number of error.

• Warning message.

• Warning number.

• An underlining line (like the one which appears when using ’-v1’).

• Part of line in front of error (’S’-1).

• Part of line which contains error (string).

• Part of line after error (’S’+1).

FIXME: to be inserted. See [Thi22], Section 6.1.6. From chktexrc:

OutFormat
{
# -v0; silent mode
%f%b%l%b%c%b%n%b%m!n

# -v1; normal mode
"%k %n in %f line %l: %m!n%r%s%t!n%u!n"

# -v2; fancy mode
"%k %n in %f line %l: %m!n%r%i%s%I%t!n!n"

# -v3; lacheck mode
"!"%f!", line %l: %m!n"

# -v4; verbose lacheck mode
"!"%f!", line %l: %m!n%r%s%t!n%u!n"

# -v5; no line number, ease auto-test
"%k %n in %f: %m!n%r%s%t!n%u!n"

# -v6; emacs compilation mode
"!"%f!", line %l.%c:(#%n) %m!n"
}

Note that “!” is to escape quotes and newline. More than these can be added to chktexrc.

This document is checked with options deviating from the default value:

-q -b0 -v1 -g0 -l ${basedir}/src/site/tex/chktexrc

The default is -q -b0, option -g0 means that the global chktexrc is not used and option

-l ${basedir}/src/site/tex/chktexrc

specifies a record file tailored to the needs of this project. In particular, the pattern for -v1 is slightly modified: It is

# -v1; normal mode
"%k %n in %f line %l: %m!n %r%s%t!n %u!n"

which adds a blank to all lines but the headlines. That way, the kind of issue (%k) is easily parsed. This could be used for emitting an error instead of a warning when processing goal check.

Although the return code of chktex is not documented, a bit of reverse engineering shows the following distinction:

1. Successful execution and found neither an error nor a warning.

2. Execution as such did not succeed, e.g. because of an invalid option like -exx.

3. An error occurred and in particular execution as such suceeded.

4. A warning occurred but no error and in particular execution as such suceeded.

On this behavior this software bases its failure messages.

The options of chktex are described in detail in [Thi22], Section 6.1.2.

6.13 Parameters for ensuring reproducibility

For a general description of the reproducibility check see Section 5.8. Here we go into the details and identify the parameters controlling the check and specified in great detail in Table 6.13. As already mentioned in Section 5.8, currently, checks are performed for artifacts in pdf format only; more formally, if the target (which is in parameter target described in Table 6.1) is pdf.

But if so, the parameter chkDiff decides whether a check is performed at all. Note that checking is off by default. Then a diffing tool given by diffPdfCommand expects the blueprints in the directory diffDirectory. In contrast, the actual artifacts to be checked are in outputDirectory, whereas the sources are in texSrcDirectory.

The location of a source tex file relative to texSrcDirectory is the location of the artifact relative to outputDirectory. This path relative to diffDirectory is the location of the blueprint. With the actual artifact in outputDirectory and the blueprint in diffDirectory the diff-tool determines whether the both are equivalent. If so, equivalence is logged as an info, else an exception described in Table 7.7 is thrown.

Note that the choiced of the diff tool diffPdfCommand determines the notion of equivalence of the pdf artifacts, ranging from byte equivalence to some kind of visual equivalence.

6.14 Parameters for latexmk and related

As described in Section 5.9, based on the parameter $latexmkUsage described in Table 6.1 on page 246, the build process can be delegated gradually to latexmk or an equivalent tool. Table 6.14 lists the parameters controlling invocation. Note that besides the options, which shall be used with care, also the config file .latexmkrc goes into. The details concerning the config file are described in [Col23], Section “CONFIGURATION/INITIALIZATION (RC) FILES”. On the other hand, as indicated in [Col23], Section “DEALING WITH ERRORS, PROBLEMS, ETC”, latexmk does not write its own log file and so there is no parameter in Table 6.14 for a pattern of warnings or errors.