Re: Help strings in the text body of the manual

[Pantxo Diribarne]

How about adding a "Function Reference" subsection at the end of each major section as proposed by Lachlan? In order to have a taste of the result, I can provide a minimal patch for the plotting section.

@Rik: coming from the function index you would land in the right section but not the right subsection. Would this be ok?

I don't know if this will work for all sections, there may be very few doc strings for some and a huge amount for others.

Pantxo

2016-04-25 14:55 GMT+02:00 John W. Eaton <address@hidden>:

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