# HG changeset patch # User Rik # Date 1300484326 25200 # Node ID 91ccd08fe80cf4851b33772adcc61a02bfcac29f # Parent 9f926b9f83cc8cba2826e0b2f4766a83a7bb355e Add gen_doc_cache, get_help_text, get_help_text_from_file, get_first_help_sentence to documentation. diff -r 9f926b9f83cc -r 91ccd08fe80c doc/ChangeLog --- a/doc/ChangeLog Fri Mar 18 09:37:28 2011 -0700 +++ b/doc/ChangeLog Fri Mar 18 14:38:46 2011 -0700 @@ -1,3 +1,8 @@ +2010-03-18 Rik + + * interpreter/basics.txi: Add gen_doc_cache, get_help_text, + get_help_text_from_file, get_first_help_sentence to documentation. + 2010-03-17 Rik * interpreter/io.txi: Add fileread to documentation. diff -r 9f926b9f83cc -r 91ccd08fe80c doc/interpreter/basics.txi --- a/doc/interpreter/basics.txi Fri Mar 18 09:37:28 2011 -0700 +++ b/doc/interpreter/basics.txi Fri Mar 18 14:38:46 2011 -0700 @@ -387,6 +387,18 @@ @DOCSTRING(suppress_verbose_help_message) +The following functions are principally used internally by Octave for +generating the documentation. They are documented here for completeness +and because they may occasionally be useful for users. + +@DOCSTRING(gen_doc_cache) + +@DOCSTRING(get_help_text) + +@DOCSTRING(get_help_text_from_file) + +@DOCSTRING(get_first_help_sentence) + @node Command Line Editing @section Command Line Editing @cindex command-line editing diff -r 9f926b9f83cc -r 91ccd08fe80c scripts/ChangeLog --- a/scripts/ChangeLog Fri Mar 18 09:37:28 2011 -0700 +++ b/scripts/ChangeLog Fri Mar 18 14:38:46 2011 -0700 @@ -1,3 +1,7 @@ +2010-03-18 Rik + + * help/get_first_help_sentence.m: Improve docstring. Add tests. + 2010-03-17 Rik * scripts/sparse/svds.m: Fix bug #32818, nonconformant arguments diff -r 9f926b9f83cc -r 91ccd08fe80c scripts/help/get_first_help_sentence.m --- a/scripts/help/get_first_help_sentence.m Fri Mar 18 09:37:28 2011 -0700 +++ b/scripts/help/get_first_help_sentence.m Fri Mar 18 14:38:46 2011 -0700 @@ -17,15 +17,14 @@ ## . ## -*- texinfo -*- -## @deftypefn {Function File} {[@var{retval}, @var{status}] =} get_first_help_sentence (@var{name}, @var{max_len}) -## Return the first sentence of a function help text. +## @deftypefn {Function File} {[@var{text}, @var{status}] =} get_first_help_sentence (@var{name}) +## @deftypefnx {Function File} {[@var{text}, @var{status}] =} get_first_help_sentence (@var{name}, @var{max_len}) +## Return the first sentence of a function's help text. ## -## The function reads the first sentence of the help text of the function -## @var{name}. The first sentence is defined as the text after the function +## The first sentence is defined as the text after the function ## declaration until either the first period (".") or the first appearance of -## two consecutive end-lines ("\n\n"). The text is truncated to a maximum -## length -## of @var{max_len}, which defaults to 80. +## two consecutive newlines ("\n\n"). The text is truncated to a maximum +## length of @var{max_len}, which defaults to 80. ## ## The optional output argument @var{status} returns the status reported by ## @code{makeinfo}. If only one output argument is requested, and @var{status} @@ -36,23 +35,23 @@ ## @example ## @group ## get_first_help_sentence ("get_first_help_sentence") -## @print{} ans = Return the first sentence of a function help text. +## @print{} ans = Return the first sentence of a function's help text. ## @end group ## @end example ## @end deftypefn -function [retval, status] = get_first_help_sentence (name, max_len = 80) +function [text, status] = get_first_help_sentence (name, max_len = 80) ## Check input - if (nargin == 0) - error ("get_first_help_sentence: not enough input arguments"); + if (nargin < 1 || nargin > 2) + print_usage (); endif if (!ischar (name)) - error ("get_first_help_sentence: first input must be a string"); + error ("get_first_help_sentence: NAME must be a string"); endif if (!isnumeric (max_len) || max_len <= 0 || max_len != round (max_len)) - error ("get_first_help_sentence: second input must be positive integer"); + error ("get_first_help_sentence: MAX_LEN must be positive integer"); endif ## First, we get the raw help text @@ -61,11 +60,11 @@ ## Then, we take action depending on the format switch (lower (format)) case "plain text" - [retval, status] = first_sentence_plain_text (help_text, max_len); + [text, status] = first_sentence_plain_text (help_text, max_len); case "texinfo" - [retval, status] = first_sentence_texinfo (help_text, max_len); + [text, status] = first_sentence_texinfo (help_text, max_len); case "html" - [retval, status] = first_sentence_html (help_text, max_len); + [text, status] = first_sentence_html (help_text, max_len); case "not documented" error ("get_first_help_sentence: `%s' is not documented\n", name); case "not found" @@ -80,18 +79,18 @@ endfunction ## This function extracts the first sentence from a plain text help text -function [retval, status] = first_sentence_plain_text (help_text, max_len) +function [text, status] = first_sentence_plain_text (help_text, max_len) ## Extract first line by searching for a period or a double line-end. - period_idx = find (help_text == ".", 1); + period_idx = find (help_text == '.', 1); line_end_idx = strfind (help_text, "\n\n"); - retval = help_text (1:min ([period_idx(:); line_end_idx(:); max_len; length(help_text)])); + text = help_text (1:min ([period_idx(:); line_end_idx(:); max_len; length(help_text)])); status = 0; endfunction ## This function extracts the first sentence from a Texinfo help text. ## The function works by removing @def* from the texinfo text. After this, we ## render the text to plain text using makeinfo, and then extract the first line. -function [retval, status] = first_sentence_texinfo (help_text, max_len) +function [text, status] = first_sentence_texinfo (help_text, max_len) ## Lines ending with "@\n" are continuation lines, so they should be concatenated ## with the following line. help_text = strrep (help_text, "@\n", " "); @@ -141,16 +140,26 @@ [help_text, status] = __makeinfo__ (help_text, "plain text"); ## Extract first line with plain text method. - retval = first_sentence_plain_text (help_text, max_len); + text = first_sentence_plain_text (help_text, max_len); endfunction ## This function extracts the first sentence from a html help text. ## The function simply removes the tags and treats the text as plain text. -function [retval, status] = first_sentence_html (help_text, max_len) +function [text, status] = first_sentence_html (help_text, max_len) ## Strip tags [help_text, status] = strip_html_tags (help_text); ## Extract first line with plain text method. - retval = first_sentence_plain_text (help_text, max_len); + text = first_sentence_plain_text (help_text, max_len); endfunction +%!assert (strcmp (get_first_help_sentence('get_first_help_sentence'), "Return the first sentence of a function's help text.")); + +%% Test input validation +%!error get_first_help_sentence () +%!error get_first_help_sentence (1, 2, 3) +%!error get_first_help_sentence (1) +%!error get_first_help_sentence ('ls', 'a') +%!error get_first_help_sentence ('ls', 0) +%!error get_first_help_sentence ('ls', 80.1) + diff -r 9f926b9f83cc -r 91ccd08fe80c src/ChangeLog --- a/src/ChangeLog Fri Mar 18 09:37:28 2011 -0700 +++ b/src/ChangeLog Fri Mar 18 14:38:46 2011 -0700 @@ -1,3 +1,7 @@ +2010-03-18 Rik + + * help.cc (get_help_text, get_help_text_from_file): Improve docstrings. + 2011-03-17 John W. Eaton * ov-float.cc (octave_float_scalar::do_index_op): Widen to float diff -r 9f926b9f83cc -r 91ccd08fe80c src/help.cc --- a/src/help.cc Fri Mar 18 09:37:28 2011 -0700 +++ b/src/help.cc Fri Mar 18 14:38:46 2011 -0700 @@ -719,16 +719,11 @@ DEFUN (get_help_text, args, , "-*- texinfo -*-\n\ @deftypefn {Loadable Function} {[@var{text}, @var{format}] =} get_help_text (@var{name})\n\ -Return the help text of a given function.\n\ +Return the raw help text of function @var{name}.\n\ \n\ -This function returns the raw help text @var{text} and an indication of\n\ -its format for the function @var{name}. The format indication @var{format}\n\ -is a string that can be either @t{\"texinfo\"}, @t{\"html\"}, or\n\ +The raw help text is returned in @var{text} and the format in @var{format}\n\ +The format is a string which is one of @t{\"texinfo\"}, @t{\"html\"}, or\n\ @t{\"plain text\"}.\n\ -\n\ -To convert the help text to other formats, use the @code{makeinfo} function.\n\ -\n\ -@seealso{makeinfo}\n\ @end deftypefn") { octave_value_list retval; @@ -793,16 +788,11 @@ DEFUN (get_help_text_from_file, args, , "-*- texinfo -*-\n\ @deftypefn {Loadable Function} {[@var{text}, @var{format}] =} get_help_text_from_file (@var{fname})\n\ -Return the help text from the given file.\n\ +Return the raw help text from the file @var{fname}.\n\ \n\ -This function returns the raw help text @var{text} and an indication of\n\ -its format for the function @var{name}. The format indication @var{format}\n\ -is a string that can be either @t{\"texinfo\"}, @t{\"html\"}, or\n\ +The raw help text is returned in @var{text} and the format in @var{format}\n\ +The format is a string which is one of @t{\"texinfo\"}, @t{\"html\"}, or\n\ @t{\"plain text\"}.\n\ -\n\ -To convert the help text to other formats, use the @code{makeinfo} function.\n\ -\n\ -@seealso{makeinfo}\n\ @end deftypefn") { octave_value_list retval;