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.
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.
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.tocOnce 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.tocCleaning 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.
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
DOCDIR= ${HOME}/doc/report
.include "latex.doc.mk"We can then proceed with the make install command:
% make install
install -d /home/michi/doc/report
install -o michi -g michi -m 440 script.pdf /home/michi/doc/reportIn comparison with the manual approach for storing the object in a
safe place with the cp command, we save retyping the target
directory name the next time we update our document. But delegating
this easy step to the Makefile has other benefits:
- It eases the organisation of our document sources library.
- It scales to a large number of documents, see Working with a large number of documents below.
- In draft-mode, a time stamp identifying the compilation time or the last modification time is automatically added to the file name, see below.
The TeX tool chain is capable of producing electronic documents in
several formats. Commonly used formats are DVI, PostScript (PS) and
PDF. The TEXDEVICE variable governs the format of documents produced
with the help of latex.doc.mk. Its value is usually pdf, so
that latex.doc.mk will produce a PDF file from our source. Other
possible values are ps or dvi. If we configured a
PostScript printer TEXPRINTER with the texconfig program, we
also can use TEXPRINTER.ps as a value in TEXDEVICE, it will
instruct dvips to use the settings for TEXPRINTER when translating
our DVI file to PostScript. It is also possible to list several
output formats in TEXDEVICE, like dvi pdf ps.TEXPRINTER1 ps.TEXPRINTER2.
Some formats or macros need our manuscript to be processed several
times by TeX or LaTeX before we obtain the final version of our
document. The latex.tex.mk module enforces multipass treatment of
the manuscript, because LaTeX needs this to produce correct cross
references created with label and ref commands within our
document. The doc.tex.mk module will not do multiple treatment of
our manuscript unless we set the variable MULTIPASS to a list of
names, each element giving its name to a pass. The choice of these
names does not have a real importance, as they are only displayed to
the user.
In the early stages of existence of a document, updates are likely to
be frequent and it is thus desirable to avoid the lengthy multiple
passes processing. BSD Owl Scripts has a draft mode for this.
To enable the draft mode, we add a statement USES+= draft to
our Makefile, as shown by the following example:
DOCUMENT= script.tex
USES+= draft
.include "latex.doc.mk"When we have finished polishing your manuscript, we can remove the
USES+= draft assignment from the Makefile, our paper is then ready for a
last make run producing the final version of our document. If we
are satisfied with it, we can install it.
When working on a document, it might be useful to keep copies of the objects we produced at some special point of your work. For instance, picture ourselves sending a copy of our work to a friend. Our friend will read our paper with attention and send us back his comments, but in the meanwhile, we kept on improving our document. When we receive the comments of our friend, we will compare them to the document we sent him. It is therefore useful to keep a copy of it. The best way to do this is to use a RCS, a special software keeping track of the various revisions of a file. Those who do not use such a system and want to try one might be interested in git, especially if they are relying on EMails to organise your collaborative work.
When working with the USES+= draft setting, the name of installed
documents is modified to display the time when make install was run.
This should help to identify the produced version. If we use a git
or subversion to keep track of the revision of our files,
we should modify the USES+= draft statement to
USES+= draft:git or USES+= draft:svn. If we do so, the time of
the last commit and its identifier (the short hash for git and the
revision number for subversion) is used to identify the produced version.
This is much more useful than the time at which make install was run
since it unambiguously identifies a state of our repository.
If we are working on a complex document, we certainly will split our sources into several files. Usually one file per chapter, or per section, plus a main file containing the preamble and many input statements to instruct LaTeX to read all of the files representing the document's contents.
Assume that our document is split into a main file galley.tex
and two other files part1.tex and part2.tex. Our galley.tex
certainly looks like this:
\documentclass{article}
\begin{document}
\input{part1}
\input{part2}
\end{document}A suitable Makefile is then:
DOCUMENT= galley.tex
SRCS= part1.tex
SRCS+= part2.tex
.include "latex.doc.mk"Modules latex.doc.mk and tex.doc.mk comes with a nice support for
METAPOST. This is something worth noting, since
METAPOST is often the right tool to be used for drawing figures
appearing in TeX documents, but support for it is missing in many GUI
editors for LaTeX.
These modules assume that METAPOST source does not manipulate the
values of the variables prologues, outputtemplate and
outputformat. They set-up these variables so that:
prologues := 3;
outputtemplate := "%j-%c.mps";
These setting are appropriate when working with modern versions of METAPOST and the graphicx LaTeX package. The first declaration parametrises the inclusion of fonts in the output, while the second reconfigures the names used for output.
Assume we prepared illustrations for our article with METAPOST,
and split our illustrations into two files illustr1.mp and
illustr2.mp. To let latex.doc.mk handle the production of our
figures, we add SRCS statements to your Makefile:
DOCUMENT= galley.tex
SRCS= part1.tex
SRCS+= part2.tex
SRCS+= illustr1.mp
SRCS+= illustr2.mp
.include "latex.doc.mk"We then type in make at the shell prompt. The latex.doc.mk will
figure out how many illustrations are present in each file, and
produce the image files required by our TEXDEVICE. For instance, if
our TEXDEVICE is pdf, and illustr1.mp contains two figures
introduced by beginfig(1) and beginfig(2), we end up with four files
% ls *.{mps,pdf}
illustr1-1.mps
illustr1-1.pdf
illustr1-2.mps
illustr1-2.pdfThe files ending in .mps are intermediary files in PostScript format,
and the remaining ones are PDF files suited for inclusion
in our document.
Using the graphicx package, inclusion is as easy as it should be:
\includegraphics{illustr1-1}%Discovering METAPOST. It seems that many people do not know about METAPOST. For those interested in discovering it, the first good news is that this program is included by many (if not all) TeX distributions, hence it is probably already available on their system. The second good news is that they can easily find plenty of information and examples of its use on the WWW. For instance, the TeX users group has a page on its website devoted to this tool. The list they will find there is pretty long, so let me add that I especially like the introduction written by André Heck, it might also be a good starting point for them.
The module mpost.doc.mk allows the creation of METAPOST pictures in
the following formats: Encapuslated PostScript, PDF, PNG and SVG.
Assume that we prepared two series of illustrations in files
illustr1.mp and illustr2.mp and we want to produce them in each of
the aforementioned formats. The corresponding Makefile is:
DOCUMENT= illustr1.mp
DOCUMENT+= illustr2.mp
MPDEVICE= eps pdf png svg
.include "mpost.doc.mk"BSD Owl Scripts support the preparation of bibliographies with BibTeX. First, we must be sure that the program TeX will find the bibliographic databases we enumerated in our document with bibliography statements. It is customary to gather these bibliographic databases in some directory, for instance ${HOME}/share/bib. To let BibTeX find these files, it is enough to add ${HOME}/share/bib to the content of the variable BIBINPUTS. If our bibliographic databases are scattered among several directories, we just need to let each of them appear in the value of the variable BIBINPUTS:
DOCUMENT= galley.tex
SRCS= part1.tex
SRCS+= part2.tex
BIBINPUTS= ${HOME}/share/bib
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.
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"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"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.
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.
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:
-
We prepare a directory holding each issue of our journal, for instance
~/journal. -
Each issue of the journal is represented by a subdirectory.
-
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.texNames 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.