Request for comments: help texts (was: Re: Inconsistent treatment of scripts by the help system?)

[John W. Eaton]

On 25-Feb-2010, David Grundberg wrote:

| Olaf Till wrote:
| > If the command "help ..." is called on a script (not a function), I
| > would expect that one either always gets "... is not documented" or,
| > if present, the first comment in the script is displayed. The current
| > behavior is not so, seemingly function definitions within the script
| > have an unwanted effect. 
| 
| I'm moving this to the maintainer list.
| 
| I can do the needed changes but I think we need to agree on the
| semantics.
| 
| For example a file with the sole contents (indented to be easier
| to read):
| 
|   ## Optional copyright block
| 
|   ## help for script
| 
|   ## other comment
| 
| is a clear. The help filename should give "help for script".
| Notice that copyright blocks should be skipped.  Yes, it's
| tricky.
| 
| 
| This however:
| 
|   ## Optional copyright block
|   1;
|   ## help for script
|   function f ()
|   endfunction
| 
| Here I think 'help filename' should be undocumented, because
| there is a statement before it.
| 
| Function declarations inside script files: Theoretically we could
| make 'help f' return "help for f", but I don't think it is worth
| supporting.  Therefore:
| 
| help filename: undocumented
| help f: undocumented
| 
| 
| Script file with function declarations:
| 
|   ## Optional copyright block
| 
|   ## help for script
| 
|   ## other comment
|   1;
|   ## help for f
|   function f ()
|   endfunction
| 
| In short:
| 
| help filename: "help for script"
| help f: undocumented
| 
| Summary: To document a script file, write your help text
| block (optionally with a copyright block before it) before the
| first statement.  All following comment blocks are ignored.
| Really simple rule.  Help text for function declarations inside
| scripts are ignored.
| 
| 
| And function files:
| 
|   ## Copyright block
| 
|   ## help for primary function
| 
|   ## ignored comment
|   function myfunction ()
|   endfunction
|   ## help for subfunction
|   function sub ()
|   endfunction
| 
| help filename: "help for primary function"
| help sub: No such function
| 
| There is no way to access sub, so it can't be described by help.
| 
| 
| There is one other kind of help text inside function files:
| 
|   function myfunction ()
|   % Help text inside function.
| 
|   % other comment.
|   end
| 
| This kind of 'stuck-inside' help text is very common in
| non-Octave contexts.  I think it's ugly and sends the wrong kind
| of signals.  But it's common and people do need the help text,
| therefore:
| 
| help filename: "Help text inside function".
| 
| 
| What do you think of this?  Is it OK?  Does it break existing
| files?  How would this affect !demo and !test blocks?

I think it would be simpler if the help function just displayed the
first non-copyright block of comments no matter where it appears in
the file.  I don't really care that it might produce strange results
if someone doesn't have an actual docstring as the first comment in
the file, and I don't think it is worth doing a lot of work to try to
distinguish all these various cases.

jwe