Latex Maven Plugin

This site is under construction. Thus, we refer the reader to the development site and in particularly the ‘README.md’ therein. Check in particular the section on the maven plugin. For a really detailed description in contrast see manual as a PDF. Note that this manual is created by this maven-latex-plugin and serves also as a test suite for the plugin. It is also available as an HTML page, created from the same source, but as HMTL creation is not really mature and comprehensive enough, we still recommend the PDF version.

If you have problems applying this maven-latex-plugin or feel a feature is missing, please don't hesitate and let me know.

The latex-maven-plugin translates LaTeX documents into PDF, HTML or other LaTeX output formats like DVI or Postscript, during the maven site lifecycle. Internally, the plugin calls the standard LaTeX tools, like lualatex for PDF and tex4ht for HTML output. Hence, a LaTeX distribution has to be installed on the computer running the maven build.

By default, LaTeX documents and resources like graphics files are assumed to reside in the maven project's src/site/tex folder. The resulting files will be in the folder target/site/tex, making them a part of the maven site. Thus, other maven site artifacts (like HTML pages build from apt files) may link to them.

The maven-latex-plugin tries to be smart by analyzing the LaTeX converter's output and running the converter as often as needed (running LaTeX more than once is needed when e.g. building a table of contents or when using bibtex to maintain a bibliography and citations).

Goals Overview

Before describing the individual goals, be warned that the according parameters are not given very explicitly. This is due to the fact, that we use a general object as parameter and this documentation treats that as a single settings parameter, not caring about its fields which are the proper parameters. For now, we overcome this problem pointing the reader to the Parameter section in the PDF manual.

Most of the goals are on creating output in a given format.

  • latex:cfg creates output in the formats listed as targets in the configuration as shown by example.
  • latex:dvi creates output in the format dvi, except for converter xelatex which generates the according format xdv.
  • latex:pdf creates output in the format pdf.
  • latex:odt creates output in the format odt.
  • latex:docx creates output in the format xdoc or doc, depending on the configuration.
  • latex:rtf creates output in the format rtf.
  • latex:html creates output in the format html or xhtml, depending on the configuration.
  • latex:txt creates output in the text format txt.
  • latex:chk checks sources via chktex without deploying an artifact. The artifact is a log file containing errors, warnings and info.

The goal cfg is special in that all other formats can be specified as targets and also combinations are possible. The other goals refer to single output formats, each of which can specified as an entry in targets. This is also true for the second special goal, chk, which performs a check only and creates nothing but a log file. Unlike the artifacts of the other goals, chk transfers no artifact to the build folder.

The following goals are not directly related with building of artifacts.

  • latex:clr cleans artifacts and intermediate files generated by this software. In general this is not needed, but for a special case.
  • latex:inj by default creates ‘injects’ configuration files for .latexmk and for .chktex fitting the configuration of this software. This is needed to synchronize .latexmk and .chktex with this software. It may also inject other types of files like installation scripts for tools or extensions or TEX-header files to unify packages used in the individual documents.
  • latex:grp creates graphic files only. Some use cases are mentioned but without aiming completeness.
  • latex:vrs displays tools used, their actual version and the allowed versions. A warning is emitted if the actual version is not intended. This is discussed also in more detail.

Usage

General instructions on how to use the Clean Plugin can be found on the usage page. Some more specific use cases are described in the examples given below.

In case you still have questions regarding the plugin's usage, please have a look at the FAQ and feel free to contact the user mailing list. The posts to the mailing list are archived and could already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching the mail archive.

If you feel like the plugin is missing a feature or has a defect, you can submit a feature request or bug report in our issue tracker. When creating a new issue, please provide a comprehensive description of your concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. Of course, patches are welcome, too. Contributors can check out the project from our source repository and will find supplementary information in the guide to helping with Maven.

Examples

To provide you with better understanding on some usages of this plugin, you can take a look into the following examples: