LaTeX-Mk


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 2.1A.


Next: , Previous: Top, Up: Top

1 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.


Next: , Previous: Introduction, Up: Top

2 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'.

2.1 Base Targets

The targets provided by LaTeX-Mk are:

— Target: clean

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.

— Target: dist

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.

— Target: dvi

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

— Target: html

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

— Target: pdf

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

— Target: print

Sends the processed document to the printer.

— Target: ps

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

— Target: rtf

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.

— Target: show-var

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.

— Target: view

Previews the .dvi file.

— Target: viewpdf

Previews the PDF (.pdf) file.

— Target: viewps

Previews the Postscript (.ps) file.

2.2 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:

— Target: pdf-draft

Draft version of the pdf target.

— Target: ps-draft

Draft version of the ps target.

— Target: print-draft

Draft version of the print target.

— Target: viewpdf-draft

Draft version of the viewpdf target.

— Target: viewps-draft

Draft version of the viewps target.

2.3 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:

— Target: print_<name>

Prints the Postscript file <name>.ps.

— Target: view_<name>

Previews the DVI file <name>.dvi.

— Target: viewpdf_<name>

Previews the PDF file <name>.pdf.

— Target: viewps_<name>

Previews the Postscript file <name>.ps.

In addition, draft versions of these targets exist:

— Target: print_<name>-draft

Draft version of the print_<name> target.

— Target: ps_<name>-draft

Draft version of the ps_<name> target.

— Target: view_<name>-draft

Draft version of the view_<name> target.

— Target: viewpdf_<name>-draft

Draft version of the viewpdf_<name> target.

— Target: viewps_<name>-draft

Draft version of the viewps_<name> target.


Next: , Previous: Targets, Up: Top

3 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.

3.1 Site Configuration Variables

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

3.1.1 Site and User Configuration File

— Variable: MAKECONF

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.

— Variable: USER_MAKECONF

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.

3.1.2 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.

— Variable: BIBTEX

The bibtex executible. Defaults to `bibtex'.

— Variable: BIBTEX_ENV

Deprecated. Actually this variable did not work correctly anyway. Use LATEX_ENV to set variables for both LaTeX and bibTeX runs.

— Variable: BIBTEX_FLAGS

A list of flags to be passed to the BIBTEX executible. Defaults to `'.

— Variable: CONVERT

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

— Variable: DVIPDFM

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.

— Variable: DVIPDFM_ENV

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

— Variable: DVIPDFM_FLAGS

A list of flags to be passed to the DVIPDFM executible. Defaults to `'.

To set flags on a per-document basis, you can use <docname>_DVIPDFM_FLAGS where <docname> is the name of the document.

— Variable: DVIPDFM_LANDSCAPE_FLAGS

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

— Variable: DVIPS

The executible which produces Postscript files from .dvi files. Defaults to `dvips'.

— Variable: DVIPS_ENV

A list of variables to be set in the environment when DVIPS is executed. Defaults to `'.

— Variable: DVIPS_FLAGS

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.

To set flags on a per-document basis, you can use <docname>_DVIPS_FLAGS where <docname> is the name of the document.

— Variable: DVIPS_LANDSCAPE_FLAGS

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

— Variable: GV

The executible which previews Postscript files. Defaults to `gv'.

— Variable: GV_FLAGS

A list of flags to be passed to the GV executible. Defaults to `'.

— Variable: GV_LANDSCAPE_FLAGS

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

— Variable: GZCAT

The gzcat file decompression utility. Defaults to `gzcat'.

— Variable: GZIP

The gzip file compression utility. Defaults to `gzip'.

— Variable: HEVEA

The Hevea executible. Defaults to `hevea'.

— Variable: HEVEA_ENV

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 `'.

— Variable: HEVEA_FLAGS

A list of flags to be passed to the HEVEA executible. Defaults to `-fix'.

— Variable: IMAGEN

The imagen executible (part of HeVeA). Defaults to `imagen'.

— Variable: JPG2EPS

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

— Variable: LATEX

The LaTeX executible. Defaults to `latex'.

— Variable: LATEX_ENV

A list of variables to be set in the environment when LATEX is run. For example:

          LATEX_ENV+=	TEXINPUTS=.:/home/usr/tex:
     

Defaults to `'.

— Variable: LATEX_FLAGS

A list of flags to be passed to the LATEX executible. Defaults to `'.

— Variable: LATEX2HTML

The LaTex2HTML executible. Defaults to `latex2html'.

— Variable: LATEX2HTML_ENV

A list of variables to be set in the environment when LATEX2HTML is run. For example:

          LATEX2HTML_ENV+=	TEXINPUTS=.:/home/usr/tex:
     

Defaults to `'.

— Variable: LATEX2HTML_FLAGS

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

— Variable: LATEX2RTF

The LaTex2rtf executible. Defaults to `latex2rtf'.

— Variable: LATEX2RTF_ENV

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

— Variable: LATEX2RTF_FLAGS

A list of flags to be passed to the LATEX2RTF executible. Defaults to `'.

— Variable: LPR

The executible which spools Postscript files to a printer. Defaults to `lpr'.

— Variable: LPR_FLAGS

A list of flags to be passed to the LPR executible. For example:

          LPR_FLAGS=	-Pbeernuts
     

Defaults to `'.

— Variable: MAKEGLS

The executible used to make glossaries. Defaults to `makeindex'.

— Variable: MAKEGLS_FLAGS

A list of flags to be passed to the MAKEGLS executible. Defaults to `'.

— Variable: MAKEIDX

The makeindex executible. Defaults to `makeindex'.

— Variable: MAKEIDX_FLAGS

A list of flags to be passed to the MAKEIDX executible. Defaults to `'.

— Variable: MPOST

The METApost executible. Defaults to `mpost'.

— Variable: MPOST_FLAGS

A list of flags to be passed to the MPOST executible. Defaults to `'.

— Variable: PDFLATEX

The PDFLaTeX executible. Defaults to `pdflatex'.

— Variable: PDFLATEX_ENV

A list of variables to be set in the environment when PDFLATEX is run. For example:

          PDFLATEX_ENV+=	TEXINPUTS=.:/home/usr/tex:
     

Defaults to `'.

— Variable: PDFLATEX_FLAGS

A list of flags to be passed to the PDFLATEX executible. Defaults to `'.

— Variable: PNG2EPS

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

— Variable: POST_BIBTEX_HOOK

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 `'.

— Variable: PS2PDF

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

— Variable: PS2PDF_FLAGS

A list of flags to be passed to the PS2PDF executible. Defaults to `'.

— Variable: TAR

The tar tape archiver utility. Defaults to `tar'.

— Variable: TEX2PAGE

The tex2page executible. Defaults to `tex2page'.

— Variable: TEX2PAGE_ENV

A list of variables to be set in the environment when TEX2PAGE is run. For example:

          TEX2PAGE_ENV+=	TEXINPUTS=.:/home/usr/tex:
     

Defaults to `'.

— Variable: TEX2PAGE_FLAGS

A list of flags to be passed to the TEX2PAGE executible. Defaults to `'.

— Variable: USE_DVIPDFM

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.

— Variable: USE_HEVEA

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

— Variable: USE_LATEX2HTML

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

— Variable: USE_PDFLATEX

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.

— Variable: USE_TEX2PAGE

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

— Variable: VIEWPDF

The executible which previews .pdf files. Defaults to `gv'.

— Variable: VIEWPDF_FLAGS

A list of flags to be passed to the VIEWPDF executible. Defaults to `'.

— Variable: VIEWPDF_LANDSCAPE_FLAGS

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

— Variable: XDVI

The executible which previews .dvi files. Defaults to `xdvi'.

— Variable: XDVI_FLAGS

A list of flags to be passed to the XDVI executible. Defaults to `'.

— Variable: XDVI_LANDSCAPE_FLAGS

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

3.1.3 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.

— Variable: LGRIND

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

— Variable: LGRIND_FLAGS

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'.

3.1.4 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.

— Variable: TGIF

The tgif executible. Defaults to `tgif'.

— Variable: TGIF_FLAGS

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'.

— Variable: TGIF_EPS_FLAGS

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

— Variable: TGIF_PDF_FLAGS

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

3.1.5 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.

— Variable: FIG2DEV

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

— Variable: FIG2DEV_FLAGS

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 `'.

— Variable: FIG2DEV_EPS_FLAGS

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

— Variable: FIG2DEV_PDF_FLAGS

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

3.2 Per-Project Variables

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

3.2.1 Required Variables

Every project must define the NAME variable.

— Variable: NAME

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
     

3.2.2 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.

— Variable: BIBTEXSRCS

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.

— Variable: CLEAN_FILES

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.

— Variable: EXTRA_DIST

Files listed in this variable will be added to the archive file created with the dist target.

          EXTRA_DIST+=   README.txt
     
— Variable: OTHER

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)
     
— Variable: TEXSRCS

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.

3.2.3 Per-Project Lgrind Variables

— Variable: LGRINDSRCS

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.

— Variable: LGRINDDIRS

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.

— Variable: foo_LGRIND_FLAGS

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
     

3.2.4 Per-Project META-post Variables

— Variable: MPOSTSRCS

All files listed in this variable are assumed to be META-post .mp 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 and/or PDF as required.

— Variable: MPOSTDIRS

A list of directories containing META-post figured can be listed in this variable. All .mp files found in those directories are assumed to be META-post .mp files. These files will be added to the top level dependency list and will be automatically re-exported to Postscript and/or PDF as required.

— Variable: MPOST_TWICE

By default META-post is run once for each of its input files. Setting this variable will cause META-post to run twice on each input file. Some figures may require this and I haven't figured out if there is a way to automatically make this determination like there is with LaTeX.

3.2.5 Per-Project Tgif Variables

— Variable: TGIFSRCS

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.

— Variable: TGIFDIRS

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.

3.2.6 Per-Project Xfig Variables

— Variable: XFIGSRCS

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.

— Variable: XFIGDIRS

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.


Next: , Previous: Variables, Up: Top

4 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.


Next: , Previous: HTML, Up: Top

5 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.


Next: , Previous: Recursive, Up: Top

6 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.


Next: , Previous: Obtaining, Up: Top

7 Installing LaTeX-Mk

7.1 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.

7.2 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.


Next: , Previous: Installation, Up: Top

8 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.


Next: , Previous: Feedback, Up: Top

9 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/


Next: , Previous: Alternatives, Up: Top

10 History

10.1 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.

10.2 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.

10.3 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.

10.4 The Modern Era of LaTeX-Mk

10.4.1 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.

10.4.2 Version 0.9.1

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

10.4.3 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:

10.4.4 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:

10.4.5 Version 1.2

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

10.4.6 Version 1.3

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

10.4.7 Version 1.4

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

10.4.8 Version 1.5

10.4.9 Version 1.6

10.4.10 Version 1.7

10.4.11 Version 1.8

10.4.12 Version 1.9

10.4.13 Version 1.9.1

10.4.14 Version 2.0

10.4.15 Version 2.1


Next: , Previous: History, Up: Top

Target Index


Next: , Previous: Target Index, Up: Top

Variable Index


Previous: Variable Index, Up: Top

General Index