Replaced the -v|--verbose option with the finer noise_level config setting.

Reworked info/warning/error/debug message which now go to stderr by the way.
Added some info for multiple arguments.  Cleaned up a few things.  Set version
number to 0.4: hopefully the last change before release.


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

1 files changed, 111 insertions, 65 deletions

diff --git a/Master/texmf/scripts/texlive/texdoc.tlu b/Master/texmf/scripts/texlive/texdoc.tlu
index a3d53906888..584f22ce19e 100755
--- a/Master/texmf/scripts/texlive/texdoc.tlu
+++ b/Master/texmf/scripts/texlive/texdoc.tlu
@@ -1,17 +1,18 @@
 #!/usr/bin/env texlua
--- $Id$
---[[ Revised by Manuel Pégourié-Gonnard and Reinhard Kotucha, 2008.
-First texlua version by Frank Küster (2007) based on the shell script by
-Thomas Esser, David Aspinall, and Simon Wilkinson.
-Public domain.]]
+-- $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 'mixed' mode (view or list)
-  - file lists are now menus (press a key to view results)
+  - 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 (see comments below), not portable
+  - /!\ zip support disabled by default (not portable) (see comments below)
 
   0.3 2007-06-28
   - added changelog
@@ -29,30 +30,37 @@ Public domain.]]
 
 -- some constants 
 progname = 'texdoc'
-version = '0.4beta'
--- make sure to update setup_config_from_cl() and the man page accordingly
+version = '0.4'
+-- 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 | [option(s)] name(s)
-    -h, --help          Show this short help.
-    -V, --version       Print the version of the program.
-    -v, --verbose       Show the command used to display the documentation.
-    -i, --interact      Use interactive menus.
-    -I, --nointeract    Use plain lists, no interaction required.
-    -a, --alias         Use the alias table.
-    -A, --noalias       Don't use the alias table.
-    -e, --extension     Restrict file extensions to the given list.
-    -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.
-The command `texdoc texdoc' gives you the full user guide in pdf.]]
+    -h, --help              Show this short help.
+    -v, --version           Print the version of the program.
+    -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.
+The command `texdoc texdoc' gives you the full user guide in pdf.
+Please report bugs and request features at texlive AT tug.org.]]
 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
+err_priority = {
+    error   = 1,
+    warning = 2,
+    info    = 3,
+    debug1  = 4,
+}
 
 -- zip/gz support
 --
@@ -217,12 +225,12 @@ end
 
 -- END kpse-like
 
--- like populate_docfiles, but exact -> rel if exact empty
+-- like populate_docfiles, but rel replaces exact if exact is empty
 function mixed_populate_docfiles (pattern)
     populate_docfiles (pattern)
     if not exact_docfiles[1] then
         if not string.find (pattern, '/') then
-            print ("texdoc info: No exact match, trying full search mode.")
+            err_print ("No exact match, trying full search mode.", "info")
         end
         exact_docfiles = rel_docfiles
     end
@@ -247,7 +255,7 @@ 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 special_sty_search (styname)
+function populate_docfiles_sty (styname)
     exact_docfiles = { kpse.find_file (styname) }
     rel_docfiles = {}
 end
@@ -259,7 +267,7 @@ end
 -- 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
+    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, ',')
@@ -278,12 +286,14 @@ function set_config_element (key, value, file, line)
             elseif value == 'false' then
                 config[key] = false
             else
-                io.write ('texdoc warning: illegal value '..value..' for '
-                ..key)
-                if file and line then 
-                    io.write ('\nin '..file..' line '..line)
-                end
-                io.write ('.  Skipping.\n')
+                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
         else
             config[key] = value
@@ -291,6 +301,18 @@ function set_config_element (key, value, file, line)
     end
 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
+    local ending = '.  Skipping.'
+    if file and line then
+        err_print (begin..'\nin '..file..' line '..line..ending, 'warning')
+    else
+        err_print (begin..ending, 'warning')
+    end
+end
+
+
 -- set a whole list, also whithout overwriting
 function set_config_list (conf)
     for key, value in pairs(conf) do
@@ -306,7 +328,7 @@ function set_alias (key, value)
 end
 
 -- set config from the command line
--- Please make sure to update usage_msg and the man page accordingly
+-- Please make sure to update usage_msg accordingly
 -- and set a default value in setup_config_from_defaults() if relevant.
 function setup_config_from_cl ()
     while arg[1] and string.match(arg[1],'^%-') do
@@ -314,11 +336,9 @@ function setup_config_from_cl ()
         if (curr_arg == '-h') or (curr_arg == '--help') then
             print (usage_msg)
             os.exit(0)
-        elseif (curr_arg == '-V') or (curr_arg == '--version') then
+        elseif (curr_arg == '-v') or (curr_arg == '--version') then
             print (progname .. ' version: ' .. version )
             os.exit(0)
-        elseif (curr_arg == '-v') or (curr_arg == '--verbose') then
-            set_config_element('verbose_switch', 'true')
         elseif (curr_arg == '-w') or (curr_arg == '--view') then
             set_config_element('mode', 'view')
         elseif (curr_arg == '-m') or (curr_arg == '--mixed') then
@@ -337,14 +357,22 @@ function setup_config_from_cl ()
             set_config_element('alias_switch', 'false')
         elseif (curr_arg == '-a') or (curr_arg == '--alias') then
             set_config_element('alias_switch', 'true')
-        elseif string.match(curr_arg, '^-e') then 
+        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=?', ''))
+        elseif string.match(curr_arg, '^%-e') then 
             set_config_element('ext_list', 
-            string.gsub(curr_arg, '^-e=?', ''))
-        elseif string.match(curr_arg, '^--extension') then
+            string.gsub(curr_arg, '^%-e=?', ''))
+        elseif string.match(curr_arg, '^%-%-extensions') then
             set_config_element('ext_list', 
-            string.gsub(curr_arg, '^--extension=?', ''))
+            string.gsub(curr_arg, '^%-%-extensions=?', ''))
         else
-            print ("texdoc error: unknow option: "..curr_arg)
+            err_print ("unknow option: "..curr_arg, "error")
+            print (usage_msg)
+            os.exit(1)
         end
     end
 end
@@ -391,8 +419,8 @@ function read_config_file(configfile)
                     set_alias(key, val)
                 else
                     if (not string.match (line, '^%s*$')) then
-                        print ('texdoc warning: syntax error in '..configfile..
-                        ' at line '..lineno..'.')
+                        err_print ('syntax error in '..configfile..
+                        ' at line '..lineno..'.', 'warning')
                     end
                 end
             end
@@ -513,8 +541,8 @@ function setup_config_from_defaults()
     -- then various stuff
     set_config_list {
         mode                = 'view',
-        verbose_switch      = 'false',
         interactive_switch  = 'true',
+        noise_level         = '3',
     }
     -- must be set after mode!
     set_config_element ('alias_switch', alias_from_mode(config.mode))
@@ -568,13 +596,13 @@ 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
-            print ("texdoc warning: 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.")
+            "' variable in texdoc.cnf to avoid this.", "warning")
             viewext = 'txt'
             if not config['viewer_'..viewext] then
-                print ("texdoc error: text viewer not found.  This "..
-                "should not happen, sorry.  Skipping\n\t"..filename)
+                err_print ("text viewer not found.  This "..
+                "should not happen, sorry.  Skipping\n\t"..filename, "error")
             end
         end -- viewer for ext
     end -- zipped or not
@@ -592,19 +620,17 @@ function try_viewing (view_command, viewer_replacement)
         else
             view_command = view_command..' "'..viewer_replacement..'"'
         end
-        if config.verbose_switch then
-            print(view_command)
-        end
+        err_print(view_command, 'debug1')
         view_result = os.execute(view_command)
         if not view_result then
-            print("texdoc error: the following command failed\n\t" 
-            .. view_command)
+            err_print (": the following command failed\n\t" 
+            .. view_command, "error")
         end
     end
     return view_result
 end
 
--- compare two files with the following rule:
+-- 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)
@@ -679,8 +705,8 @@ function apologize (reason, name)
         print (msg) -- to get rid of gsub's 2nd value
     else
         exit_code = 255
-        print ('texdoc error: Oops, this should not happen'..
-        ' (unknown error code).  Sorry.')
+        err_print ('Oops, this should not happen'..
+        ' (unknown error code).  Sorry.', 'error')
     end
 end
 
@@ -692,6 +718,15 @@ function assert_arg_not_empty ()
     end
 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
+        io.stderr:write ("texdoc "..lvl..": "..msg.."\n")
+    end
+end
+
 
 -- END of function definitions: here starts the execution
 --=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
@@ -715,29 +750,39 @@ setup_config_from_defaults ()
 -- the main loop over the args
 ------------------------------
 
+-- initialising and saving a few values
 exit_code = 0
 no_regex = true
 real_ext_list = config.ext_list
 real_populate_docfiles = populate_docfiles
 real_mixed_populate_docfiles = mixed_populate_docfiles
 real_real_path = real_path
+
+-- the actual loop
 for docname in list (arg) do
+    -- inform the user which arg beeing treated if more than one was provided
+    if arg[2] then
+        print ("*** Results for: "..docname.." ***")
+    end
+    -- applying alias if relevant
     if config.alias_switch and alias[docname] then
-        print ("texdoc info: "..docname.." aliased to "..alias[docname])
+        err_print (docname.." aliased to "..alias[docname], 'info')
         docname = alias[docname]
     end
+    -- exceptions for arguments with extension given
     if config.mode ~= 'regex' then
         docname_base, docname_ext = string.match (docname, '^(.*)%.(.*)$')
         if docname_ext == 'sty' then 
-            print ("texdoc info: using special search mode for sty files")
-            populate_docfiles = special_sty_search
-            mixed_populate_docfiles = special_sty_search
+            err_print ("using special search mode for sty files", 'info')
+            populate_docfiles = populate_docfiles_sty
+            mixed_populate_docfiles = populate_docfiles_sty
             real_path = function (arg) return arg end
         elseif docname_ext then 
             config.ext_list = { docname_ext } 
             docname = docname_base
         end
     end
+    -- main "ifcase mode" construct
     if (config.mode == 'regex') then
         no_regex = false
         populate_docfiles(docname)
@@ -778,12 +823,13 @@ for docname in list (arg) do
         else                                    -- 2 or more results
             print_menu (exact_docfiles)
         end
-    end -- if construct "case config.mode in"
+    end 
+    -- restoring possibly diverted values
     config.ext_list = real_ext_list
     populate_docfiles = real_populate_docfiles
     mixed_populate_docfiles = real_mixed_populate_docfiles
     real_path = real_real_path
-end -- for docname in arg
+end 
 
 os.exit(exit_code)
 
@@ -792,4 +838,4 @@ os.exit(exit_code)
 -- tab-width: 4
 -- indent-tabs-mode: nil
 -- End:
--- vim: sw=4 ts=4 expandtab:
+-- vim:sw=4 ts=4 expandtab: