Re: Help strings in the text body of the manual

[Michael Godfrey]

On 04/25/2016 08:55 AM, John W. Eaton wrote:

On 04/24/2016 03:41 PM, Pantxo Diribarne wrote:

I find some sections of the manual hardly readable due to the verbatim
inclusion of lists of function help strings.
At the very least having separators and/or a visual hint of what is the
text body and what is a help string would help.

Before the manual was 1000 pages long and documenting about 1500 functions, the goal was to have each section in the manual provide some explanation of a topic mixed with the docstrings of the functions relevant to that topic.  That is the same format used by the GNU C library manual, the Emacs manual, the Emacs Lisp manual, and others.

But I think writing the supporting text to tie everything together is much more difficult than writing the individual docstrings and inserting them in the manual sources.

I'm also not sure it scales very well.

For readability though I would even vote for having all those help
strings stored in an appendix, with a page break between each,  and only
hyperlinks (and usage examples) in the body of the manual.
This would even allow having demo figures appended to the help strings,
as is done by generate_html (see e.g
http://octave.sourceforge.net/octave/function/contour.html).

At this point, I can't imagine anyone actually printing the documentation. I agree that links or some other way of organizing the information would probably work better.

jwe

John,

Some of us from long ago still think of the manual as the octave.pdf. But, it seems to me that it would be
better if people were referred to the HTML version. And,  it would be good to consider this as the
primary reference. Of course, the HTML version could stand some work, actually a LOT of work , and,
for instance, the examples  could be made "executable."  MathJax could be used to make the math
presentable, particularly since the Manual should be made to work not only in a computer browser,
but also on tablets and phones. I tried the HTML version by just:  octave/doc/interpreter/octave.html/index.html
and this works quite well.

The best example that I know of showing how to make this come out better is:
http://www.feynmanlectures.caltech.edu/

As you will see this provides a lot of helpful choices, links, etc. Take a look at, for example, Vol. I. On
the right you have choices of navigation, font size, and phone/tablet or computer browser modes...

Does this make sense for Octave?

Michael