From fff617adf5f099ff23f863682f5a4cd492ef1c88 Mon Sep 17 00:00:00 2001 From: Manuel Pégourié-Gonnard Date: Fri, 1 Aug 2008 17:30:26 +0000 Subject: 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 --- Master/texmf/scripts/texlive/texdoc.tlu | 176 ++++++++++++++++++++------------ 1 file 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: -- cgit v1.2.3