Having successfully built Knuthian TeX from WEB source code (using Visual Studio), and a couple of other TeX engines, I finally feel sufficiently "brave" (or perhaps masochistic...) to attempt "the big one": LuaTeX. You may well ask "What's the point when you have MinGW/MSYS to build LuaTeX on Windows for you, and so easily?" Good question! Anyone who has looked at the C code produced by the Web2C process will understand that it's practically impossible to single-step through it with a debugger and understand what's going on: it's machine-generated C code for compilers, not humans! Having built CXTeX (which dates from 2004), it's a joy to step through CXTeX's clean C code in an attempt to understand the innards of TeX in more detail. However, CXTeX is nearly 10 years old so it would be nice to have a modern TeX-based engine to explore, hence building LuaTeX, with its CWEB-based C code base. Well, some 6 hours in I've managed to build about half the components as Windows .lib files – including Cairo, Kpathsea, FontForge, Poppler and a few others. I can't say it's been easy but it's an interesting challenge to occupy the evenings over the next few days. No doubt I'm in for some interesting challenges as I try to assemble the parts into a working LuaTeX executable. Can't wait to have LuaTeX running in Visual Studio's debugging IDE!

Cairo graphics

Cairo is an excellent graphics library, albeit a little tricky to build on Windows. After successfully compiling it as a static library (.lib) I wanted to explore using it to create PDFs containing Arabic. Cairo is a graphics engine, not a text layout engine, so with complex scripts like Arabic you need to take care of the shaping and text placement yourself. Naturally, this is pretty fiddly but it's certainly quite possible. So, here are a couple of clocks as examples – note that the positioning of the numbers is not quite perfect so I have a little tweaking to do on that. Additionally, the resulting PDF imports nicely into the latest XeTeX engine. For the digits I used the font ScheherazadeRegOT, available from SIL.

Note: if you want to zoom in on the matrices, right-click over an equation and set the MathJax parameters to your preferred values:

Introduction

In this post I'll introduce a nice matrix-manipulation library called lua-matrix. It is written in pure Lua and so should be usable with any LuaTeX installation. You can download the code from GitHub. You can use lua-matrix as a convenient method to create PDF transformation matrices.

Note: where to install Lua code modules
The texmf.cnf variable you need to check is LUAINPUTS. See this newsgroup post for more details.

Tip: a Git tool for Windows users
Like many open source projects lua-matrix is hosted on GitHub. If you are a Windows user you may need to install some utilities that let you "check out" a copy of the code on repositories such as GitHub or others based on SVN. For SVN repositories there is the excellent TortoiseSVN but for Git repos I use a free tool called Git for Windows.

Very brief summary of matrices

Quoting from the PDF standard:

"PDF represents coordinates in a two-dimensional space. The point (x, y) in such a space can be expressed in vector form as [x y 1]. The constant third element of this vector (1) is needed so that the vector can be used with 3-by-3 matrices. The transformation between two coordinate systems is represented by a 3-by-3 transformation matrix written as

Notes about the PDF graphic

In the code above we have not assigned any size to the box containing the graphic, hence I needed to add \vskip 35mm \noindent\hskip 15mm to push the graphic into a space where it will be seen. To give the graphic some dimensions, we'll need to add code such as

As far as the LuaTeX engine is concerned, the box containing the graphic has zero size, we have to tell LuaTeX how big we want it to be. In addition, the line widths, based on the above code, will be affected by any scaling but it is not too difficult to fix that.

The Lua code

The idea is that we create a number of functions based on the lua-matrix library and save those functions into a Lua module called "mymatrix.lua". Within "mymatrix.lua" we import the lua-matrix code via its module called "matrix" which we load with:

Here's the source code for mymodule.lua. One huge advantage of putting Lua code into Lua modules is that it greatly simplifies dealing with \catcode issues. Note that within code saved in Lua files you use the regular Lua comment "--" mechanism and not the TeX comment "%" mechanism. You can use "%" when the code is embedded in a \directlua{...} call.

Downloads

Introduction

Just a 10-minute hack to explore putting spot colours into a PDF via pdf_colorstack nodes. I don't have access to Acrobat Professional at the moment to check the separations properly, so treat this as an "alpha" method (i.e., not fully tested...). The colour defined below is lifted straight from an early PDF specification and implemented via LuaTeX nodes. As it says "on the tin": a quick and dirty method :-).

Resulting PDF

Introduction

This is a short example to introduce two very useful LuaTeX API functions which let you work with low-level PDF objects. Here we'll use them to explore a PDF feature called pattern fills which (from the PDF specification) are a way to

"... apply “paint” that consists of a repeating graphical figure or a smoothly varying color gradient instead of a simple color. Such a repeating figure or smooth gradient is called a pattern. Patterns are quite general, and have many uses; for example, they can be used to create various graphical textures, such as weaves, brick walls, sunbursts, and similar geometrical and chromatic effects"

I'm not going to attempt any explanation of pattern fills because the PDF specification explains them, and their many options, in great detail. Hopefully, these small code examples will be helpful should you want to explore using them in your work with LuaTeX.

LuaTeX API

Here are the functions we'll be using:

pdf.immediateobj(...)
Quoting from The LuaTeX Reference Manual: This function creates a pdf object and immediately writes it to the pdf file. It is modelled after pdfTEX's \immediate\pdfobj primitives. All function variants return the object number of the newly generated object.

n = pdf.immediateobj( objtext)

n = pdf.immediateobj("file", filename)

n = pdf.immediateobj("stream", streamtext, attrtext)

pdf.pageresources =...
This lets you add named resources to the page /Resources dictionary so that they can be used within page content streams.

In outline...

There are two parts to the approach:

Writing the appropriate pattern fill objects and data to the PDF file.