# Why does texdoc call luatex

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

• FWIW, `texdoc` does not call `luatex`; it calls `texlua`, which acts as a lua interpreter. TeXLive and MikTeX -- the two main TeX distributions that come with texdoc -- also include the full LuaTeX complement. I'm guessing that whoever wrote `texdoc` wanted to take advantage of having access to this flexible, multi-platform scripting facility.
– Mico
Apr 12, 2015 at 0:53
• Oh, thanks. But it seems to me that `"luatex"` and `"texlua"` are synonimous, aren't they? The man page says: "NAME luatex, texlua, texluac - An extended version of pdfTeX using Lua as an embedded scripting language" Apr 12, 2015 at 1:41
• I've posted a longer answer, in which I touch a bit more on the difference between `luatex` and `texlua`. Basically, the latter can be used only as a Lua interpreter, but not to compile tex documents. In contrast to "basic" `lua`, `texlua` comes with additional libraries, such as the `kpse` library, that can (and are) used by `texdoc`.
– Mico
Apr 12, 2015 at 2:53

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.

• This is a fine answer. Thanks, Mico. So calling `lua texdoc.tlu hyperref` produces the same results as `texdoc hyperref`, right? Apr 12, 2015 at 2:21
• @NVaughan - The program `lua` doesn't know what to do with the function `kpse.set_program_name` invoked by `texdoc.tlu`. If I'm in `/usr/local/texlive/2014/texmf-dist/scripts/texdoc`, I can get `texlua texdoc.tlu hyperref` to the same as `texdoc hyperref`. However, if I'm not in `/usr/local/texlive/2014/texmf-dist/scripts/texdoc` and type `texlua texdoc.tlu hyperref` anyway, I get an error message about "Script file texdoc.tlu not found". This isn't surprising, as `/usr/local/texlive/2014/texmf-dist/scripts/texdoc` is not in the main search path of a TeX distribution.
– Mico
Apr 12, 2015 at 2:34
• In miktex texdoc is an alias to the (native) miktex application mthelp and doesn't use lua. Apr 12, 2015 at 9:59
• @UlrikeFischer - Thanks for this. Glad I put in the disclaimer that I didn't know how texdoc operates under MikTeX! Do you maybe want to post an additional answer, to explain what texdoc does under MikTeX?
– Mico
Apr 12, 2015 at 10:05