Re: Help strings in the text body of the manual

[LachlanA]

Doug Stewart-4 wrote
> On Sun, Apr 24, 2016 at 5:19 PM, Pantxo Diribarne <

> pantxo.diribarne@

>> wrote:
>>> An example in the plotting section:
>>
>> https://gnu.org/software/octave/doc/interpreter/Two_002dDimensional-Plots.html#Two_002dDimensional-Plots
>>
>> A bit of text, then a block of 5 help strings, then a bit of text and
>> then an endless list of help strings.
>>
>>
> I don't see what you are talking about. Can you explain it more fully?

I can't say what Pantxo objected to, but I see this section of the manual as
an alphabetic list of functions, with no linking of them.  A manual may be
expected, for example, to explain the relationship between "rose" (an
angular histogram) and "hist", and discuss the two together rather than
separated by all of the functions i-q.

It would be useful to have short section allowing the reader to decide
*which* function to call, with only a hyperlink to show *how* to call each
option.

Having said that, I have almost never looked at the manual.  Finding what I
want in a 1000 page document is too hard.  Perhaps Pantxo's suggestion could
reduce the manual to a 200 page document, with 800 pages of appendix -- or
perhaps each chapter could have a short "synthesis" section with this sort
of discussion, followed by (and hyperlinked to) its own function list.

$0.02,
Lachlan



--
View this message in context: 
http://octave.1599824.n4.nabble.com/Help-strings-in-the-text-body-of-the-manual-tp4676467p4676476.html
Sent from the Octave - Maintainers mailing list archive at Nabble.com.