Re: Writing 'help' functions as m-files

[Søren Hauberg]

tor, 27 03 2008 kl. 11:00 -0400, skrev John W. Eaton:
> I have no objection to writing the help functions as .m files.
Okay, I'm attaching some code that illustrates how this could be done.
Not everything is working, but it should be functional enough to decide
if this approach should be used.
  I like this approach for two reasons:

1) It gives me access to the function 'get_help_text' which I have
needed in the past.
2) C++ code is moved to Octave code. This should make it easier for more
people to hack on the help system. As an example, today matlab allows
html formated help texts. If these ever catch on, I think it would be
simpler to support this (the attached code provides a *very* simple
implementation).

On the downside: the current code works well. And if it ain't broken,
don't fix it. Also, an Octave implementation will be slower, but I don't
think that matters.

Søren

get_help_text.cc
Description: Text Data

makeinfo.m
Description: Text Data

## 
## 
## This is an example of html help
## 
## 
function myhelp (arg1, arg2)
  if (nargin == 0)
    disp ("display that long list of functions/operators that come with Octave");
    
  elseif (nargin == 1 && ischar (arg1))
    ## Is 'arg1' an operator?
    [text, is_operator, format] = operator_help_text (arg1);
    
    ## Get help text if it wasn't an operator
    if (! is_operator)
      [text, format] = get_help_text (arg1);
    endif
    
    ## Take action depending on help text format
    switch (lower (format))
      case "plain text"
        status = 0;
      case "texinfo"
        [text, status] = makeinfo (text, "plaintext");
      case "html"
        [text, status] = strip_html_tags (text);
      case "not found"
        error ("help: `%s' not found", arg1);
      otherwise
        error("help: internal error: unsupported help text format: '%s'", format);
    endswitch
    
    ## Print text
    if (status == 0)
      disp(text);
    endif
    
  elseif (nargin == 2 && ischar (arg1) && ischar (arg2) && strcmp (arg1, "-i"))
    warning("help: use 'doc' instead of 'help -i'");
    doc(arg2);
    
  else
    error("help: invalid input");
  endif
endfunction

function [text, is_operator, format] = operator_help_text (arg)
  ## Define operators and their help text
  ## XXX: We could easily use texinfo here. Should we?
  operators = {
    "!",   "Logical not operator.\n  See also `~'.";
    "!=",  "Logical not equals operator.  See also `~' and `<>'.";
    "\"",  "String delimiter.";
    "#",   "Begin comment character.  See also `%'.";
    "%",   "Begin comment charcter.  See also `#'.";
    "&",   "Logical and operator.  See also `&&'.";
    "&&",  "Logical and operator.  See also `&'.";
    "'",   ["Matrix transpose operator.  For complex matrices, computes the\n"
            "complex conjugate (Hermitian) transpose.  See also `.''\n"
            "\n"
            "The single quote character may also be used to delimit strings, but\n"
            "it is better to use the double quote character, since that is never\n"
            "ambiguous"]; 
    "(",   "Array index or function argument delimiter.";
    ")",   "Array index or function argument delimiter.";
    "*",   "Multiplication operator.  See also `.*'",
    "**",  "Power operator.  See also `^', `.**', and `.^'",
    "+",   "Addition operator.";
    "++",  ["Increment operator.  As in C, may be applied as a prefix or postfix\n"
            "operator."];
    ",",   "Array index, function argument, or command separator.";
    "-",   "Subtraction or unary negation operator.";
    "--",  ["Decrement operator.  As in C, may be applied as a prefix or postfix\n"
            "operator."];
    ".'",  ["Matrix transpose operator.  For complex matrices, computes the\n"
            "transpose, *not* the complex conjugate transpose.  See also `''."];
    ".*",  "Element by element multiplication operator.  See also `*'.";
    ".**", "Element by element power operator.  See also `**', `^', and `.^'.";
    "./",  "Element by element division operator.  See also `/' and `\\'.";
    ".^",  "Element by element power operator.  See also `**', `^', and `.^'.";
    "/",   "Right division.  See also `\\' and `./'.";
    ":",   "Select entire rows or columns of matrices.";
    ";",   "Array row or command separator.  See also `,'.";
    "<",   "Less than operator.";
    "<=",  "Less than or equals operator.";
    "=",   "Assignment operator.";
    "==",  "Equality test operator.";
    ">",   "Greater than operator.";
    ">=",  "Greater than or equals operator.";
    "[",   "Return list delimiter.  See also `]'.";
    "\\",  "Left division operator.  See also `/' and `./'.";
    "]",   "Return list delimiter.  See also `['.";
    "^",   "Power operator.  See also `**', `.^', and `.**.'",
    "|",   "Logical or operator.  See also `||'.";
    "||",  "Logical or operator.  See also `|'.";
    "~",   "Logical not operator.  See also `!' and `~'.";
    "~=",  "Logical not equals operator.  See also `<>' and `!='."
  };

  ## Search for operators
  format = "plain text";
  idx = find (strcmp (arg, operators(:,1)));
  if (isempty(idx))
    text = "";
    is_operator = false;
  else
    text = operators{idx, 2};
    is_operator = true;
  endif
endfunction

function [text, status] = strip_html_tags (html_text)
  start = find (html_text == "<");
  stop  = find (html_text == ">");
  if (length (start) == length (stop))
    text = html_text;
    for n = length(start):-1:1
      text (start (n):stop (n)) = [];
    endfor
    status = 0;
  else
    warning("help: invalid HTML data");
    warning("Raw HTML source follows...");
    disp(html_text);
    text = "";
    status = 1;
  endif
endfunction