Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #52749 > unrolled thread

PEPs should be included with the documentation download

Back to article view | Back to comp.lang.python

Contents

  PEPs should be included with the documentation download Aseem Bansal <asmbansal2@gmail.com> - 2013-08-20 22:14 -0700
    Re: PEPs should be included with the documentation download Chris Angelico <rosuav@gmail.com> - 2013-08-22 03:32 +1000
      Re: PEPs should be included with the documentation download Aseem Bansal <asmbansal2@gmail.com> - 2013-08-22 01:39 -0700
        Re: PEPs should be included with the documentation download Terry Reedy <tjreedy@udel.edu> - 2013-08-22 18:46 -0400
    Re: PEPs should be included with the documentation download random832@fastmail.us - 2013-08-21 13:55 -0400
      Re: PEPs should be included with the documentation download Aseem Bansal <asmbansal2@gmail.com> - 2013-08-22 01:45 -0700
    Re: PEPs should be included with the documentation download Jerry Hill <malaclypse2@gmail.com> - 2013-08-21 14:15 -0400
    Re: PEPs should be included with the documentation download random832@fastmail.us - 2013-08-21 14:28 -0400
    Re: PEPs should be included with the documentation download Chris Angelico <rosuav@gmail.com> - 2013-08-22 04:50 +1000
    Re: PEPs should be included with the documentation download Terry Reedy <tjreedy@udel.edu> - 2013-08-21 16:15 -0400
    Re: PEPs should be included with the documentation download Dennis Lee Bieber <wlfraed@ix.netcom.com> - 2013-08-21 20:27 -0400
    Re: PEPs should be included with the documentation download Ben Finney <ben+python@benfinney.id.au> - 2013-08-23 11:47 +1000
    Re: PEPs should be included with the documentation download Chris Angelico <rosuav@gmail.com> - 2013-08-23 11:54 +1000
      Re: PEPs should be included with the documentation download Neil Cerutti <neilc@norwich.edu> - 2013-08-23 13:19 +0000
    Re: PEPs should be included with the documentation download Ben Finney <ben+python@benfinney.id.au> - 2013-08-23 16:21 +1000
    Re: PEPs should be included with the documentation download Ned Deily <nad@acm.org> - 2013-08-23 01:14 -0700
    Re: PEPs should be included with the documentation download Ben Finney <ben+python@benfinney.id.au> - 2013-08-23 19:24 +1000

#52749 — PEPs should be included with the documentation download

Currently the documentation download includes a lot of things but PEPs are not its part. I wanted to suggest that PEPs should be included in the download. They are very much relevant to Python.

[toc] | [next] | [standalone]

#52775

On Wed, Aug 21, 2013 at 3:14 PM, Aseem Bansal <asmbansal2@gmail.com> wrote:
> Currently the documentation download includes a lot of things but PEPs are not its part. I wanted to suggest that PEPs should be included in the download. They are very much relevant to Python.

The PEPs are kinda like the specs that Python is built from, rather
than being end-user documentation; certainly most, if not all, are
unnecessary to most use of Python. There's really no point downloading
a whole pile of rejected PEPs as part of the crucial user-facing docs.

Also, how many people actually depend on the downloadable
documentation, rather than simply reading things online?

ChrisA

[toc] | [prev] | [next] | [standalone]

#52820

I do depend on offline documentation. I have both Python2 and 3's documentation offline. A lot of people have 24-hour access to internet but a lot of people don't have. And while moving around it isn't always possible to have internet then offline documentation is really helpful.

[toc] | [prev] | [next] | [standalone]

#52852

On 8/22/2013 4:39 AM, Aseem Bansal wrote:
> I do depend on offline documentation. I have both Python2 and 3's documentation offline. A lot of people have 24-hour access to internet but a lot of people don't have. And while moving around it isn't always possible to have internet then offline documentation is really helpful.

If you have mercurial installed, you can easily download a read-only 
clone of the peps repository (hg.python.org/peps, I believe). You can 
even pull updates whenever you feel like it.

One can also clone the main repository and build the regular docs, 
including the html version thereof. Again, pull and rebuild when you 
expect to be offline.

-- 
Terry Jan Reedy

[toc] | [prev] | [next] | [standalone]

#52778

On Wed, Aug 21, 2013, at 13:32, Chris Angelico wrote:
> On Wed, Aug 21, 2013 at 3:14 PM, Aseem Bansal <asmbansal2@gmail.com>
> wrote:
> > Currently the documentation download includes a lot of things but PEPs are not its part. I wanted to suggest that PEPs should be included in the download. They are very much relevant to Python.
> 
> The PEPs are kinda like the specs that Python is built from, rather
> than being end-user documentation; certainly most, if not all, are
> unnecessary to most use of Python. There's really no point downloading
> a whole pile of rejected PEPs as part of the crucial user-facing docs.
> 
> Also, how many people actually depend on the downloadable
> documentation, rather than simply reading things online?

If you've taken your laptop to somewhere there's no wi-fi, it's nice to
have offline help.

I think, though, that if there's any useful information that can be
obtained by reading accepted PEPs but not the documentation, or if
things are explained less clearly than in the PEPs, that's a bug in the
documentation, and should be remedied by adding to the documentation.

[toc] | [prev] | [next] | [standalone]

#52821

On Wednesday, August 21, 2013 11:25:44 PM UTC+5:30, rand...@fastmail.us wrote:
> I think, though, that if there's any useful information that can be
> obtained by reading accepted PEPs but not the documentation, or if
> things are explained less clearly than in the PEPs, that's a bug in the
> documentation, and should be remedied by adding to the documentation.

PEP8 is referenced a lot but only a very small portion is included in the documentation (in the tutorial). I am a Python newbie and there may be other PEPs usually referenced which I might not be aware about. 

Maybe add selected PEPs to the documentation? I agree that adding rejected PEPs is no good but there may be PEPs worthy of addition to the documentation.

[toc] | [prev] | [next] | [standalone]

#52780

On Wed, Aug 21, 2013 at 1:55 PM,  <random832@fastmail.us> wrote:
> I think, though, that if there's any useful information that can be
> obtained by reading accepted PEPs but not the documentation, or if
> things are explained less clearly than in the PEPs, that's a bug in the
> documentation, and should be remedied by adding to the documentation.

Personally, the only PEPs I've used as reference material as PEP 8
(the Python Style Guide), and PEP 249 (the Python Database API
Specification v2.0).  If I recall correctly, one of the database
adapters I used basically said that they were PEP 249 compliant, and
didn't have much documentation beyond that.

It seems to me that adding the PEPs to the compiled documentation
would be a good thing.  They are at least as useful as the Language
Reference or the Embedding and Extending Python sections that are
already included.

-- 
Jerry

[toc] | [prev] | [next] | [standalone]

#52782

On Wed, Aug 21, 2013, at 14:15, Jerry Hill wrote:
> Personally, the only PEPs I've used as reference material as PEP 8
> (the Python Style Guide), and PEP 249 (the Python Database API
> Specification v2.0).  If I recall correctly, one of the database
> adapters I used basically said that they were PEP 249 compliant, and
> didn't have much documentation beyond that.

Maybe there should be documentation for PEP 249 and other such "API
Specifications" in the main documentation tree, in the same way that
.NET documents interfaces.

[toc] | [prev] | [next] | [standalone]

#52783

On Thu, Aug 22, 2013 at 4:15 AM, Jerry Hill <malaclypse2@gmail.com> wrote:
> On Wed, Aug 21, 2013 at 1:55 PM,  <random832@fastmail.us> wrote:
>> I think, though, that if there's any useful information that can be
>> obtained by reading accepted PEPs but not the documentation, or if
>> things are explained less clearly than in the PEPs, that's a bug in the
>> documentation, and should be remedied by adding to the documentation.
>
> Personally, the only PEPs I've used as reference material as PEP 8
> (the Python Style Guide), and PEP 249 (the Python Database API
> Specification v2.0).  If I recall correctly, one of the database
> adapters I used basically said that they were PEP 249 compliant, and
> didn't have much documentation beyond that.
>
> It seems to me that adding the PEPs to the compiled documentation
> would be a good thing.  They are at least as useful as the Language
> Reference or the Embedding and Extending Python sections that are
> already included.

Ah, yes, there are a few that would be good. But I don't really see
that all the internally bits (PEP 393, anyone?) and rejected proposals
(PEP 315) need to be in the download. I wouldn't expect the full set
of RFCs to be included with the docs for the socket module, so I
equally don't expect the PEPs to be included.

ChrisA

[toc] | [prev] | [next] | [standalone]

#52790

On 8/21/2013 1:32 PM, Chris Angelico wrote:
> On Wed, Aug 21, 2013 at 3:14 PM, Aseem Bansal <asmbansal2@gmail.com> wrote:
>> Currently the documentation download includes a lot of things but PEPs are not its part. I wanted to suggest that PEPs should be included in the download. They are very much relevant to Python.
>
> The PEPs are kinda like the specs that Python is built from, rather
> than being end-user documentation; certainly most, if not all, are
> unnecessary to most use of Python. There's really no point downloading
> a whole pile of rejected PEPs as part of the crucial user-facing docs.

The manuals are intended to document current reality. Accepted PEPs 
document plans, often minus details. They do not get updated to reflect 
the initial implementation, let alone subsequent changes. Thus even

There are a few chapters in the manual that reference a PEP, either 
because the details are though to be too esoteric for the manual or 
becuase no one has yet gotten around to rewriting the material for the 
manual. (In the latter case, a patch should be welcome.) So there might 
be a reason to include a '(Highly) Selected PEPs' heading to the main 
page. PEP 8 might be a candidate, though it was originally intended as 
an internal style guide for the stdlib only.

-- 
Terry Jan Reedy

[toc] | [prev] | [next] | [standalone]

#52801

On Wed, 21 Aug 2013 13:55:44 -0400, random832@fastmail.us declaimed the
following:

>I think, though, that if there's any useful information that can be
>obtained by reading accepted PEPs but not the documentation, or if
>things are explained less clearly than in the PEPs, that's a bug in the
>documentation, and should be remedied by adding to the documentation.

	The only PEP I routinely reference is the one covering the DB-API (2).
Since many of the DB adapters are supposed to follow it, and may actually
slough off documentation to that PEP.

-- 
	Wulfraed                 Dennis Lee Bieber         AF6VN
    wlfraed@ix.netcom.com    HTTP://wlfraed.home.netcom.com/

[toc] | [prev] | [next] | [standalone]

#52856

Chris Angelico <rosuav@gmail.com> writes:

> Also, how many people actually depend on the downloadable
> documentation, rather than simply reading things online?

Many countries do not have infrastructure that allows reliable, fast,
low-latency internet access 24-hours-a-day. Most countries's internet
infrastructure, in fact, does not satisfy all of those.

And without all of those being satisfied simultaneously, accessing
programmer documentation online is frustratingly inconsistent. It is
much more convenient and reliable, in those cases, to have the
documentation downloaded and accessible on one's development
workstation.

-- 
 \       “We must find our way to a time when faith, without evidence, |
  `\    disgraces anyone who would claim it.” —Sam Harris, _The End of |
_o__)                                                     Faith_, 2004 |
Ben Finney

[toc] | [prev] | [next] | [standalone]

#52857

On Fri, Aug 23, 2013 at 11:47 AM, Ben Finney <ben+python@benfinney.id.au> wrote:
> Chris Angelico <rosuav@gmail.com> writes:
>
>> Also, how many people actually depend on the downloadable
>> documentation, rather than simply reading things online?
>
> Many countries do not have infrastructure that allows reliable, fast,
> low-latency internet access 24-hours-a-day. Most countries's internet
> infrastructure, in fact, does not satisfy all of those.

I'm aware of that. However, I'm also aware that many people still read
things online, even with a less-than-reliable internet connection.
Hence the question: How many people actually do use the downloaded
docs? Maybe it'd turn out to be quite high, but it's not an
unreasonable question.

ChrisA

[toc] | [prev] | [next] | [standalone]

#52888

On 2013-08-23, Chris Angelico <rosuav@gmail.com> wrote:
> I'm aware of that. However, I'm also aware that many people
> still read things online, even with a less-than-reliable
> internet connection. Hence the question: How many people
> actually do use the downloaded docs? Maybe it'd turn out to be
> quite high, but it's not an unreasonable question.

I use the compiled html/windows help and the integrated with the
interpreter html version of the Python docs, both downloaded and
installed for easy access.

-- 
Neil Cerutti

[toc] | [prev] | [next] | [standalone]

#52865

Chris Angelico <rosuav@gmail.com> writes:

> Hence the question: How many people actually do use the downloaded
> docs? Maybe it'd turn out to be quite high, but it's not an
> unreasonable question.

I think it's an unreasonable question. What would you accept as an
answer? Who could possibly be autoritative at estimating such a number?
How would you choose between competing authorities and estimates?

It should be sufficient to realise that the reality of internet
infrastructure in most countries makes it preferable – at least some of
the time, for some significant, even if small, number of users – to read
the documentation on local storage instead of on the internet.

-- 
 \        “I took a course in speed waiting. Now I can wait an hour in |
  `\                                 only ten minutes.” —Steven Wright |
_o__)                                                                  |
Ben Finney

[toc] | [prev] | [next] | [standalone]

#52870

In article <7wvc2xkjvz.fsf@benfinney.id.au>,
 Ben Finney <ben+python@benfinney.id.au> wrote:
> Chris Angelico <rosuav@gmail.com> writes:
> > Hence the question: How many people actually do use the downloaded
> > docs? Maybe it'd turn out to be quite high, but it's not an
> > unreasonable question.
> 
> I think it's an unreasonable question. What would you accept as an
> answer? Who could possibly be autoritative at estimating such a number?
> How would you choose between competing authorities and estimates?
> 
> It should be sufficient to realise that the reality of internet
> infrastructure in most countries makes it preferable – at least some of
> the time, for some significant, even if small, number of users – to read
> the documentation on local storage instead of on the internet.

In any case if you want to see this happen, someone needs to open an 
issue and make a case for it on the Python bug tracker.

-- 
 Ned Deily,
 nad@acm.org

[toc] | [prev] | [next] | [standalone]

#52873

Ned Deily <nad@acm.org> writes:

> In article <7wvc2xkjvz.fsf@benfinney.id.au>,
>  Ben Finney <ben+python@benfinney.id.au> wrote:
> > Chris Angelico <rosuav@gmail.com> writes:
> > > Hence the question: How many people actually do use the downloaded
> > > docs? Maybe it'd turn out to be quite high, but it's not an
> > > unreasonable question.
> > 
> > I think it's an unreasonable question [in this context].

> In any case if you want to see this happen, someone needs to open an 
> issue and make a case for it on the Python bug tracker.

Neither Chris nor I are proposing to have PEPs in the installed
documentation :-) You might want to respond directly to the original
post with that suggestion.

-- 
 \     “Men never do evil so completely and cheerfully as when they do |
  `\        it from religious conviction.” —Blaise Pascal (1623–1662), |
_o__)                                                   Pensées, #894. |
Ben Finney

[toc] | [prev] | [standalone]

Back to top | Article view | comp.lang.python

csiph-web