texdoc (2feb20)

git-svn-id: svn://tug.org/texlive/trunk@53643 c570f23f-e606-0410-a88d-b1316a301751

8 files changed, 217 insertions, 133 deletions

diff --git a/Master/texmf-dist/scripts/texdoc/texdoc.tlu b/Master/texmf-dist/scripts/texdoc/texdoc.tlu
index b8598682364..bc2139435a3 100755
--- a/Master/texmf-dist/scripts/texdoc/texdoc.tlu
+++ b/Master/texmf-dist/scripts/texdoc/texdoc.tlu
@@ -7,11 +7,39 @@
 -- Note: we keep this file small as much as possible so that make it easier
 --       to install a new version of texdoc in TEXMFHOME.
 
--- setup the kpse library and load texdoclib
+local lfs = require 'lfs'
+local kpse = require 'kpse'
+
+-- setup kpse library
 kpse.set_program_name(arg[-1], 'texdoc')
-local texdoc = require('texdoclib')
 
--- execute
+-- get realpath of this file
+local function realpath(p)
+    if os.type == 'unix' then
+        local h = io.popen(string.format("realpath '%s'", p))
+        local r = h:read('*a')
+        h:close()
+        return r:gsub('\n$', '')
+    else
+        return ''
+    end
+end
+local file = realpath(arg[0])
+
+-- if the file is not in TEXMFMAIN, set temporal TEXMFAUXTREES and TEXMFDIST
+local texmf = file:match('^(.*/texmf[^/]*)/scripts/texdoc/texdoc.tlu$')
+if texmf ~= nil then
+    if texmf ~= kpse.var_value('TEXMFMAIN') then
+        io.stderr:write('Info: ' ..
+            'Running Texdoc not installed in the current TEXMFMAIN.\n')
+        os.setenv('TEXMFAUXTREES', texmf .. ',')
+        os.setenv('TEXMFDIST', ',')
+    end
+end
+
+-- load the library and execute
+local texdoc = require 'texdoclib'
+assert(texdoc.cli, 'Internal error: Texdoc is not installed properly.')
 texdoc.cli.exec()
 
 -- vim: ft=lua:
diff --git a/Master/texmf-dist/scripts/texdoc/texdoclib-alias.tlu b/Master/texmf-dist/scripts/texdoc/texdoclib-alias.tlu
index 16c375b3bad..d430623a41c 100755
--- a/Master/texmf-dist/scripts/texdoc/texdoclib-alias.tlu
+++ b/Master/texmf-dist/scripts/texdoc/texdoclib-alias.tlu
@@ -5,7 +5,7 @@
 --[[ structure of the alias table
 
 alias = {
-  name1 = {<true or nill> stop, <aliasentry> aliasentry1, ...},
+  name1 = {<true or nil> stop, <aliasentry> aliasentry1, ...},
   ...
 }
 stop == true means further alias directives should be ignored
@@ -22,7 +22,7 @@ score == nil means to use the default score (defined in texdoclib-score.tlu)
 
 -- dependencies
 local texdoc = {
-    config = require('texdoclib-config'),
+    config = require 'texdoclib-config',
 }
 
 -- shortcuts
diff --git a/Master/texmf-dist/scripts/texdoc/texdoclib-cli.tlu b/Master/texmf-dist/scripts/texdoc/texdoclib-cli.tlu
index 3de786ef2c8..95a43b7ddd9 100755
--- a/Master/texmf-dist/scripts/texdoc/texdoclib-cli.tlu
+++ b/Master/texmf-dist/scripts/texdoc/texdoclib-cli.tlu
@@ -4,11 +4,11 @@
 
 -- dependencies
 local texdoc = {
-    const = require('texdoclib-const'),
-    util = require('texdoclib-util'),
-    config = require('texdoclib-config'),
-    search = require('texdoclib-search'),
-    view = require('texdoclib-view'),
+    const = require 'texdoclib-const',
+    util = require 'texdoclib-util',
+    config = require 'texdoclib-config',
+    search = require 'texdoclib-search',
+    view = require 'texdoclib-view',
 }
 
 -- shortcuts
@@ -21,7 +21,7 @@ local err_print = texdoc.util.err_print
 -- modified Alternative GetOpt
 -- cf. http://lua-users.org/wiki/AlternativeGetOpt
 local function getopt(arg, options)
-    local tmp
+    local tmp = nil
     local tab = {}
     local saved_arg = {table.unpack(arg)}
 
@@ -30,25 +30,36 @@ local function getopt(arg, options)
             table.remove(arg, 1)
             local x = string.find(v, '=', 1, true)
             if x then
-                table.insert(tab, {string.sub(v, 3, x-1), string.sub(v, x+1)})
+                table.insert(tab, {string.sub(v, 3, x - 1), string.sub(v, x+1)})
             else
                 table.insert(tab, {string.sub(v, 3), true})
             end
+
         elseif string.sub(v, 1, 1) == '-' then
             table.remove(arg, 1)
             local y = 2
             local l = string.len(v)
             local jopt
+
             while (y <= l) do
                 jopt = string.sub(v, y, y)
+
                 if string.find(options, jopt, 1, true) then
                     if y < l then
-                        tmp = string.sub(v, y+1)
+                        tmp = string.sub(v, y + 1)
                         y = l
                     else
                         table.remove(arg, 1)
                         tmp = saved_arg[k + 1]
                     end
+
+                    -- check the existence of an argument
+                    if not tmp then
+                        err_print('error',
+                            'Option -%s requires an argument.', jopt)
+                        os.exit(C.exit_error)
+                    end
+
                     if string.match(tmp, '^%-') then
                         table.insert(tab, {jopt, false})
                     else
@@ -59,6 +70,9 @@ local function getopt(arg, options)
                 end
                 y = y + 1
             end
+
+        else
+            if tmp then tmp = nil else break end
         end
     end
 
@@ -67,7 +81,6 @@ end
 
 local function parse_options()
     local curr_arg
-    local action = true
     local cl_config = {}
 
     local function insert_cl_config(key, val, opt_name)
@@ -87,13 +100,13 @@ local function parse_options()
 
         -- action
         if (curr_arg == '-h') or (curr_arg == '--help') then
-            action = 'help'
+            return true, 'help', cl_config
         elseif (curr_arg == '-V') or (curr_arg == '--version') then
-            action = 'version'
+            return true, 'version', cl_config
         elseif (curr_arg == '-f') or (curr_arg == '--files') then
-            action = 'files'
+            return true, 'files', cl_config
         elseif curr_arg == '--just-view' then
-            action = 'view'
+            return true, 'view', cl_config
 
         -- mode
         elseif (curr_arg == '-w') or (curr_arg == '--view') then
@@ -117,8 +130,7 @@ local function parse_options()
 
         -- config
         elseif curr_arg == '-c' then
-            local item, value = string.match(v, '^([%a%d_]+)%s*=%s*(.+)')
-            insert_cl_config(item, value, curr_arg)
+            insert_cl_config(v, nil, curr_arg)
 
         -- debug
         elseif (curr_arg == '-d') or (curr_arg == '--debug') then
@@ -141,7 +153,7 @@ local function parse_options()
         end
     end
 
-    return action, cl_config
+    return true, action, cl_config
 end
 
 --------------------------   process execution   --------------------------
@@ -157,7 +169,7 @@ local function do_action(action)
             '\n\n' .. C.copyright_msg)
         os.exit(C.exit_ok)
     elseif action == 'files' then
-        print(C.fullname .. ' ' .. C.version)
+        print(texdoc.util.w32_path(C.fullname) .. ' ' .. C.version)
         texdoc.config.show_config_files(true)
         os.exit(C.exit_ok)
     elseif action == 'view' then
@@ -189,9 +201,9 @@ end
 
 function M.exec()
     -- parsing command line options
-    local action, cl_config = parse_options()
+    local ok, action, cl_config = parse_options()
 
-    if not action then
+    if not ok then
         os.exit(C.exit_usage)
     end
 
diff --git a/Master/texmf-dist/scripts/texdoc/texdoclib-config.tlu b/Master/texmf-dist/scripts/texdoc/texdoclib-config.tlu
index 471fef9fdcb..4eb660873f9 100755
--- a/Master/texmf-dist/scripts/texdoc/texdoclib-config.tlu
+++ b/Master/texmf-dist/scripts/texdoc/texdoclib-config.tlu
@@ -2,9 +2,12 @@
 --
 -- The TeX Live Team, GPLv3, see texdoclib.tlu for details
 
+-- dependencies
+local lfs = require 'lfs'
+
 -- shortcuts
 local M = {}
-local C = require('texdoclib-const')
+local C = require 'texdoclib-const'
 
 -- config is local to this file
 local config = {}
@@ -172,8 +175,20 @@ end
 -- Note: Make sure to set a default value in setup_config_from_defaults()
 --       if relevant.
 local function setup_config_from_cl(cl_config)
+    local err_print = import_function('util', 'err_print')
+
     for _, e in ipairs(cl_config) do
-        set_config_element(e[1], e[2], {src='cl', name=e[3]})
+        if e[3] == '-c' then
+            local item, value = string.match(e[1], '^([%a%d_]+)%s*=%s*(.+)')
+            if item and value then
+                set_config_element(item, value, {src='cl', name='-c'})
+            else
+                err_print('warning',
+                    'Invalid argument "%s" for Option -c. Ignoring.', e[1])
+            end
+        else
+            set_config_element(e[1], e[2], {src='cl', name=e[3]})
+        end
     end
 end
 
@@ -184,6 +199,7 @@ local function setup_config_from_env()
     local function set_config_elt_from_vars(key, vars)
         for _, var in ipairs(vars) do
             local value = os.getenv(var)
+            value = value and string.gmatch(value, '([^:]+)')()
             if value then
                 set_config_element(key, value, {src='env', name=var})
             end
@@ -316,7 +332,7 @@ function M.show_config_files(is_action)
         or function(s) dbg_print('files', s) end
 
     -- show the list of configuration files
-    print_func('Configuration files are:')
+    print_func('Configuration file(s):')
     for i, file in ipairs(config_files) do
         -- if not verbose, do not show "not found" files for -f
         if file.status ~= "not found"
@@ -329,7 +345,7 @@ function M.show_config_files(is_action)
     if is_action then
         print_func('Recommended file(s) for personal settings:')
         local sep = (os.type == 'windows') and ';' or ':'
-        local texmfhomes = string.explode(kpse.var_value('TEXMFHOME'), sep)
+        local texmfhomes = string.explode(kpse.expand_path('$TEXMFHOME'), sep)
         for _, home in ipairs(texmfhomes) do
             print_func(indent .. w32_path(home .. '/texdoc/texdoc.cnf'))
         end
@@ -340,12 +356,20 @@ end -- end scope of config_files
 
 ----------------------   config from locale settings   -------------------------
 
+-- set up the locale from the system setting
+-- Note that luatex set the locale to a neutral value for a reason, so we need
+-- to set the locale (for the category 'all') to nil to ignore it.
 local function setup_config_from_locale()
-    local current = os.setlocale(nil, 'all')
-    os.setlocale('', 'all')
-    local native = os.setlocale(nil, 'time')
-    os.setlocale(current, 'all')
-    local lang = string.match(native, '^[a-z][a-z]')
+    local current, native, lang
+    current = os.setlocale(nil, 'all')  -- save the default value
+    os.setlocale('', 'all')             -- set it to nil temporary
+    native = os.setlocale(nil, 'all')   -- get the actual system locale
+    os.setlocale(current, 'all')        -- put back the default value
+    if native == 'C' then -- the default C locale is en
+        lang = 'en'
+    else
+        lang = string.match(native, '^[a-z][a-z]')
+    end
     if lang then
         set_config_element('lang', lang, {src='loc'})
     end
@@ -381,6 +405,8 @@ local function desktop_environment_viewer()
     end
     if os.getenv('GNOME_DESKTOP_SESSION_ID')
         or string.match(xdg_current_desktop, '.*GNOME.*') then  -- gnome
+        if is_in_path('gio') then return '(gio open %s) &' end
+        -- followings are deplecated commands but keep these for compatibility
         if is_in_path('gvfs-open') then return '(gvfs-open %s) &' end
         if is_in_path('gnome-open') then return '(gnome-open %s) &' end
     end
diff --git a/Master/texmf-dist/scripts/texdoc/texdoclib-const.tlu b/Master/texmf-dist/scripts/texdoc/texdoclib-const.tlu
index 5d34bed3f67..9562122d38a 100755
--- a/Master/texmf-dist/scripts/texdoc/texdoclib-const.tlu
+++ b/Master/texmf-dist/scripts/texdoc/texdoclib-const.tlu
@@ -4,7 +4,7 @@
 
 -- use an empty environment that will become texdoc_env.C (see EOF)
 local constants = {}
-local kpse = kpse
+local kpse = kpse or require 'kpse'
 local setfenv = setfenv
 local texdoc_env
 
@@ -21,14 +21,14 @@ end
 -- progname and version
 fullname = kpse.find_file('texdoc/texdoclib', 'lua')
 progname = 'Texdoc'
-version = '3.1'
-release_date = '2019-03-28'
+version = '3.2'
+release_date = '2020-02-02'
 
 -- make sure to update setup_config_from_cl() accordingly
 -- and set a default value in setup_config_from_defaults() if relevant
 usage_msg = [[
-Usage: texdoc [OPTION...] NAME...
-  or:  texdoc [OPTION...] ACTION
+Usage: texdoc [OPTION]... NAME...
+   or: texdoc [OPTION]... ACTION
 
 Try to find appropriate TeX documentation for the specified NAME(s).
 Alternatively, perform the given ACTION and exit.
@@ -63,7 +63,7 @@ Repository: <https://github.com/TeX-Live/texdoc>
 Please email bugs to <texdoc@tug.org>.]]
 
 copyright_msg = [[
-Copyright 2008 Manuel Pégourié-Gonnard, Takuto Asakura, and the TeX Live Team.
+Copyright 2008-2020 Manuel Pégourié-Gonnard, Takuto Asakura, the TeX Live Team.
 License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
 This is free software: you are free to change and redistribute it.]]
 
diff --git a/Master/texmf-dist/scripts/texdoc/texdoclib-score.tlu b/Master/texmf-dist/scripts/texdoc/texdoclib-score.tlu
index 81e1be2a333..fdc2ef3467f 100755
--- a/Master/texmf-dist/scripts/texdoc/texdoclib-score.tlu
+++ b/Master/texmf-dist/scripts/texdoc/texdoclib-score.tlu
@@ -3,14 +3,14 @@
 -- The TeX Live Team, GPLv3, see texdoclib.tlu for details
 
 -- dependencies
+local md5 = require 'md5'
 local texdoc = {
-    util = require('texdoclib-util'),
-    config = require('texdoclib-config'),
+    util = require 'texdoclib-util',
+    config = require 'texdoclib-config',
 }
 
 -- shortcuts
 local M = {}
-local dbg_print = texdoc.util.dbg_print
 
 -- shared variables
 local global_adjscore, spec_adjscore = {}, {}
@@ -73,18 +73,19 @@ local function has_bad_basename(file)
 end
 
 -- compute a heuristic score -10 <= s < 10
-local function heuristic_score(file, pat)
-    dbg_print('score', 'Start heuristic scoring with pattern: ' .. pat)
+local function heuristic_score(file, pat, dbg_score)
+    dbg_score('Start heuristic scoring with pattern: ' .. pat)
+
     -- score management
     local score = -10
     local function upscore(s, reason, force)
         if s > score or force then
             score = s
-            dbg_print('score',
-                'New heuristic score: %.1f. Reason: %s', s, reason)
+            dbg_score('New heuristic score: %.1f. Reason: %s', s, reason)
         end
     end
     local slash = not not string.find(pat, '/', 1, true)
+
     -- look for exact or subword match
     if M.is_exact_locale(file, pat) then
         upscore(5, 'exact match with correct locale')
@@ -93,104 +94,121 @@ local function heuristic_score(file, pat)
     elseif is_subword(file, pat) then
         upscore(1, 'subword match')
     end
+
     -- try derivatives unless pat contains a slash
     if not slash then
         for _, suffix in ipairs(texdoc.config.get_value('suffix_list')) do
-            local deriv = pat..suffix
+            local deriv = pat .. suffix
             if M.is_exact(file, deriv) then
-                upscore(3, 'exact match for derived pattern: ' .. deriv)
+                upscore(4.5, 'exact match for derived pattern: ' .. deriv)
             elseif is_subword(file, deriv) then
-                upscore(2, 'subword match for derived pattern: ' .. deriv)
+                upscore(3.5, 'subword match for derived pattern: ' .. deriv)
             end
         end
     end
+
     -- if extension is bad, score becomes an epsilon
     local ext = texdoc.config.get_value('ext_list')[M.ext_pos(file)]
     if ext and texdoc.config.get_value('badext_list_inv')[ext] and score > 0 then
         upscore(0.1, 'bad extension', true)
     end
+
     -- if basename is bad, score becomes an epsilon
     if has_bad_basename(file) and score > 0 then
         upscore(0.1, 'bad basename', true)
     end
+
     -- bonus for being in the right directory
     if string.find('/' .. file, '/' .. pat .. '/', 1, true) and not slash then
         upscore(score + 1.5, 'directory bonus')
     end
+
     -- done
-    dbg_print('score', 'Final heuristic score: %.1f', score)
+    dbg_score('Final heuristic score: %.1f', score)
     return score
 end
 
 -- set the score of a docfile
 local function set_score(df, original_kw)
     -- scoring is case-insensitive (patterns are already lowercased)
-    local name = string.lower(df.shortname)
-    dbg_print('score', '----------')
-    dbg_print('score', 'Start scoring ' .. df.realpath)
-    dbg_print('score', 'Name used: ' .. name)
+    local name = string.lower(df.normname)
+    local df_id = string.sub(md5.sumhexa(name), 1, 7)
+
+    -- special debugging function
+    local function dbg_score(msg, ...)
+        -- add the hash id prefix to make the outputs grep-friendly
+        local msg = string.format('(%s) ', df_id) .. msg
+        texdoc.util.dbg_print('score', msg, ...)
+    end
+
+    dbg_score('Start scoring ' .. df.realpath)
+    dbg_score('Name used: ' .. name)
+
     -- get score from patterns
     local score = -10
     for _, pat in ipairs(df.matches) do
         local s = -10
         local p = string.lower(pat.name)
-        if pat.original then
-            s = df.tree > -1 and heuristic_score(name, p) or 1
-        elseif M.is_exact(name, p) then
+        if pat.original then  -- non-alias
+            s = df.tree > -1 and heuristic_score(name, p, dbg_score) or 1
+        elseif M.is_exact(name, p) then  -- alias
             local bonus, note = 0, ''
             if pat.locale then
                 bonus, note = 5, ', (language-based)'
             end
-            s = (pat.score or 10) + bonus -- default alias score is 10
-            dbg_print('score',
-                'Matching alias "%s", score: %.1f%s', pat.name, s, note)
+            s = (pat.score or 10) + bonus  -- default alias score is 10
+            dbg_score('Matching alias "%s", score: %.1f%s', pat.name, s, note)
         end
         if s > score then score = s end
     end
-    dbg_print('score', 'Max pattern score: %.1f', score)
+    dbg_score('Max pattern score: %.1f', score)
+
     -- get score from tlp associations
     if score == -10 and df.tlptodoc then
         score = -1
-        dbg_print('score',
-            'New score: %.1f from package name association', score)
+        dbg_score('New score: %.1f from package name association', score)
     end
+
     if score == -10 and df.runtodoc then
         score = -5
-        dbg_print('score',
-            'New score: %.1f from sty/cls association', score)
+        dbg_score('New score: %.1f from sty/cls association', score)
     end
+
     -- bonus for metadata
     if df.details then
         if string.find(string.lower(df.details), 'readme') then
             score = score + 0.1
-            dbg_print('score', 'Catalogue "readme" bonus: +0.1')
+            dbg_score('Catalogue "readme" bonus: +0.1')
         else
             score = score + 1.5
-            dbg_print('score', 'Catalogue details bonus: +1.5')
+            dbg_score('Catalogue details bonus: +1.5')
         end
     end
+
     -- adjust from keyword-specific tables
     if df.tree > -1 and spec_adjscore[original_kw] then
         for pat, val in pairs(spec_adjscore[original_kw]) do
             if val and is_subword('/' .. name, pat) then
                 score = score + val
-                dbg_print('score',
-                    'Adjust by %.1f from specific pattern "%s"', val, pat)
+                dbg_score('Adjust by %.1f from specific pattern "%s"', val, pat)
             end
         end
     end
+
     -- adjust from global tables
     if df.tree > -1 then
         for pat, val in pairs(global_adjscore) do
             if val and is_subword('/' .. name, pat) then
                 if score > -10 or val < 0 then score = score + val end
-                dbg_print('score',
-                    'Adjust by %.1f from global pattern "%s"', val, pat)
+                dbg_score('Adjust by %.1f from global pattern "%s"', val, pat)
             end
         end
     end
-    dbg_print('score', 'Final score: %.1f', score)
-    df.score = score
+
+    dbg_score('Final score: %.1f', score)
+
+    -- the final score should be a float value
+    df.score = score + 0.0
 end
 
 -- set the scores for a doclist
diff --git a/Master/texmf-dist/scripts/texdoc/texdoclib-search.tlu b/Master/texmf-dist/scripts/texdoc/texdoclib-search.tlu
index 1a7270d0b73..addb59a01f4 100755
--- a/Master/texmf-dist/scripts/texdoc/texdoclib-search.tlu
+++ b/Master/texmf-dist/scripts/texdoc/texdoclib-search.tlu
@@ -5,12 +5,14 @@
 -- Warning: Some functions here assume that M.init_databases() has been called.
 
 -- dependencies
+local kpse = require 'kpse'
+local lfs = require 'lfs'
 local texdoc = {
-    const = require('texdoclib-const'),
-    util = require('texdoclib-util'),
-    alias = require('texdoclib-alias'),
-    score = require('texdoclib-score'),
-    config = require('texdoclib-config'),
+    const = require 'texdoclib-const',
+    util = require 'texdoclib-util',
+    alias = require 'texdoclib-alias',
+    score = require 'texdoclib-score',
+    config = require 'texdoclib-config',
 }
 
 -- shortcuts
@@ -24,11 +26,11 @@ local s_doclist -- the Doclist object to be populated by various functions
 local s_meta -- {[normname] = meta, ...} (populated by init_tlp_database)
 local vanilla -- is this a vanilla TL or a re-package one without tlpdb?
 
-----------------------------   utility functions   -----------------------------
+---------------------------   utility functions   ----------------------------
 
 -- find the TeX Live root
 local function get_tlroot()
-    local tlroot = kpse.var_value('TEXMFROOT')
+    local tlroot = kpse.expand_path('$TEXMFROOT') -- it should be exisitng one
     get_tlroot = function() return tlroot end
     return tlroot
 end
@@ -36,7 +38,7 @@ end
 -- says if file has a known extension according to ext_list
 -- (or known basename according to basename_list)
 local function check_ext(file)
-    file = string.lower(file)
+    file = file:lower()
     -- remove zipext if applicable
     file = texdoc.util.parse_zip(file)
     -- then do the normal thing
@@ -44,12 +46,12 @@ local function check_ext(file)
         if e == '*' then
             return true
         elseif (e == '') then
-            if not string.find(file, '.', 1, true) then
+            if not file:find('.', 1, true) then
                 return true
             end
         else
-            local dot_e = '.'..e
-            if string.sub(file, -string.len(dot_e)) == dot_e then
+            local dot_e = '.' .. e
+            if file:sub(-#dot_e) == dot_e then
                 return true
             end
         end
@@ -63,7 +65,7 @@ local function check_ext(file)
     return false
 end
 
------------------------   docfile and doclist objects   ------------------------
+----------------------   docfile and doclist objects   -----------------------
 
 --[[
 doclist = {
@@ -128,7 +130,6 @@ docfile = {
     -- those are virtual members, see below
     realpath  = full path
     normname  = nomrmalised (path removed up to the 'doc' component)
-    shortname = short name used for scoring
     basename  = basename
     lang      = language tag from the catalogue metadata
     details   = details tag from the catalogue metadata
@@ -201,7 +202,7 @@ end
 
 -- normalise a name from the tlpdb (use for s_meta indexes)
 local function reloc_tlpdb_path(name)
-    return string.gsub(name, '^texmf[^/]*/doc/', '', 1)
+    return name:gsub('^texmf[^/]*/doc/', '')
 end
 
 -- return normalised name
@@ -221,16 +222,9 @@ function Docfile:get_details()
     return meta and (meta.details or false) or false
 end
 
--- return the short name used for scoring
-function Docfile:get_shortname()
-    if self.tree == -1 then return self.name end
-    -- remove first component of name if at least two directory levels
-    return string.match(self.normname, '^..-/(.+/.+)$') or self.normname
-end
-
 -- return the base name
 function Docfile:get_basename()
-    return string.gsub(self.name, '.*/', '', 1)
+    return self.name:gsub('.*/', '')
 end
 
 -- for interface consistency, matches should always be a table, never nil
@@ -246,12 +240,12 @@ function Docfile:get_ext_pos()
     return texdoc.score.ext_pos(self.basename)
 end
 
---------------------   select results from TEXDOCS trees   ---------------------
+-------------------   select results from TEXDOCS trees   --------------------
 
 -- says if a file (with its path) matches a pattern
 local function matches(pattern, file)
     if pattern.original then
-        return string.find(file:lower(), pattern.name:lower(), 1, true)
+        return file:lower():find(pattern.name:lower(), 1, true)
     else
         return texdoc.score.is_exact(file, pattern.name)
     end
@@ -296,25 +290,28 @@ local function init_lsr_db(root, shift)
 
     -- scan it
     local db = {}
-    local maybe_dir, isdoc = true, false
+    local maybe_dir, is_doc = true, false
     local current_dir
     local l = #shift
     while true do
         local line = lsr:read('*line')
         while line == '' do line, maybe_dir = lsr:read('*line'), true end
         if line == nil then break end -- EOF
-        local dir_line = maybe_dir and string.match(line, '^%./(.*):$')
+        local dir_line = maybe_dir and line:match('^%./(.*):$')
         if dir_line then
             maybe_dir = false -- next line may not be a dir
             if string.sub(dir_line .. '/', 1, l) == shift then
-                isdoc = true
-                current_dir = string.sub(dir_line, l+1)
+                is_doc = true
+                current_dir = dir_line:sub(l + 1)
                 db[current_dir] = nil
-            elseif isdoc then
+            elseif is_doc then
                 break -- we're exiting the ./doc (or shift) dir, so it's over
             end
-        elseif isdoc then
-            local file = (current_dir == '') and line or current_dir .. '/' .. line
+        elseif is_doc then
+            local file = line
+            if current_dir ~= '' then
+                file = current_dir .. '/' .. line
+            end
             if check_ext(line) then db[file] = line end
         end
     end
@@ -361,24 +358,24 @@ init_texdocs_database = function()
     local function lsr_root(path)
         if not lfs.isdir (path) then return end
         local root, shift = path, ''
-        if string.sub(root, -1) == '/' then root = string.sub(root, 1, -2) end
-        while string.find(root, '/', 1, true) do
+        if root:sub(-1) == '/' then root = root:sub(1, -2) end
+        while root:find('/', 1, true) do
             if lfs.isfile(root .. '/ls-R') then
                 return root, shift
             end
-            local last_comp = string.match(root, '^.*/(.*)$')
+            local last_comp = root:match('^.*/(.*)$')
             -- /!\ cannot put last_comp in a regex: can contain special char
-            root = string.sub(root, 1, - (#last_comp + 2))
+            root = root:sub(1, - (#last_comp + 2))
             shift = last_comp .. '/' .. shift
         end
     end
 
     doc_roots = {}
     local sep = (os.type == 'windows') and ';' or ':'
-    local kpse_texdocs = kpse.expand_var("$TEXDOCS")
+    local kpse_texdocs = kpse.expand_var('$TEXDOCS')
 
     -- expand the path and turn it into a lua list
-    local raw_doc_roots = string.explode(kpse.expand_braces(kpse_texdocs), sep)
+    local raw_doc_roots = kpse.expand_braces(kpse_texdocs):explode(sep)
     local max = #raw_doc_roots + 1
 
     for j, dir in ipairs(raw_doc_roots) do
@@ -387,9 +384,9 @@ init_texdocs_database = function()
         local path, db
 
         -- get path, !! and // values
-        dir, n = string.gsub (dir, '//$', '')
+        dir, n = dir:gsub('//$', '')
         local recursion_allowed = (n == 1)
-        local path, n = string.gsub (dir, '^!!', '')
+        local path, n = dir:gsub('^!!', '')
         local index_mandatory = (n == 1)
         dbg_print('texdocs',
             'texdocs[%d] = %s (index_mandatory=%s, recursion_allowed=%s)',
@@ -426,7 +423,7 @@ end
 
 end -- end scope of doc_roots
 
-----------------------------   look for sty files   ----------------------------
+---------------------------   look for sty files   ---------------------------
 
 -- add doclist entries for sty files in patlist
 local function get_doclist_sty(patlist)
@@ -443,7 +440,7 @@ local function get_doclist_sty(patlist)
     end
 end
 
---------------------------------   use tlpdb   ---------------------------------
+-------------------------------   use tlpdb   --------------------------------
 
 -- tlpdb mean TeX Live Package DataBase and tlp means TeX Live Package
 
@@ -493,23 +490,23 @@ get_tlpinfo_from_tlpdb = function(filename)
     local curr_tlp
     local state = 'none'
     for line in io.lines(filename) do
-        if state == 'none' and string.find(line, '^name ') then
+        if state == 'none' and line:find('^name ') then
             -- begin a new package
-            curr_tlp = string.lower(string.sub(line, 6, -1))
+            curr_tlp = line:sub(6, -1):lower()
             tlp_doclist[curr_tlp] = {}
         elseif state == 'docfiles' then
-            if not string.find(line, '^ ') then
+            if not line:find('^ ') then
                 state = 'none'
             else
-                local file = string.match(line, '^ ([^ ]*)')
-                local meta = string.match(line, '^ [^ ]* (.+)')
-                local basename = string.match(file, '([^/]*)$')
+                local file = line:match('^ ([^ ]*)')
+                local meta = line:match('^ [^ ]* (.+)')
+                local basename = file:match('([^/]*)$')
                 if check_ext(basename) then
                     -- we've got a docfile here, add it
                     table.insert(tlp_doclist[curr_tlp], file)
                     if meta then
-                        local details = string.match(meta, 'details="([^"]+)"')
-                        local lang = string.match(meta, 'language="([^"]+)"')
+                        local details = meta:match('details="([^"]+)"')
+                        local lang = meta:match('language="([^"]+)"')
                         s_meta[reloc_tlpdb_path(file)] = {
                             details = details,
                             lang = lang,
@@ -518,22 +515,22 @@ get_tlpinfo_from_tlpdb = function(filename)
                 end
             end
         elseif state == 'runfiles' then
-            if not string.find(line, '^ ') then
+            if not line:find('^ ') then
                 state = 'none'
             else
                 -- check for interesting runfiles
-                local e = string.sub(line, -4, -1)
+                local e = line:sub(-4, -1)
                 if e == '.tex' or e == '.sty' or e == '.cls' then
-                    local f = string.match(line, '.*/(.*)%.')
+                    local f = line:match('.*/(.*)%.')
                     tlp_from_runfile[f] = tlp_from_runfile[f] or {}
                     tlp_from_runfile[f][curr_tlp] = true
                 end
             end
         end
         -- update state
-        if string.find(line, '^docfiles ') then
+        if line:find('^docfiles ') then
             state = 'docfiles'
-        elseif string.find(line, '^runfiles ') then
+        elseif line:find('^runfiles ') then
             state = 'runfiles'
         end
     end
@@ -658,8 +655,8 @@ end -- end scope of tlpinfo table
 
 -- get tlpinfo tables initialised by whatever mean
 local function init_tlp_database()
-    local TEXMFVAR = kpse.var_value('TEXMFVAR')
-    local cache_file = TEXMFVAR .. '/' .. C.cache_name
+    -- we assume TEXMFVAR always consists of an element
+    local cache_file = kpse.expand_var('$TEXMFVAR/' .. C.cache_name)
 
     -- set vanilla and detect texlive.tlpdb to use
     local texlive_tlpdb = get_tlroot() .. '/tlpkg/texlive.tlpdb'
@@ -686,7 +683,8 @@ local function init_tlp_database()
             dbg_print('tlpdb', 'Using cached data from ' .. cache_file)
             get_tlpinfo_from_cache(cache_file)
         else
-            dbg_print('tlpdb', 'Getting data from tlpdb file ' .. texlive_tlpdb)
+            dbg_print('tlpdb',
+                'Getting data from tlpdb file ' .. texlive_tlpdb)
             get_tlpinfo_from_tlpdb(texlive_tlpdb)
             dbg_print('tlpdb', 'Writing data in cache file ' .. cache_file)
             local ok, msg = mkdir_p(texdoc.util.path_parent(cache_file))
@@ -704,7 +702,7 @@ local function init_tlp_database()
     end
 end
 
-------------------------------   main function   -------------------------------
+-----------------------------   main function   ------------------------------
 
 -- initialise the various databases (must be called first)
 function M.init_databases()
@@ -714,11 +712,13 @@ end
 
 -- find docfiles according to pattern
 function M.get_doclist(pattern, no_alias)
+    dbg_print('search', 'Searching documents for pattern "%s"', pattern)
+
     -- separate sty patterns from the rest
     local function normal_vs_sty(list)
         local normal, sty = {}, {}
         for _, p in ipairs(list) do
-            if string.match(string.lower(p.name), '%.([^/.]*)$') == 'sty' then
+            if p.name:lower():match('%.([^/.]*)$') == 'sty' then
                 table.insert(sty, p)
             else
                 table.insert(normal, p)
diff --git a/Master/texmf-dist/scripts/texdoc/texdoclib.tlu b/Master/texmf-dist/scripts/texdoc/texdoclib.tlu
index fb85895d37e..7c93fba54cf 100644
--- a/Master/texmf-dist/scripts/texdoc/texdoclib.tlu
+++ b/Master/texmf-dist/scripts/texdoc/texdoclib.tlu
@@ -1,7 +1,7 @@
 -- texdoclib.tlu: the texdoc library
 
 --[[
-Copyright 2008 Manuel Pégourié-Gonnard, Takuto Asakura, and the TeX Live Team.
+Copyright 2008-2020 Manuel Pégourié-Gonnard, Takuto Asakura, the TeX Live Team.
 
 This program is free software: you can redistribute it and/or modify it under
 the terms of the GNU General Public License as published by the Free Software