Re: Help strings in the text body of the manual

[Carnë Draug]

On 26 April 2016 at 16:38, John W. Eaton <address@hidden> wrote:
> On 04/26/2016 09:27 AM, Pantxo Diribarne wrote:
>>
>> 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.
>
>
> That's certainly the easy way out.  As I said earlier, and in spite of what
> actually happened, the original goal was to avoid having long lists of
> docstrings.  So if that's what is there now, the real problem is that we are
> missing the supporting text that describes the features and provides
> motivation for the set of functions that are grouped together in a
> particular section of the manual.
>
> jwe

Yes, that is the problem.  Most of the changes to the manual are for
inserting the help text when a new function is added to Octave.  Not
even at that point is the manual text modified.  But writing the manual
text is a lot of work which I think most of us don't want to.

It would help if we figured out what is the purpose of the manual.  It
has been said before that it's supposed to be educational, kind of an
introduction to the language.  I don't think it does a good job at it.
It seems much better as a reference to the Octave language.  We should
focus on the manual being just that then.

It's no secret I'm a fan of perl, and I also like their O'Reilly books.
There is "Learning Perl" (which is really good and targeted to someone
who is learning to program) and Programming Perl (which is more about the
gory details of the language).  Our Octave manual should be the latter.
We don't have to write a "Learning Octave" book.

Instead of a function reference at the end of each subsection, just
have a function reference for all functions at the end of the manual.
The rest of the manual can link to that page easily.  The easiest way
to start this is to modify the DOCSTRING macro so that it becomes a
link to that function reference chapter.

Carnë