Why is it that calling texdoc
runs, amongst others, luatex
? What is it needed for?
1 Answer
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 astexdoc hyperref
, right?– NVaughanApr 12, 2015 at 2:21 -
2@NVaughan - The program
lua
doesn't know what to do with the functionkpse.set_program_name
invoked bytexdoc.tlu
. If I'm in/usr/local/texlive/2014/texmf-dist/scripts/texdoc
, I can gettexlua texdoc.tlu hyperref
to the same astexdoc hyperref
. However, if I'm not in/usr/local/texlive/2014/texmf-dist/scripts/texdoc
and typetexlua 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.– MicoApr 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?– MicoApr 12, 2015 at 10:05
texdoc
does not callluatex
; it callstexlua
, 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 wrotetexdoc
wanted to take advantage of having access to this flexible, multi-platform scripting facility."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"luatex
andtexlua
. 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 thekpse
library, that can (and are) used bytexdoc
.