Build Status Codacy Badge

mathan-latex-maven-plugin

This is THE maven plugin to generate PDF, PS or DVI from LaTeX sources.

There have been some maven plugins around trying to provide an easy way to run LaTeX with maven. But it was never as easy as it should be. A lot of configuration had to be made to get the plugins working. And many of them are not maintained any more.

mathan-latex-maven-plugin changes this. It is very easy to to use and there is little or no configuration needed for the default use cases.

Usage

Using mathan-latex-maven-plugin introduces the packaging pdf. In a single maven module using mathan-latex-maven-plugin a PDF artifact is created. If you want to split the .tex sources or reuse them in multiple maven modules consider the Dependencies section.

The minimal configuration looks like this:

...
<packaging>pdf</packaging>
...
<build>
  <plugins>
    <plugin>
      <groupId>io.mathan.maven</groupId>
      <artifactId>mathan-latex-maven-plugin</artifactId>
      <version>0.9.0</version>
    </plugin>
  </plugins>
</build>

Goal —- If the packaging is set to pdf mathan-latex-maven-plugin will be executed in package, install and deploy phase. Otherwise the explicit goal mathan:latex can be used.

Tex source files

By default mathan-latex-maven-plugin will search for a .tex file in the source directory *src/main/tex. The default behaviour can be changed using the configuration parameter sourceDirectory. Please note that for setting configuration parameters the extensions have to be activated.

Example for using a non-default source directory.

...
<plugin>
  <groupId>io.mathan.maven</groupId>
  <artifactId>mathan-latex-maven-plugin</artifactId>
  <version>0.9.0</version>
  <extensions>true</extensions>
  <configuration>
    <sourceDirectory>src/main/custom</sourceDirectory>
  </configuration>
</plugin>

LaTeX distribution —————— A LaTeX distribution is required to execute all LaTeX commands. By default mathan-latex-maven-plugin will assume that the bin directory of the LaTeX distribution is set on the PATH environment variable. As alternative the environment variable texBin can be used. It is also possible to use the configuration parameter texBin but this is not recommended as details about a local environment would become part of the Maven pom.xml.

Dependencies

To share resources (.bib, .tex, .eps, …) for multiple maven modules they can be assembled in a separate module (can be jar or zip or whatever) used as a dependency for the maven project building you LaTeX document. Using the configuration parameter resources filters can be used to identify the resources to use.

Features

The mathan-latex-maven-plugin supports the output formats PDF, PS and DVI. The build process also includes the execution of

Logging / Debugging

While building snapshot artifacts consider to set the configuration parameter keepIntermediateFiles to true to be able to review the latex files created withing the build process. You will find a file target/latex/mathan-latex-mojo.log containing the log output of all latex steps executed.

Configuration

The following configuration parameters can be used to change the default behaviour of the build.

Parameter Description Default
outputFormat The desired output format. Can be either dvi, ps or pdf pdf
sourceDirectory Where to find *.tex documents. src/main/tex
texBin The bin directory of the tex distribution. Searches on PATH environment and looks for system property texBin
texFile Name of the main *.tex file to use defaults to a single .tex file found in sourceDirectory
latexSteps The latex commands to execute to generate the output document. This is latex for dvi, latex,dvips for ps and pdflatex for pdf.
buildSteps The build steps executed for a single document. The keyword LaTeX defines all steps configured with latexSteps LaTeX, bibtex, makeindex, makeindexnomencl, LaTeX, LaTeX
steps Configuration for user-defined steps. none
keepIntermediateFile Sets whether intermediate files created during the build should be kept. false
makeIndexStyleFile Name of the index style file to use for makeindex none
makeIndexNomenclStyleFile Name of the nomencl style file to use for makeindex nomencl.ist from the TeX distribution
resources A FileSet defining the resources to include from given dependencies. By default all files with the following extensions will be included: tex,cls,clo,sty,bib,bst,idx,ist,glo,eps,pdf
haltOnError Sets whether the build should be stopped in case a single step finished with a non-zero exit code true

Samples / Integration tests

The following integration tests are samples how to use mathan-latex-maven-plugin also. On Travis all integration tests are executed successfully.

Project Description
configuration/dependencyincludes Sample using .bib resources from dependency only.
configuration/keepintermediatefiles Sample not removing intermediate files created.
configuration/makeindexstylefile Sample using a style file for makeindex.
configuration/makeindexnomenclstylefile Sample using a style file for makeindexnomencl.
configuration/outputformat Sample using all supported output formats.
configuration/sourcedirectory Sample using custom source directory.
configuration/texfile Sample specifying master tex file.
dependencies/dependency Dependency providing resource in a jar.
dependencies/main Sample using a resource from a dependency.
dependencies/zip-dependency Dependency providing resource in a zip.
dependencies/zip-main Sample using a resource from a zip dependency.
features/biber Sample using biber.
features/bibtex Sample using bibtex.
features/makeindex Sample using makeindex.
features/nomenlc Sample using nomencl.