[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Help strings in the text body of the manual
From: |
Mike Miller |
Subject: |
Re: Help strings in the text body of the manual |
Date: |
Tue, 26 Apr 2016 10:03:09 -0400 |
User-agent: |
Mutt/1.5.24 (2015-08-30) |
On Tue, Apr 26, 2016 at 09:38:54 -0400, John W. Eaton 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.
I hardly look at any of the plotting sections as a readable block, but I
see what Pantxo means about that particular subsection. I agree it could
use some more supporting narrative to tie the various function
references together. Maybe some of the basic line-oriented functions
could be kept there, and others moved into more subsubsections.
The Two-Dimensional Plotting section has 39 docstrings, the 4th highest
in a single block after Distributions, Signal Processing (with a FIXME:
organize this), and Trigonometry. And the plot docstrings to tend to be
much wordier that a function like "cos".
--
mike