Automate Document Generation From Latex Part 2

Introduction

In Part 1 we looked at how we could use the Linux make program to automate latex tasks.

In this part of the tutorial we will take a look at the Apache Ant utility to do the same.

There is an in depth manual here about what Ant is and how it works.

So anyway. Ant uses an XML file to describe the tasks it needs to perform. The default name of this file is build.xml.
If you have several project specific properties than you can put them in a file called for example build.propreties and load it in with ant.

The build.properties file

Lets look at a build.properties file which we will use to define what program to use to show PDF files we generate.

# Uncomment the one you want to use. 
# Change path according to your setup
#
# For Windows 
project.showpdf=C:/Program Files/Adobe/Reader 8.0/Reader/AcroRd32.exe

# For Linux
#project.showpdf=acroread
#project.showpdf=xpdf

Okay. So lines starting with the character # are comments. In this file we define a property called project.showpdf. After including this file in out build.xml file we can use ${project.showpdf} and ant will substitute in the value we entered for it in the properties file.

Creating the build.xml file

To make things a bit easier for use we will use the ant_latex package to generate the documents.
The package can be found here (note: it is a german site) Direct link to the download. Just place the .jar file into the directory path/to/ant/lib.

Now let’s look at the file build.xml and then go through each section in a bit more detail.

<project name="Automate Latex Document Creation Part 2"
   	default="all" basedir=".">
	<taskdef name="latex" classname="de.dokutransdata.antlatex.LaTeX"
		classpath="d:/ant-1.7.1/lib/ant_latex.jar" />

	<property file="build.properties" />

	<target name="all">
		<latex
			verbose="on"
			clean="on"
			pdftex="off"
			workingDir="${basedir}"
			>
			<makeindex
				run="on"
				workingDir="${basedir}">
				<fileset dir="${basedir}">  
	               <include name="*.nlo" />  
    	        </fileset>  
			</makeindex>
			<bibtex
				run="on"
				workingDir="${basedir}" />
		<fileset dir="${basedir}">
			<include name="*.tex" />
		</fileset>
		</latex>
	</target>

	<target name="clean">
		<echo>Cleaning up</echo>
	</target>

	<target name="dvi">
		<echo message="Creating ${file.name}.dvi from ${file.name}.tex" />
		<latex
			latexfile="${file.name}.tex"
			verbose="on"
			clean="on"
			pdftex="off"
			workingDir="${basedir}">
				<makeindex
				run="on"
				workingDir="${basedir}">
				<fileset dir="${basedir}">  
	               <include name="*.nlo" />  
    	        </fileset>  
			</makeindex>
			<bibtex
				run="on"
				workingDir="${basedir}" />
		</latex>
	</target>

	<target name="pdf">
		<echo message="Creating ${file.name}.pdf from ${file.name}.tex" />
		<latex
			latexfile="${file.name}.tex"
			verbose="on"
			clean="on"
			pdftex="on"
			workingDir="${basedir}">
				<makeindex
				run="on"
				workingDir="${basedir}">
				<fileset dir="${basedir}">  
	               <include name="*.nlo" />  
    	        </fileset>  
			</makeindex>
			<bibtex
				run="on"
				workingDir="${basedir}" />
		</latex>
	</target>

	<target name="show" depends="pdf">
		<echo>Running show for ${file.name}.pdf</echo>
		<exec executable="${project.showpdf}" spawn="true">
			<arg value="${file.name}.pdf" />
		</exec>
	</target>
</project>

Each Ant build file needs to have a root element called project

<project name="Automate Latex Document Creation Part 2"
   	default="all" basedir=".">
...
</project>

Here we define the name of the project, “Automate Latex Document Creation Part 2″ in this case. The default target called all and the base directory.

Next we need to load the ant latex task definition. We do it with a taskdef element:

 <taskdef name="latex" classname="de.dokutransdata.antlatex.LaTeX"  
         classpath="d:/ant-1.7.1/lib/ant_latex.jar" /> 

Then we load out properties file.

<property file="build.properties" />

After this we can define our targets.

The all target

With this target we generate a dvi document from each and every .tex file found in the base directory.

Let’s go step by step:

		<latex
			verbose="on"
			clean="on"
			pdftex="off"
			workingDir="${basedir}"
			>
		<fileset dir="${basedir}">
			<include name="*.tex" />
		</fileset>
		</latex>

The verbose attribute tells Ant to print invoke latex in verbose output mode. So we can see what is happening on the command line. The clean attribute tells whether Ant should delete temporary files.
The pdftex attribute if set to on will invoke pdflatex and will create a PDF document instead of a DVI document. The workingDir sets the work directory as it’s name suggests.
The fileset tag tells latex to use all the files specified by the include tag from the dir directory. Here we simply set it to the project’s base directory and to include all .tex files. If we want to generate documents from all .tex files in the base directory and any subdirectories then we would write **/*.tex in the include tag.

<makeindex
	run="on"
	workingDir="${basedir}">
	<fileset dir="${basedir}">  
	        <include name="*.nlo" />  
    	</fileset>  
</makeindex>

The makeindex tag controls the index creation. It is the equivalent of running $ makeindex after a latex command.
The run attribute controls whether makeindex should be run.

<bibtex
	run="on"
	workingDir="${basedir}" />

The bibtex tag is the equivalent of writing $ bibtex after executing a latex command.

Now let’s have a look at the whole target:

<target name="all">
	<latex
		verbose="on"
		clean="on"
		pdftex="off"
		workingDir="${basedir}"
		>
		<makeindex
			run="on"
			workingDir="${basedir}">
			<fileset dir="${basedir}">  
               <include name="*.nlo" />  
            </fileset>  
		</makeindex>
		<bibtex
			run="on"
			workingDir="${basedir}" />
	<fileset dir="${basedir}">
		<include name="*.tex" />
	</fileset>
	</latex>
</target>

The dvi target

With this target we will create a dvi file from one .tex file. To do this we will pass a property to ant from the command line.
To do this we need to specifie the -D option.
ant -Dproperty=value target
So for example the commandant -Dfile.name=automate_latex_p2 dvi
would generate automate_latex_p2.dvi from automate_latex_p2.tex.

<target name="dvi">
	<echo message="Creating ${file.name}.dvi from ${file.name}.tex" />
	<latex
		latexfile="${file.name}.tex"
		verbose="on"
		clean="on"
		pdftex="off"
		workingDir="${basedir}">
			<makeindex
			run="on"
			workingDir="${basedir}">
			<fileset dir="${basedir}">  
               <include name="*.nlo" />  
            </fileset>  
		</makeindex>
		<bibtex
			run="on"
			workingDir="${basedir}" />
	</latex>
</target>

To use only one file we need to set the latexfile argument for the latex tag.
To achive this we use the property we passed to ant from the command line file.name. To use it’s value we need to reference it like ${file.name}.

That’s it we can create a dvi file from only one tex document.

The pdf target

The pdf target is the same as the dvi target, with the only difference in setting the pdftex attribute to on

        <target name="pdf">
		<echo message="Creating ${file.name}.pdf from ${file.name}.tex" />
		<latex
			latexfile="${file.name}.tex"
			verbose="on"
			clean="on"
			pdftex="on"
			workingDir="${basedir}">
				<makeindex
				run="on"
				workingDir="${basedir}">
				<fileset dir="${basedir}">  
	               <include name="*.nlo" />  
    	        </fileset>  
			</makeindex>
			<bibtex
				run="on"
				workingDir="${basedir}" />
		</latex>
	</target>

To run this target we would type ant -Dfile.name=automate_latex_p2 pdf on the command line.

The show target

With this target we create a pdf file and execute the command we specified in build.properties to show it.

	<target name="show" depends="pdf">
		<echo>Running show for ${file.name}.pdf</echo>
		<exec executable="${project.showpdf}" spawn="true">
			<arg value="${file.name}.pdf" />
		</exec>
	</target>

The depends attribute tells ant that it needs to run that this target depends on the specified one. We can list more than one target here. They need to be separated by commas. For more info look at the Ant manual.

The exec tag is where we specify which program to run. We set the executable attribute to the value we defined in build.properties. The spawn attribute tells ant to execute and then terminate the ant target. This makes sure that the build process is not going to wait until we close for example acroread. The arg tag specifies the arguments to pass to the executable. Here we set it to the pdf file we created.

Conclusion

With this method we can use make like automation on all platforms that support Java.

The source code can be downloaded from here.

This post by Péter Halász is licensed under a Creative Commons Attribution-Noncommercial-No Derivative Works 3.0 United States License.

About these ads