Skip to content

Latest commit

 

History

History
90 lines (64 loc) · 4.74 KB

README.md

File metadata and controls

90 lines (64 loc) · 4.74 KB
Raw

ufy

WARNING: This is pre-release code, and very much a work in progress. Lots of functionality is missing and existing functionality may have serious bugs.

ufy is wrapper around the LuaTeX typesetting engine. It exposes the core Lua-based API of LuaTeX in a clean and minimal way. This API could be used to perform typesetting using only Lua, without needing to use the TeX macro language.

Benefits of using ufy

  • You don’t need to know the TeX macro language, which can be very confusing for modern-day programmers. Write your typesetting code in pure Lua (refer to the LuaTeX user manual).
  • You don’t need an elaborate TeX installation like TeX Live, MikTeX etc. to get up and running. The only dependencies are – Lua, LuaRocks and the LuaTeX binary for your platform.
  • You don’t need to deal with legacy TeX based font formats like .tfm, .pfb, .map files etc. Basic loading of TTF/OTF files is supported by the ufy.fonts module (see example).
  • Use or write LuaRocks modules for reusable and distributable code. For example, one could use luaharfbuzz and luabidi to reorder and shape text (see example) in non-latin scripts like Arabic before using the TeX engine for typesetting.

Drawbacks of using ufy

Using the LuaTeX API only gives access to low-level internals of the TeX engine. The client has to still provide the higher level functionality. TeX distributions like MacTeX and MikTeX come bundled with macro packages like LaTeX, fonts and other artefacts that do a lot of the heavy lifting in typesetting complex documents.

With ufy, you are pretty much on your own at the moment. ufy invokes the LuaTeX binary with the --ini flag (which doesn’t load any formats, not even Plain TeX), so that is the environment you get dropped into when ufy starts. You could extend the capabilities of ufy by writing LuaRocks modules for more complex typesetting tasks. Please consider sharing them if they are of use generally.

Running

Install Lua 5.2 and LuaRocks in a sandboxed environment

It is highly recommended that you install Lua 5.2 and LuaRocks in a sandboxed environment on your machine. Hererocks makes it dead simple to do, on all platforms.

wget https://raw.githubusercontent.com/mpeterv/hererocks/latest/hererocks.py
hererocks lua52 -l5.2 -rlatest
source lua52/bin/activate
eval $(luarocks path)

Install ufy

From LuaRocks

luarocks install ufy

From source code

The following commands install ufy and make it available as an executable on PATH. If you encounter any problems, make sure you have followed the instructions above to install and activate Lua and LuaRocks in a sandbox first. File an issue if the problems persist.

git clone https://github.com/deepakjois/ufy
cd ufy
luarocks make

Run ufy

Run an example file that generates a PDF:

$ cd examples

$ ufy hello.lua
Checking if luatex is present…

luatex --shell-escape --lua=/Users/deepak/code/personal/ufy-sandbox/lua52/lib/luarocks/rocks/ufy/scm-1/config/ufy_pre_init.lua --jobname=hello --ini '\catcode`\{=1' '\catcode`\}=2' '\directlua{ufy.init()}' '\directlua{dofile("hello.lua")}' '\end'

This is LuaTeX, Version 1.0.0 (TeX Live 2017/dev)  (INITEX)
 system commands enabled.
…
…<snip>…
…
Output written on hello.pdf (1 page, 17251 bytes).
Transcript written on hello.log.

References

  • TeX by Topic (PDF) – Understand the internals of TeX.
  • LuaTeX Reference (PDF) – The definitive reference to the Lua API provided by LuaTeX.
  • Tex without TeX – The information on this page may be a bit outdated, but it is a good reference to understand the basic concepts behind using LuaTeX without the TeX macro language.

Credits