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
- bibtex or biber
- makeindex including makeindex style file
- nomencl including nomencl style file
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. |