13

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

  • 2
    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 '15 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" – NVaughan Apr 12 '15 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 '15 at 2:53
19

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? – NVaughan Apr 12 '15 at 2:21
  • 2
    @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 '15 at 2:34
  • In miktex texdoc is an alias to the (native) miktex application mthelp and doesn't use lua. – Ulrike Fischer Apr 12 '15 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 '15 at 10:05

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.