[Python-Dev] undocumented help() function change in Python 3.4?

[Guido van Rossum]

I'm not sure I agree completely with this lax attitude about the contents
of the docs, and especially the What's New parts of it (both Misc/NEWS and
Doc/whatsnew/3.4.rst). I find it very useful to have these pinpoint
*exactly* what made it into the tarball or zipfile or whatever other form I
happen to find the release -- you don't always have the full hg logs lying
around, nor do you always know from which exact revision or tag a tree was
built.

Of course it's fine to improve the docs in an ongoing fashion, and if it's
just a wording change to NEWS or whatsnew I don't mind missing it. But for
specific entries I'd like to strive for completeness in each branch/tag/rc.

Also, tonds of thanks to RDM for his work on the new whatsnew!


On Tue, Mar 11, 2014 at 6:52 AM, R. David Murray <rdmurray at bitdance.com>wrote:

> On Tue, 11 Mar 2014 10:15:21 +0100, Georg Brandl <g.brandl at gmx.net> wrote:
> > Am 11.03.2014 08:00, schrieb Ned Deily:
> > > In article <lfmbjj$nka$2 at ger.gmane.org>,
> > >  Georg Brandl <g.brandl at gmx.net> wrote:
> > >
> > >> Am 11.03.2014 06:31, schrieb Ned Deily:
> > >> > In article
> > >> > <CADiSq7eif2yBkwR4NQLxi800CRqZWwVzmS11eNMt0PQnA23cLA at mail.gmail.com
> >,
> > >> >  Nick Coghlan <ncoghlan at gmail.com> wrote:
> > >> >> On 11 March 2014 11:29, R. David Murray <rdmurray at bitdance.com>
> wrote:
> > >> >> > The whatsnew updates (including the one for help) weren't copied
> into
> > >> >> > rc3.  They will be in final though, unless Larry forgets.
> > >> >>
> > >> >> Oh, cool - yes, it will be good to have an up to date What's New
> > >> >> shipped, especially as part of the compiled Windows docs.
> > >> >
> > >> > I was going to bring that point up today. How are all the new
> whatsnew
> > >> > updates going to get into the 3.4.0 release?  They've, correctly,
> been
> > >> > being pushed to the default branch.  But, AFAIK, for them to show
> up in
> > >> > the 3.4.0 released docs we ship, all of the doc changes are going to
> > >> > need to be cherry picked (or a big mass diff from the default
> branch)
> > >> > into the 3.4 release branch, otherwise they will not be part of the
> > >> > release.  (They certainly won't be part of the docs included with
> the
> > >> > installers I build unless they are in the 3.4 releasing branch.)
> > >>
> > >> Copying the file from default and doing just one commit in the
> releasing
> > >> branch should be the easiest way.
> > >
> > > That covers the whatsnew file but the changes RDM have been making
> > > affect other parts of the documentation and Misc/NEWS, too.
> >
> > NEWS can also be copied of course.  As long as the others aren't critical
> > updates, just skip it for the final.
> >
> > Most people read the online docs anyway.
>
> I don't think the NEWS changes are that important to copy either.  None
> of the changes I made outside of whatsnew are substantive, they were
> either adding or fixing version tags, fixing formatting, or fixing
> typos or other copy-edit type things.  At least, I can't remember
> anything that was substantive :)
>
> Oh, there was one thing that might be worth cherry picking: the change
> to the email docs.  The new EmailMessage class was documented as being
> in the wrong module.  But even that isn't a big deal, since it's
> a provisional class, and as Georg said most people read the online
> docs anyway, since they get the ongoing updates between releases.
>
> --David
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> https://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe:
> https://mail.python.org/mailman/options/python-dev/guido%40python.org
>



-- 
--Guido van Rossum (python.org/~guido)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20140311/e0427d3a/attachment.html>