Re: [AUCTeX-devel] Changing TeX-doc?

[Nicolas Richard]

Hello Mosè,

Mosè Giordano <address@hidden> writes:
> I've just noticed that texdoc doesn't rely on that file[1] even though
> it's referenced in texdoc code: if I remove the file texdoc works just
> fine, and it's also able to find documentation for packages not listed
> in Data.tlpdb.lua when the file is there.  I gave a look to the code,
> but I'm not familiar with lua, do you have an idea how texdoc actually
> works?

I only have a superficial idea of how it works. I only used this file
because it was there and seemed to contain the information I wanted :)
Anyway, I just had a closer look.

First, about the Data.tlpdb.lua file, I looked in
/usr/local/texlive/2015/texmf-dist/scripts/texdoc/search.tlu, which has
this snippet:
--8<---------------cut here---------------start------------->8---
-- get pre-hashed tlpdb info from a pseudo-cache file
function get_tlpinfo_from_dist()
    local f = assert(kpse.find_file(C.data_tlpdb_name, 'texmfscripts'))
    s_meta, tlp_from_runfile, tlp_doclist = dofile(f)
end
--8<---------------cut here---------------end--------------->8---
I don't know what "C." means in "C.data_tlpdb_name", but constants.tlu has :
data_tlpdb_name = 'texdoc/Data.tlpdb.lua'
so I guess thats what we're referring to at that point. IOW,
Data.tlpdb.lua might be some kind of (pseudo-?)cache file but I'm not sure why 
it
exists at all. 

Anyway it seems that the file
/usr/local/texlive/2015/tlpkg/texlive.tlpdb is the authoritative source
for texdoc, but texdoc uses a cache file if one exists. You can see this
when running with the -d switch, it outputs:
--8<---------------cut here---------------start------------->8---
texdoc debug-tlpdb: Using cached data from 
~/.texlive2015/texmf-var/texdoc/cache-tlpdb.lua
--8<---------------cut here---------------end--------------->8---
(the actual output has the tilde expanded), but removing that file shows:
--8<---------------cut here---------------start------------->8---
texdoc debug-tlpdb: Getting data from tlpdb file 
/usr/local/texlive/2015/tlpkg/texlive.tlpdb
texdoc debug-tlpdb: Writing data in cache file 
/home/youngfrog/.texlive2015/texmf-var/texdoc/cache-tlpdb.lua
--8<---------------cut here---------------end--------------->8---

However, it's not clear to me how it selects which files will be
presented to the user. e.g. my texlive.tlpdb has this for ocr-b-outline :
--8<---------------cut here---------------start------------->8---
docfiles size=2
 texmf-dist/doc/fonts/ocr-b-outline/README details="Readme"
 texmf-dist/doc/fonts/ocr-b-outline/xe-test.tex
--8<---------------cut here---------------end--------------->8---
but texdoc does not show the xe-test.tex file, even when invoking it as
    texdoc -s -l ocr-b-outline
It's not even mentionned in the debug output (which prints information on
the scoring routine), so there's some more magic happening.

HTH, and thanks for working on this !

-- 
Nicolas