Texdoc version 0.42.

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

1 files changed, 394 insertions, 278 deletions

diff --git a/Master/texmf/scripts/texdoc/texdoc.tlu b/Master/texmf/scripts/texdoc/texdoc.tlu
index defad83abb8..2f5969af8ed 100755
--- a/Master/texmf/scripts/texdoc/texdoc.tlu
+++ b/Master/texmf/scripts/texdoc/texdoc.tlu
@@ -1,89 +1,109 @@
 #!/usr/bin/env texlua
 -- $Id$ -*-Lua-*-
---[[Revised 2008 by Manuel Pégourié-Gonnard 
-    with contributions from Reinhard Kotucha.
-    First texlua versions by Frank Küster (2007). 
-    Origial shell script by Thomas Esser, David Aspinall, and Simon Wilkinson.
-    Public domain.]]
---[[ Changelog
-  0.4 2008-07
-  - moved configuration from texmf.cnf to texdoc.cnf
-  - added an 'alias' feature
-  - new modes 'mixed' and 'regex'
-  - file lists are now menus (select number to view results)
-  - changed the search modes to get only the more relevant results (hopefully)
-  - /!\ zip support disabled by default (not portable) (see comments below)
-
-  0.3 2007-06-28
-  - added changelog
-  - better OS detection for default viewer settings
-  - removed some debugging code
-  - -s now works in dirs without ls-R, too
-  
-  0.2 2007-06-28
-  - implemented reading of configuration from texmf.cnf
-  - fixed "-s" option
-  
-  0.1
-  - initial public release 
-]]
-
--- some constants 
+--[[
+Copyright 2008, 2009 Manuel Pégourié-Gonnard.
+
+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
+Foundation, either version 3 of the License, or (at your option) any later
+version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with
+this program.  If not, see <http://www.gnu.org/licenses/>.
+
+Previous work in the public domain:
+- Contributions from Reinhard Kotucha (2008).
+- First texlua versions by Frank Küster (2007).
+- Original shell script by Thomas Esser, David Aspinall, and Simon Wilkinson.
+--]]
+
+--------------------------------------------------------------------------------
+------------------   global constants and general functions   ------------------
+--------------------------------------------------------------------------------
+
+-----------------------------   global constants   -----------------------------
+
+-- progname and version
 progname = 'texdoc'
-version = '0.4'
--- make sure to update setup_config_from_cl() accordingly
+version = '0.42'
+if string.sub(version, -1) == '+' then
+    local svnrev = string.match('$Rev: 44 $', '%$Rev:%s*(%d*)%s*%$');
+    version = version..' svn r'..svnrev
+end
+
+-- 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  -h, --help | -v, --version | -f, --files | [option(s)] name(s)
-    -h, --help              Show this short help.
-    -v, --version           Print the version of the program.
-    -f, --files             Print the name of the config files being used.
-    -e, --extensions=L      Require file extensions to be in the list L.
-    -w, --view              Use view mode: start a viewer.
-    -m, --mixed             Use mixed mode (view or list).
-    -l, --list              Use list mode: don't start a viewer.
-    -s, --search            Search for name as a substring.
-    -r, --regex             Search for name as a lua regex.
-    -a, --alias             Use the alias table.
-    -A, --noalias           Don't use the alias table.
-    -i, --interact          Use interactive menus.
-    -I, --nointeract        Use plain lists, no interaction required.
-    -n, --noise-level=N     Set verbosity level to N.
-Environment: 
-    PAGER, BROWSER, PDFVIEWER, PSVIEWER, DVIVIEWER.
-Files: 
-    <texmf>/texdoc/texdoc.cnf files, see the -f option.
-Homepage: 
-    http://tug.org/texdoc/
-The full manual is accessed via `texdoc texdoc'.]]
+texdoc tries to find appropriate TeX documentation for the specified NAME(s).
+With no NAME, it can print configuration information (-f, --files);
+the usual --help and --version options are also accepted.
+Usage: texdoc [OPTIONS]... [NAME]...
+  -f, --files           Print the name of the config files being used.
+  -e, --extensions=L    Require file extensions to be in the list L.
+  -w, --view            Use view mode: start a viewer.
+  -m, --mixed           Use mixed mode (view or list).
+  -l, --list            Use list mode: don't start a viewer.
+  -s, --search          Search for name as a substring.
+  -r, --regex           Search for name as a lua regex.
+  -a, --alias           Use the alias table.
+  -A, --noalias         Don't use the alias table.
+  -i, --interact        Use interactive menus.
+  -I, --nointeract      Use plain lists, no interaction required.
+  -v, --verbosity=N     Set verbosity level to N.
+  -d, --debug           Set verbosity level to maximum.
+Environment: PAGER, BROWSER, PDFVIEWER, PSVIEWER, DVIVIEWER.
+Files: <texmf>/texdoc/texdoc.cnf files, see the -f option.
+Homepage: http://tug.org/texdoc/
+Manual: displayed by `texdoc texdoc'.]]
+
+error_msg = [[
+Try `texdoc --help' for a short help, `texdoc texdoc' for the user manual.]]
 notfound_msg = [[
 Sorry, no documentation found for PKGNAME.
 If you are unsure about the name, try searching CTAN's TeX catalogue at
 http://ctan.org/search.html#byDescription.]]
-place_holder = '%%s' -- used for viewer commands
+
+known_options = {
+    'viewer_.*',
+    'mode',
+    'interact_switch', 'alias_switch',
+    'ext_list',
+    'verbosity_level',
+    'lastfile_switch',
+}
+
 err_priority = {
     error   = 1,
     warning = 2,
     info    = 3,
     debug1  = 4,
+    debug2  = 5,
+    debug3  = 6,
 }
+err_max = 6
+
+place_holder = '%%s' -- used for viewer commands
 
 -- zip/gz support
 --
 -- optionally, texdoc can support compressed documentation, but this is
 -- system-dependant (commands for unzipping, temporary files, etc).
 -- Since TeX Live doesn't ship compressed doc, downstream distributors who
--- want to ship zipped should change support_zipped to true *and* make sure
+-- want to ship zipped doc should change support_zipped to true *and* make sure
 -- everything  works for them (look for support_zipped in the code).
 -- If you use this feature, please let us know: if nobody uses it,
 -- we'll drop it at some point.
 support_zipped = false
 
+--------------------------   general-use functions   ---------------------------
 
--- BEGIN function definitions (till the 'END' mark)
----=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
-
--- a general-use function
+-- Remark: we always assume our tables have no hole (that is, no nil value
+-- followed by a non-nil value). So we use the simple iterator below, and 
+-- the # operator sometimes (a bit faster than table.getn).
 function list (t)
     local i = 0
     return function ()
@@ -92,66 +112,81 @@ function list (t)
     end
 end
 
--- Remark: we always assume our tables have no hole (that is, no nil value
--- followed by a non-nil value). So we use the simple iterator above, and 
--- the # operator sometimes (bit faster than table.getn).
+-- remove the 'abc/../' components in a path
+function simplify_path (path)
+    local res = string.gsub (path, '/[^/]+/%.%./', '/')
+    return res -- get rid of gsub's 2nd return value
+end
 
--- functions for the search options
------------------------------------
+-- change '/' to '\' on windows, removine 'abc/../' components first
+if os.type == "windows" then
+    function win32_hook (path)
+        local res = string.gsub (simplify_path(path), '/', '\\')
+        return res -- get rid of gsub's 2nd return value
+    end
+else
+    function win32_hook (path)
+        return simplify_path(path)
+    end
+end
+
+--------------------------------------------------------------------------------
+--------------------------   functions for searching   -------------------------
+--------------------------------------------------------------------------------
+
+------------------   exploring trees (kpse-style functions)   ------------------
 
--- BEGIN kpse-like
+-- global variables:
+-- texdocs: a Lua table version of $TEXDOCS
+-- do_recurse: do_recurse[i] = 1 iff texdocs[i] ends with // in $TEXDOCS
+-- must_have_lsr: must_have_lsr[i] = 1 iff texdocs[i] starts with !! in $TEXDOCS
+-- exact_docfiles: list of "exact matches"
+-- rel_docfiles: list of "non-exact matches"
 
--- get global texdocs, do_recurse and must_have_lsr lists from kpse's $TEXDOCS
+-- set texdocs, do_recurse and must_have_lsr lists from kpse's $TEXDOCS
 function get_texdocs ()
     local sep = (os.type == 'windows') and ';' or ':'
     texdocs = kpse.expand_var ("$TEXDOCS")
     -- expand the path and turn it into a lua list
     texdocs = string.explode (kpse.expand_braces (texdocs), sep)
     do_recurse, must_have_lsr = {}, {} -- global
+    err_print('Search paths:', 'debug3')
     for i, dir in ipairs (texdocs) do
         local n
         dir, n = string.gsub (dir, '//$', '')
         do_recurse[i] = (n == 1)
         texdocs[i], n = string.gsub (dir, '^!!', '')
         must_have_lsr[i] = (n == 1)
+        err_print(string.format('%s (do_recurse=%s, must_have_lsr=%s)',
+            texdocs[i],
+            do_recurse[i] and 'true' or 'false',
+            must_have_lsr[i] and 'true' or 'false'), 'debug3')
     end
 end
 
--- says if ext is 'good' according to ext_list
-function is_good_ext (ext)
-    for e in list (config.ext_list) do
-        if e == '*' then
-            return true 
-        elseif (e == '') and (not ext) then
-            return true
-        elseif ext == e then
-            return true
-        end
-    end
-    return false
-end
+-- once get_texdocs() is done, roots are represented by their index in texdocs
+-- usefull to avoid fake matches and also for the sort routine
+-- the next two functions do the conversions
 
--- include a file in the lists if it should be
-function process_file (file, pathfile, code, pattern)
-    local base, ext = string.match(file, '^(.*)%.(.*)$')
-    if string.find(pathfile, pattern, 1, no_regex) and is_good_ext (ext)
-        then 
-        if (base == pattern) or (file == pattern) then 
-            table.insert(exact_docfiles, code_path (code, pathfile))
-        else
-            table.insert(rel_docfiles, code_path (code, pathfile))
-        end
-    end
-end
-
--- encodes the base path on two digits and concatenate with filename
--- see real_path() for decoding
+-- encode the base path on two digits and concatenate with filename
 function code_path (code, file)
     local padding = (code > 9) and '' or '0'
     return padding..code..':'..file
 end
 
--- scan a tree
+-- decode a path as given in *_docfiles into a real path
+function real_path (fake)
+    local code, file = string.match (fake, '^(.-):(.*)$')
+    code = tonumber (code)
+    return win32_hook (texdocs[code]..'/'..file)
+end
+
+-- merge two components of a path, taking care of empty components
+function merge_path (a, b)
+    return ((a == '') or (b == '')) and a..b or a..'/'..b
+end
+
+-- scan a tree without ls-R file
 function scan_tree (code, path, pattern, recurse)
     for file in lfs.dir(path) do
         if file ~= '.' and file ~= '..' then
@@ -165,7 +200,7 @@ function scan_tree (code, path, pattern, recurse)
     end
 end
 
--- finds a root with ls-R above path and return it or nil
+-- finds a ls-R file in a parent directory an return it or nil
 function lsr_root (path)
     if not lfs.isdir (path) then return end
     local root, shift = path, ''
@@ -181,11 +216,6 @@ function lsr_root (path)
     end
 end
 
--- merge two components of a path, taking care of empty components
-function merge_path (a, b)
-    return ((a == '') or (b == '')) and a..b or a..'/'..b
-end
-
 -- scan a ls-R file
 function scan_lsr (code, shift, pattern)
     local isdoc = false
@@ -215,8 +245,18 @@ function scan_lsr (code, shift, pattern)
     lsr:close()
 end
 
--- find dirfiles according to pattern
+-- remove directories from a list
+function rmdirs (files)
+    local res = {}
+    for f in list (files) do
+        if not is_dir[f] then table.insert(res, f) end
+    end
+    return res
+end
+
+-- find docfiles "matching" pattern
 function populate_docfiles (pattern)
+    pattern = normalize_pattern(pattern)
     if not texdocs then get_texdocs() end
     rel_docfiles, exact_docfiles = {}, {} -- global
     is_dir = {} -- global; is_dir[path] = true iff path is a dir, see scan_lsr
@@ -236,8 +276,6 @@ function populate_docfiles (pattern)
     rel_docfiles = rmdirs (rel_docfiles)
 end
 
--- END kpse-like
-
 -- like populate_docfiles, but rel replaces exact if exact is empty
 function mixed_populate_docfiles (pattern)
     populate_docfiles (pattern)
@@ -249,99 +287,149 @@ function mixed_populate_docfiles (pattern)
     end
 end
 
--- translate a path as given by populate_docfiles into a real path
--- should never be called before get_texdocs()
-function real_path (fake)
-    local code, file = string.match (fake, '^(.-):(.*)$')
-    code = tonumber (code)
-    return win32_hook (texdocs[code]..'/'..file)
+-- for sty files, we obviously don't want to look in TEXDOCS...
+-- and we don't need a list since those are not duplicated (ahem...)
+function populate_docfiles_sty (styname)
+    exact_docfiles = { kpse.find_file (styname) }
+    rel_docfiles = {}
 end
 
--- now a special function that does nothing on Unix
-if os.type == "windows" then
-    function win32_hook (path)
-        local res = string.gsub (path, '/', '\\')
-        return res -- get rid of gsub's 2nd arg
-    end
-else
-    function win32_hook (path)
-        return path
+----------------------------   selecting results   -----------------------------
+
+-- says if ext is 'good' according to ext_list
+function is_good_ext (ext)
+    for e in list (config.ext_list) do
+        if e == '*' then
+            return true 
+        elseif (e == '') and (not ext) then
+            return true
+        elseif ext == e then
+            return true
+        end
     end
+    return false
 end
 
--- remove directories from the files list
-function rmdirs (files)
-    local res = {}
-    for f in list (files) do
-        if not is_dir[f] then table.insert(res, f) end
+-- include a file in the *_docfiles lists if it "matches"
+function process_file (file, pathfile, code, pattern)
+    local base, ext = string.match(string.lower(file), '^(.*)%.(.*)$')
+    if string.find(string.lower(pathfile), pattern, 1, no_regex) 
+        and is_good_ext (ext) then 
+        if (base == pattern) or (file == pattern) then 
+            table.insert(exact_docfiles, code_path (code, pathfile))
+        else
+            table.insert(rel_docfiles, code_path (code, pathfile))
+        end
     end
-    return res
 end
 
--- for sty files, we obviously don't want to look in TEXDOCS...
--- and we don't need a list since those are not duplicated (ahem...)
-function populate_docfiles_sty (styname)
-    exact_docfiles = { kpse.find_file (styname) }
-    rel_docfiles = {}
+-- for now, just make lowercase, but may do more later
+function normalize_pattern (pattern)
+    return string.lower(pattern)
+end
+
+-----------------------------   sorting results   ------------------------------
+
+-- compare two filenames with the following rule:
+-- 1. extensions are ordered as in ext_list first,
+-- 2. then filenames lexicographically.
+function file_order (a, b)
+    local ext_a = string.match (a, '^.*%.(.*)$')
+    local ext_b = string.match (b, '^.*%.(.*)$')
+    ext_pos_a = config.ext_list_inv[ext_a] or (config.ext_list_max+1)
+    ext_pos_b = config.ext_list_inv[ext_b] or (config.ext_list_max+1)
+    if ext_pos_a < ext_pos_b then
+        return true
+    elseif ext_pos_a > ext_pos_b then
+        return false
+    else
+        return (a < b)
+    end
 end
 
+--------------------------------------------------------------------------------
+----------------   functions to set config values and aliases   ----------------
+--------------------------------------------------------------------------------
 
--- functions to set config values and aliases
----------------------------------------------
+----------------------------   general functions   -----------------------------
 
--- set a value without overwriting if already set and
--- using to special types: *_list and *_switch
-function set_config_element (key, value, file, line)
-    if config[key] == nil then -- must explicitly test for nil, not false
-        if string.match(key, '_list$') then
-            -- this is actually a coma-separated list of values
-            local values = string.explode(value, ',')
-            local inverse = {}
-            for i, j in ipairs(values) do
-                values[i] = string.gsub(j, '%s*$', '')
-                values[i] = string.gsub(j, '^%s*', '')
-                inverse[j] = i
-            end
-            config[key] = values
-            config[key..'_inv'] = inverse
-            config[key..'_max'] = #values
-        elseif string.find (key, '_switch$') then
-            if value == 'true' then
-                config[key] = true
-            elseif value == 'false' then
-                config[key] = false
-            else
-                config_warn (key, value, file, line)
-            end
-        elseif string.find (key, '_level$') then
-            local val = tonumber (value)
-            if val then 
-                config[key] = val
-            else
-                config_warn (key, value, file, line)
-            end
+-- set a config parameter, but don't overwrite it if already set
+-- three special types: *_list (list), *_switch (boolean), *_level (number)
+function set_config_element (key, value, context)
+    local is_known = false -- is key a valid option?
+    for option in list(known_options) do
+        if string.match(key, option) then is_known = true break end
+    end
+    -- warn and exit if key is not a known option
+    if not is_known then config_warn(key, nil, context) return end
+    -- exit if key is already set (/!\ must test for nil, not false)
+    if not (config[key] == nil) then return nil end
+    if string.match(key, '_list$') then -- coma-separated list
+        local values = string.explode(value, ',')
+        local inverse = {}
+        for i, j in ipairs(values) do -- sanitize values...
+            values[i] = string.gsub(j, '%s*$', '')
+            values[i] = string.gsub(j, '^%s*', '')
+            inverse[j] = i -- ... and build inverse mapping on the way
+        end
+        config[key] = values
+        config[key..'_inv'] = inverse
+        config[key..'_max'] = #values
+    elseif string.find (key, '_switch$') then -- boolean
+        if value == 'true' then
+            config[key] = true
+        elseif value == 'false' then
+            config[key] = false
+        else
+            config_warn (key, value, context)
+        end
+    elseif string.find (key, '_level$') then -- integer
+        local val = tonumber (value)
+        if val then 
+            config[key] = val
         else
-            config[key] = value
+            config_warn (key, value, context)
         end
+    else -- string
+        config[key] = value
+    end
+    -- special case: if we just set verbosity_level, print version info now
+    if key == 'verbosity_level' then
+        err_print(arg[0]..' version '..version, 'debug1')
     end
+    -- now tell what we have just done, for debugging
+    err_print('Setting "'..key..'='..value..'" '
+    ..context_to_string(context)..'.', 'debug2')
 end
 
 -- a helper  function for warning messages in the above
-function config_warn (key, value, file, line)
-    local begin = 'illegal value '..value..' for key '..key
+function config_warn (key, value, context)
+    local begin = value and 'Illegal value "'..value..'" for option "'..key..'"'
+    or 'Unkown option "'..key..'"'
     local ending = '.  Skipping.'
-    if file and line then
-        err_print (begin..'\nin '..file..' line '..line..ending, 'warning')
+    err_print (begin..'\n    '..context_to_string(context)..ending, 'warning')
+end
+
+-- interpreting 'context' for the previous functions
+function context_to_string(context)
+    if not context then return '(no context)' end
+    if      context.src == 'cl' then
+        return 'from command line option "'..context.name..'"'
+    elseif  context.src == 'env' then
+        return 'from environment variable "'..context.name..'"'
+    elseif  context.src == 'file' then
+        return 'in file "'..context.file..'" on line '..context.line
+    elseif  context.src == 'def' then
+        return 'from built-in defaults'
     else
-        err_print (begin..ending, 'warning')
+        return 'from unkown source (should not happen, please report)'
     end
 end
 
-
 -- set a whole list, also whithout overwriting
-function set_config_list (conf)
+function set_config_list (conf, context)
     for key, value in pairs(conf) do
-        set_config_element (key, value)
+        set_config_element (key, value, context)
     end
 end
 
@@ -352,89 +440,96 @@ function set_alias (key, value)
     end
 end
 
+------------------------   options from command line   -------------------------
+
 -- set config from the command line
 -- Please make sure to update usage_msg accordingly
 -- and set a default value in setup_config_from_defaults() if relevant.
+-- TODO: should use some getopt_long()-like mechanism some day
 function setup_config_from_cl ()
+    local curr_arg
+    local function set_config_elt(key, val) 
+        set_config_element(key, val, {src='cl', name=curr_arg})
+    end
     while arg[1] and string.match(arg[1],'^%-') do
         curr_arg = table.remove(arg,1)
         if (curr_arg == '-h') or (curr_arg == '--help') then
             print (usage_msg)
             os.exit(0)
-        elseif (curr_arg == '-v') or (curr_arg == '--version') then
-            print (progname .. ' version: ' .. version )
+        elseif (curr_arg == '-V') or (curr_arg == '--version') then
+            print (progname .. ' ' .. version )
             os.exit(0)
         elseif (curr_arg == '-f') or (curr_arg == '--files') then
-            print_config_files ()
+            print (progname .. ' ' .. version )
+            setup_config_from_files ()
+            show_config_files (print, true)
             os.exit(0)
         elseif (curr_arg == '-w') or (curr_arg == '--view') then
-            set_config_element('mode', 'view')
+            set_config_elt('mode', 'view')
         elseif (curr_arg == '-m') or (curr_arg == '--mixed') then
-            set_config_element('mode', 'mixed')
+            set_config_elt('mode', 'mixed')
         elseif (curr_arg == '-l') or (curr_arg == '--list') then
-            set_config_element('mode', 'list')
+            set_config_elt('mode', 'list')
         elseif (curr_arg == '-s') or (curr_arg == '--search') then
-            set_config_element ('mode', 'search')
+            set_config_element ('mode', 'search', {src='cl', name=curr_arg})
         elseif (curr_arg == '-r') or (curr_arg == '--regex') then
-            set_config_element ('mode', 'regex')
+            set_config_element ('mode', 'regex', {src='cl', name=curr_arg})
         elseif (curr_arg == '-I') or (curr_arg == '--nointeract') then
-            set_config_element('interact_switch', 'false')
+            set_config_elt('interact_switch', 'false')
         elseif (curr_arg == '-i') or (curr_arg == '--interact') then
-            set_config_element('interact_switch', 'true')
+            set_config_elt('interact_switch', 'true')
         elseif (curr_arg == '-A') or (curr_arg == '--noalias') then
-            set_config_element('alias_switch', 'false')
+            set_config_elt('alias_switch', 'false')
         elseif (curr_arg == '-a') or (curr_arg == '--alias') then
-            set_config_element('alias_switch', 'true')
-        elseif string.match(curr_arg, '^%-n') then 
-            set_config_element('noise_level', 
-            string.gsub(curr_arg, '^%-n=?', ''))
-        elseif string.match(curr_arg, '^%-%-noise%-level') then
-            set_config_element('noise_level', 
-            string.gsub(curr_arg, '^%-%-noise%-level=?', ''))
+            set_config_elt('alias_switch', 'true')
+        elseif (curr_arg == '-d') or (curr_arg == '--debug') then
+            set_config_elt('verbosity_level', err_max)
+        elseif string.match(curr_arg, '^%-v') then 
+            local value = string.gsub(curr_arg, '^%-v=?', '')
+            set_config_elt('verbosity_level', value)
+        elseif string.match(curr_arg, '^%-%-verbosity') then
+            local value = string.gsub(curr_arg, '^%-%-verbosity=?', '')
+            set_config_elt('verbosity_level', value)
         elseif string.match(curr_arg, '^%-e') then 
-            set_config_element('ext_list', 
-            string.gsub(curr_arg, '^%-e=?', ''))
+            local value = string.gsub(curr_arg, '^%-e=?', '')
+            set_config_elt('ext_list', value)
         elseif string.match(curr_arg, '^%-%-extensions') then
-            set_config_element('ext_list', 
-            string.gsub(curr_arg, '^%-%-extensions=?', ''))
+            local value = string.gsub(curr_arg, '^%-%-extensions=?', '')
+            set_config_elt('ext_list', value)
         else
-            err_print ("unknow option: "..curr_arg, "error")
-            print (usage_msg)
+            err_print ("unknown option: "..curr_arg, "error")
+            print (error_msg)
             os.exit(1)
         end
     end
 end
 
--- the default value af config.alias_switch depends on the mode as follows
-function alias_from_mode (mode)
-    if (mode == 'view') or (mode == 'mixed') or (mode == 'list') then 
-        return 'true'
-    else
-        return 'false'
-    end
-end
+-------------------------   config from environment   --------------------------
 
 -- set config from environment if available
 function setup_config_from_env ()
-    set_config_list {
-        viewer_pdf  = os.getenv ("PDFVIEWER_texdoc") 
-        or os.getenv ("TEXDOCVIEW_pdf") or os.getenv ("TEXDOC_VIEWER_PDF")
-        or os.getenv ("PDFVIEWER"),
-        viewer_ps   = os.getenv ("PSVIEWER_texdoc")
-        or os.getenv ("TEXDOCVIEW_ps") or os.getenv ("TEXDOC_VIEWER_PS")
-        or os.getenv ("PSVIEWER"),
-        viewer_dvi  = os.getenv ("DVIVIEWER_texdoc")
-        or os.getenv ("TEXDOCVIEW_dvi") or os.getenv ("TEXDOC_VIEWER_DVI")
-        or os.getenv ("DVIVIEWER"),
-        viewer_html = os.getenv ("BROWSER_texdoc")
-        or os.getenv ("TEXDOCVIEW_html") or os.getenv ("TEXDOC_VIEWER_HTML")
-        or os.getenv ("BROWSER"),
-        viewer_txt  = os.getenv ("PAGER_texdoc")
-        or os.getenv ("TEXDOCVIEW_txt") or os.getenv ("TEXDOC_VIEWER_TXT")
-        or os.getenv ("PAGER"),
-    }
+    local function set_config_elt_from_vars(key, vars)
+        for var in list(vars) do
+            local value = os.getenv(var)
+            if value then
+                set_config_element(key, value, {src='env', name=var})
+            end
+        end
+    end
+    set_config_elt_from_vars('viewer_pdf',
+    {"PDFVIEWER_texdoc", "TEXDOCVIEW_pdf", "TEXDOC_VIEWER_PDF", "PDFVIEWER"})
+    set_config_elt_from_vars('viewer_ps',
+    {"PSVIEWER_texdoc", "TEXDOCVIEW_ps", "TEXDOC_VIEWER_PS", "PSVIEWER"})
+    set_config_elt_from_vars('viewer_dvi',
+    {"DVIVIEWER_texdoc", "TEXDOCVIEW_dvi", "TEXDOC_VIEWER_DVI", "DVIVIEWER"})
+    set_config_elt_from_vars('viewer_html',
+    {"BROWSER_texdoc", "TEXDOCVIEW_html", "TEXDOC_VIEWER_HTML", "BROWSER"})
+    set_config_elt_from_vars('viewer_txt',
+    {"PAGER_texdoc", "TEXDOCVIEW_txt", "TEXDOC_VIEWER_TXT", "PAGER"})
 end
 
+----------------------   options and aliases from files   ----------------------
+
 -- set config+aliases from a particular config file assumed to exist
 function read_config_file(configfile)
     local cnf = assert(io.open(configfile, 'r')) 
@@ -449,7 +544,8 @@ function read_config_file(configfile)
         line = string.gsub(line, '^%s*', '')    -- remove leading spaces
         key, val = string.match(line, '^([%a%d_]+)%s*=%s*(.+)')
         if key and val then 
-            set_config_element(key, val, configfile, lineno)
+            set_config_element(key, val, {
+                src='file', file=configfile, line=lineno})
         else
             key, val = string.match(line, '^alias%s+([%a%d_-]+)%s*=%s*(.+)')
             if key and val then
@@ -471,33 +567,54 @@ function get_config_files ()
     local TEXMFHOME  = kpse.var_value ('TEXMFHOME')
     local TEXMFLOCAL = kpse.var_value ('TEXMFLOCAL')
     local TEXMFMAIN  = kpse.var_value ('TEXMFMAIN')
-    local config_files = {}
     return {
         TEXMFHOME  .. '/texdoc/texdoc-'..platform..'.cnf',
         TEXMFHOME  .. '/texdoc/texdoc.cnf',
+        TEXMFHOME  .. '/texdoc/texdoc-dist.cnf',
         TEXMFLOCAL .. '/texdoc/texdoc-'..platform..'.cnf',
         TEXMFLOCAL .. '/texdoc/texdoc.cnf',
         TEXMFMAIN  .. '/texdoc/texdoc.cnf'
     } 
 end
 
+-- the config_files table is shared by the next two functions
+do
+local config_files = {}
+
 -- set config/aliases from all config files 
 function setup_config_from_files ()
-    for file in list (get_config_files ()) do
-        if lfs.isfile(file) then read_config_file (file) end
+    for i, file in ipairs (get_config_files ()) do
+        local found = lfs.isfile(file)
+        config_files[i] = {
+            path = file,
+            status = found and (config.lastfile_switch 
+            and 'disabled' or 'active') or 'absent',
+        }
+        if config_files[i].status == 'active' then
+            read_config_file (file) 
+        end
     end
 end
 
 -- now a special information function (see -f,--file option)
-function print_config_files ()
-    print "Configuration files are:"
-    for i, file in ipairs (get_config_files ()) do
-        local found = lfs.isfile(file) and "(active)" or "(not found)"
-        local home = (i==2) and "* " or "" -- home conffile is the 2nd
-        print (home..found, win32_hook(file))
+function show_config_files (print_fun, prefix)
+    print_fun("Configuration files are:")
+    for i, file in ipairs (config_files) do
+        local home = prefix and 
+        ((i==2) and "(*) " or "    ") -- home conffile is the 2nd
+        or ''
+        print_fun (home..file.status..'\t'..win32_hook(file.path))
+    end
+    if prefix then 
+        print("(*) This is the recommended configuration file "
+        .. "for your personal preferences.")
     end
 end
 
+end -- scope of config_files
+
+----------------------   options from built-in defaults   ----------------------
+
 -- for default viewer on general Unix, we have a list; the following two
 -- functions are used to check in the path which program is available
 
@@ -521,19 +638,23 @@ end
 
 -- set some fall-back default values if no previous value is set
 function setup_config_from_defaults()
+    local function set_config_ls(ls) set_config_list(ls, {src='def'}) end
+    local function set_config_elt(key, val) 
+        set_config_element(key, val, {src='def'}) 
+    end
     if (os.type == "windows") then
         -- probably Windows (or OS/2)
         -- which commands should we use for unzipping?
-        set_config_list {
+        set_config_ls {
             viewer_dvi    = 'start ""',
             viewer_html   = 'start ""',
             viewer_pdf    = 'start ""',
             viewer_ps     = 'start ""',
-            viewer_txt    = 'start ""',
+            viewer_txt    = 'start cmd /k more',
         }
     else -- since we don't support msdos, if os.type is not windows, it's unix
         if (os.name == 'macosx') then
-            set_config_list {
+            set_config_ls {
                 viewer_dvi    = 'open',
                 viewer_html   = 'open',
                 viewer_pdf    = 'open',
@@ -541,7 +662,7 @@ function setup_config_from_defaults()
                 viewer_txt    = 'less',
             }
         else
-            set_config_list {
+            set_config_ls {
                 viewer_dvi      = first_in_path {
                     {'evince',  '(evince %s) &'},
                     {'okular',  '(okular %s) &'},
@@ -583,33 +704,45 @@ function setup_config_from_defaults()
         end
     end
     -- then various stuff
-    set_config_list {
+    set_config_ls {
         mode                = 'view',
-        interact_switch  = 'true',
-        noise_level         = '3',
+        interact_switch     = 'true',
+        verbosity_level     = '3',
     }
     -- must be set after mode!
-    set_config_element ('alias_switch', alias_from_mode(config.mode))
+    set_config_elt ('alias_switch', alias_from_mode(config.mode))
     -- now a particular case for config.ext_list and zip-related stuff
     -- Note: removed texdoc_formats/zip_formats, gives simpler & generic code
     if support_zipped then
-        set_config_element('ext_list', 
+        set_config_elt('ext_list', 
         'pdf,pdf.gz,pdf.bz2, html,html.gz,html.bz2, txt,txt.gz,txt.bz2,'..
         'dvi,dvi.gz,dvi.bz2, ps,ps.gz,ps.bz2, ,gz,bz2')
-        set_config_list {
+        set_config_ls {
             unzip_gz    = 'gzip -d -c ',
             unzip_bz2   = 'bzip -d -c ',
             rm_file     = 'rm -f',
             rm_dir      = 'rmdir'
         }
     else
-        set_config_element('ext_list', 'pdf, html, txt, dvi, ps, ')
+        set_config_elt('ext_list', 'pdf, html, txt, dvi, ps, ')
+    end
+end
+
+-- the default value of config.alias_switch depends on the mode as follows
+function alias_from_mode (mode) -- /!\ returns a string!
+    if (mode == 'view') or (mode == 'mixed') or (mode == 'list') then
+        return 'true'
+    else
+        return 'false'
     end
+
 end
 
+--------------------------------------------------------------------------------
+---------------   functions for viewing/displaying the results   ---------------
+--------------------------------------------------------------------------------
 
--- functions for viewing/displaying the results
------------------------------------------------
+---------------------------------   viewing   ----------------------------------
 
 -- prepare for viewing: set viewer_replacement and viewer_ext
 -- may uncompress if support_zipped is set (giving the complete filename on the
@@ -640,7 +773,7 @@ function how_to_view (filename)
         -- files without extension are assumed to be text
         viewext = string.match(filename,'.*%.(.*)$') or 'txt'
         if not config['viewer_'..viewext] then
-            err_print (": cannot determine type of file\n\t"
+            err_print ("cannot determine type of file\n\t"
             ..filename.."Assuming text.  Set the `viewer_"..viewext..
             "' variable in texdoc.cnf to avoid this.", "warning")
             viewext = 'txt'
@@ -674,22 +807,7 @@ function try_viewing (view_command, viewer_replacement)
     return view_result
 end
 
--- compare two filenames with the following rule:
--- 1. extensions are ordered as in ext_list first,
--- 2. then filenames lexicograhpicaly.
-function file_order (a, b)
-    local ext_a = string.match (a, '^.*%.(.*)$')
-    local ext_b = string.match (b, '^.*%.(.*)$')
-    ext_pos_a = config.ext_list_inv[ext_a] or (config.ext_list_max+1)
-    ext_pos_b = config.ext_list_inv[ext_b] or (config.ext_list_max+1)
-    if ext_pos_a < ext_pos_b then
-        return true
-    elseif ext_pos_a > ext_pos_b then
-        return false
-    else
-        return (a < b)
-    end
-end
+--------------------------------   displaying   --------------------------------
 
 -- display a table, sorted, numbered with given offset (0 by default), 
 -- with real path
@@ -697,11 +815,7 @@ function display_table (t, offset)
     offset = offset or 0
     table.sort(t, file_order)
     for i, val in ipairs (t) do
-        if config.interact_switch then 
-            print (i+offset, real_path(val))
-        else
-            print (real_path(val))
-        end
+        print(string.format('%2d %s', i+offset, real_path(val)))
     end
 end
 
@@ -732,8 +846,9 @@ function print_menu (files, comp)
     end
 end
 
--- error handling
------------------
+--------------------------------------------------------------------------------
+-----------------------   functions for error handling   -----------------------
+--------------------------------------------------------------------------------
 
 -- exit codes (probably make sense only with a single argument)
 -- 0    OK
@@ -764,19 +879,18 @@ end
 
 -- generic error display function (see the error_priority constant)
 function err_print (msg, lvl)
-    -- be careful: maybe config.noise_level is not set yet
-    local noise_level = config.noise_level or 10000
-    if err_priority[lvl] <= noise_level then
+    -- be careful: maybe config.verbosity_level is not set yet
+    local verbosity_level = config.verbosity_level or 2
+    if err_priority[lvl] <= verbosity_level then
         io.stderr:write ("texdoc "..lvl..": "..msg.."\n")
     end
 end
 
+--------------------------------------------------------------------------------
+---------------------------   main code execution   ----------------------------
+--------------------------------------------------------------------------------
 
--- END of function definitions: here starts the execution
---=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
-
--- initialisations
-------------------
+-----------------------------   initialisations   ------------------------------
 
 -- initialize kpathsea
 kpse.set_program_name(arg[-1], "texdoc")
@@ -791,8 +905,10 @@ setup_config_from_env ()
 setup_config_from_files ()
 setup_config_from_defaults ()
 
--- the main loop over the args
-------------------------------
+-- now that verbosity_level is known...
+show_config_files(function(s) err_print(s, 'debug1') end)
+
+------------------------   looping over the arguments   ------------------------
 
 -- initialising and saving a few values
 exit_code = 0