Fetching contributors…
Cannot retrieve contributors at this time
629 lines (500 sloc) 22.9 KB

# Producing LaTeX documents

On this page, you will learn how to use BSD Owl Scripts to:

• Produce simple LaTeX documents and publish them on the file system.
• Install or publish LaTeX documents.
• Produce LaTeX documents in various output formats.
• Produce drafts of LaTeX documents.
• Produce documents having more than one source file.
• Produce documents including METAPOST figures.
• Produce standalone figures with METAPOST.
• Produce documents including BibTeX bibliographies
• Produce an index for a LaTeX document.
• Produce documents having parts that need to be automatically generated, like tables or database reports.
• Deal with documents whose source spans across several directories.
• Deal with a huge number of documents.

There is a useful program called latexmk whose functionality partially overlaps what BSD Owl Scripts offers. These tools are however built under distinct, complementary perpsectives. Indeed latexmk focuses on the very production of a document, while BSD Owl Scripts allows to integrate the production of this document in the context of the production of a full project. The integration of latexmk in BSD Owl Scripts is planned.

## Foreword — Working with TeX or LaTeX

There is multiple TeX formats in use, plain TeX and LaTeX are examples of such formats. The LaTeX format enjoys a wide community of users, so the module latex.doc.mk is used in examples. However most of the following also applies to the module tex.doc.mk supporting plain TeX. It is easy to write a customised version of latex.doc.mk to support other TeX formats, if required. Some paragraphs in the sequel document mechanisms specific to latex.doc.mk, they are explicitly identified as such.

## Produce simple LaTeX documents

Assume the file script.tex holds our manuscript. We put it in a directory dedicated to our document, and create a Makefile file (note the leading capital) with the following content:

DOCUMENT=		script.tex
.include "latex.doc.mk"

Our document's directory now contains the paper.tex file and the Makefile described above. We visit this directory with our shell and issue the make command:

% make
make build
===> Multipass job for script.pdf (aux)
latex script.tex
This is pdfeTeX, Version 3.141592-1.21a-2.2 (Web2C 7.5.4)
entering extended mode
(./script.tex
LaTeX2e <2003/12/01>
...

If our manuscript has no error, we end up with the following object files in our working directory:

% ls
Makefile    script.log
script.aux  script.tex
script.pdf  script.toc

Once we are done with these objects, we can clean the directory with the make clean mantra:

% make clean
rm -f script.pdf script.log script.aux script.toc

Cleaning the directory is an optional step, but it prevents our storage and your archive media to end up filled with unused data, that can be quickly recreated on demand. While DVI files are usually very small, a few hundred kilobytes, the PS or PDF objects are often much larger.

## Install or publish documents

Before we clean up your working directory with the make clean mantra, we may wish to store the document we created in some adequate place of the local file system. This step is called installation of our document, because it is analogous to the installation of a program we freshly compiled. We can require the installation of our document with the make install command, but we must first tell make which place is actually adequate. This is done by assigning the DOCDIR variable with the path to the directory we want our files to be copied to, as displayed by the following Makefile:

DOCUMENT=		script.tex
BIBINPUTS+=		${.CURDIR}/morebib USES+= bibtex .include "latex.doc.mk" We note that the make clean mantra will leave intact the BBL file produced by BibTeX. This is because we sometimes need to send this file to our publisher rather than an unprocessed BibTeX database. Hence the make clean or make distclean will leave our document's directory in the state we want to have it when we want to redistribute it. To get rid of the BBL file as well, we need to use the more powerful mantra make realclean. ## Produce an index for a LaTeX document If an index must be prepared for a LaTeX document with the program makeindex a USES+=index statement must be added to the Makefile, as displayed by the following example: DOCUMENT= galley.tex SRCS= part1.tex SRCS+= part2.tex USES+= index .include "latex.doc.mk" ## Several documents in the same directory While it is often a good idea to reserve a directory for each of your documents, we might have some reasons to keep several documents in the same directory. We have your reasons and they are probably good ones, so BSD Owl Scripts will do its best to help us. We assume that we have two documents whose sources are living in the same directory, let's say an article and an abridged version of this article. These manuscripts share a macro file macro.tex, but are otherwise rather independent from LaTeX's point of view. The text of the article is split across two files, section1.tex and section2.tex. The abridged version has just one text file summary.tex. The Makefile we use looks like this: DOCUMENT= article.tex DOCUMENT+= summary.tex SRCS= macros.tex SRCS.article.tex= section1.tex SRCS.article.tex+= section2.tex .include "latex.doc.mk" ## Produce documents having automatically generated parts Assume we are working on a document containing a table whose content is likely to change several times and will need to be updated. Such a table could be a budget: when the corresponding project evolves, so does the budget. It can be quite tedious to type in a table in LaTeX, and updating it might even be trickier. In such a situation, it is a good idea to write a program reading the raw data of our table and writing a LaTeX table displaying our data and everything we want to compute from it. Such a program is usually very easy to write, because we only need to deal with text files all of the time. The awk programming language could be a natural choice here but actually, almost any programming language would fit pretty neatly. So we have gathered the raw data of our table in the file table.raw and written a small filter gentable that will read that table data and write for us a LaTeX table on its standard output. In our manuscript, we use the name table to refer to the file containing the generated table. Here is our Makefile: DOCUMENT= galley.tex table.tex: gentable table.raw ./gentable < table.raw > table.tex REALCLEANFILES+= table.tex .include "latex.doc.mk" If we send your files to someone else, he will maybe not want to run our program gentable, so it is better to list table.tex in REALCLEANFILES rather than in CLEANFILES: we can clean your directory with make clean, archive its contents and send the archive to someone else without handling the generated table.tex in a special way. Of course, we can compute some text or a METAPOST picture, or pretty-print a piece of code, or whatever, instead of generating a table! Note that if you take advantage of the OBJDIR feature of BSD Owl Scripts, the production rule for table.tex should actually be: table.tex: gentable table.raw${.CURDIR}/gentable < ${.ALLSRC:M*.raw} >${.TARGET}
.include "latex.doc.mk"

The special variables .CURDIR, .ALLSRC and .TARGET are aware of the mechansisms involved in the use of OBJDIR.

## Deal with documents whose source spans across several directories

Some workflows may prescribe that our source files are not located in a single directory, but disseminated across the file system.

A reason for doing this could be that our organisation uses a custom document class for its letters, where some picture appears. We do not want to copy the picture file in each of the folders hosting our letters, nor do we want to have a symbolic link to the picture in each of our directories because the file is irrelevant to our work: we just want to not even know anything about the existence of this picture. The solution to this problem is to rely on the TEXINPUTS variable, its content is a list of directories searched by TeX for its input files.

Another reason motivating the dissemination of source files in several directories could be the preparation of a large document such as a book. If the files for each chapter are in separated directories, it is easy to process an isolated chapter with LaTeX during the preparation of the manuscript, for the purpose of proofreading. TeX must find all these files when it processes the main file including all the chapters, which is achieved by setting TEXINPUTS to an appropriate value, as explained in the sequel.

We can set the TEXINPUTS variable in our environment or in our Makefile, or even write a custom Makefile template including this setting. The role of this variable for TeX is pretty similar to the role of the PATH environment variable for the shell.

Assume that the picture visually impersonating our organisation is saved in ${HOME}/share/texmf/tex/organisation/visual.eps. In order to let TeX look for files in the folder containing the picture, we add a TEXINPUTS statement to our Makefile, like this: DOCUMENT= galley.tex TEXINPUTS=${HOME}/share/texmf/organisation
.include "latex.doc.mk"

If we now run make in the folder containing this Makefile, we will see an output similar to the following in our terminal:

% make
make build
===> Multipass job for galley.pdf (aux)
env TEXINPUTS=".:${HOME}/share/texmf/organization:" pdflatex galley.tex This is pdfeTeX, Version 3.141592-1.21a-2.2 (Web2C 7.5.4) … Let us take a look at the TEXINPUTS assignment which is part of the env command. Its difference with respect to the declaration in the Makefile above means that TeX will also look for files in the current directory (this is what the initial dot stands for) and all standard TeX locations (this is what the final colon stands for). If we want to have absolute control on the value of TEXINPUTS, we must add the assignment USES+=texinputs:strict in our Makefile. If it reads this statement BSD Owl Scripts will refrain from adding the initial dot and the final colon to our TEXINPUTS declaration. The supporting macros for METAPOST also understand TEXINPUTS and USES+=texinputs:strict. There is an analogous variable MPINPUTS governing the look up of METAPOST input files, it is accompanied with an USES+=mpinputs:strict option. If we want to have our TeX program and our METAPOST program to be run with different values for TEXINPUTS, we can pass the correct value to METAPOST through the MPTEXINPUTS variable, this variable is also accompanied by an USES+=mptexinputs:strict option. ## Deal with a huge number of documents We demonstrate how to use the bps.subdir.mk module to organise a collection of documents. For the purpose of the example, we assume that we are preparing an electronic journal and want to distribute each article of the journal as a separate electronic document. We use the following simple organisation: 1. We prepare a directory holding each issue of our journal, for instance ~/journal. 2. Each issue of the journal is represented by a subdirectory. 3. Each article of the journal is represented by a subdirectory of the directory corresponding to the issue it belongs to. Assume we already have several articles, as demonstrated by the following commnad output: % find ./journal -type f ./journal/issue-2013-1/01-galdal/Makefile ./journal/issue-2013-1/01-galdal/article.tex ./journal/issue-2013-1/02-arathlor/Makefile ./journal/issue-2013-1/02-arathlor/article.tex ./journal/issue-2013-2/01-mirmilothor/Makefile ./journal/issue-2013-2/01-mirmilothor/article.tex ./journal/issue-2013-2/02-eoron/Makefile ./journal/issue-2013-2/02-eoron/article.tex ./journal/issue-2013-2/03-echalad/Makefile ./journal/issue-2013-2/03-echalad/article.tex Names like galdal, arathlor are the names of fictional authors of articles of our journal. Each submission has a directory containing the text article.tex of the article and a Makefile similar to those described on this page which can be used to build the matching article. Each of these Makefiles can actually be as simple as DOCUMENT= article.tex .include "latex.doc.mk" To orchestrate the preparation of all our articles with BSD Owl Scripts we just need to write additional Makefiles: ./journal/Makefile ./journal/issue-2013-1/Makefile ./journal/issue-2013-2/Makefile ./journal/issue-2013-3/Makefile  Each Makefile basically contains the list of subdirectories where make should descend to actually build, install or clean. So the file ./journal/Makefile should contain: PACKAGE= journal SUBDIR= issue-2013-1 SUBDIR+= issue-2013-2 SUBDIR+= issue-2013-3 .include "bps.subdir.mk" The file ./journal/issue-2013-1/Makefile should contain: SUBDIR= 01-galdal SUBDIR+= 02-arathlor .include "bps.subdir.mk" The remaining files ./journal/issue-2013-2/Makefile and ./journal/issue-2013-3/Makefile can be similarly prepared. With these settings, the targets all, build, clean, distclean, realclean and install are delegated to Makefiles found in the subdirectories listed by SUBDIR. The variable SUBDIR_PREFIX can be used to define a customised installation path for each article, so that the Makefile building a document could be DOCUMENT= article.tex DOCDIR=${HOME}/publish/journal${SUBDIR_PREFIX} .include "latex.doc.mk" With this setting, the document ./journal/issue-2013-1/01-galdal/article.pdf will be installed as ${HOME}/publish/journal/issue-2013-1/01-galdal/article.pdf and so on. It is possible to tweak this in all possible ways to use arbitrary naming schemes for installed articles.

You can’t perform that action at this time.