# HG changeset patch # User Rik # Date 1372621896 25200 # Node ID 5372068bb148165d1f5fe5ea898df71e310aa5e7 # Parent 5e30b1c950b8d0b7cf9710b42f24996cc3f9c7fc Rename gen_doc_cache() to doc_cache_create(). * scripts/help/doc_cache_create.m: Renamed from gen_doc_cache.m * scripts/help/gen_doc_cache.m: deleted. * scripts/help/module.mk: Add doc_cache_create to build system. * scripts/deprecated/module.mk: Add gen_doc_cache to deprecated directory. * NEWS: Add note about deprecated function gen_doc_cache and new function doc_cache_create. * doc/interpreter/basics.txi: Add doc_cache_create to manual. * libgui/src/resource-manager.cc: Update list of keywords to include doc_cache_create. * libinterp/interpfcn/help.cc: Add seealso links to doc_cache_create. * scripts/pkg/private/generate_lookfor_cache.m: Change function calls to doc_cache_create. diff -r 5e30b1c950b8 -r 5372068bb148 NEWS --- a/NEWS Sun Jun 30 09:09:49 2013 -0700 +++ b/NEWS Sun Jun 30 12:51:36 2013 -0700 @@ -176,19 +176,20 @@ ** Other new functions added in 3.8.0: - base64_decode erfcinv rgbplot - base64_encode erfi shrinkfaces - betaincinv expint splinefit - built_in_docstrings_file findfigs strjoin - cmpermute fminsearch struct2hdl - cmunique gallery tetramesh - colorcube gco waterfall - copyobj hdl2struct - dawson importdata - dblist iscolormap + base64_decode ellipke polyeig + base64_encode erfcinv rgbplot + betaincinv erfi shrinkfaces + built_in_docstrings_file expint splinefit + cmpermute findfigs strjoin + cmunique fminsearch struct2hdl + colorcube gallery tetramesh + copyobj gco waterfall + dawson hdl2struct + dblist importdata + doc_cache_create iscolormap ellipj lines - ellipke polyeig - + + ** Deprecated functions. The following functions were deprecated in Octave 3.4 and have been @@ -204,6 +205,7 @@ be removed from Octave 3.12 (or whatever version is the second major release after 3.8): + gen_doc_cache java_convert_matrix java_debug java_get diff -r 5e30b1c950b8 -r 5372068bb148 doc/interpreter/basics.txi --- a/doc/interpreter/basics.txi Sun Jun 30 09:09:49 2013 -0700 +++ b/doc/interpreter/basics.txi Sun Jun 30 12:51:36 2013 -0700 @@ -441,7 +441,7 @@ generating the documentation. They are documented here for completeness and because they may occasionally be useful for users. -@DOCSTRING(gen_doc_cache) +@DOCSTRING(doc_cache_create) @DOCSTRING(get_help_text) diff -r 5e30b1c950b8 -r 5372068bb148 libgui/src/resource-manager.cc --- a/libgui/src/resource-manager.cc Sun Jun 30 09:09:49 2013 -0700 +++ b/libgui/src/resource-manager.cc Sun Jun 30 12:51:36 2013 -0700 @@ -695,6 +695,7 @@ "do_braindead_shortcircuit_evaluation " "do_string_escapes " "doc " + "doc_cache_create " "doc_cache_file " "dos " "dot " @@ -865,7 +866,6 @@ "gcd " "gcf " "ge " - "gen_doc_cache " "genpath " "genvarname " "geocdf " diff -r 5e30b1c950b8 -r 5372068bb148 libinterp/interpfcn/help.cc --- a/libinterp/interpfcn/help.cc Sun Jun 30 09:09:49 2013 -0700 +++ b/libinterp/interpfcn/help.cc Sun Jun 30 12:51:36 2013 -0700 @@ -1401,7 +1401,7 @@ When called from inside a function with the \"local\" option, the variable is\n\ changed locally for the function and any subroutines it calls. The original\n\ variable value is restored when exiting the function.\n\ -@seealso{lookfor, info_program, doc, help, makeinfo_program}\n\ +@seealso{doc_cache_create, lookfor, info_program, doc, help, makeinfo_program}\n\ @end deftypefn") { return SET_NONEMPTY_INTERNAL_STRING_VARIABLE (doc_cache_file); diff -r 5e30b1c950b8 -r 5372068bb148 scripts/deprecated/module.mk --- a/scripts/deprecated/module.mk Sun Jun 30 09:09:49 2013 -0700 +++ b/scripts/deprecated/module.mk Sun Jun 30 12:51:36 2013 -0700 @@ -7,6 +7,7 @@ deprecated/cut.m \ deprecated/java_debug.m \ deprecated/error_text.m \ + deprecated/gen_doc_cache.m \ deprecated/isstr.m \ deprecated/java_convert_matrix.m \ deprecated/java_get.m \ diff -r 5e30b1c950b8 -r 5372068bb148 scripts/help/doc_cache_create.m --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/scripts/help/doc_cache_create.m Sun Jun 30 12:51:36 2013 -0700 @@ -0,0 +1,159 @@ +## Copyright (C) 2009-2012 S�ren Hauberg +## +## This file is part of Octave. +## +## Octave 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. +## +## Octave 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 Octave; see the file COPYING. If not, see +## . + +## -*- texinfo -*- +## @deftypefn {Function File} {} doc_cache_create (@var{out_file}, @var{directory}) +## Generate documentation caches for all functions in a given directory. +## +## A documentation cache is generated for all functions in @var{directory}. +## The +## resulting cache is saved in the file @var{out_file}. +## The cache is used to speed up @code{lookfor}. +## +## If no directory is given (or it is the empty matrix), a cache for builtin +## operators, etc. is generated. +## +## @seealso{doc_cache_file, lookfor, path} +## @end deftypefn + +function doc_cache_create (out_file = "doc-cache", directory = []) + + ## Check input + if (! ischar (out_file)) + print_usage (); + endif + + ## Generate cache + if (isempty (directory)) + cache = gen_builtin_cache (); + elseif (iscell (directory)) + if (all (cellfun (@ischar, directory))) + cache = gen_doc_cache_in_dir (directory); + else + error ("doc_cache_create: cell must contain only strings"); + endif + elseif (ischar (directory)) + cache = gen_doc_cache_in_dir (directory); + else + error ("doc_cache_create: second input argument must be a string or a cell of strings"); + endif + + ## Save cache + if (! isempty (cache)) + save ("-text", out_file, "cache"); + endif + +endfunction + +function [text, first_sentence, status] = handle_function (f, text, format) + first_sentence = ""; + ## Skip functions that start with __ as these shouldn't be searched by lookfor + if (length (f) > 2 && all (f (1:2) == "_")) + status = 1; + return; + endif + + ## Take action depending on help text format + switch (lower (format)) + case "plain text" + status = 0; + case "texinfo" + [text, status] = __makeinfo__ (text, "plain text"); + case "html" + [text, status] = strip_html_tags (text); + otherwise + status = 1; + endswitch + + ## Did we get the help text? + if (status != 0 || isempty (text)) + warning ("doc_cache_create: unusable help text found in file '%s'", f); + return; + endif + + ## Get first sentence of help text + first_sentence = get_first_help_sentence (f); +endfunction + +function cache = create_cache (list) + cache = {}; + + ## For each function: + for n = 1:length (list) + f = list {n}; + + ## Get help text + [text, format] = get_help_text (f); + + [text, first_sentence, status] = handle_function (f, text, format); + + ## Did we get the help text? + if (status != 0) + continue; + endif + + ## Store the help text + cache (1, end+1) = f; + cache (2, end) = text; + cache (3, end) = first_sentence; + endfor +endfunction + +function cache = gen_doc_cache_in_dir (directory) + + ## If 'directory' is not in the current path, add it so we search it + dir_in_path = ismember (directory, ostrsplit (path (), pathsep ())); + + # dirs not in path + if (! iscell (directory)) + directory = {directory}; + endif + dirs_notpath = {directory{!dir_in_path}}; + + # add them + if (! isempty (dirs_notpath)) + cellfun (@addpath, dirs_notpath); + endif + + # create cache + func = @(s_) create_cache (__list_functions__ (s_)); + cache = cellfun (func, directory, 'UniformOutput', false); + + # concatenate results + cache = [cache{:}]; + + #remove dirs form path + if (! isempty (dirs_notpath)) + cellfun (@rmpath, dirs_notpath); + endif + +endfunction + +function cache = gen_builtin_cache () + operators = __operators__ (); + keywords = __keywords__ (); + builtins = __builtins__ (); + list = {operators{:}, keywords{:}, builtins{:}}; + + cache = create_cache (list); +endfunction + + +%% No true tests desirable for this function. +%% Test input validation +%!error doc_cache_create (1) diff -r 5e30b1c950b8 -r 5372068bb148 scripts/help/gen_doc_cache.m --- a/scripts/help/gen_doc_cache.m Sun Jun 30 09:09:49 2013 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,159 +0,0 @@ -## Copyright (C) 2009-2012 S�ren Hauberg -## -## This file is part of Octave. -## -## Octave 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. -## -## Octave 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 Octave; see the file COPYING. If not, see -## . - -## -*- texinfo -*- -## @deftypefn {Function File} {} gen_doc_cache (@var{out_file}, @var{directory}) -## Generate documentation caches for all functions in a given directory. -## -## A documentation cache is generated for all functions in @var{directory}. -## The -## resulting cache is saved in the file @var{out_file}. -## The cache is used to speed up @code{lookfor}. -## -## If no directory is given (or it is the empty matrix), a cache for builtin -## operators, etc. is generated. -## -## @seealso{lookfor, path} -## @end deftypefn - -function gen_doc_cache (out_file = "doc-cache", directory = []) - - ## Check input - if (! ischar (out_file)) - print_usage (); - endif - - ## Generate cache - if (isempty (directory)) - cache = gen_builtin_cache (); - elseif (iscell (directory)) - if (all (cellfun (@ischar, directory))) - cache = gen_doc_cache_in_dir (directory); - else - error ("gen_doc_cache: cell must contain only strings"); - endif - elseif (ischar (directory)) - cache = gen_doc_cache_in_dir (directory); - else - error ("gen_doc_cache: second input argument must be a string or a cell of strings"); - endif - - ## Save cache - if (! isempty (cache)) - save ("-text", out_file, "cache"); - endif - -endfunction - -function [text, first_sentence, status] = handle_function (f, text, format) - first_sentence = ""; - ## Skip functions that start with __ as these shouldn't be searched by lookfor - if (length (f) > 2 && all (f (1:2) == "_")) - status = 1; - return; - endif - - ## Take action depending on help text format - switch (lower (format)) - case "plain text" - status = 0; - case "texinfo" - [text, status] = __makeinfo__ (text, "plain text"); - case "html" - [text, status] = strip_html_tags (text); - otherwise - status = 1; - endswitch - - ## Did we get the help text? - if (status != 0 || isempty (text)) - warning ("gen_doc_cache: unusable help text found in file '%s'", f); - return; - endif - - ## Get first sentence of help text - first_sentence = get_first_help_sentence (f); -endfunction - -function cache = create_cache (list) - cache = {}; - - ## For each function: - for n = 1:length (list) - f = list {n}; - - ## Get help text - [text, format] = get_help_text (f); - - [text, first_sentence, status] = handle_function (f, text, format); - - ## Did we get the help text? - if (status != 0) - continue; - endif - - ## Store the help text - cache (1, end+1) = f; - cache (2, end) = text; - cache (3, end) = first_sentence; - endfor -endfunction - -function cache = gen_doc_cache_in_dir (directory) - - ## If 'directory' is not in the current path, add it so we search it - dir_in_path = ismember (directory, ostrsplit (path (), pathsep ())); - - # dirs not in path - if (! iscell (directory)) - directory = {directory}; - endif - dirs_notpath = {directory{!dir_in_path}}; - - # add them - if (! isempty (dirs_notpath)) - cellfun (@addpath, dirs_notpath); - endif - - # create cache - func = @(s_) create_cache (__list_functions__ (s_)); - cache = cellfun (func, directory, 'UniformOutput', false); - - # concatenate results - cache = [cache{:}]; - - #remove dirs form path - if (! isempty (dirs_notpath)) - cellfun (@rmpath, dirs_notpath); - endif - -endfunction - -function cache = gen_builtin_cache () - operators = __operators__ (); - keywords = __keywords__ (); - builtins = __builtins__ (); - list = {operators{:}, keywords{:}, builtins{:}}; - - cache = create_cache (list); -endfunction - - -%% No true tests desirable for this function. -%% Test input validation -%!error gen_doc_cache (1) diff -r 5e30b1c950b8 -r 5372068bb148 scripts/help/module.mk --- a/scripts/help/module.mk Sun Jun 30 09:09:49 2013 -0700 +++ b/scripts/help/module.mk Sun Jun 30 12:51:36 2013 -0700 @@ -8,7 +8,7 @@ help/__makeinfo__.m \ help/__unimplemented__.m \ help/doc.m \ - help/gen_doc_cache.m \ + help/doc_cache_create.m \ help/get_first_help_sentence.m \ help/help.m \ help/lookfor.m \ diff -r 5e30b1c950b8 -r 5372068bb148 scripts/pkg/private/generate_lookfor_cache.m --- a/scripts/pkg/private/generate_lookfor_cache.m Sun Jun 30 09:09:49 2013 -0700 +++ b/scripts/pkg/private/generate_lookfor_cache.m Sun Jun 30 12:51:36 2013 -0700 @@ -25,7 +25,7 @@ function generate_lookfor_cache (desc) dirs = strtrim (ostrsplit (genpath (desc.dir), pathsep ())); for i = 1 : length (dirs) - gen_doc_cache (fullfile (dirs{i}, "doc-cache"), dirs{i}); + doc_cache_create (fullfile (dirs{i}, "doc-cache"), dirs{i}); endfor endfunction