Le 27/04/2016 12:18, Carnë
Draug a écrit :
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ë
Yes, rewriting the @DOCSTRING macro in munge-texi.pl is
definitely the best solution. Unfortunately I got lost as soon
as I dared looking for the first time at a a Perl script. I'll
remember the references, if ever I want to learn a minimal bit
of perl :-).