Re: Help strings in the text body of the manual

[John W. Eaton]

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