Well, it feels like it has taken a lot of writing to get to this, the final Part of A minimal LuaTeX setup on Windows. At the end of Part 5 we had discussed creating a minimal TDS-compliant directory structure to contain the file types we need to install for a minimal plain TeX setup:

• TeX Font Metric files (extension .tfm)
• Font encoding files (extension .enc)
• Glyph data files (extension .pfb, on Windows)
• The plain TeX format file (extension .fmt)
• The plain TeX source files (plain.tex and hyphen.tex)
• .map files (specifically for pdfTeX)

We decided on a minimal TDS-compliant directory, starting with c:\luatexblog\texmf. Considering just the fonts, they will be located in subdirectories of c:\luatexblog\texmf. We’ll create a set of directories which follow the structure:

c:\luatexblog\texmf\fonts\[type]\[supplier]\[typeface]

Where [type] will be

• tfm: for .tfm files (TeX font metrics)
• type1: for .pfb files (Printer Font Binary)

Where [supplier] will be public (i.e., for free fonts) and [typeface] will simply be cm (for Computer Modern). In addition, under c:\luatexblog\texmf\fonts\ we’ll need to create directories for

• map: for .map files (pdfTeX and LuaTeX font mapping files)
• enc: for .enc files (font encoding)

Finally, we directories to contain

• plain TeX source files (plain.tex and hyphen.tex)
• the plain TeX .fmt file
• the texmf.cnf file that we’ll write for Kpathsea

Going back to the Kpathsea documentation which gives a nice example of a skeleton TDS, you should create a directory structure that looks something like this:

Note that if you add more .pfb files under the directory c:\luatexblog\texmf\fonts\type1 then it is best practice to create a new subdirectory whose name reflects the supplier, for example I have added “adobe” as an example. Under each supplier you add a name for the typeface, e.g., utopia, and that’s where you would put the .pfb files:

c:\luatexblog\texmf\fonts\type1\adobe\utopia\*.pfb

Here is where we will put the various files we need.

File type	TDS file path
.tfm	c:\luatexblog\texmf\fonts\tfm\public\cm\
.pfb	c:\luatexblog\texmf\fonts\type1\public\cm\
.enc	c:\luatexblog\texmf\fonts\enc\
.map	c:\luatexblog\texmf\fonts\map\
plain.tex	c:\luatexblog\texmf\tex\plain\base\
hyphen.tex	c:\luatexblog\texmf\tex\generic\hyphen\
texmf.cnf	c:\luatexblog\texmf\web2c\
plain.fmt	c:\luatexblog\texmf\web2c\

Filling these directories with files

Clearly, we will be generating plain.fmt and you saw in Part 5 where to get plain.tex and hyphen.tex. We will shortly be writing texmf.cnf by hand, so that leaves the following files to be obtained from somewhere:

• TeX Font Metric files (.tfm)
• Font encoding files (.enc)
• Glyph data files (.pfb, on Windows)
• .map files (specifically for pdfTeX)

But firstly, a note of caution

TeX Font Metric files (for text fonts) need to used and obtained with a little caution because they are tied to a specific font encoding. In general, and particularly with plain TeX (which assumes a certain encoding) you cannot just use them without knowing how they were encoded when they were created. For example, the afm2tfm.exe utility available from TeX Live (converts Adobe’s AFM files to TeX’s .tfm) can be given an encoding vector on its command line. Certainly, LaTeX has far more flexibility with encodings but plain TeX is rather less versatile.

Obtaining the .tfm files for the Computer Modern fonts

Using the method of browsing TeX Live, you can access the Computer Modern .tfm files here:

svn://tug.org/texlive/trunk/Master/texmf-dist/fonts/tfm/public/cm

One oddity: manfnt.tfm
This .tfm is required to build the plain TeX format and you can get it here.

Obtaining the .pfb files for the Computer Modern fonts

The American Mathematical Society provides the Computer Modern fonts in Adobe Type 1 format, which can be downloaded as part of their AMSFonts collection.

Obtaining the .map file for pdfTeX (pdftex.map)

I have created an absolutely minimal pdftex.map file which you can download from this site.

Obtaining the .enc files

In short, for this ultra-minimal setup you won’t need any so we’ll ignore them.

What about luatex.exe?

Download a copy of the latest binary and copy it to c:\luatexblog\luatex.exe.

Note: edit your PATH
Don’t forget that you will need to add c:\luatexblog to your computer’s PATH environment variable otherwise your PC won’t be able to find luatex.exe when you try to run it!

Kpathsea and texmf.cnf

We are nearly finished! All we now need to do is tell Kpathsea where to locate the various files in our minimal TDS tree and we do this through a texmf.cnf file that we must save to c:\luatexblog\texmf\web2c\texmf.cnf.

If you look at the texmf.cnf file supplied with TeX Live it looks quite daunting and complex because Kpathsea’s powerful searching algorithms allow you to construct quite complex expressions to describe paths and directory structures. Kpathsea allows you to create TeX installations of quite some complexity with multiple TDS trees being used for different purposes. We will not even touch a tiny fraction of Kpathsea’s power and flexibility.

See, for example

• Michael J Downes: Managing Multiple TDS Trees
• Siep Kroonenberg: Juggling texmf trees

Describing the features of Kpathsea in detail is far beyond the scope of this post, perhaps one for another day. Interested readers should refer to the Kpathsea documentation and the texmf.cnf file available on theTeX Live repository – it contains very many helpful comments. For those who are comfortable reading C, there is a lot of additional information in the comments scattered throughout the Kpathsea source code. Happy reading!

Final steps

1. Set an environment variable called TEXMFCNF which tells Kpathsea where to start looking for your configuration files (texmf.cnf). For our installation it should be set to
   • TEXMFCNF=c:\luatexblog\texmf\web2c\
2. Enable Kpathsea debugging environment variables:
   • KPATHSEA_DEBUG_OUTPUT=c:/kspsluatex.log
   • KPATHSEA_DEBUG=-1
3. Put the following into a text file called texmf.cnf and save it to
   c:\luatexblog\texmf\web2c

   
             WEB2C=c:/luatexblog/texmf/web2c
             TEXINPUTS = ./:c:/luatexblog/texmf/tex//
             TEXFONTMAPS = c:/luatexblog/texmf/fonts/map
             TFMFONTS = c:/luatexblog/texmf/fonts/tfm//
             TEXFORMATS=c:/luatexblog/texmf/web2c
             T1FONTS = c:/luatexblog/texmf/fonts/type1//
             ENCFONTS = c:/luatexblog/texmf/fonts/enc
   
   Erratum: Apologies, the above texmf.cnf is not correct (although it works). A far better way is as follows.
   
             TEXMF=$SELFAUTOLOC/texmf
             WEB2C=$TEXMF/web2c
             TEXINPUTS = .;$TEXMF/tex//
             TEXFONTMAPS = $TEXMF/fonts/map
             TEXFORMATS=$TEXMF/web2c
             TFMFONTS = $TEXMF/fonts/tfm//
             T1FONTS = $TEXMF/fonts/type1//
             ENCFONTS = $TEXMF/fonts/enc
   
   
   

Summary of these texmf.cnf variables

Source: The pdfTeX Manual

• $SELFAUTOLOC: An environment variable set by Kpathsea (when it starts running) which gives the location of the executable; i.e., c:\luatexblog for luatex.exe as that is where we put it.
• TEXINPUTS: This variable specifies where pdfTeX (and LuaTeX) finds its input files. Image files are considered input files and searched for along this path.
• TEXFONTMAPS: Search path for font map (.map) files.
• TFMFONTS: Search path for font metric (.tfm) files.
• TEXFORMATS: Search path for format (.fmt) files.
• T1FONTS: Search path for Type 1 font files (.pfa and .pfb).
• ENCFONTS: Search path for encoding (.enc) files.

General notes

• Kpathsea uses forward slashes “/”
• In our example, TEXINPUTS starts with “.” and has a second path “c:/luatexblog/texmf/tex//” (separated by “;“) which ends in “//“.
  • “.“: this means “the current directory”.
  • The “//” means search recursively into the directory
  • “;” is a separator for Kpathsea “path elements”

Something I have ignored: ls-R databases
Kpathsea can use an externally-built filename database file named ls-R that maps files to directories, thus avoiding the need to exhaustively search the disk. See the Kpathsea documentation for more detail.

Running luatex

If you type luatex --help at the DOS prompt you’ll see a number of command-line options. But of these only 4 are of immediate interest:

--fmt=FORMAT	load the format file FORMAT
--ini	be iniluatex, for dumping formats
--output-directory=DIR	use DIR as the directory to write files to
--output-format=FORMAT	use FORMAT for job output; FORMAT is ‘dvi’ or ‘pdf’

Note that when you run LuaTeX it will write the PDF file, and maybe others, to the current working directory unless you specify an another directory using --output-directory=DIR

Generating plain.fmt

We’ll use the fact that LuaTeX will write to the current directory unless told otherwise. Start a DOS prompt and change the directory to where we want the plain.fmt file to be located:

c:\luatexblog\texmf\web2c

Run the command line:

c:\luatexblog\texmf\web2c> luatex --ini plain.tex \dump

You should see something like the following, and a file called plain.fmt created in
c:\luatexblog\texmf\web2c

This is LuaTeX, Version beta-0.65.0-2010121314 (rev 4033) (INITEX)
(c:/luatexblog/texmf/tex/plain/base/plain.tex
Preloading the plain format: codes, registers, parameters, fonts, more fonts,
macros, math definitions, output routines, hyphenation
(c:/luatexblog/texmf/tex/generic/hyphen/hyphen.tex))
Beginning to dump on file plain.fmt
(format=plain 2011.1.25)

...
...
...

TeXing our first file

Create a directory called myfiles under c:\luatexblog and change to that directory.

c:\luatexblog\myfiles>

Grab any plain TeX example from the web (for example http://www.combinatorics.org/Information/plain.html)

Save it to a text file c:\luatexblog\myfiles\test.tex

Run the command

c:\luatexblog\myfiles> luatex --fmt=plain test.tex

You should see

c:\luatexblog\myfiles> luatex --fmt=plain test.tex
This is LuaTeX, Version beta-0.65.0-2010122301
(./test.tex 1. Introduction. [1] )
Output written on test.dvi (1 page, 2432 bytes).
Transcript written on test.log.

With a file test.dvi output in c:\luatexblog\myfiles

Now run the command

c:\luatexblog\myfiles> luatex --fmt=plain --output-format=pdf test.tex

You should see

c:\luatexblog\myfiles>luatex --fmt=plain --output-format=pdf test.tex
This is LuaTeX, Version beta-0.65.0-2010122301
(./test.tex 1. Introduction. [1{c:/luatexblog/texmf/fonts/map/pdftex.map}] )
<c:/luatexblog/texmf/fonts/type1/public/cm/cmbx10.PFB><c:/luatexblog/texmf/fonts/
type1/public/cm/cmcsc10.PFB><c:/luatexblog/texmf/fonts/type1/public/cm/cmr10.PF
B><c:/luatexblog/texmf/fonts/type1/public/cm/cmr12.PFB><c:/luatexblog/texmf/fon
ts/type1/public/cm/cmtt10.PFB>
Output written on test.pdf (1 page, 70507 bytes).
Transcript written on test.log.

With a file test.pdf output in c:\luatexblog\myfiles

Conclusion

Over these 6 tutorials I have tried to cover, in general terms, some of the “TeX landscape” and to equip you with enough information to begin building your own LuaTeX test environment, should you wish to. Of course, I have omitted vast amounts of technical detail in the interest of simplicity and building “a conceptual framework” for your own investigations. I hope that I have not made any serious errors but if anyone spots some, do please let me know so that I can release corrected and updated posts.

I hope that somewhere “out on the web” someone has enjoyed these and found them to be useful.

Cheers

Graham!