octave-maintainers
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Help message "tags" about additional help somewhat redundant and irrelev


From: Daniel J Sebald
Subject: Help message "tags" about additional help somewhat redundant and irrelevant
Date: Wed, 11 Jan 2017 17:17:03 -0600
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.5.1

Just curious people's thoughts on the format of help documentation when running the command line "help" function. It is of this format:

~~~~~~~~~~~~~~~
'SOMEFUNC' is a function from the file <SYSTEM PATH>/octave/4.3.0+/m/plot/util/SOMEFUNC.m

COMMENTS ASSOCIATED WITH THE FUNCTION IN SOMEFUNC.m OR BUILTIN CODE

Additional help for built-in functions and operators is
available in the online version of the manual.  Use the command
'doc <topic>' to search the manual index.

Help and information about Octave is also available on the WWW
at http://www.octave.org and via the address@hidden
mailing list.
~~~~~~~~~~~~~~~

For short help printouts, I find that those last paragraphs consume a lot of space and sort of obscure the actual printout. For example (just found a bug... https://savannah.gnu.org/bugs/index.php?50034):

~~~~~~~~~~~~~~~
octave:36> help --

 -- --
     Decrement operator.  As in C, may be applied as a prefix or postfix
     operator.

     See also: ++.

Additional help for built-in functions and operators is
available in the online version of the manual.  Use the command
'doc <topic>' to search the manual index.

Help and information about Octave is also available on the WWW
at http://www.octave.org and via the address@hidden
mailing list.
~~~~~~~~~~~~~~~

Anyway, it just seems to me that after short use of Octave, that "Additional help..." text becomes really redundant. I wouldn't call it annoying, but it detracts from the cleanliness of the display, i.e., clutter.

Aside from the "seen that before, so I'll ignore it" factor, there is a lack of clarity as to exactly what those sentences mean. For example, the first sentence refers to "online version of the manual". That implies Internet (which does exist in nice form), but then the sentence after that indicates "doc ..." which is the same thing as the Internet version, I believe, but resident in the program. And then the next paragraph mentions the web. It seems to me that this info could be summarized less verbosely, say:

Use 'doc <topic>' or visit www.gnu.org/software/octave/doc/interpreter/
for further help, or inquire via the address@hidden mailing list.

and still capture the same info.

Now, as for the "Additional help for built-in functions and operators", that clause suggests relevance to built-ins. However, it is always displayed. So, if I do something like "help MYFUNC" for which the help is in a script file, I'm not really interested in built-ins and there is nowhere to go on the Internet or manual to get further information about my own function.

Dan



reply via email to

[Prev in Thread] Current Thread [Next in Thread]