summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorManuel Pégourié-Gonnard <mpg@elzevir.fr>2008-08-01 17:30:26 +0000
committerManuel Pégourié-Gonnard <mpg@elzevir.fr>2008-08-01 17:30:26 +0000
commitfff617adf5f099ff23f863682f5a4cd492ef1c88 (patch)
treef46d7ee0fb412157f4594b9b14e733b664634cc3
parent6e8b21e130d1879f95bcaedd269c2eebe45bcfe7 (diff)
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
-rwxr-xr-xMaster/texmf/scripts/texlive/texdoc.tlu176
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: