3 Usage of Plugin and Task

This software offers both, a maven plugin and an according ant task, but the emphasis is on the maven plugin. Thus, the sections of this chapter are either general or apply to the maven plugin; only Section 3.8 specifically refers to the ant task. Usage presupposes installation as described in Chapter 2 including settings in pom.xml as described in Section 2.2 for the maven plugin and the settings in build.xml as described in Section 2.3 for the ant task.

This plugin may be used both if the LaTeX-sources are ready to create “final” output from them and also to support development of the LaTeX sources. Accordingly, this chapter has Section 3.1 devoted to the form of the sources, including directory structure, LaTeX-files and others, mainly graphic files included and a Section 3.2 on exporting into various formats.

There is a very special usage, called development of documents, which means while the document is under construction. The features and goals tied to this phase are collected in Section 3.6.

In contrast, Section 3.7 is on usage of the maven plugin within the lifecycles. This can be used during development of documents but is more appropriate for small changes or when development finished at a stage.

3.1 The source files and their directories

Source files are files contributing to creating documentation from LaTeX-files in the build process which are not themselves created in the build process. They are searched in the TeX source directory and subdirectories recursively. By default, this is ./src/site/tex, where “.” is the base directory of this maven/ant-project. This structure complies with conventions in maven-projects.

Note that, against the convention of maven-projects, the TeX source directory may contain also files created during the build process. By default, after the build process is finished, they are removed again. For some background on this see Section 3.1.3.

Source files may be TEX files treated in Section 3.1.1 and various kinds of graphic files described in Section 3.1.2, but may include also

3.1.1 gls:lmf and other latex files

The TEX files are special in that only part of them is processed explicitly invoking a compiler like lualatex on them, part is just included via \input or \include. The LaTeX-files to be compiled top level, are called LaTeX main files. As an example, in the TEX source directory of this software, manualLMP.tex is a LaTeX main file, whereas the file header.tex is not, although also a LaTeX-file: it is intended to be input in another TEX file, in this case manualLMP.tex.

LaTeX main files are detected automatically by fitting the regular expression patternLatexMainFile described in detail in Table 6.1 on page 246, and in the reference given there, whereas the description here is quite high level.

As a first approximation, a LaTeX main file is one invoking the command \documentclass or the outdated \documentstyle, both specifying the document class. It must be excluded that the pattern matches a textual occurrence of \documentclass, which just occurs because the document is on LaTeX and mentions the command \documentclass. This is quite easy, since there is little allowed in TEX files preceding these commands.

Consequently, the pattern matches the region from the start of the file to and including the \documentclass or \documentstyle command. This starting segment of a LaTeX main file is called the opening.

Here a word of warning is at place: if a TEX file does not fit the pattern, it is not interpreted as a LaTeX main file without further warning. So check whether the file under consideration is processed if

If you distrust the recognition mechanism via pattern matching altogether, you can explicitly specify each LaTeX main file in the parameter mainFilesIncluded described in Table 6.1 on page 246. This is safe because if a file specified in mainFilesIncluded that like is not a LaTeX main file according to the pattern patternLatexMainFile, a warning is emitted. That way one can check whether the pattern is matched. We could have decided that these files are compiled with or without warning, but this would lead to a technique is that it is inconvenient and not well maintainable.

On openings neglecting (magic) comments

This section contains material both specific for supported document classes and general information but magic comments are deferred to Section 3.1.1.0.

Note that scrlttr2 replaces the built-in letter which is not recommended. In fact, is the only KOMA class this software is tested for. The attentive reader may realize that the built-in document class report is not mentioned. It shall work but is currently not tested.

Nevertheless, the pattern patternLatexMainFile matches all possible document classes. Typically, the document class is loaded with options. The most frequent class may be article followed by report and book. For these, we suggest something like

where a4paper is a setting, typical for Europe or, not the US. The default font size is 10pt and sometimes it makes sense to increase this. For documents which are solely in English no language setting is required, except if loading the package babel, else the hyphenation patterns get lost. Since we recommend inputting the header file header.tex described in Section 3.5.2 which in turn loads babel and by the way also csquotes, a language setting is mandatory. It is possible specifying the language when loading babel as an option like so \usepackage[english]{babel}, but it is recommended to specify the language as an option of the document class, in order to make it available for various packages, besides babel also for csquotes. If a document has more than one language, specify all of them, the last the one the document starts with, but [BB24] Sections 1.7 and 1.8 show how to change language, here temporarily into German, which requires specifying german in front of english in the document class. Note the quotes and the correct hyphenation in the following paragraph.

To obtain correct quotes in the above paragraph, package csquotes must be loaded with option autostyle. Since csquotes is loaded in header.tex given by an injection as described in Section 3.5, this option must be passed to csquotes before loading the document class, e.g. via

For documents of class minimal there are no requirements imposed. No checks and no PDF-info. For all other document classes, it is recommended to load nag before \documentclass by

Thus the pattern patternLatexMainFile allows \RequirePackage with its options preceding \documentclass.

There are cases, where one and the same document comes in two flavors both of which must be built. As an example, consider a document with a confidential variant and with a non-confidential variant. To define these, the declaration of the document class must be preceded by the following kind of code:

The new thing is defining and setting a boolean via \newbool and \setbool, respectively. It is a good idea to set a watermark via

The same technique differentiating between confidential and public may be used to define a lecture with and without solution or any other kind of variant.

Documents of class leaflet resemble articles, except special options like notumble.

The same is true for letters of type scrlttr2, except for the special specification of font size and versioning of the class:

Observe that after inputting header.tex which loads geometry, various pseudo lengths have to be re-adjusted. This is done by loading the letter option. Without it may happen, that the text does not reach until the bottom of the frame.

What is special for beamer presentations is, that in general two documents with the same identifier, e.g. title are created, the proper presentation, e.g.

both including the same piece of code which is included from file useBeamer.tex. The author recommends to stick to this convention. As an example document may serve [Rei23a] which is a presentation of this software including the handout and illustrates the use of the beamer class. Observe, that both documents use header.tex injected as described in Section 3.5.2 loading various packages. The beamer class is special in that it loads the hyperref package itself. To avoid option clash with header.tex, for document class beamer option destlabel must be passed to the package. Maybe it is a matter of taste, but beamer tends to make links invisible. To force loading options specifying colors for links and destlabel, use \PassOptionsToPackage as shown above.

All documents but beamer documents must specify the paper size globally via \documentclass. Beamer documents may specify accordingly aspectratio. All this must be allowed for LaTeX main files.

Magic comments

It also makes sense to allow comments also in openings, i.e. text from unescaped % to the end of the line, and also magic comments. A magic comment, as all comments, is ignored by the LaTeX compilers but give hints to more high level tools like IDEs or build tools like this LaTeX builder. It is the mechanism to treat a document in a specific way so magic comments override the general settings.

Typically, a magic comment comprises a whole line and starts with % !, maybe followed by an identifier of the tool it refers to or by an identifier referring to TEX files in general. For example latex workshop and TeXshop support the magic comment % !TEX root and this must be essentially in the first line. The magic comments specific for this tool may be preceded by general magic comments and start with % !LMP which is short for “latex maven plugin”. This is not fully correct but easy to remember.

This LaTeX builder is designed to cooperate with other tools. The magic comments of the other tools as described in various places in Section 3.6 on document development and in particular in Section 3.6.2. Thus, if appropriate, also magic comments of other tools are read, except those of AUCTeX, because AUCTeX places magic comments at the end of file, forcing this software to read all the file if it accessed AUCTeX magic comments also. All other tools including latex workshop for VS Code support a subset of what is defined by TeXstudio. From all magic comments in the context of signifying LaTeX main files only program and root are relevant. If a root is given, then the file is no LaTeX main file and, provided the feature is used, also the converse is true. Since this software shall not rely on further tooling, it does not use root. All in all, among the general magic comments only % !TEX program=… is read. It can occur more than once, but the first occurrence is what counts; the others are ignored silently. Note that the magic comment % !TEX program=… overrides the setting latex2pdfCommand for creating PDF files and related, specified in Table 6.4 on page 262, but not the tex4htCommand from Table 6.10 on page 274.

After the general magic comments of the form % !TEX … come the ones specific for this LaTeX builder. They take the form % !LMP …. Like the general magic comments, the specific ones are all optional, but in contrast, they come in a fixed order without repetition.

Section 6.2.1 describes the meaning of the individual comments in the course of explaining the pattern patternLatexMainFile. Note that there the names of the magic comments is given, whereas the above listing refers to the content, but it is easy to identify the according magic comments. The relation of the magic comments is described in the following.

The magic comments may come only in the ordering given in the above listing, but each of them is optional. They can be freely combined, but note that chkDiff and latexmkMagic apply to creation and check PDF files only. So, for targets=pdf,html, these magic comments apply to target pdf, but not to html. For targets=chk,html it even takes no effect at all without issuing a warning. As explained above, program affects only the targets pdf and dvi including also XDV files.

Note that documents of the classes beamer, leaflet and scrlttr2 can essentially only be compiled into a PDF, and maybe further to a TXT file. In addition, to targets and goals pdf and txt, it can be checked with target or goal chk. Other targets are skipped, and a message is displayed. The relations are configurable through settings targets and docClassesToTargets both in Table 6.1 on page 246. Also, if a document class occurs, which is not registered in docClassesToTargets, a warning WLP09 described in Table 7.10 on page 308 is displayed.

3.1.2 Source graphic files

The great bulk of file types occurring as sources, are graphic files in various formats. Note that this section is not about intermediate file types like PDF or MPS used to include the original file types into the target.

As regards the way the according files are included in LaTeX-files, there are the following kinds of graphic formats, all included in the TEX source directory.

3.1.3 Created files in the TeX source directory

Note that against maven convention and unlike former versions of this software, the current version does not create a working directory by cloning the TEX source directory. Instead, it operates directly on the TEX source directory also creating intermediate files, deleting them again by default after the build process. The advantage of processing that way is, that this allows cooperation between this software and other tool chains which are better suited for developing latex files. Details are described in Section 3.6 an in particular in Section 3.6.2.

The downside is that a file residing in the TEX source directory risks being overwritten or deleted by this software, if it does not stick to the rules. The rules are simple:

Note Section 3.5 which is on goal inj injecting diles in the TeX source directory and Section 3.6.4 on goal grp processing graphic files which creates intermediate files therein also.

To get rid of intermediate files, there is a separate goal clr described in Section 3.6.5.

3.2 Exporting in various formats and checking sources

After having added the configuration of the plugin to the pom.xml, minimally the one given in Listing 2.2, it can be used directly invoking maven through mvn latex:cfg. Here latex is the (short) name of the plugin and cfg is the goal. It can also be interpreted as mvn <source>:<targets>: The source files are in latex-format and the targets are read from the configuration in the pom (configuration is what cfg stands for) which is illustrated in Listing 2.3. For a detailed description of the setting targets see Table 6.1 on page 246. Here only an overview is given.

By default, the targets configured are chk, pdf and html. The following Listing 3.1 shows a configuration with the full range of output formats including in addition the OpenOffice document format odt, the MS word-formats doc(x) and rtf and also plain text format txt in utf8 encoding.

Note that the target docx converts by default into docx but may also be configured to produce the old-fashioned doc format.

Be aware that the target dvi creates output in DVI format only for LaTeX engines lualatex and pdflatex, whereas xelatex creates the XDV (extended DVI) format for target dvi.

<!-- create html and pdf and other formats from latex --> 
<plugin> 
  <groupId>eu.simuline.m2latex/groupId> 
  <artifactId>latex-maven-plugin</artifactId> 
  <version>2.1</version> 
 
  <configuration> 
    <settings> 
      <targets>chk,pdf,dvi,html,odt,docx,rtf,txt</targets> 
    </settings> 
  </configuration> 
</plugin>

Listing 3.1: Configuration with full range output formats

Somehow special is the target chk which is mere checking by invoking chktex without resulting output file. It just displays a warning if a rule is violated.

The resulting files in the given output formats are copied to the site directory, which is ./target/site in a default maven project.

Sometimes it is more convenient to specify the output formats not via the pom but directly as a goal on the command line. In particular, one may write mvn latex:pdf to create documentation in PDF-format only. Likewise, command mvn latex:dvi to get good old dvi/xdv files or even mvn latex:txt for plain text, just as examples. Accordingly, mvn latex:chk performs a pure check. This occurs preferably in the context of documentation development. In particular, checking is treated separately in Section 3.6.3.

Note that the -X switch activates debugging which results in a more verbose output. Example: mvn -X latex:cfg.

Although the possible targets can be configured globally via the setting targets, the possible targets may depend on the document class of the LaTeX main file. At time of this writing, all document classes in preferred usage as defined in Chapter 10 support all targets with obvious exceptions: Besides checking (target chk) for obvious reasons the classes beamer, leaflet and the letter class scrlttr2 directly support only target pdf and because texts are created from PDF files, also target txt. The mapping from document classes to allowed targets is given in setting docClassesToTargets given in Table 6.1 on page 246. This parameter restricts the targets given in parameter targets. As explained in detail in Section 3.1.1.0, if a document class cannot be identified by the command documentclass or the outdated documentstyle, it can be specified by a magic comment directly.

Finally, the targets can be specified individually for each LaTeX main file using a magic comment as described in Section 3.1.1.0. A target specification in a magic comment overwrites all settings in targets and in docClassesToTargets. If a magic comment specifies the targets directly, the document class need not be known. In particular, a magic comment only specifying targets identifies already a LaTeX main file as specified in Section 3.1.1.0.

As a magic comment can be used to specify the target formats for a LaTeX main file individually, Section 3.1.1.0 shows how to specify the LaTeX engine to be used for this file overwriting the general setting latex2pdfCommand in the pom given in Table 6.4 on page 262.

In a standard maven project, the above minimal configuration should be sufficient. Only if the folder structure deviates from the standard or if the LaTeX sources require special configuration, parameters have to be given explicitly, because they deviate from the default values. Chapter 6 summarizes all available parameters, giving the default value and a description.

For sake of uniformity, the name of the ant-task is latex:cfg, and it can be invoked via ant latex:cfg. Unlike the maven-plugin, the ant-task does not allow to specify a target on the command line. The -d switch activates debugging which results in a more verbose output. Example: ant -d latex:cfg.

Whereas by default the target directory and in particular the target site directory with all output of this plugin is deleted in maven’s clean life-cycle, the tools invoked by this software also create intermediate files in the source directory. By default, i.e. for setting <cleanUp>true</cleanUp>, all files created in the source directory in the last run are cleaned. Nevertheless, for document development intermediate files are vital and so cleanup is frequently set to false. In this case, cleanup must be done in a separate goal, described in Section 3.6.5.

3.3 Checking versions of converters

displays something like what is displayed in Listing 3.2. Besides information on this software including version and even git commits, there are information on so-called registered converters, i.e. converters intended to be invoked by this software.

The goal yields a full list of registered converters, signifying which of them are excluded according to parameter convertersExcluded, which are not installed, and for each of the rest, the actual version, the allowed range and a warning if the actual version is out of range.

The parameter convertersExcluded is described in Table 6.1 on page 246. Excluded converters are prevented from being used: if tried, Exception TSS07 described in Table 7.4 on page 302 is thrown. If a converter is not installed, but tired to be used, this kind of failure is obvious. Only if a converter is used with an unintended version bears some risk. Note that also unregistered converters can be used; but then the user is responsible to provide an appropriate version. An example for an unregistered converter is given in Table 6.8 on page 272: pythontexW:pythontex indicating the converter pythontexW with category pythontex.

As one can see, a warning WMI02 indicates that the version of a converter is out of the intended range, provided, the converter is installed, and it is not excluded according to the configuration convertersExcluded.

Note that in the given version and in the installation of the author, of course, all converters are installed and are up-to-date to be able to check validity. The according messages are forced for illustration only. For a user of this software which does no development, of course only converters need to be installed which are really needed.

[INFO] --- latex:2.0-SNAPSHOT:vrs (default-cli) @ latex-maven-plugin --- 
[INFO] Manifest properties: 
[INFO] MANIFEST: (1.0) 
[INFO]         Implementation-Version: '2.0-SNAPSHOT' 
[INFO] PackageImplementation-Version: '2.0-SNAPSHOT' 
[INFO] pom properties: 
[INFO] coordinate.groupId:    'eu.simuline.m2latex' 
[INFO] coordinate.artifactId: 'latex-maven-plugin' 
[INFO] coordinate.version:    '2.0-SNAPSHOT' 
[INFO] git properties: 
[INFO] build version:  '2.0-SNAPSHOT' 
[INFO] commit id desc: 'latex-maven-plugin-1.8-209-g5ac27b7-dirty' 
[INFO] buildTime:      '2023-06-25T23:31:20+0200' 
[INFO] tool versions: 
[INFO] ?warn?    command              'actual version'(not)in[expected version interval] 
[INFO]            mvn:                  '3.9.4'in[3.9.1;3.9.4] 
[INFO]            ant:                  '1.10.14'in[1.10.12;1.10.14] 
[INFO]            java:                 '17.0.9'in[17.0.9] 
[INFO]            python:              '3.11.6'in[3.11.6] 
[INFO]            perl:                 '5.38.2'in[5.38.2] 
[INFO]            pdflatex:            '1.40.25'in[1.40.21;1.40.25] 
[INFO]            lualatex:            '1.17.0'in[1.12.0;1.17.0] 
[INFO]            xelatex:             '0.999995'in[0.999992;0.999995] 
[INFO]            latex2rtf:           '2.3.18 r1267'in[2.3.16 r1254;2.3.18 r1267] 
[INFO]            odt2doc:             '0.9.0'in[0.9.0] 
[INFO]            pdftotext:           '23.11.0'in[21.04.0;23.11.0] 
[INFO]            dvips:                '2023.1'in[2020.1;2023.1] 
[INFO]            dvipdfm:             '20220710'in[20210318;20220710] 
[INFO]            dvipdfmx:            '20220710'in[20200315;20220710] 
[INFO]            xdvipdfmx:           '20220710'in[20200315;20220710] 
[INFO]            dvipdft:             '20090604.0046'in[20090604.0046] 
[INFO]            gs:                   '9.56.1'in[9.52.0;9.56.1] 
[INFO]            chktex:              '1.7.8'in[1.7.8] 
[INFO]            diff-pdf-visually:  '1.7.0'in[1.6.4;1.7.0] 
[INFO]            diff-pdf:            '300'in[300] 
[INFO]            diff:                 '3.10'in[3.8;3.10] 
[INFO]            pdfinfo:             '23.11.0'in[22.01.0;23.11.0] 
[INFO]            exiftool:            '12.71'in[12.39;12.71] 
[INFO]            bibtex:              '0.99d'in[0.99d] 
[INFO]            bibtexu:             '4.00'in[4.00;4.00] 
[INFO]            bibtex8:             '4.00'in[4.00;4.00] 
[WARNING] WMI02: makeindex:           '2.17'not in[2.15;2.16] 
[INFO]            splitindex:          '0.1'in[0.1] 
[INFO]            makeglossaries:     '4.51'in[4.45;4.51] 
[INFO]            pythontex:           '0.18'in[0.17;0.18] 
[INFO]            depythontex:         '0.18'in[0.17;0.18] 
[INFO]            mpost:                '2.02'in[2.00;2.02] 
[INFO]            ebb:                  '20220710'in[20200315;20220710] 
[INFO]            gnuplot:             '5.4 patchlevel 10'in[5.4 patchlevel 0;5.4 patchlevel 10] 
[INFO]            inkscape:            '1.3.2'in[1.0.2;1.3.2] 
[INFO]            fig2dev:             '3.2.9'in[3.2.7b;3.2.9] 
[INFO] tools excluded: 
[INFO] upmendex, xindy 
[INFO] tools not found: 
[INFO] latexmk 
[INFO] ------------------------------------------------------------------------

Listing 3.2: Output of goal latex:vrs

3.4 Logging of errors and warnings

It is a design goal to notify the user of formal deficiencies of the created documents by tight logging of errors and warnings to give high confidence in the formal quality of the result in the absence of errors and warnings. Logging is devoted all of Chapter 7. Of particular intestest is Table 7.8 on failures running a tool on page 306. We highlight

3.5 Injection of files

The goal inj is to inject files into the working directory texSrcDirectory, by default in maven lifecycle phase valiate or from command line in the root directory. The injected files are in general adapted to the current configuration of the plugin.

Note that each of these files is written only if it is guaranteed that only files written by this plugin are overwritten. This is the case, if no file is overwritten at all or if the file to be overwritten is recognized to start with a comment indicating that this file is written by this plugin. Of course the guarantee holds only if the headline does not tell a lie.

If the headline cannot be read or in some other exotic conditions, it cannot be ensured that the files are written by this software, and so they are not overwritten by goal inj and by the way not erased by goal clr as described in Section 3.6.5. In case of such a doubt, a warning is displayed.

That way, injected files written by the plugin can be updated each run, which is necessary to keep them synchronized with the configuration of this plugin, but according files written e.g. by the user are protected.

which yields a list of files which can be injected. Note the distinction between the injection, which is the act of injecting and the according file which is injected.

The set of injections can be divided into the following categories according to the function of the files injected:

Table 3.1 shows the possible injections and the ones really to be performed are given in the configuration injections. This configuration is described in Section 6.3 on page 254. It is a comma separated list and the default is latexmkrc,chktexrc, representing the configuration files.

Table 3.1: Overview over all injections

Name	File	explanation




configuration files

latexmkrc	.latexmkrc	config file for latexmk
chktexrc	.chktexrc	config file for chktex

header files

header	header.tex	fundamental
headerGrp	headerGrp.tex	for graphics
headerSuppressMetaPDF	headerSuppressMetaPDF.tex	to control PDF meta-info

shell scripts

vscodeExt	instVScode4tex.sh	installs VS Code extensions
ntlatex	ntlatex	timeless LaTeX compiler
vmdiff	vmdiff	special diff tool for PDF files
pythontexW	pythontexW	surrogate for pythontex
depythontexW	depythontexW	surrogate for depythontex

As described in Section 2.2.3, by default the goal inj is tied to the maven phase validate, an early phase preparing the proper build process, because the injected files are a prerequisite for building. Then the files are injected in the TEX root directory texSrcDirectory.

On the other hand, injections can be also invoked by command line via mvn latex:inj with the default injections or, with given list of injections, e.g.

In fact, injection from command line is typically used for scripts, whereas the others files are injected during the build process in phase validate. Of course maven is invoked from the project root and there also the prescribed files are injected.

Note that the folder where cleanup of injections with mvn clean is done, depends also on whether -Dlatex.injections=… is specified, but the value is irrelevant as long as it is valid.

In the sequel, all these injections are described in detail separately, but in fact they are all related. For example, header.tex handles the possible configurations reflected in .latexmkrc. It provides packages used in headerGrp.tex and provides commands to exclude checking by chktex controlled by .chktexrc. The header header.tex is very crucial for example controlling and guaranteeing rerun of the LaTeX engine by including package rerunfilecheck. Its presence makes the results uniform and is a cornerstone for quality guarantees. As said above, the default for injections is latexmkrc,chktexrc, but it is advisable to use latexmkrc,chktexrc,header.

3.5.1 The configuration files .latexmkrc and .chktexrc

For document development the tool latexmk is a valuable build tool. Also, a linter like chktex is helpful both for end control and for document development.

The file .latexmkrc tied to the injection latexmkrc is the configuration file for the build tool latexmk and likewise .chktexrc tied to the injection chktexrc is the configuration file for the style check tool chktex. The configuration files determine the behavior of the two tools without further options. The user is kindly asked to help to improve these files, in particular .chktexrc.

Ideally, the injected .latexmkrc is adapted to the current settings of this plugin and so invoking latexmk invoked with its configuration file behaves like this latex plugin. Currently, not all possible settings of this plugin are taken into account in the .latexmkrc, but the magic comments in the source files described in Section 3.1.1.0 are read and taken into account as far as this makes sense.

For default settings, maybe partially overwritten by magic comments, this maven plugin and latexmk create the same target files. This is true even for this manual. In particular, the graphic formats described in Chapter 4 are supported. So are bibliographies, indices and glossaries and also material computed by pythontex as described in Chapter 5, but without reflecting all options and patters to supervise log files. Also, reproducibility check is supported including magic comments and all parameters.

At time of this writing, .latexmkrc works for various LaTeX generators but supports target pdf only, although in the long run also chk and dvi could be useful. Still, creation of PDF files is supported in both variants, via DVI/XDV or directly. Compilation via latexmk is based on code in .latexmkrc and this mimics a wide range of functionality offered by this tool. Among these also build for reproducibility checks as described in Section 5.8

A sensible config file .chktexrc mainly depends on the packages loaded. In Section 3.5.2 we suggest injecting also a header file header.tex loading packages. The config file .chktexrc is adapted to the header file header.tex.

Observe, that due to an incompatibility between tool latexmk and package listings, this manual can only be compiled with latexmk if listings is not only loaded but also patched as done by header.tex and described in Section 3.5.2. With that patch, this software yields the same resulting PDF file as compilation with latexmk.

Currently, .chktexrc serves only to suppress warnings, mainly on material which is the argument of commands or the content of an environment. What is really needed depends on the packages loaded and on the commands and environments defined in addition.

Since basic packages are loaded and basic commands are defined in the injected header.tex which is described in Section 3.5.2, it makes sense, to synchronize .chktex and header.tex. As an example, header.tex loads package listings which provides the environment lstlisting and the command \listinputlisting. The content of both shall not be subject to checks via chktex and must thus be excluded in .chktexrc.

All this together illustrates why it is recommended to inject besides the default .chktexrc and .latexmkrc also header.tex.

As described in Sections 3.6.2 and 3.6.3, both tools chktex and latexmk are invoked directly by the user in the course of document development, but they may be invoked by this LaTeX builder in the course of a regular build, i.e. for maven goal cfg also. So their respective configuration files must be injected in the maven build process before the LaTeX build tools are invoked, i.e. prior to the phase site. Thus, goal inj has default phase validate.

As described in [Col23], Section “CONFIGURATION/INITIALIZATION (RC) FILES”, there are various configuration files latexmkrc or .latexmkrc, among these a global one, a local one referring to the enclosing folder, and finally one specified by the command line option -r which is described in [Col23], Section “LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE”.

Likewise, [Thi22], Section 6.1.3, shows that also chktexrc has a global configuration file chktexrc and a local one .chktexrc or chktexrc, depending on the operating system. Finally, a configuration file can be specified with the option -l, according to [Thi22], Section 6.1.1. Unfortunately, [Thi22] does not tell about the ordering in which the configuration file given by the option -l is read in.

For sake of reproducibility, we recommend restricting to the global configuration file which is tied to the installation and to a local file, specific to the latex source directory which shall be valid for all LaTeX main files in that directory.

Goal inj injects the configuration files .latexmkrc, .chktexrc and further files, all in the latex source directory. It is natural to use each as the local configuration file.

Caution: According to [Thi22], Section 6.1.3, as described, the local configuration file fits only for UNIX-like operating systems. For Windows and that like, chktexrc is expected instead of .chktexrc. Uniformity with respect to the operating systems can be realized with a link to chktexrc named .chktexrc. That way independent of the operating system, the configuration files .latexmkrc and .chktexrc are sufficient.

It is important that there is a unique central configuration file applying to all LaTeX main files. There is the choice between at least two mechanisms to ensure this: Either latexmk and chktex are invoked with options -r and -l, respectively, specifying the configuration file explicitly or for each folder containing a LaTeX main file there must be a link named .latexmkrc and .chktexrc, respectively, to the according central configuration file.

We recommend using links because then latexmk and chktex can be used on the command line without further options. This is convenient for the user when invoking the tools directly which is the typical usage for document development.

3.5.2 A generic header file header.tex

It is observed that the headers of various LaTeX files are quite similar. In particular the packages loaded have a huge overlap and at the same time, although rare, exotic packages tend to be loaded which may be replaced by standard ones. This hurts single source principle and at the same times makes it almost impossible for a build tool as this one, to make guarantees that it works still with the unexpected packages. This is, e.g. because a package may write warnings in an unexpected format into some log file.

The injection header is tied to the file header.tex, which is intended to be included in each LaTeX main file. Essentially it includes packages always needed. It is inspired by the packages pandoc includes by default according to https://pandoc.org/MANUAL.html#creating-a-pdf.

Some loaded packages are also patched. The patch for package listings is given in Listing 3.3. It applies only if listings is loaded prior input of header.tex. One modification is, redefinition of \lstlistoflistings to make the list of listings occur in the table of contents and to rename the title so that it fits other lists as the list of figures. The other point is modifying listings’ output to make it digestible for latexmk. For details see Section 3.6.2.

The other package patched is luamplib; the patch is given in Listing 3.4. It applies only if luamplib is loaded prior input of header.tex. As discussed in Section 4.5, luamplib is available for lualatex only. It provides an environment mplibcode to enclose literal MetaPost. The enhancement is an additional command \inputmpcode which allows including MetaPost files. This functionality is analogous to package listings which allows both literal listings and loading listings from files. MetaPost code within a LaTeX document typically disturbs syntax highlighting of both, enclosing code and included code.

Besides loading packages it also sets synctex which is crucial for synchronizing TEX files and according PDF files via forward search and backward search as described in Section 3.6.1.

It also provides the command \setMinorVersionPdf to set the minor version of the PDF file created. This is mostly needed because some graphic tool creates PDF files with a newer PDF version than the LaTeX distribution does. Setting the version high enough, avoids an according warning WAP03 listed in Table 7.8 on page 306. The warning pattern is described in Section 6.5.2 in detail. As described in [MF23], Section 2 the recommended way to set major and minor version of the PDF output like in \DocumentMetadata{pdfversion=1.7}, but due to a bug, any invocation of \DocumentMetadata corrupts reproducibility of the created PDFs. After this is fixed, the \setMinorVersionPdf shall be removed again.

Another class of commands provided is represented by \textttNoChk which sets the argument in typewriter font just like \texttt but for which checks by chktex are suppressed. Another example for this kind of command is \inputNoChk which may be used to input either generated material like TikZ, or text which is no LaTeX at all. For details see Sections 3.5.1 and 3.6.3.

As the configuration files described above, header.tex is intended to be injected in phase validate.

Which packages are loaded at all and if loaded their options, depend on the LaTeX compiler, the output/intermediate format, the document class, packages loaded before and maybe on other criteria.

This is realized with a bunch of if-constructs. In the long run, header.tex could be adapted to the configuration as .latexmkrc, but currently it detects the use case as the LaTeX engine or the target format and loads the according packages. It is also conceivable to create different headers, one for each document class.

3.5.3 A header file for graphics via package graphicx

Chapter 4 lists various techniques to include graphics into a LaTeX document. Most are based on the package graphicx and related packages. The injection headerGrp is tied to the file headerGrp.tex, which is intended to be included in the LaTeX main file after header.tex described in Section 3.5.2 and which loads the packages required for that kind of graphics by need and with the appropriate options, depending on the LaTeX compiler, the output/intermediate format, packages loaded before and maybe on other criteria.

3.5.4 A header file to suppress meta-info for PDF files

Whereas the header file described in Section 3.5.2 is intended to be used in merely any LaTeX main file, the one described here, is optional.

It refers to created PDF files only and does not influence the optical appearance but suppresses writing certain meta-data. The main motivation is security, i.e. privacy, but it can also be used to turn the resulting PDF reproducible.

The injection headerSuppressMetaPDF is tied to headerSuppressMetaPDF.tex. Above all, it suppresses information on creation and modification time, on the tool chain used and the trailer identifier. By intention the latter changes in each build run even if the sources are the same. Typically, this is implemented merging the current time into the build process. The trailer identifier is fixed by the header file and so created PDF files created from the same sources are the same, except if date and time are included manually, as e.g. by the command \today, except for xelatex, which uses the system time to create further hash codes. So, including headerSuppressMetaPDF.tex may serve to create reproducible PDF files. As described in Section 5.8, the mainstream technique to reach reproducibility is via manipulating the system time, but if an environment does not support this, including headerSuppressMetaPDF.tex is a fallback strategy, if not using xelatex.

The extent to which meta info is suppressed is inspired by reproducibility but above all, it is subjective. It is planned to make it configurable, i.e. the file headerSuppressMetaPDF.tex is created according to security settings of this maven plugin.

For further information on meta info in PDF files related with security and reproducibility see [Rei23b], Section 4 and how this software treats the handles the issues see Section 5.8.

3.5.5 An installation script for VS Code Extensions

If the editor VS Code is already installed, the script instVScode4tex.sh, installs and updates all extensions of VS Code the author used to write LaTeX-code. Project https://github.com/Reissner/QMngMnt uses the script for automation of installation and update. It is the only injected file which is executable.

Pasting .latexmkrc, which is just Perl code, into VS Code, one can see the highlighting, of course provided the extensions given by instVScode4tex.sh are installed; The configuration file .latexmkrc for the development tool latexmk is in fact a Perl script.

3.5.6 Scripts in conjunction with reproducibility

The injection ntlatex injects the file ntlatex which runs the LaTeX compiler specified in the pom, or in the magic comments if present, to create a PDF file. As usual, magic comments override configuration in the pom. Also, it takes into account whether the PDF file is created via intermediate DVI/XDV files or not, depending on the configuration.

This invocation takes also processing time and the timezone into account to guarantee reproducibility if so configured. As latexmk is, also ntlatex shall be independent of the configuration given by the pom. This is realized in the same way, namely by encoding the configuration in the injection .latexmkrc. The downside is, that ntlatex like latexmk requires Perl to work. For details see Section 5.8 on reproducibility.

But if ntlatex so close to latexmk, why is it needed in addition? It is because latexmk won’t recompile, if the expected PDF file exist already and no sources changed. So ntlatex is needed to force recompilation.

Complementary to this vmdiff is a diff tool for PDF files combining visual equality checked with diff-pdf-visually with equality of metadata checked via pdfinfo if the files are visually the same. It is realized as a bash script vmdiff and requires no installation except diff-pdf-visually and pdfinfo.

3.5.7 Script (de)pythontexW patching (de)pythontex

injects the according files pythontexW and depythontexW which just invokes (de)pythontex but does not simply output feedback on stdout but besides doing so writes it in a log file. This is needed to provide an interface usual in the TeX ecosystem.

Note that all this is specific for unix -like operating systems but can be easily adapted to windows.

3.6 Development of documents

The term “development of documents” is coined by the author and reflects that writing a document resembles developing software in that it is an iterative process consisting in producing pieces of information, checking, modifying, correcting, erasing it, checking again…. After initial creation, is like a dialog between the author and its work.

This is true of course independent of the tools used, but some tools support this process better than others. For document development the ideal are WYSIWYG (“what you see is what you get”) editors, which should maybe be better called WYRIWYR (“what you write is what you read”), or, taking also drawings into account, IllO (“input looks like output”). For software development the ideal languages are prototyping languages, interpreted at least.

The situation is visualized in Figure 3.1. It is no UML diagram although using elements of UML. The developer of the document (it may or may not be the author) is visualized as a stick figure and the tools used for development are the boxes surrounding it, resembling instances in a UML class diagram. Besides the tool under consideration, the according files are shown. The console is to invoke conversion commands like lualatex. This shows already, that the user does not face a single counterpart, but has to juggle with a bunch of tools at once. The arrows represent data flows. If this data comprises commands the lines are solid, else they are dashed.

At first sight, this LaTeX-builder is not to contribute to document development, because it is used after the end of the development process, automating the compilation process. Since the LaTeX-builder is also a checker tool, supervising even warnings, e.g. on bad boxes, and by default invoking chktex and monitoring its log file, and since compilation may always fail, the LaTeX-builder may initiate another loop in the development process.

Before describing the contribution of this LaTeX-builder to the process of document development, let us describe the process of document development in more detail, in particular the other tools supporting document development and their interaction. With this background in mind, it is easier to describe the role of the LaTeX-builder in the team of development tools.

The minimum needed to develop a document in LaTeX are an editor, an according viewer and the LaTeX tools for build and check as described in Section 3.6.1. As described above, using this basic tools directly distracts much of the attention of the author/developer from the content. Thus, it is a good idea to use a tool to orchestrate the LaTeX tools. The author of this software prefers the orchestration tool latexmk which is described in Section 3.6.2.

The check tool chktex and the according goal chk are already described in Section 3.2. Nevertheless, the aspects of checking in the context of document development is treated separately in Section 3.6.3.

The goals grp and clr described in Sections 3.6.4 and 3.6.5 make sense only in the context of document development. For details see these sections.

Finally, Section 3.6.6 is on installing extensions for document development on the editor VS Code. To that end, this software provides an installation script.

3.6.1 Editors, viewers and LaTeX

Although there are alternatives like Emacs with extension AUCTeX, the author recommends using VS Code in conjunction with extensions to write and build LaTeX documents and to view the results on okular. The recommended extensions are those installed by the script instVScode4tex.sh described in Section 3.6.6.

Most of the recommended extensions of VS Code are to highlight the code of the various file types, one, LTeX is a spell and grammar checker, but the central extension is james-yu.latex-workshop which also provides build functionality. Among the build “recipies” is latexmk (latexmkrc) which is recommended because it integrates well with build tool latexmk described in Section 3.6.2 in a way which integrates latexmk well with this LaTeX builder. Note that LaTeX Workshop also offers a command “clean up”, corresponding with goal clr of this software which is described in more detail in Section 3.6.5

As a PDF viewer, we use okular with settings given by the menu “settings” and submenu “configure okular”. To make okular update as soon as the PDF changes, in tab General

To enable backward search described below, in tab Editor choose “custom editor” and type

Together the “general” settings make okular update automatically when a new PDF occurs.

As an HTML viewer any of the usual browsers is usable; they all update as soon as the rendered HMTL file changes.

Still it is a problem to synchronize editor and viewer. As far as the author knows, synchronization is possible only for PDF viewers. Synchronization means at least that for a position on the editor, the according position on the viewer must easily be found and vice versa. Even better would be if moving in the editor selects the according site at the viewer and the other way round. These two features are called forward search and backward search, respectively. If the LaTeX main file has a setting synchtex=1 or synchtex=-1, then the created PDF has the according information. Then for VS Code with LaTeX Workshop offers forward search: the keystroke ctrl-alt-j makes the viewer move to the site corresponding with the cursor position. For the viewer okular, backward search is configured in tab “editor” as described above, and it works with the browse tool just hovering over the location of interest and pressing shift plus mouse left key.

This software supports forward and backward search in that it offers injection of a header file header.tex which sets synchtex=1 and offers injection of an installation script instVScode4tex.sh which allows installation of the relevant extensions of VS Code.

Besides the separation of editor and viewer, the time delay between writing and reading disturbs document development. LaTeX has a way to speed up compilation: compiling only parts of a longer document which are under construction and which may thus change. These parts must be in separate TEX files and must be included with \include not just input using \input. With the command \includeonly one can specify the files to be recompiled. This works particularly well for document class book when including chapters because each chapter starts with a new page, so, page breaks are the same whether compiling a chapter with \includeonly or compiling the whole document.

This plugin supports partial compilation insofar as the goal clr described in Section 3.6.5 eliminates additional AUX files tied to included sections.

3.6.2 The build tool latexmk

Essentially, it is possible to compile latex files only with editor, viewer and a console. Let us collect the challenges. The document may contain graphic files which must be precompiled by further tools which must be invoked a priori on the console. For FIG files this is fig2dev. This invocation must be repeated as soon as a FIG file changes³ .

Then a LaTeX engine like lualatex must be invoked. Typically, the LaTeX engine must be invoked more than once and besides the LaTeX engine some further auxiliary programs like makeindex must be run. The console displays indications to the user what action to be taken next. Normally after invocation of an auxiliary program, the LaTeX engine must be rerun at least once. Each of the programs may fail. Most of the programs write success messages and more detailed information containing error messages, warnings or just information messages on the console and in their respective log files. Potentially, these influence the actions the user must take next.

What is needed, is a tool for orchestration of the basic tools: Orchestration means invoking more basic tools in a reasonable order and supervising the results, at least success and to react appropriately. This frees the user from deciding which of the many auxiliary programs are to be invoked next and whether the LaTeX engine is to be invoked once more to get final correct output. Also, an orchestration tool detects if a build fails or ideally even if a warning indicates that the result is not correct or maybe only not ideal.

There is a tool doing this work, latexmk, except that it does not care about warnings.

If something goes wrong, and it is not clear what, it is typically a good idea to fall back to the more basic tools. A great point with latexmk is, that this is possible without any problem, and it is as simple to switch back from basic tools to latexmk. This is what we mean saying that latexmk integrates the basic tools.

According to [Col23], Section “DESCRIPTION”, the option -pvc is shorthand for “preview continuously”, a kind of nonstop mode: The PDF file, or whatsoever is created, then a viewer is opened in the background if not yet open and then latexmk monitors changes of dependencies and triggers a rebuild each time a change is detected performing a proper sequence of invocations of LaTeX engines and auxiliary tools. Note that latexmk does not stop after finishing a compilation, whether successful or not. Instead, it awaits a change of a source file which triggers a new run of some basic tool until interrupted by the user. The option -pvc is described in more detail in [Col23], Section “LATEXMK OPTIONS AND ARGUMENTS ON COMMAND LINE”. One detail to be added, mentioned in [Col23], Section “DESCRIPTION”, is, that latexmk detects dependencies based on the FLS file written by the LaTeX engine when invoked with the -recorder option.

A small fallback step advisable if something goes wrong is to interrupt continuous viewing and to invoke latexmk without options. Then latexmk performs a single build and finishes; no viewer is opened. This may help in understanding the problem, but in general, it is advisable to go back to basic tools like lualatex. To understand the build process from scratch, erase all created files by latexmk -C or all intermediate files by latexmk -c, which does not erase the resulting PDF file, before using the basic tools.

Differences of latexmk with this LaTeX builder

Let us discuss the differences between latexmk and this latex plugin: First, the plugin runs within a maven process which introduces a lot of overhead. So this cannot be as fast as latexmk is. In addition, a maven plugin cannot open a viewer. Moreover, the plugin is designed to build all LaTeX main files and not to focus on a single one. In many cases, more than one output format shall be created. The latter properties which are disadvantages in the context of document development, can be overcome, by specifying a single target in the setting targets or by invoking goals with a single target, e.g. by mvn latex:pdf and to restrict to building a subset of files and if needed a single LaTeX main file with the settings mainFilesExcluded or mainFilesIncluded described in Table 6.1 on page 246.

Another difference is, that by default, the plugin cleans up the folder with the TEX sources, and only the resulting file, e.g. PDF is copied to the target folder before cleanup. To be more precise, only the files present before the build are kept, possibly updated, all the others are removed. This is appropriate for a maven plugin but destroys log files containing vital information if the build goes wrong. Still if a file is interesting it may be created by touch or by some basic latex tool as lualatex or makeindex and then a build done by this plugin will pertain the file updated by the build process. For document development, the parameter cleanUp, also described in Table 6.1, which is true by default, can be set to false so that no file in the latex directory is deleted.

So, it is clear that this plugin is for final global build with a lot of supervision sensitive to detecting caveats. To overcome these, further development of the document is necessary, which is better done individually on the problematic document with latexmk. In a sense latexmk is the fallback to this maven plugin as much as lualatex is the fallback to latexmk.

To make this work, this plugin must integrate latexmk as latexmk integrates lualatex. This is guaranteed, if this plugin can write a config file .latexmkrc which causes latexmk to behave like this plugin. This is exactly what injection of .latexmkrc is intended to do according to Section 3.5.1. Note that this feature is just offered, but the user may also use his/her own file .latexmkrc.

Based on injection of .latexmkrc, this plugin may even use latexmk as a means to build bypassing its internal build rules. For motivation of this feature and for details in implementation see Section 5.9.

There is a difference in the build processes (except if this plugin uses latexmk) concerning mostly graphic files: latexmk detects dependencies via the -recorder option of the latex generator and creates or recreated what is new or changed. This is more elegant than the idea of this plugin which is creates a fixed set of graphic files first and is from that point on based on detecting hard coded set of files and tracing log files. In other words, latexmk has no graphic preprocessing as Chapter 4 describes for this build tool. This offers the advantage, that latexmk never creates graphic files which are later not needed for inclusion. Nevertheless, to deal with graphic files which are to be created in the course of the build, latexmk runs the LaTeX engine in nonstopmode mode. Still, the run of the engine is interrupted, a single graphic file is created according to some rule and then the engine is rerun. For a document with 10 graphic files to be created in the course of the build, for latexmk only the 10th runs of the LaTeX engine is completed. In contrast, this plugin requires a single run, so performance is significantly better. The use of \IfFileExists is not really elegant but prevents latexmk from frequent reruns and in some cases is a technique to make the build process with latexmk work. One of these cases, related with using listings is discussed below in this section.

More general, there are cases, where this latex builder succeeds but latexmk does not. As this latex builder may invoke latexmk either in general or for selected files, this latex builder is mightier than latexmk. If both approaches succeed, the results shall be the same for this plugin and for latexmk.

cleans like latexmk -C and in validate invokes goal inj injecting .latexmkrc to configure latexmk and maybe header.tex necessary to compile the latex files at all. Finally, goal grp creates the graphic files which speeds up latexmk. Of course the above maven invocation is also a good initialization for building with the basic tools without latexmk.

Finally, goal clr tied to phase clean erases all intermediate files and thus makes the next build independent of the previous one.

For further reading on goal grp creating graphics files see Section 3.6.4, Section 3.5 is on file injection and goal clr to clear created files is described in Section 3.6.5.

How latexmk is integrated

Finally, we show how this plugin may support latexmk where. To understand in which sense, one must dive very deep. In short, injection of a header patches package listings in a way that saves performance of latexmk. Let us elaborate.

This software and latexmk follow a different philosophy in finding dependencies: Whereas this software creates image files in advance before invoking a LaTeX engine, latexmk first calls the LaTeX engine in nonstopmode to avoid a stop because of a missing file. Then the file is created using the appropriate rule (hopefully unique) and the emgome is run again, this time passing the inclusion of the first created files failing at the next one. To find out that another rule is needed, latexmk parses the LOG file of the latex compiler. As the packages write log messages in their own style, this is the point where the solution is no longer generic and so it is no wonder that there is at least one kind of inclusion which does not work that way: inclusion with \lstinputlisting provided by listings. In fact, the author has an email from J. Hoffmann, author of listings telling that there are more packages with the same problem. To be checked: fancyvrb and moreverb. Nevertheless, all other ways of inclusion used by this manual like the one with \import seem to work fine.

The current workaround for the second problem is by patching listings as described in Section 3.5.2.

The suggested workaround for the first problem is creating graphic files using goal grp as described in Section 3.6.4 before invoking latexmk.

Another point is, that currently for each file latexmk creates with a separate rule, another run of the LaTeX engine is required: The initial run is interrupted with the first missing file. Then that file is created by an appropriate rule and the LaTeX engine is rerun failing with the next missing file. That way the process goes on until the last file is created with a rule. Of course this procedure is quite time-consuming, so an alternative is required.

3.6.3 Checks in the context of document development

The target chk just invoke the tool chktex and logs finding in a CLG file. It is invoked as the final quality check for the documents created from latex sources. But if this check fails, there is a transition to document development. As said in Section 3.6.2 on running this plugin on a single file with a single target applies here also. But here again, this plugin is not the first choice: Better is to invoke chktex directly and to eliminate the warnings iteratively. Since the file .chktexrc injected by this plugin as described in Section 3.5 configures chktex whether chktex is invoked directly by the user or via the plugin in goal chk, the results are the same. In the wording coined in Section 3.6.2, this plugin integrates chktex very much the same way as it integrates latexmk namely by injection of a config file.

The config file .chktexrc in turn is adapted to the header header.tex which is also injected. In general, .chktexrc excludes content of environments and of arguments of commands defined in packages loaded by header.tex or defined therein directly. A nice example of another kind of synergy is the command \textttNoChk defined in header.tex. Functionally, it is just \texttt which sets the argument in typewriter font, but in .chktexrc it is listed among the commands the arguments of which shall not be checked by chktex.

After eliminating warnings until direct invocation of chktex displays no warnings, one can be sure that also check with goal chk of this plugin does not yield warnings.

3.6.4 Goal Graphics grp

In the context of document development, typically compilation is done by basic tools like lualatex or by an orchestration tool like latexmk. Nevertheless, since separation of builds is desirable, intermediate files like graphic files are not present. Maybe they are removed by cleaning.

TBD: check whether this is really needed: is also described in section on latexmk. Maybe we need a section on this plugin describing grp and clr uniformly. Maybe also first write on chktex and its relation to this plugin.

For creating the graphic files in the TEX source directory, there is a goal graphics, invoked by mvn latex:grp. This goal does not create any output in the site directory. Instead, it populates the source directories with graphic files which can be directly included into the LaTeX-file and so it allows to run the LaTeX-compiler on the LaTeX main files from within a development environment. Thus, the goal graphics is thus a vital feature for development of documents.

Note that in general mvn clean validate latex:grp creates all files necessary to compile with a LaTeX engine like lualatex and also to compile smoothly with latexmk.

3.6.5 Goal Clear clr

When invoking this plugin as a final build, cleanUp is set to its default true. Thus, all files not present at the beginning of the build process are removed. As a consequence, there is no need for a separate goal clr. This comes into the game only in the context of document development. Either cleanUp was set to false or other more basic tools created intermediate files which must be deleted by clr.

Cleaning is vital because it makes the next build independent of the previous one. Deletion is driven by a regular expression patternCreatedFromLatexMain described in Table 6.1 on page 246. Completeness can be guaranteed only if the set of loaded packages is limited. Of course, only created files shall be deleted. For packages introduced in the injected header header.tex described in Section 3.5.2, this shall be the case. The author’s criterion for a correct regular expression is, that after deletion exactly the files under version control remain.

Clearing comprises files created by the goal grp and by any other goals. Note that AUX files are deleted if they belong to a LaTeX main file or to an included file.

The most interesting files are those created by injection, i.e. by goal inj like .latexmkrc: As pointed out in Section 3.5, each of the files in question is deleted only if they were definitively written by this plugin. If this is proved to be false or a proof is not possible, the configuration files are not deleted. As for goal inj, in case of a doubt, a warning is displayed.

3.6.6 Installation and Configuration

TBD: rework: maybe better describe the goal inj. The goal inj is to create a set of files, partially adapted to the current configuration.

By default, it is tied to lifecycle phase validate and comprises the set of injections latexmkrc,chktexrc.

The first we treat is injection vscodeExt injecting a file instVScode4tex.sh in the TEX source directory. Typically, this is not injected during a lifecycle, but when installing or updating extensions for VS Code used during document development. Thus, typically it is invoked in the form

Install script for installing extensions for VS Code helping in developing LaTeX documents.

In addition, configuration scripts for latexmk and chktex. Also describe how to use.

3.6.7 Miscellaneous

During development, it is comfortable, to have the log-file in the same directory as the LaTeX main file. Also, if PDF- and TEX-files are synchronized, also the PDF-file should be in the same directory. Likewise, files in graphic formats which cannot be included into a LaTeX-file without conversion, that converted file shall be in the same directory as the original one. So, all files, manually created files and files arising from automatic conversions shall be in the same folder, at least during development. Also, typically, one wants to mix creation by this maven-plugin or ant-task with at least partial creation through external tools. For example, if writing LaTeX-files with Emacs, it is much more convenient, to compile the LaTeX main file via pdflatex from within Emacs or to create a PDF-file from a fig-file through xfig’s export dialog, than using this maven-plugin or this ant-task. Also, these tools work best, if all is in one folder.

On the other hand, conventionally, in a maven project, sources are held in folder src, whereas created files occur in the folder target. Likewise for ant. The compromise, this maven-plugin and this ant-task take, is, that at the end of a run, at most the files present at the beginning of the run may be present in the source directory. So, this software builds in the following steps:

To keep e.g. the resulting PDF, just create it via compilation through Emacs, even if not all graphic files to be included are present or just by a touch-command. Then in the next run of this plugin, this PDF will be re-created, that time complete with the graphics output. That way, synchronization between LaTeX- and PDF-files is possible. Likewise, to keep the log-file or the aux-file, just touch it. This technique is really valuable for debugging.

To keep all created files after a run of this maven-plugin, set the parameter cleanUp in the pom to false as illustrated in Listing 3.5. For the ant-task likewise.

<!-- create html and pdf and other formats from latex --> 
<plugin> 
  <groupId>eu.simuline.m2latex</groupId> 
  <artifactId>latex-maven-plugin</artifactId> 
  <version>2.1</version> 
 
  <configuration> 
    <settings> 
      <targets>pdf</targets> 
      <cleanUp>false</cleanUp> 
    </settings> 
  </configuration> 
</plugin>

Listing 3.5: Configuration without cleanup

But how can one get rid of all these newly created files? That is what is the goal latex:clr is for: mvn latex:clr removes all created graphic files and for each LaTeX main file, it removes all files with “similar” names including log files, index files and that like. Typically, this suffices, to remove all files created. If not, try to modify parameter $patternCreatedFromLatexMain in the pom accordingly. If this does not help either, please inform the developer of this software. Of course, if further software is used which creates additional files, like Emacs creates a folder auto, these files cannot be removed by this maven-plugin or this ant-task. Note that latex:clr also removes exported files as listed in Section 3.2 from the target folder.

During development of a LaTeX-main file, it is often more convenient to compile from within an editor like Emacs. The problem is, that compilation fails if the graphic files are missing. This is what the goal graphics accessible via

Still this does not create a bibliography, an index or a glossary. With AUCTeX, an Emacs-package for editing LaTeX, bibliography and index are well-supported. To create a glossary, AUCTeX has to be modified a little.

That way also the log-files required are created: In case of this manual, the files manualLMP.xxx are created where xxx is

The last goal regularly used for development of documentation is check. It is invoked via

and runs chktex, described in [Thi22], on each LaTeX main file after having created graphic files as for goal graphics. As a result, a log-file with suffix .clg is created but not copied to the target folder. If the log-file contains an entry, an according message is logged. Note that, with default configuration, chktex requires the LaTeX-package booktabs described in [Fea16].

Besides the basic configuration packaged with chktex, there can be an additional configuration file .chktexrc which partially overwrites variables set by the basic configuration file, partially, for list-valued variables, adds entries. Section 2.2 describes how to access the .chktexrc with which this manual is checked and details to the form of .chktexrc can be found in [Thi22], Section 6.1.5.

Document development starts with the editor. Above the Emacs editor enhanced with AUCTeX was mentioned. We recommend VS Code in conjunction with several extensions. If VS Code itself is already installed the script instVScode4tex.sh installs and updates all extensions the author used to develop this manual. The core extension is latex workshop, the others are mainly used for editing graphic files. For details see Section 2.2.

3.7 Goals in the maven lifecycle

The goal latex:cfg exporting in the formats configured is tied to the lifecycle phase site so is invoked when commanding

Also, the goal latex:clr cleaning created files both from source directory and from target directory is tied to phase clean so is invoked when commanding

Finally, the goal latex:vrs displaying versions of converters and the goal latex:inj injecting a set of files depending on the configuration are tied to the phase validate. Thus, both goals are invoked when commanding

which is invoked not only in installation, but also by the site plugin. This ensures, that the converters are checked for correct version before being used. Note that by default, mvn latex:vrs displays complete version info, whereas mvn validate only displays warnings if appropriate. This is, because in the first case the plugin runs with the default versionsWarnOnly=true whereas in the second case, is configured with versionsWarnOnly=false as in Listing 2.4. Also Listing 2.4 shows a recommended configuration for the goal latex:inj which determines injected the files.

3.8 The ant-tasks

Section 3.2 treats goal cfg to create output from one source in various formats and also check which is without output. The target formats and also the checks are specified in the parameter targets.

There is an according ant task cfg doing the same also based on parameter targets. Whereas the maven plugin provides separate goals for each target, the ant-task has no such convenience feature. Section 3.2 briefly mentions goal clr used for cleanup. There is an according ant-task relying on according parameters. Note that the ant task does not support very much of document development, but it is likely, that the user performs document development and runs other programs than the ant task on the sources. In this case, the clr task is vital.

If this ant-task is used in an ant project with folder structure conforming with a maven project and if the LaTeX sources do not require a special configuration, the above configuration is sufficient. Otherwise, parameters have to be given explicitly overwriting the default values.

Chapter 3Usage of Plugin and Task