Why does texdoc call luatex

Question

Why is it that calling texdoc runs, amongst others, luatex? What is it needed for?

Answer 1

I'll first address the "how" and "what" components of your question, and defer the "why" component to the end of this answer.

Both TeXLive and MikTeX include the texdoc utility. (I don't know if any other TeX distributions do as well.) The following is applicable for a MacTeX-based system; I would assume that other TeXLive systems are set up very similarly. I'm afraid I can't provide much detailed information as to how, precisely, texdoc is implemented in a MikTeX-based system.

On MacTeX2014, the executable texdoc is located in the directory

/usr/local/texlive/2014/bin/x86_64-darwin

Running ls -l texdoc in that directory reveals that the file texdoc is a so-called symbolic link:

lrwxr-xr-x [...] texdoc -> ../../texmf-dist/scripts/texdoc/texdoc.tlu

Switching to /usr/local/texlive/2014/texmf-dist/scripts/texdoc and typing ls -l texdoc.tlu produces

-rwxr-xr-x [...] texdoc.tlu

i.e., it's an ordinary file whose status is "world-executable" (and "world-readable").

Typing cat texdoc.tlu produces:

#!/usr/bin/env texlua

-- texdoc.tlu: small wrapper around main.tlu
-- (makes it easier to install a new version of texdoc in TEXMFHOME)

kpse.set_program_name(arg[-1], 'texdoc')
require('texdoc.main')

The first line shows that texlua -- not luatex -- is launched via /usr/bin/env. Even though texlua is nothing but a symbolic link to luatex (both are located in /usr/local/texlive/2014/bin/x86_64-darwin), they are not identical. The man page says: "If [luatex is] called as texlua it acts as Lua interpreter". Section 3.1.1 of the LuaTeX reference guide notes that "LuaTeX behave[s] like a standalone Lua interpreter [...] if the executable is named texlua". Thus, texlua can only be run as a Lua interpreter.

Aside: One of the many very useful properties of Lua is that it is multi-platform, meaning that one and the same set of Lua scripts will (generally...) produce the same results regardless of the platform it's run on. While one cannot assume that lua (the executable) is available on any given system, it's of course permissible for the texdoc to assume that texlua is available on any system that features texdoc.

Once texlua is launched, two lua functions are called: kpse.set_program_name, which is provided in luatex's kpse library (do check out section 4.6.1 of the LuaTeX reference manual for information on what the kpse.set_program_name function does), and require, which is a built-in lua function.

The file main.tlu, which is loaded by the require function, contains another Lua script -- in MacTeX2014, this script consists of 79 lines of code -- that does most of the "real work". If texdoc is invoked with no argument at all or as texdoc -h, a help screen is generated. If texdoc is invoked with one or more "real" arguments, further Lua scripts are launched to invoke whatever programs are appropriate (usually, but not necessarily, a pdf viewer) to display the argument(s). For instance, if I type

texdoc hyperref cleveref

the user guides of the hyperref and cleveref packages are launched in my pdf file viewing program.

---

So far, I've only examined what texdoc does, but I haven't offered a reason as to why texdoc uses texlua -- as opposed to, say, perl, which is another multi-platform scripting utility. I haven't checked back with the author of the texdoc utility (Manuel Pégourié-Gonnard), but I strongly suspect it's because, as noted earlier, every TeX distribution that provides the texdoc utility also contains texlua, a full-fledged Lua interpreter. In contrast, expecting perl to be installed on all users' systems may not be that great of an idea.