Re: PEPs should be included with the documentation download
On 2013-08-23, Chris Angelico 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 -- http://mail.python.org/mailman/listinfo/python-list
Re: PEPs should be included with the documentation download
Ned Deily writes: > In article <7wvc2xkjvz@benfinney.id.au>, > Ben Finney wrote: > > Chris Angelico 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 -- http://mail.python.org/mailman/listinfo/python-list
Re: PEPs should be included with the documentation download
In article <7wvc2xkjvz@benfinney.id.au>, Ben Finney wrote: > Chris Angelico 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, n...@acm.org -- http://mail.python.org/mailman/listinfo/python-list
Re: PEPs should be included with the documentation download
Chris Angelico 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 -- http://mail.python.org/mailman/listinfo/python-list
Re: PEPs should be included with the documentation download
On Fri, Aug 23, 2013 at 11:47 AM, Ben Finney wrote: > Chris Angelico 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 -- http://mail.python.org/mailman/listinfo/python-list
Re: PEPs should be included with the documentation download
Chris Angelico 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 -- http://mail.python.org/mailman/listinfo/python-list
Re: PEPs should be included with the documentation download
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 -- http://mail.python.org/mailman/listinfo/python-list
Re: PEPs should be included with the documentation download
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. -- http://mail.python.org/mailman/listinfo/python-list
Re: PEPs should be included with the documentation download
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. -- http://mail.python.org/mailman/listinfo/python-list
Re: PEPs should be included with the documentation download
On 22Aug2013 03:32, Chris Angelico wrote: | Also, how many people actually depend on the downloadable | documentation, rather than simply reading things online? I do. It is outstandingly faster, and works when one is offline; I always have a local copy of a 2.x and 3.x documentation set as desktop icons, ready for instant opening. I agree I rarely need the PEPs unless I want to look up something unusual. Cheers, -- Cameron Simpson I need your clothes, your boots, and your motorcycle. - Arnold Schwarzenegger, Terminator 2 -- http://mail.python.org/mailman/listinfo/python-list
Re: PEPs should be included with the documentation download
On 8/21/2013 1:32 PM, Chris Angelico wrote: On Wed, Aug 21, 2013 at 3:14 PM, Aseem Bansal 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 -- http://mail.python.org/mailman/listinfo/python-list
Re: PEPs should be included with the documentation download
On Thu, Aug 22, 2013 at 4:15 AM, Jerry Hill wrote: > On Wed, Aug 21, 2013 at 1:55 PM, 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 -- http://mail.python.org/mailman/listinfo/python-list
Re: PEPs should be included with the documentation download
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. -- http://mail.python.org/mailman/listinfo/python-list
Re: PEPs should be included with the documentation download
On Wed, Aug 21, 2013 at 1:55 PM, 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 -- http://mail.python.org/mailman/listinfo/python-list
Re: PEPs should be included with the documentation download
On Wed, Aug 21, 2013, at 13:32, Chris Angelico wrote: > On Wed, Aug 21, 2013 at 3:14 PM, Aseem Bansal > 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. -- http://mail.python.org/mailman/listinfo/python-list
Re: PEPs should be included with the documentation download
On Wed, Aug 21, 2013 at 3:14 PM, Aseem Bansal 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 -- http://mail.python.org/mailman/listinfo/python-list
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. -- http://mail.python.org/mailman/listinfo/python-list
