Both the ant-task and the maven-plugin just direct parameters from ant and from maven, respectively, to the programs that do the proper work. Thus, installation of the ant-task and of the maven-plugin requires that all needed programs are installed. These prerequisites are collected in Section 2.1.
The ant-task is tested with
Apache Ant(TM) version 1.10.12 compiled on December 14 1969
(of course the year is not correct, but this is the version string displayed by that release) and the maven-plugin with
Apache Maven 3.9.2
Both, ant and maven are written in java and require a java installation. The java version used for tests is 17.0.8.
So, a java installation is the base for running either the ant-task or the maven-plugin. Also, this plugin is written in java. To use the maven-plugin, of course maven must be installed and to use the ant-task, ant must be installed.
The ant-task just passes parameters in the build file to the core and accordingly the maven-plugin passes parameters in the pom to the core of this software. The core just invokes various programs to do the actual work.
Besides plain building of documentation, this software also supports development of documents. LaTeX and related programs are based on text files mainly and so a good editor is required for development.
The author recommends and uses VS Code, e.g. 1.81.1 in conjunction with package LaTeX workshop 9.13.4 and LTeX 13.1.0.
An alternative is good old
GNU Emacs 24.3.1 (x86\_64-suse-linux-gnu, GTK+ Version 3.16.7)
together with several packages to support various file formats. To list the available packages type M-x list-packages. For comfortable development with LaTeX, the AUCTeX package, version 11.88 is recommended. The version is displayed from within Emacs by typing C-h v AUCTeX-version RET. For an overview on AUCTeX see [TAK+14].
FIXME: gnuplot-mode expects file extension gp. Should be made configurable.
To edit metapost, the mode built-in mode Metamode is used.
Built-in mode Docview to view PDF, PS and DVI.
latexmk
Builtin modes bib-mode and bibtex
Built in reftex-modes
Useful: ac-math, auto-complete-auctex
Depending on what kinds of graphic formats are used, the following programs are required:
To convert the fig-files into pdf-files, by default fig2dev is used. It makes sense to have xfig installed to create and edit fig-files, but this is not mandatory.
To convert gnuplot files into PDF-files, there is no alternative, to have installed gnuplot. It serves as an interpreter and also as a converter. Strictly speaking, only the latter functionality is required here.
To convert mp-files into eps-files, the interpreter mpost or equivalent is required. This comes with a standard TeX installation. With the standard configuration, the resulting EPS-file can be viewed with ghostscript and for developing it is recommended to have ghostscript installed.
To include svg-files into LaTeX, inkscape must be installed. It also serves to create and to edit SVG-files.
Currently, for including PDF-files in both cases, the driver dvipdfmx must be installed. Strictly speaking, this is required only for HTML-creation and related. Note that if no pictures created by fig2dev, gnuplot, mpost or by inkscape are used, of course, neither fig2dev nor gnuplot, mpost, inkscape nor dvipdfmx is needed. To include graphics, the graphics bundle described in [Car16] is required, except for SVG-files which requires the svg-package described in [Ilt12].
As the set of required software depends on the graphic formats which shall be imported, it depends also on the set of output-formats to be supported:
To create PDF-files from LaTeX-files we use LaTeX engines like lualatex, xelatex or pdflatex.
LaTeX uses several auxiliary programs. Above all bibtex, to create the bibliography and makeindex and splitindex for the index and makeglossaries for the glossary. The latter two also require the latex packages makeidx, optionally showidx, both described in [BLC+14], the package splitidx documented in [Koh16] and glossaries specified in [Tal24b]. Note that makeglossaries either invokes makeindex or xindy, depending on the parametrization of the package glossaries. Both, makeglossaries and xindy are written in Perl, which shall also be installed if a glossary is required.
To include program code in Python, octave and other language, pythontex is needed; to eliminate that code creating an equivalent TEX file, one has to combine it with depythontex. Both are written in Python3 which shall be installed also as a dependency. To use them, one also needs to install the package pythontex.
It is standard to endow a PDF-file with hyperlinks. To support this, the package hyperref is required.
****
To create html-files, or to be more precise any kind of sgml and xml, from LaTeX-files, htlatex or alternatively htxelatex is used. Currently, the author is not aware of any alternative to the two. This includes also creating OpenOffice documents like ODT-files. Thus, OpenOffice documents are created in two steps, the first is to create PDF-files with the according tools, the second one is done by htlatex or that like.
To create RTF-files, currently latex2rtf is used. Note that this does not require pdflatex. As a drawback, not all LaTeX-packages are supported.
MS Word documents are created from OpenOffice documents via the command odt2doc and thus require three steps and so the according tool chain.
Finally, there is a way, to create plain text files from the PDF-files via pdftotext. The way from LaTeX to text via PDF makes sense because that text is well formatted math mode symbols like π and because table of contents, index, glossary and that like are included. So, for that task, besides pdftotext the whole tool chain to create PDF-files is required.
An application which does not create a target, i.e. a file in the target directory is chktex which just checks the gls:lmf and associated files.
So to run this software, the aforementioned programs or at least the subset used, must be installed. To obtain reproducible results, the versions must fit. This version is checked with the executables with versions given by an according properties file version.properties.
There are also several LaTeX-packages needed or at least recommended. The recommended ones are
described in [Ume10] to control page layout.
described in [Sch16] improve readability and make the document look nicer. It also helps to avoid bad boxes.
described in [RO22] to insert hypertext marks, which I do not want to miss in larger documents.
described in [SU06] which allows jumping from the DVI file to the TEX source and back.
if geometry is not used with option showframe. There seems to be no package documentation for package showframe.
described in [Fea16]
described in [Sza07] to allow arbitrary font sizes, eliminating certain warnings. An alternative may be fix-cm described in [SMCR15].
Almost required are
rerunfilecheck described in [Obe22] which writes additional rerun warnings to the log file if some auxiliary files have changed. This software partially relies on these warnings to control rerun the LaTeX engine. Although rerunfilecheck is intended to detect also rerunning auxiliary programs, this does not work properly and so this software bases reruns on internal algorithms.
iftex described in [Tea22] which has two functions:
It provides the \ifpdf-command to detect pdf-mode. This is required to distinguish creation of PDF and text from HTML, ODT, DOC and others, based on DVI/XDV.
Also, it is able to detect a specific LaTeX engine via commands like \ifluatex or \ifpdftex but also \iftutex being true for lualatex and xelatex, but not for pdflatex. This is used if a document shall work for more than one engine like this manual and is in particular used to create reproducible PDF files which is engine specific. Finally, there is a way to force an exception if the wrong engine is used, e.g. by specifying \RequireLuaTeX.
The graphics packages described in [Car16], in particular graphicx, xcolor and transparent, the latter two described in [Ker16] and in [Obe16b], respectively. Sometimes also bmpsize described in [Obe16a] if pixel graphics is used.
import described in [Ars09] e.g. to import nested graphic files from arbitrary directories.
inputenc described in [JM15] to select an input encoding fontenc to select a font encoding. Font selection is described in [Tea00] in general, with Section 5 on font encoding and Section 5.1 on the fontenc package. This package is almost indispensable if you do not write English, e.g. to access German umlauts. Note that [MFL16] describes font encoding in more detail.
makeidx and showidx described in [BLC+14] or something comparable for creating indices.
glossaries described in [Tal24b] with tutorial [Tal24a] or something comparable for creating glossaries.
tocbibind described in [WP10] to include bibliography and index (what about glossaries?) into the table of contents.
nag described in [Sch11] which performs certain checks unveiling deficiencies not filtered by the compiler nor by another check tool.
babel described in [BB24] for language support. This is not used by this manual, because it is in English.
Useful packages with which this software is tested:
The ams-packages **** amsmath
longtable described in [Car98] for long tables, i.e. tables exceeding a page.
listings described in [HMH15] for listings.
fancyvrb described in [Zan10] provides useful environments to mark verbatim text.
If this software is used as a maven plugin, it need not explicitly be installed, maven itself does this by need based on the entries of the pom.
We can distinguish between entries in the pom which are necessary for any kind of usage of this maven plugin described in Section 2.2.1, configuration settings to obtain behavior deviating from the default as sketched in Section 2.2.2 and finally executions to integrate this plugin in the lifecycle as described in Section 2.2.3.
Unfortunately, this plugin did not yet make it into maven central. Thus, one has to add the providers’ repository to the pom as shown in Listing 2.1 to enable maven to find the software.
<project ...> ... <repositories> <repository> <id>publicRepoAtSimuline</id> <name>repo at simuline</name> <url>https://www.simuline.eu/RepositoryMaven</url> </repository> </repositories> ... </project>
Then just adding the coordinates in the build-plugins section of the pom as shown in Listing 2.2, and it can be used from command line, e.g. to create PDF files as mvn latex:pdf or for cleanup mvn latex:clr with default configuration. Alternatively, the plugin can be inserted also in the reporting-plugins section of the pom.
<project ...> ... <build> ... <plugins> ... <!-- create html and pdf and other formats from latex --> <plugin> <groupId>eu.simuline.m2latex</groupId> <artifactId>latex-maven-plugin</artifactId> <version>2.1</version> </plugin> ... </plugins> ... </build> ... </project>
This plugin is indexed in https://mvnrepository.com/artifact/eu.simuline.m2latex/latex-maven-plugin.
This plugin is highly configurable by means of a lot of settings. Listing 2.3 shows some of them, but all are in their default settings, so no need to specify them explicitly:
defines the output formats and the checks to be run (chk signifies running chktex) for goal cfg.
whether all generated files shall be removed leaving the LaTeX source folder untouched.
is one of the names of the tools to be invoked. There are more settings for treating tools.
It is the experience of the author, that in many situations no explicit setting is necessary at all. The only setting needed to be configured regularly is targets which determines the output formats and whether sources are checked for goal cfg. It is recommended to use checking via target chk in any case. Some settings are only relevant only for document development as described in Section 3.6, one of these is cleanUp: setting this to false keeps intermediate files, in particular log files available which helps to find errors and in locating the sources of warnings. There are further situations where the user is grateful of being able to configure this software, or even where it is not usable with default settings. Chapter 6 describes the complete set of settings. The same pieces of information is given in the pom.xml used to test this plugin. Although each setting takes its default value, it is given explicitly and is endowed with a comment describing it in detail as in Chapter 6. Since this pom is quite long, it is not part of this manual but is given by reference on the project site.
<!-- 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, html</targets--> <!--latex2pdfCommand>lualatex</latex2pdfCommand--> <!--cleanUp>true</cleanUp--> ... </settings> </configuration> </plugin>
To make the plugin available within a build, one has to add executions, e.g. as shown in Listing 2.4. For all goals specified there, a default phase is defined, as given as a comment but as this is hard-coded, one has to specify in the executions only when deviating from the default.
Typically, this plugin, to be more precise its goal cfg, which allows configuring checks and the output formats in setting targets, is used in the site lifecycle phase to process latex sources. It is perfectly ok to stick to a single format like pdf and configure target accordingly.
Alternatively, one may define an execution with the required goals like pdf, but then the phase must be specified explicitly, because there is no default phase. Of course, then no additional check is performed.
The goal inj injects files into the working directory texSrcDirectory as described in detail in Section 3.5. For some files it makes sense to do this independent of the build process e.g. by invoking mvn latex:inj, but in general it is preferable to perform the injection each build process anew because that way the injected file can be adapted to the current settings of this plugin. Note that the execution of the goal inj has its own configuration, which allows a single parameter, injections. Listing 2.4 gives a recommended parameter value, although not the default.
Normally, all created files in the source directory are removed after the output has been copied to the target, but during document development, described in Section 3.6, cleanup may be deactivated by setting cleanUp and so the source directory may be polluted. This may happen if other tools are used in conjunction with this plugin.
Nevertheless, cleanup is recommended to make the individual runs of this plugin independent. Thus, for document development, there is a dedicated goal clr to clean up the source directory in phase clean. Note that also the configuration files created by goal inj are cleared. Since cleanup occurs in the course of the build and not with goal clr the parameter cleanUp is given in the general settings. The goal clr cannot be configured.
Finally, it is recommended to add a check of the versions of the programs called converters used right in the phase validate via goal vrs. Listing 2.4 specifies versionsWarnOnly=true, which restricts goal vrs to just display a warning if something is wrong which seems appropriate in the context of validation.
For the default configuration versionsWarnOnly=false, the goal vrs yields a full list of registered converters, signifying which one may cause trouble because its version is out of range as displayed in Listing 3.2. In the course of a build run, this seems too much information, but in fact, it is just a matter of taste.
For details on executions of goals inj, clr and vrs see Section 3.6.
<plugin> <groupId>eu.simuline.m2latex</groupId> <artifactId>latex-maven-plugin</artifactId> <version>2.1</version> <configuration> <settings> <!--targets>chk, pdf, html</targets--> <!--cleanUp>false</cleanUp--> ... </settings> </configuration> <executions> <execution> <id>process-latex-sources</id> <!-- chk, dvi, pdf, html, odt, docx, rtf, txt --> <goals><goal>cfg</goal></goals> <!-- phase>site</phase--> </execution> <execution> <id>clear-latex-sources</id> <goals><goal>clr</goal></goals> <!-- phase>clean</phase--> </execution> <execution> <?m2e execute onConfiguration?> <id>inject-files</id> <goals><goal>inj</goal></goals> <!-- phase>validate</phase--> <configuration> <injections>latexmkrc,chktexrc,header</injections> </configuration> </execution> <execution> <id>validate-converters</id> <goals><goal>vrs</goal></goals> <!-- phase>validate</phase--> <configuration> <versionsWarnOnly>true</versionsWarnOnly> </configuration> </execution> </executions> </plugin>
The executions considered so far are appropriate for mavens default lifecycle. Typically, this maven plugin is used in the site lifecycle, which does not contain the phase validate, but accordingly pre-site. As a consequence, goals inj and vrs are not invoked. To get around, one could specify the phase pre-site in the execution explicitly. The author uses the maven-jxr-plugin as illustrated in Listing 2.5, which, as a side effect, forks the lifecycle and includes phase validate of the default lifecycle and in particular goals inj and vrs.
It is planned to perform a version check in first usage of a tool, except tools in the environment, i.e. build tools and programming languages. This avoids check of tools which are not needed. Also, for the generic user, no execution for goal vrs is needed any more; by need it can be invoked from the command line as mvn latex:vrs. Still the developer of this software will continue to specify that execution.
<project> ... <reporting> <plugins> ... <!-- as a side effect, triggers 'generate-sources' forked phase execution --> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-jxr-plugin</artifactId> <version>3.3.0</version> </plugin> ... </plugins> </reporting> </project>
Note that in Listing 2.4 the section configuration which is not part of an execution contains an empty configuration and is thus as much as empty. It can thus be skipped in a default configuration creating output in formats PDF and HTML and performing checks on the LaTeX-sources. However, pom.xml gives an example pom using this latex plugin with full configuration with default values and executions. In addition, Chapter 6 describes each setting individually.
As you can see, the taskdef’s refer to java classes. Unlike maven which loads jars with the classes inside automatically from
https://www.simuline.eu/RepositoryMaven%
the jar for the tasks, latex-maven-plugin-2.1-antTask.jar, must be downloaded manually from
https://www.simuline.eu/RepositoryMaven/eu/simuline/m2latex/latex-maven-plugin/2.1%
Moreover, ant expects to find the jar files in an according folder. In my installation it is /usr/share/ant/lib/; as can be seen in the ant documentation, in general it is in folder lib in ant’s installation directory.
However, build.xml gives an example build file using this latex ant task with full configuration with default values and executions. From that, one has to copy the following into the build.xml file in the current project:
The properties antJarDir and createdJar,
The path element with the id latex.classpath
The taskdefs latexCfg and latex:Clr
The targets latex:cfg and latex:clr
As for the maven plugin, for the ant task, add configuration, where a deviation from the default requires to do so. The configuration is the same and is described in detail in Chapter 6.
The first step to install from source, is to clone from the repository by
git clone https://github.com/Reissner/maven-latex-plugin
of course assuming that git has been installed. Then change into the root repository where pom.xml for maven and also built.xml for ant are located.
To install the maven-plugin, ensure that maven is installed. One is tempted just to type
mvn clean install
but this does not work since the plugin needs itself to be installed to perform even clean. To solve that problem just comment out all its executions in the local pom.xml by enclosing them in <!–…–>. In fact this is a minor bug, since, to be strict, only the executions for verification and clearing must be deactivated. For processing, it would be sufficient to add <phase>site</phase> to execution process-latex-sources.
Since the author develops with maven, including the development of the ant task, the maven built, creates the file latex-maven-plugin-2.1-antTask.jar defining the ant task. To this end, also mvn clean package is sufficient. After that, installation proceeds like described in Section 2.3 copying that jar file ant’s lib-folder where ant can find it.
With root access and after having checked the proper paths, the build file build.xml can be used to perform copy task by ant install, to insert an according link by ant link to remove it again with ant uninstall. The build file build.xml works only if latex-maven-plugin-2.1-antTask.jar is placed where ant can find it or if the parts are deactivated below the line
<!-- deactivate the following, unless the ant task is installed already -->
I feel building with maven and linking the jar created is a very good way to develop the ant task, because after changes the new ant task is available immediately.
For typical changes in the sources, it is possible to recompile and package the ant task by ant jar also cleanup is possible with ant clean. Finally, the ant task can be tested with ant latex:cfg and ant latex:clr.
In the long run, it should be possible to build the ant task from sources with ant alone.