LaTeX-Mk

Node: Top, Next: , Previous: (dir), Up: (dir)

LaTeX-Mk

This file documents the LaTeX-Mk package. LaTeX-Mk is a collection of Makefile fragments and shell scripts for managing small to large sized LaTeX projects. This edition documents version 1.8.

Node: Introduction, Next: , Previous: Top, Up: Top

Introduction

LaTeX-Mk is a tool for managing small to large sized LaTeX projects. The typical LaTeX-Mk input file is simply a series of variable definitions in a Makefile for the project. After creating a simple Makefile the user can easily perform all required steps to do such tasks as: preview the document, print the document, or produce a PDF file. LaTeX-Mk will keep track of files that have changed and how to run the various programs that are needed to produce the output.

As a quick example, consider a project which has a single LaTeX file, mydoc.tex, as its input. To produce a .pdf file you might use the following sequence of commands: 

     latex mydoc.tex
     latex mydoc.tex
     latex mydoc.tex
     dvips -Ppdf -j0 -o mydoc.ps mydoc.dvi
     ps2pdf mydoc.ps mydoc.pdf
The triple invocation of latex is to ensure that all references have been properly resolved and any page layout changes due to inserting the references have been accounted for. The sequence of commands isn't horrible, but it still is several commands and one of them, dvips, has some flags to remember. To use LaTeX-Mk for this project, you would create a Makefile that contains the following. 
     NAME=mydoc
     
     include /usr/local/share/latex-mk/latex.gmk
Note that the include /usr/local/share/latex-mk/latex.gmk is the syntax for GNU make. If you are using BSD make you would replace the include line with .include "/usr/local/share/latex-mk/latex.mk". In both examples, you would replace /usr/local with the installation prefix on your system. For the remainder of this document we will use the BSD style of include in the examples. Now to create a .pdf file you simply run make pdf. For larger projects which may need to run programs to export drawings to Postscript files for inclusion or run BibTeX to generate bibliographies, the generation of .pdf (or other) files becomes increasingly complicated to run manually. With LaTeX-Mk, such operations are still very simple.

As a more complicated example, consider a project whose LaTeX input is broken apart in to many .tex files which are all included by mydoc.tex. Also suppose the project includes a bibliography and a large number of figures created with the Tgif program. An example Makefile for this project might look like: 

     NAME=        mydoc
     TEXSRCS=     ch1.tex ch2.tex ch3.tex refs.tex
     BIBTEXSRCS=  mybib.bib
     TGIFDIRS=    tgif_figs
     
     .include "/usr/local/share/latex-mk/latex.mk"
In this example is it assumed that all of the Tgif figures reside in a subdirectory called tgif_figs. When the user issues a make command, all of the steps required to reformat the document are taken. Because of the dependency structure imposed by make, only the steps which need to be taken are done. This avoids re-exporting a large number of figures which may have not changed, but ensures that files which need processing are processed.

Hopefully this introduction has provided an adequate example for how LaTeX-Mk can simplify the management of LaTeX based documents. The LaTeX-Mk system is simple enough for small projects and powerful enough for large projects. The remainder of this manual will provide complete documentation on the use of LaTeX-Mk as well as configuration and installation instructions.

Node: Targets, Next: , Previous: Introduction, Up: Top

Targets

LaTeX-Mk provides a fixed set of targets, the argument to the make command, for all projects. The default target is view whose ultimate goal is to provide an on-screen preview of the formatted document. For additional information on the make program, please refer to the documentation for your copy of make.

Base Targets

The targets provided by LaTeX-Mk are:

clean Target
Cleans the current working directory by removing all LaTeX output and other output files created during processing of the project. In addition, emacs ~ files are removed.

dist Target
Creates a .tar.gz file containing an archive of the project. It contains the source files and additionally some generated files which are generated with tools which someone else may not have installed. For example, any tgif drawings are included both in tgif .obj form as well as encapsulated Postscript (or PDF if you are using pdflatex). For a multiple document project, a master .tar.gz file is created containing the entire project as well as smaller .tar.gz files for each document.

dvi Target
Performs all processing required to produce the .dvi file for the project.

html Target
Performs all processing required to produce HTML output for the project.

pdf Target
Performs all processing required to produce a PDF (Portable Document Format) file, .pdf, for the project.

print Target
Sends the processed document to the printer.

ps Target
Performs all processing required to produce a Postscript file, .ps, for the project.

rtf Target
Performs all processing required to produce a RTF (Rich Text Format) file, .rtf, for the project. Please note that the ability of LaTex to RTF converters to work correctly is somewhat limited. Your mileage may vary.

show-var Target
This target is used to help debug users Makefiles as well as the LaTeX-Mk system. This target displays the value of the variable whose name is given by the variable VARNAME. For example: 
            make show-var VARNAME=TEXSRCS
will display the value of the TEXSRCS variable.

view Target
Previews the .dvi file.

viewpdf Target
Previews the PDF (.pdf) file.

viewps Target
Previews the Postscript (.ps) file.

Draft Targets

LaTeX-Mk supports adding a DRAFT watermark and timestamp for the Postscript, PDF, and printed output. To produce the draft versions, simply append -draft to the target. The currently supported draft targets are:

pdf-draft Target
Draft version of the pdf target.

ps-draft Target
Draft version of the ps target.

print-draft Target
Draft version of the print target.

viewpdf-draft Target
Draft version of the viewpdf target.

viewps-draft Target
Draft version of the viewps target.

Per Document Targets

LaTeX-Mk supports multiple top level documents in a single directory controlled by a single makefile. For each top level document specified in the NAME variable (more on variables later), there will be a set of targets defined which are specific to the document. The per document targets are:

print_<name> Target
Prints the Postscript file <name>.ps.

view_<name> Target
Previews the DVI file <name>.dvi.

viewpdf_<name> Target
Previews the PDF file <name>.pdf.

viewps_<name> Target
Previews the Postscript file <name>.ps.

In addition, draft versions of these targets exist:

print_<name>-draft Target
Draft version of the print_<name> target.

ps_<name>-draft Target
Draft version of the ps_<name> target.

view_<name>-draft Target
Draft version of the view_<name> target.

viewpdf_<name>-draft Target
Draft version of the viewpdf_<name> target.

viewps_<name>-draft Target
Draft version of the viewps_<name> target.

Node: Variables, Next: , Previous: Targets, Up: Top

Variables

The variables used by LaTeX-Mk can be categorized roughly into two groups. The first set of variables are typically set during the installation of LaTeX-Mk and these defaults used for all projects. These variables can be overridden on a per-user or per-project basis for maximum flexibility. The second set of variables are set by the user on a per-project basis.

Site Configuration Variables

This section documents the variables which are typically set on a site-wide or user-wide basis.

Site and User Configuration File

MAKECONF Variable
This variable is set to the location of the site-wide configuration file. If this file exists, it is sourced at the beginning of the LaTeX-Mk code. Default is ${sysconfdir}/latek-mk.conf for BSD make and ${sysconfdir}/latex-gmk.conf for GNU make. This is where system administrators can set system wide configuration variables. Any variables defined here should be defined using VARIABLE?= "new value" instead of VARIABLE= "new value" so that individual users can easily override the setting. The default setting may be changed during configuration of the package using the --with-mkconf and --with-gmkconf flags to configure. The sysconfdir directory can be specified to configure with the --sysconfdir= option.

USER_MAKECONF Variable
This variable is set to the location of a users personal configuration file. If this file exists, it is sourced at the beginning of the LaTeX-Mk code. Default is $HOME/.latex-mk.conf for BSD make and $HOME/.latex-gmk.conf for GNU make. This file is sourced before the file specified by MAKECONF. The default setting may be changed during configuration of the package using the --with-usermkconf and --with-usergmkconf flags to configure.

Generic Project Variables

This section documents the variables which are typically set on a site-wide or user-wide basis. In a typical installation these variables do not need to be explicitly set as they will take on reasonable defaults.

BIBTEX Variable
The bibtex executible. Defaults to bibtex.

BIBTEX_ENV Variable
A list of variables to be set in the environment when bibtex is run. For example: 
          BIBTEX_ENV+=	BIBINPUTS=.:/home/usr/bib:
Defaults to .

BIBTEX_FLAGS Variable
A list of flags to be passed to the BIBTEX executible. Defaults to .

CONVERT Variable
The image file format conversion executible which is part of the ImageMagick (<http://imagemagick.org/>) suite. Defaults to convert.

DVIPDFM Variable
The executible which produces PDF files from .dvi files. Defaults to dvipdfm. Note that the default behavior is to use DVIPS to produce Postscript and then PS2PDF to produce a PDF file. To use DVIPDFM to directly produce PDF from DVI, set the USE_DVIPDFM variable.

DVIPDFM_ENV Variable
A list of variables to be set in the environment when DVIPDFM is executed. Defaults to .

DVIPDFM_FLAGS Variable
A list of flags to be passed to the DVIPDFM executible. Defaults to

DVIPDFM_LANDSCAPE_FLAGS Variable
A list of flags to be added to DVIPDFM_FLAGS when the LANDSCAPE variable is set. Defaults to -l.

DVIPS Variable
The executible which produces Postscript files from .dvi files. Defaults to dvips.

DVIPS_FLAGS Variable
A list of flags to be passed to the DVIPS executible. Defaults to -j0. Note: versions of latex-mk prior to 1.2 used -Ppdf -j0 as the default. If you wish to maintain this behavior on latex-mk-1.2 and newer, you will need to set this variable in your site or user configuration file.

DVIPS_LANDSCAPE_FLAGS Variable
A list of flags to be added to DVIPS_FLAGS when the LANDSCAPE variable is set. Defaults to -t landscape.

GV Variable
The executible which previews Postscript files. Defaults to gv.

GV_FLAGS Variable
A list of flags to be passed to the GV executible. Defaults to .

GV_LANDSCAPE_FLAGS Variable
A list of flags to be added to GV_FLAGS when the LANDSCAPE variable is set. Defaults to -landscape.

GZCAT Variable
The gzcat file decompression utility. Defaults to gzcat.

GZIP Variable
The gzip file compression utility. Defaults to gzip.

HEVEA Variable
The Hevea executible. Defaults to hevea.

HEVEA_ENV Variable
A list of variables to be set in the environment when HEVEA or IMAGEN is run. For example: 
          HEVEA_ENV+=	TEXINPUTS=.:/home/usr/tex:
Defaults to .

HEVEA_FLAGS Variable
A list of flags to be passed to the HEVEA executible. Defaults to -fix.

IMAGEN Variable
The imagen executible (part of HeVeA). Defaults to imagen.

JPG2EPS Variable
The command to convert a JPEG file to an Encapsulated Postscript (EPS) file. Defaults to ${CONVERT}.

LATEX Variable
The LaTeX executible. Defaults to latex.

LATEX_ENV Variable
A list of variables to be set in the environment when LATEX is run. For example: 
          LATEX_ENV+=	TEXINPUTS=.:/home/usr/tex:
Defaults to .

LATEX_FLAGS Variable
A list of flags to be passed to the LATEX executible. Defaults to .

LATEX2HTML Variable
The LaTex2HTML executible. Defaults to latex2html.

LATEX2HTML_ENV Variable
A list of variables to be set in the environment when LATEX2HTML is run. For example: 
          LATEX2HTML_ENV+=	TEXINPUTS=.:/home/usr/tex:
Defaults to .

LATEX2HTML_FLAGS Variable
A list of flags to be passed to the LATEX2HTML executible. Defaults to -image_type png -local_icons -show_section_numbers.

LATEX2RTF Variable
The LaTex2rtf executible. Defaults to latex2rtf.

LATEX2RTF_ENV Variable
A list of variables to be set in the environment when LATEX2RTF is run.

LATEX2RTF_FLAGS Variable
A list of flags to be passed to the LATEX2RTF executible. Defaults to .

LPR Variable
The executible which spools Postscript files to a printer. Defaults to lpr.

LPR_FLAGS Variable
A list of flags to be passed to the LPR executible. For example: 
          LPR_FLAGS=	-Pbeernuts
Defaults to .

MAKEIDX Variable
The makeindex executible. Defaults to makeindex.

MAKEIDX_FLAGS Variable
A list of flags to be passed to the MAKEIDX executible. Defaults to .

PDFLATEX Variable
The PDFLaTeX executible. Defaults to pdflatex.

PDFLATEX_ENV Variable
A list of variables to be set in the environment when PDFLATEX is run. For example: 
          PDFLATEX_ENV+=	TEXINPUTS=.:/home/usr/tex:
Defaults to .

PDFLATEX_FLAGS Variable
A list of flags to be passed to the PDFLATEX executible. Defaults to .

PNG2EPS Variable
The command to convert a Portable Network Graphic (PNG) file to an Encapsulated Postscript (EPS) file. Defaults to ${CONVERT}.

POST_BIBTEX_HOOK Variable
If this variable is set to the name of an executible, then LaTeX-Mk will run this program/script immediately after a BibTeX run. This hook provides the ability to do post-processing of the BibTeX output prior to the final LaTeX run(s). This feature is likely to be of interest to advanced users only. The program/script is run in the same environment as specified by LATEX_ENV and is given the project name as an argument. For example if your Makefile contains 
          NAME= mydoc
          POST_BIBTEX_HOOK=  ./my_bib_fixup
then the after BibTeX is run, ./my_bib_fixup mydoc will be run. POST_BIBTEX_HOOK defaults to .

PS2PDF Variable
The executible which produces PDF (.pdf) files from Postscript (.ps) files. Defaults to ps2pdf.

PS2PDF_FLAGS Variable
A list of flags to be passed to the PS2PDF executible. Defaults to .

TAR Variable
The tar tape archiver utility. Defaults to tar.

TEX2PAGE Variable
The tex2page executible. Defaults to tex2page.

TEX2PAGE_ENV Variable
A list of variables to be set in the environment when TEX2PAGE is run. For example: 
          TEX2PAGE_ENV+=	TEXINPUTS=.:/home/usr/tex:
Defaults to .

TEX2PAGE_FLAGS Variable
A list of flags to be passed to the TEX2PAGE executible. Defaults to .

USE_DVIPDFM Variable
When set, this variable causes the DVIPDFM program to be used to directly generate .pdf files from the .dvi files instead of using DVIPS to generate a Postscript file and then PS2PDF to convert the Postscript to PDF. Please note that the use of this option currently precludes the generation of the -draft versions of PDF files.

USE_HEVEA Variable
When set, this variable causes the HEVEA program to be used to generate HTML output.

USE_LATEX2HTML Variable
When set, this variable causes the LATEX2HTML program to be used to generate HTML output.

USE_PDFLATEX Variable
When set, this variable causes the PDFLATEX program to be used to directly generate .pdf files from the .tex files instead of using LATEX to generate a .dvi file, DVIPS to generate a Postscript file and then PS2PDF to convert the Postscript to PDF. Please note that the use of this option currently precludes the generation of the -draft versions of PDF files.

USE_TEX2PAGE Variable
When set, this variable causes the TEX2PAGE program to be used to generate HTML output.

VIEWPDF Variable
The executible which previews .pdf files. Defaults to gv.

VIEWPDF_FLAGS Variable
A list of flags to be passed to the VIEWPDF executible. Defaults to .

VIEWPDF_LANDSCAPE_FLAGS Variable
A list of flags to be added to VIEWPDF_FLAGS when the LANDSCAPE variable is set. Defaults to -landscape.

XDVI Variable
The executible which previews .dvi files. Defaults to xdvi.

XDVI_FLAGS Variable
A list of flags to be passed to the XDVI executible. Defaults to .

XDVI_LANDSCAPE_FLAGS Variable
A list of flags to be added to XDVI_FLAGS when the LANDSCAPE variable is set. Defaults to -paper usr.

Lgrind Site Configuration Variables

This section documents the variables related to lgrind source code processing. Lgrind is a source code formatter which takes source code files in various programming languages and formats them for inclusion in a LaTeX document.

LGRIND Variable
The lgrind executible used for formatting source code for inclusion into a LaTeX document. Defaults to lgrind.

LGRIND_FLAGS Variable
A list of flags to be passed to the LGRIND executible. For example: 
          LGRIND_FLAGS=	-i -t 4 -d /my/private/lgrindef
Defaults to -i.

Tgif Site Configuration Variables

This section documents the variables related to Tgif file processing. Tgif (<http://bourbon.usc.edu:8001/tgif/tgif.html>) is a nice vector drawing program which works well with LaTeX. Please note that LaTeX-Mk requires that all Tgif files use the extension .obj.

TGIF Variable
The tgif executible. Defaults to tgif.

TGIF_FLAGS Variable
A list of flags to be passed to the TGIF executible to cause it to print to a file. These flags will be used for both PDF and EPS export. Defaults to -color -print.

TGIF_EPS_FLAGS Variable
A list of flags to be passed to the TGIF executible when exporting to an encapsulated Postscript, .eps, file. Defaults to -eps.

TGIF_PDF_FLAGS Variable
A list of flags to be passed to the TGIF executible when exporting to a PDF, .pdf, file. Defaults to -pdf.

Xfig Site Configuration Variables

This section documents the variables related to Xfig file processing. Please note that LaTeX-Mk requires that all Xfig files use the extension .fig.

FIG2DEV Variable
The executible which can convert xfig .fig files to encapsulated Postscript .eps files. Defaults to fig2dev.

FIG2DEV_FLAGS Variable
A list of flags to be passed to the FIG2DEV executible to cause it to print to a file. These flags will be used for both PDF and EPS export. Defaults to .

FIG2DEV_EPS_FLAGS Variable
A list of flags to be passed to the FIG2DEV executible when exporting to an encapsulated Postscript, .eps, file. Defaults to -L eps.

FIG2DEV_PDF_FLAGS Variable
A list of flags to be passed to the FIG2DEV executible when exporting to a PDF, .pdf, file. Defaults to -L pdf.

Per-Project Variables

This section documents variables which can be set in project Makefiles to accommodate other dependencies which may be added.

Required Variables

Every project must define the NAME variable.

NAME Variable
Name of the project. The top level LaTeX input file is assumed to be called <NAME>.tex. For projects which have multiple documents, you would list the top level name for each document here. For example, if you have a single document, mydoc, you would use 
          NAME= mydoc
and if you have multiple documents, mydoc1, mydoc2, and mydoc3, you would use 
          NAME= mydoc1 mydoc2 mydoc3

Generic Variables

The variables described in this section affect all of the top level documents listed in the NAME variable. This is useful for listing common dependencies like a header or style file used by all documents. To list dependencies which are specific to one of the top level documents, you can use the variable <docname>_<VARNAME> where <docname> is the name of the document and <VARNAME> is the name of the variable. For example, 

     NAME= doc1 doc2
     TEXSRCS= header.tex
     doc1_TEXSRCS= intro1.tex body1.tex conclusions.tex
defines a project with two top level documents, doc1 and doc2. Both documents depend on header.tex and in addition, doc1 depends on intro1.tex, body1.tex, and conclusions.tex. More information on the TEXSRCS variable is given later.

BIBTEXSRCS Variable
All files listed in this variable are assumed to be BibTeX input files. Listing files in this variable will cause a dependency to be added to the top level project and BibTeX will be run on these files as needed.

CLEAN_FILES Variable
Files listed in this variable will be removed when the clean target is made. When setting this variable in a Makefile, the += syntax should be used to append to this variable. For example: 
          CLEAN_FILES+=   my_leftover_file foo.bak
will add my_leftover_file and foo.bak to the list of files to be removed when make clean is run.

EXTRA_DIST Variable
Files listed in this variable will be added to the archive file created with the dist target. 
          EXTRA_DIST+=   README.txt

OTHER Variable
Files listed in this variable will be added to the dependency list for the .dvi file. For example if you want to add all .eps and .epsi files in a particular directory as well as some .png files from another directory to the dependency list, then using BSD make, you could add: 
          OTHER_EPS!=     ls eps/*.eps*
          OTHER+=         $(OTHER_EPS)
          OTHER_PNG!=	ls png/*.png
          OTHER+=         $(OTHER_PNG:.png=.eps)
          CLEAN_FILES+=   $(OTHER_PNG:.png=.eps)
If you are using GNU make, you would use 
          OTHER_EPS=      $(wildcard eps/*.eps*)
          OTHER+=         $(OTHER_EPS)
          OTHER_PNG=      $(wildcard png/*.png)
          OTHER+=         $(OTHER_PNG:.png=.eps)
          CLEAN_FILES+=   $(OTHER_PNG:.png=.eps)

TEXSRCS Variable
All files listed in this variable are assumed to be LaTeX input files. Listing files in this variable will cause a dependency to be added to the top level project. All LaTeX files used in the project should be listed in this variable with the exception of the top level LaTeX file which is automatically included by LaTeX-Mk.

Per-Project Lgrind Variables

LGRINDSRCS Variable
All files listed in this variable are assumed to be source code files to be processed by lgrind. Listing files in this variable will cause a dependency to be added to the top level project and will cause these files to be automatically re-formatted as required.

LGRINDDIRS Variable
A list of directories containing source code can be listed in this variable. All files found in those directories which have extensions will be formated using lgrind. Files without a .* extension will be ignored. These files will be added to the top level dependency list and will be automatically re-formatted as required.

foo_LGRIND_FLAGS Variable
This variable sets specific flags which should be passed to lgrind when processing the source file foo. For example, 
          mymodule.v_LGRIND_FLAGS=        -lverilog

If foo is a directory which has been listed in LGRINDDIRS, then foo_LGRIND_FLAGS will be used for all files in the specified directory. You can define flags for an entire directory and then override it for a single file if needed. For example, suppose you want to use 4 as the tab width for all sources in the directory srcs except for srcs/funny.c where you want to use a tab width of 8. You would achieve this with 

          srcs_LGRIND_FLAGS=              -t 4
          srcs/funny.c_LGRIND_FLAGS=      -t 8

Per-Project Tgif Variables

TGIFSRCS Variable
All files listed in this variable are assumed to be tgif .obj files. Listing files in this variable will cause a dependency to be added to the top level project and will cause these files to be automatically re-exported to Postscript as required.

TGIFDIRS Variable
A list of directories containing tgif drawings can be listed in this variable. All .obj files found in those directories are assumed to be tgif .obj files. These files will be added to the top level dependency list and will be automatically re-exported to Postscript as required.

Per-Project Xfig Variables

XFIGSRCS Variable
All files listed in this variable are assumed to be xfig .fig files. Listing files in this variable will cause a dependency to be added to the top level project and will cause these files to be automatically re-exported to Postscript as required.

XFIGDIRS Variable
A list of directories containing xfig drawings can be listed in this variable. All .fig files found in those directories are assumed to be xfig .fig files. These files will be added to the top level dependency list and will be automatically re-exported to Postscript as required.

Node: HTML, Next: , Previous: Variables, Up: Top

HTML Output

LaTeX-Mk includes support for generating HTML output. Currently Latex2HTML (see <http://www.latex2html.org>), HeVeA (see <http://para.inria.fr/~maranget/hevea/>), or tex2page (see <http://www.ccs.neu.edu/home/dorai/tex2page/>) can be used for producing an HTML version of your document. The selection of which program to use is done with the USE_HEVEA, USE_LATEX2HTML, and USE_TEX2PAGE variables. Simply define one of these in your ${sysconfdir}/latex-mk.conf file (for site-wide configuration) or $HOME/.latex-mk.conf (for per-user configuration). If you are using GNU make, the variable would be set in ${sysconfdir}/latex-gmk.conf or $HOME/.latex-gmk.conf instead. You can also override this setting in your project Makefile. For example, to use Latex2HTML, add 

     USE_LATEX2HTML=  yes
to your configuration file or to your project Makefile.

To generate HTML output, simply run make html. The HTML output along with any image files will be placed in a subdirectory called ${NAME}.html_dir. For example, if you have a project with two top level documents, your Makefile might look like: 

     NAME=  doc1 doc2
     .include "/usr/pkg/share/latex-mk/latex.mk"
After running make html, you will have two new subdirectories called doc1.html_dir and doc2.html_dir containing HTML versions of the two documents.

To keep track of which files have been generated during the conversion, a temporary file, ${NAME}.www_files gets created and all generated files are recorded there. This allows the output produced by HeVeA to be moved to the correct subdirectory as well as allowing make clean to work.

The HTML generation is still new and there are probably some bugs to work out. Please submit bug reports. There are also some features which may be useful that have not been integrated. For example the program hacha could be used for breaking the HeVeA output into several smaller files.

Node: Recursive, Next: , Previous: HTML, Up: Top

Using LaTeX-Mk Recursively

In some cases you may wish to organize multiple documents into their own subdirectories but still be able to build all of them with a single make call. This is supported in LaTeX-Mk via the use of the latex.subdir.mk makefile fragment. To use recursion, create a Makefile, in your top level directory which looks something like the following example. 

     
     SUBDIR+=        project1
     SUBDIR+=        project2
     SUBDIR+=        project3
     
     .include "/usr/local/share/latex-mk/latex.subdir.mk"
Now create your usual LaTeX-Mk Makefiles in the project1, project2, and project3 subdirectories. Additional subdirectories are added to the SUBDIR variable. Multiple levels of subdirectories make be used. Please note that currently the use of both latex.mk and latex.subdir.mk in a single Makefile is not supported.

Node: Obtaining, Next: , Previous: Recursive, Up: Top

Obtaining LaTeX-Mk

The latest information and version of LaTeX-Mk can be found on the main LaTeX-Mk web site at <http://latex-mk.sourceforge.net>. A package for the NetBSD operating system (see <http://www.NetBSD.org> for information about NetBSD) exists at <ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/print/latex-mk/README.html>. A port for the FreeBSD operating system (see <http://www.FreeBSD.org> for information about FreeBSD) exists at <http://www.freshports.org/misc/latex-mk>.

Node: Installation, Next: , Previous: Obtaining, Up: Top

Installing LaTeX-Mk

System Requirements

To configure and install LaTeX-Mk, you will need a Unix-like operating system or shell with a compatible make program. In addition, to use LaTeX-Mk, you will require:

  1. latex. The development of LaTeX-Mk was done using Thomas Esser's TeX distribution, teTeX, version 1.0.7. More information on teTeX can be found at <http://www.tug.org/tetex/>.
  2. Either GNU make version 3.80 or higher or a BSD make program. For information on GNU make, see <http://www.gnu.org/software/make/>. For information on the NetBSD operating system (which of course includes BSD make), see <http://www.netbsd.org>. If you wish to install BSD make on a non-BSD system, you can try downloading one of the bmake snapshots from files area of the LaTeX-Mk sourceforge project page at <http://www.sourceforge.net/projects/latex-mk>. The GNU make version requirement is firm. LaTeX-Mk will not work with versions of GNU make prior to 3.80. It is highly unlikely that LaTeX-Mk will be ported to older GNU make versions due to the lack of some important features in older versions.

Installation

Installation of LaTeX-Mk consists of three steps: configuration, building, and installing. In a typical installation, this is as simple as 

     ./configure
     make
     make install
This will configure LaTeX-Mk with the defaults, create the final files to be installed, and install them in the proper location. The configure script is a standard GNU autoconf script. The most common option is the --prefix=<installation prefix> option. This causes LaTeX-Mk to use <installation prefix> as the base directory for the installation.

Running configure --help will give a list of the available configuration options. The ones which are specific to LaTeX-Mk, as opposed to being generic configure options are listed here. --with-mkconf=<mkconf>: this option changes the default system configuration file for BSD make. This file defaults to ${sysconfdir}/latex-mk.conf. --with-gmkconf=<gmkconf>: this option changes the default system configuration file for GNU make. This file defaults to ${sysconfdir}/latex-gmk.conf. --with-usermkconf=<usermkconf>: this option changes the default user configuration file for BSD make. This file defaults to $HOME/.latex-mk.conf. --with-usergmkconf=<usergmkconf>: this option changes the default user configuration file for GNU make. This file defaults to $HOME/.latex-gmk.conf.

Node: Feedback, Next: , Previous: Installation, Up: Top

Feedback

To report bugs, provide feedback, suggest new features, etc. visit the LaTeX-Mk Project management page at <http://www.sourceforge.net/projects/latex-mk> or send email to the author at danmc@users.sourceforge.net. For information on the current version of LaTeX-Mk, visit the LaTeX-Mk homepage at <http://latex-mk.sourceforge.net>.

Node: Alternatives, Next: , Previous: Feedback, Up: Top

Alternatives

There are a few tools which are somewhat similar to LaTeX-Mk. I have not reviewed them in any detail and thus am unable to comment on how similar or different they are compared to LaTeX-Mk.

  1. "mk" <http://www.servalys.nl/scripts/>

Node: History, Next: , Previous: Alternatives, Up: Top

History

The Dark Ages

In the beginning I used a WYSIWYG word processor from a large software vendor in the Pacific Northwest of the US. It worked for short papers, it was horrible for medium to long documents, painful for equations, and painful for figures. Then I learned LaTeX and life was much much better.

The Giant Per-Project Makefile

In graduate school, a friend showed me a makefile he had set up for his thesis. It contained all sorts of targets and some intelligence about running LaTeX multiple times for resolving references. I made a modified version of that for my thesis and even wrote a book where I used yet another modified version of that makefile. This approach was much better than doing everything by hand because I had added a lot of functionality over my friends makefile. In particular, my new makefile automatically dealt with tgif figures and I had many many figures in the thesis and the book.

Despite the utility of the large customized makefile I had, it was not maintainable in the sense that every time I started a new document, I'd end up with another copy of a very large makefile to maintain. If I fixed a bug in one, I'd have several other documents in progress which needed updating.

Enter LaTeX-Mk

For those of you familiar with the build system used by the BSD operating systems, you'll know that for each program, there is a very simple makefile which lists the source files along with a couple of other variables which can optionally be set. Then a system makefile called bsd.prog.mk is included. That included makefile fragment has all the code required to provide all the standard targets, sets up the various compiler flags and correctly handles all the dependencies. It is maintainable because the bulk of the code is common and only needs to be maintained in one place.

Being inspired by the BSD style makefile approach, I converted my most up to date giant per-project makefile into an include-able makefile fragment and spent some time defining the interface a bit more generically than I'd done in the past. Since that time I've used the result, LaTeX-Mk, for the last few documents at school, some papers I've worked on since then and also for work related documentation. So far, the makefile framework has proven to be very useful and a big time saver for me. Since I believe in open-source software I felt it was appropriate to document my efforts and provide a packaged solution that others could also use.

The Modern Era of LaTeX-Mk

Version 0.9

Released on 2002-10-09, this was the first public release of LaTeX-Mk. My reason for using 0.9 instead of 1.0 is that LaTeX-Mk had not been tested or used much by others yet. Even though it works well for me, as with any product I'm sure others will quickly find other ways to use it that I had not anticipated. My goal is to collect feedback over the first few months of public consumption and come out with a 1.0 version which incorporates the primary improvements.

Version 0.9.1

This is a bug fix version released on 2002-10-29. The significant changes over the previous version are:

Version 1.0

This is the long awaited 1.0 release! Hopefully LaTeX-Mk can be considered production/stable at this point. This release was made on 2003-02-26. The significant changes/additions over the previous version are:

Version 1.1

This is the "HTML Support" release. Version 1.1 was released on 2003-06-15. The significant changes/additions over the previous version are:

Version 1.2

Version 1.2 was released on 2004-03-21. The significant changes/additions over the previous version are:

Version 1.3

Version 1.3 was released on 2004-05-29. The significant changes/additions over the previous version are:

Version 1.4

Version 1.4 was released on 2005-10-04. The significant changes/additions over the previous version are:

Version 1.5

Version 1.6

Version 1.7

Version 1.8

Node: Target Index, Next: , Previous: History, Up: Top

Target Index

Node: Variable Index, Next: , Previous: Target Index, Up: Top

Variable Index

Node: General Index, Previous: Variable Index, Up: Top

General Index