Re: [Python-Dev] [Doc-SIG] that library reference, again

[Fredrik Lundh]

> [David Goodger]
> >> Could be. I don't see HTML+PythonDoc as a significant improvement
> >> over LaTeX.
>
> [Fredrik Lundh]
> > Really?
>
> Yes, really.

Your reply makes it obvious that you don't understand the issues involved
here, nor how the goals address them.

(Snipping heavily below due to lack of time; if you want some other argument
refuted, you have to repost and wait until next week.)

> Another goal is highly biased toward XML-style markup:
>
> * Make it trivial to do basic rendering to HTML (a few re.sub
>   calls should suffice), to enable simple tools (CGI scripts, etc)
>   to be able to render reference documentation.
>
> This is the tail wagging the dog.

No, it's a fundamental goal: to support light-weight generation of rendered
markup directly from source code, to enable simple tools (CGI scripts, etc)
to be able to render reference documentation.

The issue this is addressing is that the current workflow is way too heavy;
when I made my first post, it typically took 3-6 months for a contribution to
the documentation to appear on python.org.  Thanks to Trent and Neal, the
situation is a bit better today, but it's far from ideal.  (More on this below).

> The second sentence lacks a rationale.  What's wrong with "-- dashes"?
> What's "silly" about "``quotes''"?

I'd say that the fact that you're asking this should disqualify you from ever
working on documentation tools again...  don't you know *anything* about
typography ?

> The reference to ReST is wrong here; ReST certainly can know the
> semantics of a given identifier.

> I don't think you understand ReST except superficially.

That's why I'm listening to people who've tried to use ReST for this pur-
pose.  They've all failed.  Maybe they also only understood ReST super-
ficially.  Or maybe it's because ReST is created by people who have a
very shallow understanding of the issues involved in writing structured
reference documentation.  Your guess is as good as mine.

> My bias is simple: I am against wasting the time and effort required
> to replace one form of verbose markup with a different but equivalent
> form.  The proposed solution is no better than the status quo.

Support for quick turnaround, edit via the web, richer semantic information,
and a larger existing toolbase isn't better than the status quo ?

Sounds more like a ReSTian sour-grapes (or scorched-earth) approach
than a serious argument from someone who's interested in improving the
Python documentation.

> IMO, the markup itself is almost irrelevant.  As others have stated,
> writing good documentation is hard.  People will latch on to any
> excuse to avoid it, and markup is convenient.  But even if the docs
> had no markup whatsoever, if they were written in plain text like
> RFCs, I doubt there would be significantly more patch contributions.

The problem is that the WORKFLOW doesn't work.  Quoting from an earlier
post (you have read the earlier discussion, right?):

If an ordinary user finds a minor issue, a typo, or an error in the
documentation, the current user workflow is:

1) (optionally) cut and paste the text to an editor, edit, and save to disk
2) go to the sourceforge site, and locate the python project
3) (optionally) sign up for a sourceforge account
4) log in to your sourceforge account
5) open a new bug or patch issue, and attach your suggestion
6) wait 3-6 months for someone to pick up your patch, and for the
   next documentation release to appear on the site

to which can be added:

If a developer finds a minor issue, a typo, or an error in the 
documentation,
the current developer workflow is:

If logged in to a machine with a full Python development environment:

1) sync the project
2) locate the right source file
3) edit, and save to disk
4) (optionally) regenerate the documentation and inspect it (3-6 minutes
if you have the toolchain installed)
5) commit the change (alternatively, generated a patch; see 2-5 above)
6) wait up to 12 hours for the updated text to appear on the developer
   staging area on python.org, and 3-6 months for the next documentation
   release to appear on the site

If no access to a Python development environment:

1) (optionally) cut and paste the text to an editor, edit, and save to disk
2) write note or mail to self (or generated a patch; see user instructions
   above)
3) at an unspecified later time, try to remember what you did, and follow
   the developer instructions above.  wait 3-6 months for the next doc
   release to appear on the site.

I'm not arguing that a change of markup will solve this; I'm saying that a
a light-weight toolchain will make it possible to cut this down to 3-6 seconds
(plus optional moderation overhead for ordinary users).  If people get feedback,
they contribute.

The need for a light-weight markup language follows from this; to eliminate
as much overhead as

Re: [Python-Dev] New PEP: Using ssize_t as the index type

[Travis E. Oliphant]

Martin v. Löwis wrote:
> Please let me know what you think.
> 
> Regards,
> Martin
> 
> PEP: XXX
> Title: Using ssize_t as the index type
> Version: $Revision$
> Last-Modified: $Date$
> Author: Martin v. Löwis <[EMAIL PROTECTED]>
> Status: Draft
> Type: Standards Track
> Content-Type: text/x-rst
> Created: 18-Dec-2005
> Post-History:
> 
> 
> Abstract
> 
> 
> In Python 2.4, indices of sequences are restricted to the C type
> int. On 64-bit machines, sequences therefore cannot use the full
> address space, and are restricted to 2**31 elements. This PEP proposes
> to change this, introducing a platform-specific index type
> Py_ssize_t. An implementation of the proposed change is in
> http://svn.python.org/projects/python/branches/ssize_t.

Sounds wonderful.   Would love to see this in Python 2.5.  This will fix 
important 64-bit issues.  Perhaps someone could explain to me what the 
difference between Py_ssize_t and Py_intptr_t would be? Is this not a 
satisfactory Py_ssize_t already?


> 
> 
> Rationale
> =
> 
> 64-bit machines are becoming more popular, and the size of main memory
> increases beyond 4GiB. On such machines, Python currently is limited,
> in that sequences (strings, unicode objects, tuples, lists,
> array.arrays, ...)  cannot contain more than 2GiElements.
> 
> Today, very few machines have memory to represent larger lists: as
> each pointer is 8B (in a 64-bit machine), one needs 16GiB to just hold
> the pointers of such a list; with data in the list, the memory
> consumption grows even more.  However, there are three container types
> for which users request improvements today:
> 
> * strings (currently restricted to 2GiB)
> * mmap objects (likewise; plus the system typically
>   won't keep the whole object in memory concurrently)
> * Numarray objects (from Numerical Python)

scipy_core objects are the replacement for both Numarray and Numerical 
Python and support 64-bit clean objects *except* for the sequence 
protocol and the buffer protocol.  Fixing this problem will clean up a 
lot of unnecessary code.

Looking forward to it...

-Travis



___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Naming conventions in Py3K

[Reinhold Birkenfeld]

Ka-Ping Yee wrote:
> In a fair number of cases, Python doesn't follow its own recommended
> naming conventions.  Changing these things would break backward
> compatibility, so they are out of the question for Python 2.*, but
> it would be nice to keep these in mind for Python 3K.
> 
> Constants in all caps:
> NONE, TRUE, FALSE, ELLIPSIS

That's ugly. I bet with this change you will find modules out there
which do

True = TRUE

at the start.

In fact, I like it that the basic Python functions and most of the types
are all-lowercase. It find the code to be better readable.

Reinhold

-- 
Mail address is perfectly valid!

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] New PEP: Using ssize_t as the index type

[Martin v. Löwis]

Fredrik Lundh wrote:
> well, one thing seems to missing from your PEP: in several modules, you've
> changed the cast used in the type table. e.g.
...
> is this change backwards compatible ?

See the section "Conversion guidelines". I prefer the approach taken in
the patch below, i.e. remove the casts in initializing the type object.
Adding more typedefs for the function types would be the other option.

Regards,
Martin

Index: Modules/_elementtree.c
===
--- Modules/_elementtree.c  (Revision 41837)
+++ Modules/_elementtree.c  (Arbeitskopie)
@@ -92,6 +92,9 @@
 #endif

 /* compatibility macros */
+#if (PY_VERSION_HEX < 0x0205)
+typedef int Py_ssize_t;
+#endif
 #if (PY_VERSION_HEX < 0x0204)
 #define PyDict_CheckExact PyDict_Check
 #if (PY_VERSION_HEX < 0x0202)
@@ -916,8 +919,9 @@
 }

 static PyObject*
-element_getitem(ElementObject* self, Py_ssize_t index)
+element_getitem(PyObject* _self, Py_ssize_t index)
 {
+ElementObject* self = (ElementObject*)_self;
 if (!self->extra || index < 0 || index >= self->extra->length) {
 PyErr_SetString(
 PyExc_IndexError,
@@ -931,8 +935,9 @@
 }

 static PyObject*
-element_getslice(ElementObject* self, Py_ssize_t start, Py_ssize_t end)
+element_getslice(PyObject* _self, Py_ssize_t start, Py_ssize_t end)
 {
+ElementObject* self = (ElementObject*)_self;
 Py_ssize_t i;
 PyObject* list;

@@ -1158,8 +1163,9 @@
 }

 static int
-element_setslice(ElementObject* self, Py_ssize_t start, Py_ssize_t end,
PyObject* item)
+element_setslice(PyObject* _self, Py_ssize_t start, Py_ssize_t end,
PyObject* item)
 {
+ElementObject* self = (ElementObject*)_self;
 int i, new, old;
 PyObject* recycle = NULL;

@@ -1228,8 +1234,9 @@
 }

 static int
-element_setitem(ElementObject* self, Py_ssize_t index, PyObject* item)
+element_setitem(PyObject* _self, Py_ssize_t index, PyObject* item)
 {
+ElementObject* self = (ElementObject*)_self;
 int i;
 PyObject* old;

@@ -1371,10 +1378,10 @@
 (inquiry) element_length,
 0, /* sq_concat */
 0, /* sq_repeat */
-(ssizeargfunc) element_getitem,
-(ssizessizeargfunc) element_getslice,
-(ssizeobjargproc) element_setitem,
-(ssizessizeobjargproc) element_setslice,
+element_getitem,
+element_getslice,
+element_setitem,
+element_setslice,
 };

 statichere PyTypeObject Element_Type = {
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] New PEP: Using ssize_t as the index type

[Martin v. Löwis]

Travis E. Oliphant wrote:
> Sounds wonderful.   Would love to see this in Python 2.5.  This will fix 
> important 64-bit issues.  Perhaps someone could explain to me what the 
> difference between Py_ssize_t and Py_intptr_t would be? Is this not a 
> satisfactory Py_ssize_t already?

Practically, yes. Conceptually, intptr_t and size_t are different
things: sizeof(void*) might differ from sizeof(size_t) (e.g. when you
have segment and offset in pointers). I believe in flat-address space
machines, they are always the same.

Regards,
Martin
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] New PEP: Using ssize_t as the index type

[Martin v. Löwis]

Armin Rigo wrote:
> I guess you mean LONG_MAX instead of MAX_INT, in the event that ssize_t
> is larger than a long.

Right, changed.

> Also, distinguishing between PyInt_AsSsize_t()
> and PyLong_AsSsize_t() doesn't seem to be useful (a quick look in your
> branch makes me guess that they both accept an int or a long object
> anyway).

In changing this, I found there is a difference: callers typically check
for int, then do PyInt_AS_LONG, and use the result right away, then
they check for long, use PyLong_AsSsize_t, check for a -1 result, check
if an exception occurred, and only then use the result.

With PyLong_AsSsize_t gone, this can be unified (done in r41851);
the code becomes clearer, but there will be more type checks in the
usual code path.

> Hum.  It would be much cleaner to introduce a new format character to
> replace '#' and deprecate '#'...

That would certainly be clearer. What character would you suggest?

I see two drawbacks with that approach:
1. writing backwards-compatible modules will become harder.
   Users have to put ifdefs around the ParseTuple calls (or atleast
   around the format strings)
2. I see this as a transitional change; in P3k, indexing should be
   done exclusively through Py_ssize_t. Then '#' can be removed,
   and we are stuck with that other character.

Regards,
Martin
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] New PEP: Using ssize_t as the index type

[Martin v. Löwis]

Tim Peters wrote:
> Better to use a new gibberish character and deprecate the old one? 
> Otherwise I'm afraid we'll be stuck supporting PY_SIZE_T_CLEAN
> forever, and it's not good to have the meaning of a format string
> depend on the presence or absence of a #define far away in the file.

See my response to Armin also; I'm concerned that writing code that uses
that character will not easily be backwards compatible. What character
would you suggest?

I would not expect that we are stuck with PY_SIZE_T_CLEAN: In P3k,
Py_ssize_t should become the only type to do indexing, at which
point PY_SIZE_T_CLEAN could go.

> That can be done in one gulp via:
> 
> some_int = Py_SAFE_DOWNCAST(some_value, Py_ssize_t, int);

Thanks, added (I didn't know it existed).

Regards,
Martin
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Naming conventions in Py3K

[Martin v. Löwis]

Brett Cannon wrote:
> I am fine with changing the built-in types, but changing the built-in
> singletons just looks *really* odd to me.  So odd that I just don't
> want to see them changed.  I mean when I think of constants, I think
> of a variable that references an object and that reference never
> changes.  The built-ins you are referencing, though, are singletons:
> named objects that are not variables.  So keeping their naming scheme
> as-is does not feel like a breaking of the rules to me since they are
> not treated the same (especially at the C level).

Actually, I thought some of them would become reserved words in P3k,
anyway.

Regards,
Martin
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Naming conventions in Py3K

[Ka-Ping Yee]

On Fri, 30 Dec 2005, Reinhold Birkenfeld wrote:
> Ka-Ping Yee wrote:
> > Constants in all caps:
> > NONE, TRUE, FALSE, ELLIPSIS
>
> That's ugly.

I know it looks ugly to you now.  But there's a good reason why we use
capitalization for class names -- anyone reading code who comes across
a CapitalizedName can be reasonably certain that it refers to a class.
It's a helpful way to express the intended usage.  And, like it or not,
None, True, False, and Ellipsis aren't classes.

> In fact, I like it that the basic Python functions

I didn't say anything about renaming functions.  Functions in lowercase
are one of the naming conventions that Python does follow consistently.

> and most of the types are all-lowercase.

That's just not true, though.  (Or at least it depends on what you mean
by "most" and by "types".)  The types in the built-in module are in
lowercase, and the vast majority of the other types aren't.


-- ?!ng
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Naming conventions in Py3K

[Ka-Ping Yee]

Brett Cannon wrote:
> I am fine with changing the built-in types, but changing the built-in
> singletons just looks *really* odd to me.  So odd that I just don't
> want to see them changed.  I mean when I think of constants, I think
> of a variable that references an object and that reference never
> changes.  The built-ins you are referencing, though, are singletons:
> named objects that are not variables.

In behaviour and intended usage, they are much more like constants than
like classes, though.

> So keeping their naming scheme
> as-is does not feel like a breaking of the rules to me since they are
> not treated the same (especially at the C level).

I don't know if we share the same philosophy on this, but i don't think
the C level should play a big role here -- the names in Python programs
should express how something works (and more importantly how it is
intended to be used) at the Python level, not details under the hood.

On Fri, 30 Dec 2005, "Martin v. Löwis" wrote:
> Actually, I thought some of them would become reserved words in P3k,
> anyway.

That would be cool.  If so, it would make sense for them to be all in
lowercase.


-- ?!ng
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Naming conventions in Py3K

[Martin v. Löwis]

Ka-Ping Yee wrote:
>>Actually, I thought some of them would become reserved words in P3k,
>>anyway.
> 
> 
> That would be cool.  If so, it would make sense for them to be all in
> lowercase.

And rename None to null in the process :-)

Regards,
Martin
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Naming conventions in Py3K

[Ka-Ping Yee]

On Fri, 30 Dec 2005, "Martin v. Löwis" wrote:
> Ka-Ping Yee wrote:
> > That would be cool.  If so, it would make sense for them to be all in
> > lowercase.
>
> And rename None to null in the process :-)

Is there a really good reason to do that?  It's not obvious to me.


-- ?!ng
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] a quit that actually quits

[Samuele Pedroni]

Nick Coghlan wrote:
> Samuele Pedroni wrote:
> 
>>Michael Chermside wrote:
>>
>>>The F-bot writes:
>>>
>>>
in reality, some things are carefully thought out and craftily im-
plemented, some things are engineering tradeoffs made at a certain time,
and some things are just accidents -- but python-dev will happily defend
the current solution with the same energy, no matter what it is.
>>>
>>>+1 QOTF.
>>>
>>>Seriously... I've seen this behavior also, but I haven't ever thought
>>>about it as clearly as Fredrik does here. When we go to answer questions
>>>we ought to pause briefly first and decide which of these categories
>>>applies to a given piece of behavior. I think users will be understanding
>>>if we're honest about what are the accidents -- every language or
>>>software package has some, and just because it's an accident does NOT
>>>mean we should "fix" it.
> 
> 
> Most of the times I've asked questions along these lines I've gotten 
> well-considered answers (usually because something I thought was a deliberate 
> design decision on Guido's part turned out to simply be an accident of the 
> way 
> it happened to be implemented in CPython).
> 
> 
>>it's indeed a matter of trade-offs. Converting NameErrors into commands
>>doesn't look like a good trade off in terms of expectations management
>>and understandable behavior. Ka-Ping Yee ExitHatch still seem a 
>>reasonable improvement. Fernando Perez considerations about Python
>>vs. "commands" and prefixing and extra-linguistic extensions seem
>>also on spot. It's not a matter of defending the status quo, more about
>>what kind of price is reasonable for DWIM.
> 
> 
> I think Fredrik has made an excellent case for promoting the quit & exit 
> interpreter-only builtins to be proper callables.
> 

notice that I wrote that Ka-Ping Yee ExitHatch is an improvement!

> Hell, we even have that capability for the callable that displays the 
> *license* text. . . surely quitting the interpreter is far more important 
> than 
> being able to display the license text, but the support for the latter is 
> significantly better:
> 
> 
> Python 2.4.1 (#65, Mar 30 2005, 09:13:57) [MSC v.1310 32 bit (Intel)] on win32
> Type "help", "copyright", "credits" or "license" for more information.
> Py> exit
> 'Use Ctrl-Z plus Return to exit.'
> Py> quit
> 'Use Ctrl-Z plus Return to exit.'
> Py> license
> Type license() to see the full license text
> Py> type(license)
> 
> 
> Counting blank lines, 60 lines of site.py are devoted to getting copyright, 
> credit and license to work right, 16 to getting help to work, and only 12 to 
> setting quit and exit to the 'right' strings - and due to modules like 
> readline for Windows and differences in the way interpreters buffer the line 
> input, the exit string for Windows is not always correct.
> 
> Cheers,
> Nick.
> 

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Naming conventions in Py3K

[Martin v. Löwis]

Ka-Ping Yee wrote:
> On Fri, 30 Dec 2005, "Martin v. Löwis" wrote:
> 
>>Ka-Ping Yee wrote:
>>
>>>That would be cool.  If so, it would make sense for them to be all in
>>>lowercase.
>>
>>And rename None to null in the process :-)
> 
> 
> Is there a really good reason to do that?  It's not obvious to me.

That was mostly joking: it would sound more familiar to people from
Java and C#.

Recalling the  introduction, I don't expect Guido can
agree to writing true and false instead of True and False; nobody
has ever proposed to write none (AFAIR).

Regards,
Martin
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] [Doc-SIG] that library reference, again

[Donovan Baarda]

I've been dodging this thread because I don't really have much to add,
apart from a documentation end user point of view...

On Fri, 2005-12-30 at 09:25 +0100, Fredrik Lundh wrote:
[...]
> > Another goal is highly biased toward XML-style markup:
> >
> > * Make it trivial to do basic rendering to HTML (a few re.sub
> >   calls should suffice), to enable simple tools (CGI scripts, etc)
> >   to be able to render reference documentation.
> >
> > This is the tail wagging the dog.
> 
> No, it's a fundamental goal: to support light-weight generation of rendered
> markup directly from source code, to enable simple tools (CGI scripts, etc)
> to be able to render reference documentation.

Python is run-time interpreted, but I don't think we need its
documentation to be. "trivial" is a relative term. From my point of
view, provided I can apt-get one or to not-too-esoteric packages then do
something like "make html", it's trivial enough for me.

> The issue this is addressing is that the current workflow is way too heavy;
> when I made my first post, it typically took 3-6 months for a contribution to
> the documentation to appear on python.org.  Thanks to Trent and Neal, the
> situation is a bit better today, but it's far from ideal.  (More on this 
> below).
[...]
> That's why I'm listening to people who've tried to use ReST for this pur-
> pose.  They've all failed.  Maybe they also only understood ReST super-
> ficially.  Or maybe it's because ReST is created by people who have a
> very shallow understanding of the issues involved in writing structured
> reference documentation.  Your guess is as good as mine.

As a some-times developer not really interested in writing
documentation, I must admit I really like ReST. It looks like plain
text, so I can write and use it as plain text, but it also can magically
transform to other formats and look pretty good.

I hate writing XML/HTML, and my only experience with LaTex was brief and
painful too. If I was forced to choose, I'd probably pick LaTex even
though I don't know it as well as XML/HTML (I'd rather face an unknown
evil than that particular devil I know).

> > My bias is simple: I am against wasting the time and effort required
> > to replace one form of verbose markup with a different but equivalent
> > form.  The proposed solution is no better than the status quo.
> 
> Support for quick turnaround, edit via the web, richer semantic information,
> and a larger existing toolbase isn't better than the status quo ?
[...]

I'm not going to write docs for stuff I didn't write myself. I'm not
going to submit patches to Javadoc, LaTex or XML/HTML, but I might post
vague "change this to..." bug reports. As an end user, one of the best
things about Python is the on-line documentation... the status-quo looks
pretty good from here. 

...but I'm not the person doing it... remember I'm providing a
documentation end-user POV here :-)

> > IMO, the markup itself is almost irrelevant.  As others have stated,
> > writing good documentation is hard.  People will latch on to any
> > excuse to avoid it, and markup is convenient.  But even if the docs
> > had no markup whatsoever, if they were written in plain text like
> > RFCs, I doubt there would be significantly more patch contributions.

Writing good documentation is hard (which is why I prefer to leave it to
others if I can), but fixing almost good documentation doesn't have to
be, and for that, the markup used can make a difference. 

As an end user that spots a problem, I'll look at the source, and if
it's in a language I know well enough to fix the problem, I'll submit a
patch. If I find it's in a language I don't know and can't grok well
enough to see how to fix the problem in 10 minutes, I'm going to submit
a verbal description as a bug. 

If this is the 5+ time I've stalled on this language, I might consider
learning it so I can do a patch next time. However, in this case the
language in question is a "documentation language" and I want to be a
software programmer, not a document publisher, so I'll probably just
submit bugs every time, and after the 2+ time I won't even bother
looking at the source.

> It's the workflow that's the real problem here, but you cannot fix the 
> workflow
> without fixing the markup.

I must say I disagree with this statement... changing the markup will
not change the workflow at all, just shave 3-6 mins off the compile-test
step. I don't do this enough to really know if that's worth it.

If the markup is changed to something more widely known and/or simple,
more people might participate in the "generate patch" workflow rather
than the "submit bug" workflow, and maybe that will make things easier
for the big picture "update and release docs" workflow. But the speed of
the tool-chain has little to do with this, only the "documentation
language" popularity among the developers and users.

...and if the LaTeX guys don't mind fixing bugs instead of applying
patches and are handling the

Re: [Python-Dev] Naming conventions in Py3K

[Stephan Richter]

On Friday 30 December 2005 06:10, Ka-Ping Yee wrote:
> > In fact, I like it that the basic Python functions
>
> I didn't say anything about renaming functions.  Functions in lowercase
> are one of the naming conventions that Python does follow consistently.

well, it is not consistent when looking at functions versus methods. The best 
example here is hasattr() versus dict.has_key().

Overall I agree with your proposal to use a consistent naming style. Whatever 
it may turn out to be. We have done the same when we started with Zope 3 and 
while having some few inconsistencies, the overall code base benefitted a 
lot, I think.

Regards,
Stephan
-- 
Stephan Richter
CBU Physics & Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Naming conventions in Py3K

[Fred L. Drake, Jr.]

On Friday 30 December 2005 06:31, Ka-Ping Yee wrote:
 > Is there a really good reason to do that?  It's not obvious to me.

No more than there is to rename None to none or NONE.


  -Fred

-- 
Fred L. Drake, Jr.   
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Naming conventions in Py3K

[Michael Chermside]

?!ng proposes:
> Constants in all caps:
> NONE, TRUE, FALSE, ELLIPSIS
>
> Classes in initial-caps:
> Object, Int, Float, Str, Unicode, Set, List, Tuple, Dict,
> and lots of classes in the standard library, e.g.
> anydbm.error, csv.excel, imaplib.error, mutex.mutex...

(All that follows is just my opinion. Feel free to disregard.)

 1. PEP 8 is just some recommended conventions, not absolute rules.

 2. "None", "True", and "False" are the divinely inspired correct
spellings of these objects. All caps would be incorrect.

 3. "object", "int", "float", "str", "unicode", "set", "list",
"tuple", and "dict" all follow the common convention that the
fundamental built-in types are in all lowercase. Note that I
am distinguishing between built-in types and standard library
types. I rather like this convention and would favor keeping
it.

 4. I am a big fan of consistancy in naming. I try to follow PEP 8
in my own code, even when I don't think it's as pretty as some
other practice. But I just don't think the consistancy is worth
the cost of breaking existing code. Python 3000 is ALLOWED to
break code, but that doesn't mean it should do so gratuitously
or break more code than necessary.

 5. For some of the classes within the standard library I'm much
more open to being convinced. They are less often used, thus
more suitable for a global fix-and-replace or at tweak to the
input statements at the top of the file. Being less frequently
used also means that consistancy in naming is more important
because people don't necessarily use these every day.

-- Michael Chermside

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Naming conventions in Py3K

[Ka-Ping Yee]

On Fri, 30 Dec 2005, Fred L. Drake, Jr. wrote:
> On Friday 30 December 2005 06:31, Ka-Ping Yee wrote:
>  > Is there a really good reason to do that?  It's not obvious to me.
>
> No more than there is to rename None to none or NONE.

For that, there is a reason: None is not a class.


-- ?!ng
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Naming conventions in Py3K

[Barry Warsaw]

On Thu, 2005-12-29 at 22:29 -0600, Ka-Ping Yee wrote:
> In a fair number of cases, Python doesn't follow its own recommended
> naming conventions.  Changing these things would break backward
> compatibility, so they are out of the question for Python 2.*, but
> it would be nice to keep these in mind for Python 3K.
> 
> Constants in all caps:
> NONE, TRUE, FALSE, ELLIPSIS

Just from a practical standpoint, I'm -1 on this.  These names (at least
the first three) are typed /so/ often in Python programs, just think of
the finger pain caused by excessive use of the shift key.  Now, I
personally swap capslock and control so it would be a PITA  for
me, but doable.  But I know a lot of people who disable capslock
altogether so they'd be performing all kinds of pinkie stretching
gymnastics all the time.

-Barry



signature.asc
Description: This is a digitally signed message part
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Naming conventions in Py3K

[Guido van Rossum]

I think the discussion is coming to a clear conclusion here not to do
this (except for the standard library classes like anydbm.error). I'm
piping in with my own -1 (for all the sane reasons) to hopefully stop
this thread quickly. We don't need more noise here.

--Guido

On 12/29/05, Ka-Ping Yee <[EMAIL PROTECTED]> wrote:
> In a fair number of cases, Python doesn't follow its own recommended
> naming conventions.  Changing these things would break backward
> compatibility, so they are out of the question for Python 2.*, but
> it would be nice to keep these in mind for Python 3K.
>
> Constants in all caps:
> NONE, TRUE, FALSE, ELLIPSIS
>
> Classes in initial-caps:
> Object, Int, Float, Str, Unicode, Set, List, Tuple, Dict,
> and lots of classes in the standard library, e.g.
> anydbm.error, csv.excel, imaplib.error, mutex.mutex...
>
> I know these probably look a little funny now to most of us, as
> we're used to looking at today's Python (they even look a little
> funny to me) but i'm pretty convinced that consistency will be
> better in the long run.
>
>
> -- ?!ng
> ___
> Python-Dev mailing list
> Python-Dev@python.org
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: 
> http://mail.python.org/mailman/options/python-dev/guido%40python.org
>


--
--Guido van Rossum (home page: http://www.python.org/~guido/)
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Naming conventions in Py3K

[Thomas Wouters]

On Fri, Dec 30, 2005 at 10:16:43AM -0500, Barry Warsaw wrote:
> On Thu, 2005-12-29 at 22:29 -0600, Ka-Ping Yee wrote:
> > In a fair number of cases, Python doesn't follow its own recommended
> > naming conventions.  Changing these things would break backward
> > compatibility, so they are out of the question for Python 2.*, but
> > it would be nice to keep these in mind for Python 3K.
> > 
> > Constants in all caps:
> > NONE, TRUE, FALSE, ELLIPSIS

> Just from a practical standpoint, I'm -1 on this.  These names (at least
> the first three) are typed /so/ often in Python programs, just think of
> the finger pain caused by excessive use of the shift key.  Now, I
> personally swap capslock and control so it would be a PITA  for
> me, but doable.  But I know a lot of people who disable capslock
> altogether so they'd be performing all kinds of pinkie stretching
> gymnastics all the time.

Well, we all know code is read many more times than written, so that's a bit
of a weak argument. Personally, I'd be -1 on this because just reading the
example makes me want to jerk upright, stand at attention, salute and shout
"SIR SORRY I ASKED SIR".

There's a lot to be said for consistency and accomodating newbies (given
that we assume oldbies are already used to the current Spelling.) For
example, I've encountered many new programmers who are confused by the (lack
of) difference between builtins and variables. This would seem to be an
argument to use a form of sigils or declarations to indicate variables.
Peronally, I prefer to explain the (lack of) difference, and trust in the
fact that they'll encounter the situation in real code often enough not to
have a problem with it.

The same can be said for the suggested changes (except the stdlib modules.)
I've never seen anyone be confused about int vs Int, None vs none vs NONE,
etc. It's also not hard to get used to the particular spelling in each case;
there's more than enough exposure to burn it into even the casual
programmer's mind. And that is how people will remember it. Not by some rule
("oh, it's a constant, it has to be all caps") but by seeing it all caps all
the time. This also suggests people actively using the old names in Py3K (by
using None = NONE or what not) will actively be inhibiting the acceptance of
the new names ;)

This is all much less the case with stdlib modules, I guess, and I see no
real objection to making those conform to PEP 8.

-- 
Thomas Wouters <[EMAIL PROTECTED]>

Hi! I'm a .signature virus! copy me into your .signature file to help me spread!
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] [Doc-SIG] that library reference, again

[David Goodger]

[David Goodger]
>> The second sentence lacks a rationale.  What's wrong with "--
>> dashes"?  What's "silly" about "``quotes''"?

[Fredrik Lundh]
> don't you know *anything* about typography ?

Yes, for a layman, I know plenty.  I am not a typographer though.

Simply put, your "list of goals" provides no context for your
statements.  *I* know that "--" is turned into an en-dash in TeX, and
that "``these''" are turned into curly quotes.  So?  What's "silly"
about that?  Spell it out, man!  And what about 99% of the people who
read your page?  They won't know the first thing about what you're
talking about.

>> The reference to ReST is wrong here; ReST certainly can know the
>> semantics of a given identifier.
>
>> I don't think you understand ReST except superficially.
>
> That's why I'm listening to people who've tried to use ReST for this
> purpose.  They've all failed.  Maybe they also only understood ReST
> superficially.

Perhaps, since ReST is *not* designed as a semantic markup language.
It's designed as an implicit markup language, with explicit extensions
for semantic markup.  In any case, ReST is *not* being proposed here.

> Or maybe it's because ReST is created by people who have a very
> shallow understanding of the issues involved in writing structured
> reference documentation.  Your guess is as good as mine.

Why does Fredrik find it necessary to descend to personal insults?
Your guess is as good as mine.

> Support for quick turnaround, edit via the web, richer semantic
> information, and a larger existing toolbase isn't better than the
> status quo ?

Those would be good features.  Those features are not mentioned in
your list of goals though!  (http://effbot.org/zone/pythondoc-lib.htm)
AFAICT, you just went off on a tangent to create a new markup
language, which we don't need.

> The problem is that the WORKFLOW doesn't work.

So fix the workflow.  Something like Ian Bicking's Commentary system,
or something more specific to Python's docs, seems to fit the bill.

> It's the workflow that's the real problem here, but you cannot fix
> the workflow without fixing the markup.

I disagree.  The markup doesn't need an overhaul to fix the workflow.

> I assume this means that we're going to keep getting more "ReST can
> certainly do this but we're not going to show anyone how" posts from
> the ReST camp ?

You assume incorrectly.  I'm not talking about ReST.  I'm not
proposing ReST for anything.  Please ignore the fact that I'm the
author of ReST; I never brought it up, I never proposed it.  *You* are
the one harping on it.

I'm just against an arbitrary and unnecessary change of markup in
Python's docs.

> Your reply makes it obvious that you don't understand the issues
> involved here, nor how the goals address them.

Your reply, and your regular descent to personal insults, make it
excruciatingly obvious that you're a troll.

I hesitated before first replying to this thread, suspecting (from
past experience) that this would be the response I'd get.  From now
on, I'll avoid feeding this particular troll.

> I'd say that the fact that you're asking this should disqualify you
> from ever working on documentation tools again...

Your writing malicious crap like this ought to disqualify you from
ever participating in python-dev discussions again.

Fredrik, we all know that you you are a superb developer who makes
wonderful contributions to Python.  We also know that when faced with
disagreement (and sometimes, seemingly, without any provocation at
all) you are a malicious prick.

-- 
David Goodger 



signature.asc
Description: OpenPGP digital signature
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] [Doc-SIG] that library reference, again

[M.-A. Lemburg]

I haven't followed the thread, so many I'm repeating things.

Has anyone considered using e.g. MediaWiki (the wiki used for
Wikipedia) for Python documentation ?

I'm asking because this wiki has proven to be ideally suited
for creating complex documentation tasks and offers many features
which would make Python documentation a lot easier and more
accessible:

* people wouldn't have to learn LaTeX to commit doc-patches
* it's easy to monitor and revert changes, discuss changes
* there's version history available
* new docs would be instantly available on the web
* builtin search facility, categories and all the other nifty
  wiki stuff
* it's one of the more popular wikis around and due to Wikipedia
  it's here to stay
* conversion to XML and DocBook is possible, providing
  entry points for conversion to other formats (including
  LaTeX)
* more following means more tools (over time)

Just a thought.

Thanks,
-- 
Marc-Andre Lemburg
eGenix.com

Professional Python Services directly from the Source  (#1, Dec 30 2005)
>>> Python/Zope Consulting and Support ...http://www.egenix.com/
>>> mxODBC.Zope.Database.Adapter ... http://zope.egenix.com/
>>> mxODBC, mxDateTime, mxTextTools ...http://python.egenix.com/


::: Try mxODBC.Zope.DA for Windows,Linux,Solaris,FreeBSD for free ! 
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

[Python-Dev] slight inconsistency in svn checkin email subject lines

[Trent Mick]

Here are the subject lines for two recent svn commit emails:

   [Python-checkins] commit of r41847 - in python/trunk: 
Lib/test/test__locale.py Python/as...
   [Python-checkins]  commit of r41848 - python/trunk/setup.py
 ^
 `--- one extra space

There is an extra space when the checkin includes exactly one file (at
least, I think that is the condition).

Is this intentional? If not, could someone point me to where the svn
trigger scripts are maintained so I could poke around for a fix? (Or
just fix it themselves. :)

Cheers,
Trent

-- 
Trent Mick
[EMAIL PROTECTED]
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] [Doc-SIG] that library reference, again

[Ian Bicking]

David Goodger wrote:
>>The problem is that the WORKFLOW doesn't work.
> 
> 
> So fix the workflow.  Something like Ian Bicking's Commentary system,
> or something more specific to Python's docs, seems to fit the bill.

I'll just note that Commentary works on any HTML, so it doesn't matter 
what the original source is written in.

Obviously it is better if the markup of submitted comments match the 
original format; but it's unreasonable to accept LaTeX input in comments 
and render that to HTML for inline display.  When I have a chance I want 
to add ReST input, since some level of markup in comments is really 
called for, and I prefer not to create Yet Another Wikiish Markup (and I 
like ReST).  But manually translating ReST to LaTeX when integrating 
comments is no harder than any other manual translation, and people have 
indicated they are willing to do that translation.

Because Commentary writes to flat files, workflow should be fairly 
simple -- you submit most updates as comments.  Maybe a login or CAPTCHA 
should be added to avoid spam flooding.  rel=nofollow on links is a 
no-brainer as well (since unlike a Wiki these are relatively transient 
bits of content, so you aren't trapping link information forever by 
putting this on all links), but nofollow isn't likely itself to stop spam.

Anyway, submitted comments can be edited by hand through a text editor, 
alongside the original documentation, or through the web interface 
(right now anyone can delete a comment, but we could restrict that to 
documentation maintainers).  If the documentation contains good ids 
(that can be traced back to the original source) I think it is 
reasonable to do the entire process using the text files (comments are 
marked by their relation to a nearby id) -- but the current 
documentation has rather meaningless ids, so this might not work.

The flat files can also go in Subversion, with useful diffs and complete 
history, living safely in the same repository as the documentation or in 
a separate repository.  Comments can be branched or dumped or whatever, 
with a workflow parallel to the documentation.  Notification and 
tracking tools already exist for Subversion; additional feeds and 
whatnot could also certainly be built for Commentary, but it's not clear 
that is necessary.

Commentary is still rough in places, but it's pretty much orthogonal to 
all the other parts of the documentation system, so it doesn't require 
any big investment or conversion process.  Heck, it doesn't even require 
buy-in by anyone (except, perhaps, at least one person to generate 
comments and one person to consume them), though at some point if it 
works well it would be useful to link it from the official 
documentation.  But I think it can be useful in a non-official state as 
well.

Right now most people who might be willing to contribute to the Python 
documentation don't.  Well, "most don't" is an understatement.  "Hardly 
any" would be more accurate.  If just a small portion of people could 
contribute fairly easily that would be a big step forward.

Anyway, another even more expedient option would be setting up a 
separate bug tracker (something simpler to submit to than SF) and 
putting a link on the bottom of every page, maybe like: 
http://trac.python.org/trac/newticket?summary=re:+/path/to/doc&component=docs 
-- heck, we all know SF bug tracking sucks, this is a good chance to 
experiment with a different tracker, and documentation has softer 
requirements other parts of Python.


-- 
Ian Bicking  /  [EMAIL PROTECTED]  /  http://blog.ianbicking.org
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] [Doc-SIG] that library reference, again

[Shane Hathaway]

Ian Bicking wrote:
> Right now most people who might be willing to contribute to the Python 
> documentation don't.  Well, "most don't" is an understatement.  "Hardly 
> any" would be more accurate.  If just a small portion of people could 
> contribute fairly easily that would be a big step forward.

+1.  I've often wanted to contribute some small patch to the docs, but 
then went back to work and forgot my patch.

Shane
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] [Doc-SIG] that library reference, again

[Christopher Armstrong]

On 12/30/05, Robey Pointer <[EMAIL PROTECTED]> wrote:
>
> On 29 Dec 2005, at 18:58, David Goodger wrote:
>
> > [Fredrik Lundh]
>  I'm beginning to fear that I've wasted my time on a project
>  that nobody's interested in.
> >
> > [David Goodger]
> >>> Could be. I don't see HTML+PythonDoc as a significant improvement
> >>> over LaTeX.
> >
> > [Fredrik Lundh]
> >> Really?
> >
> > Yes, really.
>
> Just out of curiosity (really -- not trying to jump into the flames)
> why not just use epydoc?  If it's good enough for 3rd-party python
> libraries, isn't that just a small step from being good enough for
> the builtin libraries?

It's not really even "good enough" for a lot of my usage without some
seriously evil hacks. The fundamental design decision of epydoc to
import code, plus some other design decisions on the way it figures
types and identity seriously hinder its utility. Ever notice how
trying to document your third-party-library-using application will
*also* document that third party library, for example? Or how it'll
blow up when you're trying to document your gtk-using application on a
remote server without an X server running? Or how it just plain blows
right up with most Interface systems? etc.

--
  Twisted   |  Christopher Armstrong: International Man of Twistery
   Radix|-- http://radix.twistedmatrix.com
|  Release Manager, Twisted Project
  \\\V///   |-- http://twistedmatrix.com
   |o O||
wvw-+
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Gaming on Sunday (Jan 1)

[Nick Coghlan]

Grant Crawley wrote:
> no worriesI assume that we will be gaming till somewhat late?

Well, Monday's a public holiday, so. . .


Cheers,
Nick.


-- 
Nick Coghlan   |   [EMAIL PROTECTED]   |   Brisbane, Australia
---
 http://www.boredomandlaziness.org
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] [Doc-SIG] that library reference, again

[Nick Coghlan]

Ian Bicking wrote:
> Anyway, another even more expedient option would be setting up a 
> separate bug tracker (something simpler to submit to than SF) and 
> putting a link on the bottom of every page, maybe like: 
> http://trac.python.org/trac/newticket?summary=re:+/path/to/doc&component=docs 
> -- heck, we all know SF bug tracking sucks, this is a good chance to 
> experiment with a different tracker, and documentation has softer 
> requirements other parts of Python.

While I quite like this idea, would it make it more difficult when the bug 
tracking for the main source code is eventually migrated off SF? And what 
would happen to existing documentation bug reports/patches on the SF trackers?

Is it possible to do something similar for the online version of the current 
docs, simply pointing them at the SF tracker? (I know this doesn't help people 
without an SF account. . .)

Cheers,
Nick.

-- 
Nick Coghlan   |   [EMAIL PROTECTED]   |   Brisbane, Australia
---
 http://www.boredomandlaziness.org
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Gaming on Sunday (Jan 1)

[Nick Coghlan]

Sorry about that folks - finger trouble in the mail client ;)

Cheers,
Nick.

-- 
Nick Coghlan   |   [EMAIL PROTECTED]   |   Brisbane, Australia
---
 http://www.boredomandlaziness.org
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com