Re: [Python-Dev] Sets are mappings?
Aahz wrote: > On Tue, Dec 20, 2005, M.-A. Lemburg wrote: >> Josiah Carlson wrote: >>> New superclasses for all built-in types (except for string and unicode, >>> which already subclass from basestring). >>> >>> int, float, complex (long) : subclass from basenumber >>> tuple, list, set : subclass from basesequence >>> dict : subclass from basemapping >> set should be under basemapping. > > Are you sure? Sets are not actually a mapping; they consist only of > keys. The Python docs do not include sets under maps, and sets do not > support some of the standard mapping methods (notably keys()). Raymond > Hettinger has also talked about switching to a different internal > structure for sets. > > (Should this discussion move to c.l.py? Normally I'd think so, but I > think it's critical that the core developers agree about this. It's > also critical for me to know because I'm writing a book, but that's not > reason enough to stick with python-dev. ;-) Close enough to on-topic to stay here, I think. However, I tend to think of the taxonomy as a little less flat: basecontainer (anything with __len__) - set - basemapping (anything with __getitem__) - dict - basesequence (anything which understands x[0:0]) - list - tuple - string - unicode - basearray (anything which understands x[0:0,]) - Numeric.array/scipy.array 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] Sets are mappings?
Josiah Carlson writes: > New superclasses for all built-in types (except for string and unicode, > which already subclass from basestring). > > int, float, complex (long) : subclass from basenumber > tuple, list, set : subclass from basesequence > dict : subclass from basemapping > > The idea is that each of the above classes define a group in which items > are comparable. Nick Coghlan writes: > Close enough to on-topic to stay here, I think. However, I tend to think of > the taxonomy as a little less flat: > > basecontainer (anything with __len__) >- set >- basemapping (anything with __getitem__) > - dict > - basesequence (anything which understands x[0:0]) > - list > - tuple > - string > - unicode > - basearray (anything which understands x[0:0,]) > - Numeric.array/scipy.array Hold on a sec folks! I really don't understand why we are trying to build a taxonomy of container classes. There are some languages which have rather elaborate taxonomys of container classes. The STL comes to mind, Smalltalk (I think), even Java's collection classes are somewhat elaborate. But this is NOT how things have been done in the Python world. We believe that flat is better than nested. We believe in one simple-and-obvious way to do things. For goodness sakes, we don't even have a basic linked-list type because we figure it's simpler to make people just use the single well-tuned array-list implementation. Furthermore, I AGREE with this choice. I realize that in THEORY, a list is simply a bag with the extra feature of ordering, and that a list you can iterate backward is just an iterate-only-forwards list with an extra feature. But I have never found it USEFUL in practice. In languages that support it, I hardly ever find myself saying "well, I'm planning to pass a list, but this method really only needs a bag... it doesn't matter whether it is ordered", then later finding that this made it easy to re-use the method when I had some other bag implementation. Frankly, I find this sort of re-use MORE likely in Python simply because of support for duck typing. So I have a counter-proposal. Let's NOT create a hierarchy of abstract base types for the elementary types of Python. (Even basestring feels like a minor wart to me, although for now it seems like we need it.) If the core problem is "how do you create a canonical ordering for objects that survives serialization and deserialization into a different VM?", then somehow abstract base types doesn't seem like the most obvious solution. And if that's not the problem we're trying to solve here, then what IS? Because I don't know of very many ACTUAL (as opposed to theoretical) use cases for abstract base classes of fundamental types. -- 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] Sets are mappings?
Michael Chermside wrote: > Nick Coghlan writes: >> Close enough to on-topic to stay here, I think. However, I tend to think of >> the taxonomy as a little less flat: >> >> basecontainer (anything with __len__) >>- set >>- basemapping (anything with __getitem__) >> - dict >> - basesequence (anything which understands x[0:0]) >> - list >> - tuple >> - string >> - unicode >> - basearray (anything which understands x[0:0,]) >> - Numeric.array/scipy.array > So I have a counter-proposal. Let's NOT create a hierarchy of abstract > base types for the elementary types of Python. (Even basestring feels > like a minor wart to me, although for now it seems like we need it.) Sorry - I meant to indicate that I didn't think the base classes were necessary because the relevant checks already existed in a "does it behave like one" sense: def is_container(x): try: len(x) return True except (TypeError, AttributeError): return False def is_mapping(x): return hasattr(x, "__getitem__") def is_sequence(x): try: x[0:0] return True except LookupError: return False def is_multiarray(x): try: x[0:0,] return True except LookupError: return False I agree it's a definite tangent to the original topic :) 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] Sets are mappings?
Nick Coghlan writes: > Sorry - I meant to indicate that I didn't think the base classes were > necessary because the relevant checks already existed in a "does it behave > like one" sense: > >def is_container(x): [...] >def is_mapping(x): [...] >def is_sequence(x): [...] >def is_multiarray(x): [...] That sounds much more reasonable to me, although I'd also mention that it is unusual to need to test for the "protocol support" as you describe. Instead, it usually suffices to just USE the darn thing and handle failures in an except clause. This is MORE powerful than the hierarchy you describe, because it winds up testing for only the features actually needed rather than testing for adherence to some abstract base class. An example should make it easy to understand. It is perfectly reasonable for a container to support __getitem__, but not support __len__. Perhaps the container uses an algorithm to generate the items and is effectively of infinite size. In your hierarchy, this wouldn't even be a basecontainer (and thus, clearly not a basesequence). But if all you want to do is to use __getitem__ then it ought to work fine. -- 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] Sets are mappings?
On Wed, Dec 21, 2005, Michael Chermside wrote: > > So I have a counter-proposal. Let's NOT create a hierarchy of abstract > base types for the elementary types of Python. (Even basestring feels > like a minor wart to me, although for now it seems like we need > it.) If the core problem is "how do you create a canonical ordering > for objects that survives serialization and deserialization into a > different VM?", then somehow abstract base types doesn't seem like > the most obvious solution. And if that's not the problem we're trying > to solve here, then what IS? Because I don't know of very many ACTUAL > (as opposed to theoretical) use cases for abstract base classes of > fundamental types. You've got a good point, but the documentation issue still exists; that's what I was more interested in. Clearly lists, tuples, and strings are sequences; clearly dicts are a mapping; the question is whether sets get tossed in with dicts. Overall, I think it's pretty clear that the answer is "no", particularly given that sets don't support __getitem__(). -- Aahz ([EMAIL PROTECTED]) <*> http://www.pythoncraft.com/ "Don't listen to schmucks on USENET when making legal decisions. Hire yourself a competent schmuck." --USENET schmuck (aka Robert Kern) ___ 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] status of development documentation
Martin v. Löwis wrote: > If you just want to know what your changes look like: type "make html" > in the Doc directory, and wait a moment for it to complete. I get > xml.etree as section 13.13. provided you have all the right stuff on your machine, that is: $ make html TEXINPUTS=... +++ TEXINPUTS=... +++ latex api *** Session transcript and error messages are in .../Python-2.5/Doc/html/api/api.how. *** Exited with status 127. The relevant lines from the transcript are: +++ latex api sh: latex: command not found *** Session transcript and error messages are in .../Python-2.5/Doc/html/api/api.how. *** Exited with status 127. make: *** [html/api/api.html] Error 127 I'm not sure I have enough time to sort this out... my original questions remain: - could a cronjob that does this be set up on some python.org machine (or on some volunteer's machine) - is it perhaps time to start investigating using "lighter" tools for the core documentation ? (as I hinted, I'd prefer HTML with microformat annotations as the main format; with roundtripping to markdown or rest (etc) for people who prefer to author in that, and tidy->xhtml->python tools for the HTML generation) ___ 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] os.startfile with optional second parameter
Thomas Heller <[EMAIL PROTECTED]> writes:
> Would a patch be accepted that implemented an optional second parameter
> for the os.startfile function on Windows?
>
> Sometimes I missed the possibility to write
>
> os.startfile("mydocs.pdf", "print")
The other possibility would be to extend the subprocess module with this
functionality.
Thomas
___
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] Build failure and problem on Windows
Thomas Heller <[EMAIL PROTECTED]> writes: > Thomas Heller <[EMAIL PROTECTED]> writes: > >> Building the svn trunk on Windows fails because Python\pyarena.c is >> missing in the pythoncore.vcproj file (I'm not yet up to speed with svn, >> otherwise I would have checked in a fix for this myself). >> >> Worse, when running the built exe it segfaults in Py_GetBuildInfo(), >> because it is picking up somehow a definition of #define BUILD 'b' (from >> cPickle.c? Could that be?) > > I should have known better, but BUILD is defined in the MSVC project > file as BUILD=60. I've committed a fix for both (Hope these comments aren't off-topic nowadays for python-dev). Thomas ___ 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] status of development documentation
Fredrik Lundh wrote: > > - is it perhaps time to start investigating using "lighter" tools for the core > documentation ? > +1 regards Steve -- Steve Holden +44 150 684 7255 +1 800 494 3119 Holden Web LLC www.holdenweb.com PyCon TX 2006 www.python.org/pycon/ ___ 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] status of development documentation
Steve Holden <[EMAIL PROTECTED]> wrote: > > Fredrik Lundh wrote: > > > > > - is it perhaps time to start investigating using "lighter" tools for the > > core > > documentation ? > > > +1 +1 for using ReST. +0 for sticking with latex. -1 for choosing something not ReST or latex. +10 for any language we can generate from the latex sources so that a complete rewrite is unnecessary. - Josiah ___ 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] status of development documentation
At 05:10 PM 12/21/2005 +0100, Fredrik Lundh wrote: >- is it perhaps time to start investigating using "lighter" tools for the core >documentation ? > >(as I hinted, I'd prefer HTML with microformat annotations as the main format; >with roundtripping to markdown or rest (etc) for people who prefer to >author in >that, and tidy->xhtml->python tools for the HTML generation) I don't see how HTML is any "lighter" than LaTeX - to me it feels a lot heavier, even if you only consider the number of shifted keystrokes needed to type it. And attempting to roundtrip HTML back to reST would lose far too much information, like trying to decompile Python bytecode. I'm +0.5 for reST, but -1000 for HTML as an authoring format. The reason I'm only +0.5 for reST is that *any* change from the status quo, with so much documentation in existence, has a very high standard to meet. If there were no existing docs to convert, I'd be +1 on reST. ___ 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] status of development documentation
Josiah Carlson wrote: > -1 for choosing something not ReST or latex. yeah, because using something that everyone else uses would of course not be the python way. ___ 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] hashlib - faster md5/sha, adds sha256/512 support
On Fri, Dec 16, 2005 at 02:50:36PM -0800, Brett Cannon wrote: > On 12/16/05, Tim Peters <[EMAIL PROTECTED]> wrote: > [SNIP] > > python-dev'ers: I failed to find anything in the trunk's NEWS file > > about this (neither about `hashlib`, nor about any of the specific new > > hash functions). It's not like it isn't newsworthy ;-) > > I have fixed the faux pas and added an entry. thanks :) ___ 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] Incorporation of zlib sources into Python subversion
On Sun, Dec 18, 2005 at 11:09:54AM +0100, "Martin v. L?wis" wrote: > Thomas (Heller) and I have been discussing whether the zlib > module should become builtin, atleast on Win32 (i.e. part > of python25.dll). This would simplify py2exe, which then could > bootstrap extraction from the compressed file just with > pythonxy.dll (clearly, zlib.pyd cannot be *in* the compressed > file). That makes sense. One note of caution... zlib has has several security vulnerabilities revealed in the past. zlib 1.1.x (4?) seems to have had less than the more recent 1.2.x zlibs so it may be prudent to play conservative and stick with the older one to avoid chances of having to release a python security update when zlib bugs are found. (i don't know what version python uses today maybe this is a non issue?) > Whether or not this copy of zlib would be integrated in the > Unix build process, in case where the system does not provide > a zlib, is a separate question. scary to think of a system without zlib. tsk tsk on whoever makes those. -g ___ 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] status of development documentation
[Copied to the Doc-SIG list.] On Wednesday 21 December 2005 13:02, Josiah Carlson wrote: > +1 for using ReST. > +0 for sticking with latex. I'll try and spend a little time on this issue this week, but time is hard to come by these days. ReST (as implemented in docutils) at this point does *not* support nested markup constructs, unless something has changed in the last few months. I think this is a significant limitation. LaTeX, for all the tool requirements, is a fairly light-weight markup language. Yes, it has too many special characters. But someone else invented it, and I'm not keen on inventing any more than we have to. There is the matter of all the semantic markup we're doing in the LaTeX sources; some people think it's fine, and others think using a specialized semantic markup is either a bad idea or at the least a barrier to contributions (though I've pointed out that contributing just plain text is fine many, many times). Alternatives to the semantic markup that I expect to see suggested include: nothing special, just using presentation markup directly: This prevents even simple information re-use. Conventions can help, but require a careful eye on the part of editors (possibly with tools to help). something like HTML, but with "microformat" style annotations: More reasonable, especially if we rely on conventions and stylesheets for presentation. I expect the markup will actually be much heavier than the current markup, though it will be somewhat more familiar to someone when they first look at it. Adding in the annotations changes that a bit. docbook, because others use that: This is really heavy, but tools exist. The last I looked at the OOP extensions, they were fairly simple, but not well matched to Python. ReST, possibly with additional interpreted text roles: This has been explored in the past, and would likely not be a bad approach. As noted above, I expect non-support for nested markup in docutils to be a problem that will become evident fairly quickly. All that said, I think this discussion belongs on the Doc-SIG; I've CC'd that list. -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] status of development documentation
Phillip J. Eby wrote: > >(as I hinted, I'd prefer HTML with microformat annotations as the main > >format; > >with roundtripping to markdown or rest (etc) for people who prefer to > >author in that, and tidy->xhtml->python tools for the HTML generation) > > I don't see how HTML is any "lighter" than LaTeX - to me it feels a lot > heavier, even if you only consider the number of shifted keystrokes needed > to type it. umm. I was thinking "light" in terms of - tools required for the processing chain - the chance that someone new to python actually knows the stuff - support for the format in widely used word processing tools and you're talking about - number of keystrokes in a vintage text editor with no syntax support since I prefer to avoid "whitespace vs. braces" arguments, let's leave it there. > And attempting to roundtrip HTML back to reST would lose far too much > information in a less dogmatic Python universe, that would be considered a major design flaw in ReST. ___ 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] hashlib - faster md5/sha, adds sha256/512 support
> A new core `hashlib` module will be included in Python 2.5, but will > not be backported to older Python versions. It includes new > implementations for SHA-224, -256, -384 and -512. The code and tests > are already written, and can be gotten from Python's SVN trunk. Another thing I intended to do is package hashlib as standalone to make it available as an addon for python 2.3 and 2.4 users. Obviously I haven't gotten around to that yet but it remains on my TODO list. -g ___ 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] status of development documentation
On Wed, Dec 21, 2005 at 05:10:24PM +0100, Fredrik Lundh wrote: > (as I hinted, I'd prefer HTML with microformat annotations as the > main format; with roundtripping to markdown or rest (etc) for people > who prefer to author in that, and tidy->xhtml->python tools for the > HTML generation) I don't see how HTML can be used to support printed versions of the docs (e.g. PostScript, PDF). Even if you generated one big HTML file instead of a zillion section-by-section files, web browsers are terrible at printing. I don't know how you could get a table of contents that refers you to the actual pages, for example. Are there any HTML-to-print converters that are better? reST is a possibility, though I don't think anyone has worked on building the required toolchain. Fred has a LaTeX-to-XML-format converter kicking around somewhere, but the toolchain has never gotten good enough to permit making that final transition. --amk ___ 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] status of development documentation
A.M. Kuchling wrote: > On Wed, Dec 21, 2005 at 05:10:24PM +0100, Fredrik Lundh wrote: > >>(as I hinted, I'd prefer HTML with microformat annotations as the >>main format; with roundtripping to markdown or rest (etc) for people >>who prefer to author in that, and tidy->xhtml->python tools for the >>HTML generation) > > I don't see how HTML can be used to support printed versions of the > docs (e.g. PostScript, PDF). Even if you generated one big HTML file > instead of a zillion section-by-section files, web browsers are > terrible at printing. I don't know how you could get a table of > contents that refers you to the actual pages, for example. Are there > any HTML-to-print converters that are better? Why not use our own XML format? The element names could be the same as the names of the LaTeX macros. Converting to HTML and DocBook should be semi-trivial. > reST is a possibility, though I don't think anyone has worked on > building the required toolchain. Fred has a LaTeX-to-XML-format > converter kicking around somewhere, Is this available somewhere? > but the toolchain has never gotten > good enough to permit making that final transition. Bye, Walter Dörwald ___ 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] status of development documentation
At 07:33 PM 12/21/2005 +0100, Fredrik Lundh wrote: > > And attempting to roundtrip HTML back to reST would lose far too much > > information > >in a less dogmatic Python universe, that would be considered a major >design flaw in ReST. Since when is having a more expressive source language than HTML a flaw? :) ___ 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] status of development documentation
A.M. Kuchling wrote: > I don't see how HTML can be used to support printed versions of the > docs (e.g. PostScript, PDF). Even if you generated one big HTML file > instead of a zillion section-by-section files, web browsers are > terrible at printing. I don't know how you could get a table of > contents that refers you to the actual pages, for example. Are there > any HTML-to-print converters that are better? http://www.openoffice.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] status of development documentation
Fred L. Drake, Jr. wrote: > LaTeX, for all the tool requirements, is a fairly light-weight markup > language. Yes, it has too many special characters. But someone else > invented it, and I'm not keen on inventing any more than we have to. "someone else invented it" is of course why I'm advocating an HTML- based format. There's a huge infrastructure, both on the tool side and on the spec side, that deals with (X)HTML. And *everyone* knows how to write HTML. > nothing special, just using presentation markup directly: > This prevents even simple information re-use. Conventions can help, but > require a careful eye on the part of editors (possibly with tools to help). > > something like HTML, but with "microformat" style annotations: > More reasonable, especially if we rely on conventions and stylesheets for > presentation. I expect the markup will actually be much heavier than the > current markup, though it will be somewhat more familiar to someone when > they first look at it. Adding in the annotations changes that a bit. Light annotations plus simple conventions (with corresponding simple tools) should be more than good enough to match the current level. > docbook, because others use that: > This is really heavy, but tools exist. The last I looked at the OOP > extensions, they were fairly simple, but not well matched to Python. > > ReST, possibly with additional interpreted text roles: > This has been explored in the past, and would likely not be a bad approach. > As noted above, I expect non-support for nested markup in docutils to be a > problem that will become evident fairly quickly. > > All that said, I think this discussion belongs on the Doc-SIG; I've CC'd that > list. The doc-sig didn't look too active when I checked the archives, but maybe it's time to change that. ___ 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] status of development documentation
"Fredrik Lundh" <[EMAIL PROTECTED]> wrote: > > Josiah Carlson wrote: > > > -1 for choosing something not ReST or latex. > > yeah, because using something that everyone else uses would of course > not be the python way. No, because ReST is significantly easier to learn and use than basically every other markup language I've gotten my hands on. Also, considering that we are talking about documenting Python, perhaps using Perl or Ruby for the generation of Python documentation would be right out, but Python is perfectly reasonable - regardless of what 'everyone else uses' (which is a poor reason to use a tool). So far our alternatives to latex or ReST have been html, docbook, or our own XML. Though docbook and XML (thankfully) leave formatting up to the converter, all suffer from ML-itis (hard to write, hard to read, hard to maintain, syntax highlighting matters, ...), though has the benefit that it can at least be partially generated from the latex source - Walter just mentioned Fred's latex->XML converter. Depending on the output of this coverter, it may be very reasonable to convert it to ReST, or perhaps some other markup that is determined to be the rightful destination. - Josiah ___ 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] status of development documentation
Fredrik> "someone else invented it" is of course why I'm advocating an Fredrik> HTML- based format. Of course, someone also invented HTML and TeX+LaTeX predates HTML by quite a bit. Fredrik> And *everyone* knows how to write HTML. That's debatable. Maybe most people in the python-dev community know how. Even within this communitiy I suspect there are at least a few people who normally use something else (like Word) to generate HTML for them. I suspect to use the microformat stuff you'd have to restrict your authoring toolchain substantially, perhaps restricting it to plain old text editors. Skip ___ 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] status of development documentation
On Wed, Dec 21, 2005 at 07:55:42PM +0100, Walter Dörwald wrote: > >reST is a possibility, though I don't think anyone has worked on > >building the required toolchain. Fred has a LaTeX-to-XML-format > >converter kicking around somewhere, > > Is this available somewhere? Docs/tools/sgmlconv/, I think. The code's age is apparent from the README saying "Python 2.0 is required." --amk ___ 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] status of development documentation
Phillip J. Eby wrote: > > > And attempting to roundtrip HTML back to reST would lose far too much > > > information > > > >in a less dogmatic Python universe, that would be considered a major > >design flaw in ReST. > > Since when is having a more expressive source language than HTML a flaw? :) more syntax != more expressive. ___ 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] status of development documentation
Josiah Carlson wrote: > > yeah, because using something that everyone else uses would of course > > not be the python way. > > No, because ReST is significantly easier to learn and use than basically > every other markup language I've gotten my hands on. I'm not really interested in optimizing for you, I'm interested in optimizing for everyone else. They already know HTML. They don't know ReST, and I doubt they care about it (how many blogs accept ReST for comments?) ___ 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] status of development documentation
At 08:21 PM 12/21/2005 +0100, Fredrik Lundh wrote: >Phillip J. Eby wrote: > > > > > And attempting to roundtrip HTML back to reST would lose far too much > > > > information > > > > > >in a less dogmatic Python universe, that would be considered a major > > >design flaw in ReST. > > > > Since when is having a more expressive source language than HTML a > flaw? :) > >more syntax != more expressive. reST is more expressive than HTML in terms of allowing meaningful choices for readability and *human* expression. In reST, I have the choice of inlining a URL or deferring it to later, according to what's readable. I can give links friendly names, and so on. Your statement that more syntax != more expressive is true, but also irrelevant, because it doesn't imply any useful conclusions. Python is more expressive than Java because of the syntax it adds, relative to Java. Specialized syntax for lists and dictionaries, mappings, sequence iteration, etc. are precisely the things that make it more expressive for the human reader or writer of code. But the thing that makes it more expressive is not the quantity of syntax, but the balanced selection of *task-appropriate* syntax for *human* use. More syntax doesn't always mean more expressiveness or readability, but less syntax can often mean less expressiveness, readability, and usability. ___ 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] status of development documentation
[EMAIL PROTECTED] wrote: > Fredrik> And *everyone* knows how to write HTML. > > That's debatable. Maybe most people in the python-dev community know how. > Even within this communitiy I suspect there are at least a few people who > normally use something else (like Word) to generate HTML for them. I > suspect to use the microformat stuff you'd have to restrict your authoring > toolchain substantially, perhaps restricting it to plain old text editors. If we were using a microformat, it is likely that the CSS class would be used to mark content. At least that's what I've noticed in some recent microformat specs, and there's lots of good reasons to follow that. Tool support for adding classes to elements is relatively good; not great from what I can tell, but good. Not that I use a lot of these editing tools, so I might be wrong. Still, the output of WYSIWYG tools remains very poor. Because not everyone will be using WYSIWYG tools, it is likely that any such output will be to be cleaned -- reindented, and probably with any unrecognized styling removed. But this isn't that hard. Also, I assume that most documentation maintainers will continue to use text editors, because programmers use text editors, and this is programer documentation. I think it is very reasonable to expect people to know HTML; I find it unlikely that many people will enjoy authoring HTML. I know HTML quite well, I continue to write lots of it, and I've never enjoyed writing programming documentation in HTML. I guess in practice I write very little HTML *content*, just structure, and when I'm writing structure I don't mind the markup. But when I want to focus on content the markup is very distracting, and even moreso when writing about programming (where ASCII, newlines, and whitespace is the native layout technique). To me, using HTML feels like sacrificing the authoring experience for expedient tools. This doesn't seem like a big step forward from LaTeX. -- 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] status of development documentation
At 08:36 PM 12/21/2005 +0100, Fredrik Lundh wrote: >Josiah Carlson wrote: > > > > yeah, because using something that everyone else uses would of course > > > not be the python way. > > > > No, because ReST is significantly easier to learn and use than basically > > every other markup language I've gotten my hands on. > >I'm not really interested in optimizing for you, I'm interested in optimizing >for everyone else. They already know HTML. They don't know ReST, and >I doubt they care about it (how many blogs accept ReST for comments?) I think you're asking the wrong question. A better one is, how many blogs require valid HTML for comments, without offering any user-friendly bits like converting line feeds and paragraph breaks to BR and P for you? How many blogs offer other humane formats like Textile and Markdown? (Neither of which is very different from a stripped-down and underspecified version of reST.) If anything, I'd think that the fact that blogs found it necessary to invent reST-like formats implies that far more people can deal with reST-like formats than with unadulterated HTML! In addition to the syntaxes with names like Markdown and Textile and reST, I've seen lots of comment systems with their own primitive markups using similar approaches. So, using the infrequent availability of one particular humane format in blogging comment software as an argument for HTML is missing the forest for the tree. If you want to use blog comments as a test case, the evidence is overwhelming that people *don't* know HTML and/or find it hard to use. Sure, they have to type it in a text box. But you're the one who picked blog comments as an example. In any case, blog comments rarely need the full expressiveness of reST. You're not going to need section headings and intra-document links, file inclusion, footnotes, etc. in a blog comment, so it's natural that anybody inventing their own format is either going to try and make HTML more humane, or invent a reST-like mini-markup ala Textile or Markdown. ___ 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] status of development documentation
At 01:43 PM 12/21/2005 -0600, Ian Bicking wrote: > But when I want to focus >on content the markup is very distracting, and even moreso when writing >about programming (where ASCII, newlines, and whitespace is the native >layout technique). And where characters like '<' and '>' occur frequently as part of the text, especially in showing Python interactions like this: >>> print "hello world" hello world I can't imagine trying to author the above in an HTML/XML based format, whereas in reST (or even LaTeX) I can just copy and paste it from an interpreter window. ___ 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] status of development documentation
"Fredrik Lundh" <[EMAIL PROTECTED]> wrote: > > Josiah Carlson wrote: > > > > yeah, because using something that everyone else uses would of course > > > not be the python way. > > > > No, because ReST is significantly easier to learn and use than basically > > every other markup language I've gotten my hands on. > > I'm not really interested in optimizing for you, I'm interested in optimizing > for everyone else. They already know HTML. They don't know ReST, and > I doubt they care about it (how many blogs accept ReST for comments?) I'm not suggesting that anyone optimize for me. Re-read my comment. Did you re-read it? Off the top of my head, I can't think of an easier markup to learn or use that provides a variety of output. Can you? Can anyone? If so, I'm ready to listen. Until then, I'm standing by my opinion that ReST is the easiest language to learn and use for right now, which is MY criteria for selecting a documentation language. Not yours? Ok, we just have different criteria for selecting a language for documentation, so please stop suggesting that I want everyone to "optimize for [me]". Now, this is documentation for a language and its standard library. But since you brought up blogs, should we be offering LJ tags (in use by ~4 million active LJ users), BBCode (used by 10s of millions), or wiki syntax for markup? In my opinion, marketshare means close to nothing. If we were going by marketshare, we'd be documenting Python with Java, and only developing on Windows. - Josiah ___ 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] status of development documentation
On Wed, 2005-12-21 at 20:36 +0100, Fredrik Lundh wrote: > I'm not really interested in optimizing for you, I'm interested in optimizing > for everyone else. They already know HTML. They don't know ReST, and > I doubt they care about it (how many blogs accept ReST for comments?) Sorry, but HTML and (even more so) XML are not human-writable. :) Yeah, we can all do the simple stuff, but I absolutely hate authoring in HTML, and it would be a nightmare if the documentation production system didn't handle lots and lots of magic for you (like weaving in the right footers, css, etc. -- oh wait, that's ht2html!). reST is a fine language but it seems more suitable to simpler linear documents like wiki pages and PEPs, rather than those with complicated nested structure. Maybe it's just because I came in late on this thread, but what exactly is broken about the current LaTeX documentation? -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] status of development documentation
On 12/21/05, Barry Warsaw <[EMAIL PROTECTED]> wrote: [SNIP] > Maybe it's just because I came in late on this thread, but what exactly > is broken about the current LaTeX documentation? > Well, the toolchain is not necessarily installed on everyone's computer. Plus not everyone knows LaTeX comparative to other possible markup languages we could be using. Personally I am fine with LaTeX, but that is because I *learned* LaTeX to be able to edit the Python docs and have continued to use it for my school assignments. -Brett ___ 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] status of development documentation
Hallöchen! "A.M. Kuchling" <[EMAIL PROTECTED]> writes: > On Wed, Dec 21, 2005 at 05:10:24PM +0100, Fredrik Lundh wrote: > >> (as I hinted, I'd prefer HTML with microformat annotations as the >> main format; with roundtripping to markdown or rest (etc) for >> people who prefer to author in that, and tidy->xhtml->python >> tools for the HTML generation) > > I don't see how HTML can be used to support printed versions of the > docs (e.g. PostScript, PDF). I've used XSLT heavily for converting XML/XHTML to PDF. It was pretty easy, and the result was of very high typographic quality. The only disadvantage is that XSLT is *slow*. My standard approach was to convert XML to LaTeX and to substitute all unicodes with LaTeX commands. Thus, the depenencies are LaTeX, an XSLT processor (Saxon), and a tiny program for the substitutions. (The latter can be avoided by LaTeX's Unicode package; however, expect problems in some cases.) > [...] Are there any HTML-to-print converters that are better? I don't understand exactly how the HTML is to be used for Python but I assume that not everything could be done via CSS, so own converters will be necessary for perfect output. Alternatively, you can use XSLT so that the browser can convert the original document to a printable document (with table of contents, index etc). For perfect typography you need LaTeX though. > reST is a possibility, though I don't think anyone has worked on > building the required toolchain. I used reST last spring for a small package project. Although I love its goals (reST as well as Wiki languages are a perfect "front-end" for the XML family), I was disappointed with its rather small semantic vocabulary. I felt forced to use visual markup tricks and things like that. If nothing significant has changed, I think that reST is too young for a really big project. Tschö, Torsten. -- Torsten Bronger, aquisgrana, europa vetusICQ 264-296-646 ___ 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] status of development documentation
At 03:16 PM 12/21/2005 -0500, Barry Warsaw wrote: >Maybe it's just because I came in late on this thread, but what exactly >is broken about the current LaTeX documentation? As far as I can tell from his comments: 1. Fredrik doesn't want to have to install a LaTeX toolchain in order to get an HTML version of the documentation 2. Fredrik likes using whatever tools he has for editing HTML better than whatever he has for editing LaTeX 3. Fredrik believes that more people would participate in updating Python documentation if it didn't require a LaTeX toolchain or LaTeX-friendly editor. (Of course, these are equally arguments for using other formats besides HTML, especially formats that are closer to plain text.) By the way, I'm not sure I see what the problem with authoring Python documentation with reST would be. I've written fairly sizable documents (at least the size of a large library reference chapter (section?)) with both the pythondoc toolchain and with reST. It seems to me that even the largest Python manual is composed of chunks that are that size or smaller, so I don't think I see what constructs would be missing. ___ 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] status of development documentation
[Fredrik Lundh wrote] > $ make html > TEXINPUTS=... > +++ TEXINPUTS=... > +++ latex api > *** Session transcript and error messages are in > .../Python-2.5/Doc/html/api/api.how. > *** Exited with status 127. > The relevant lines from the transcript are: > > +++ latex api > sh: latex: command not found > *** Session transcript and error messages are in > .../Python-2.5/Doc/html/api/api.how. > *** Exited with status 127. > make: *** [html/api/api.html] Error 127 > > I'm not sure I have enough time to sort this out... For the record... I remember way back that I hit a limitation in latex2html that disallowed having any hyphens in the path to where the docs were being built. So your hyphen in "Python-2.5" might be confounding latex2html there. 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] status of development documentation
Barry Warsaw wrote: > Sorry, but HTML and (even more so) XML are not human-writable. :) Yeah, > we can all do the simple stuff, but I absolutely hate authoring in HTML, > and it would be a nightmare if the documentation production system > didn't handle lots and lots of magic for you (like weaving in the right > footers, css, etc. -- oh wait, that's ht2html!). Sure, and some people hate using whitespace for block structure. > Maybe it's just because I came in late on this thread, but what exactly > is broken about the current LaTeX documentation? Checked the python-list archives lately? If you google c.l.python for the word "documentation", you'll find recent megathreads with subjects like "bitching about the documentation", "opensource documentation problems" and "python documentation should be better" among the top hits. But if you check the bug and patch trackers, you don't find many contributions. Something's definitely broken. ___ 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] Incorporation of zlib sources into Python subversion
[Gregory P. Smith wrote] > (i don't know what version python uses today maybe this is a non issue?) $ svn cat http://svn.python.org/projects/python/trunk/PCbuild/zlib.vcproj | grep "zlib-" ... zlib 1.2.3 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] status of development documentation
On Wed, 2005-12-21 at 22:40 +0100, Fredrik Lundh wrote:
> > Sorry, but HTML and (even more so) XML are not human-writable. :) Yeah,
> > we can all do the simple stuff, but I absolutely hate authoring in HTML,
> > and it would be a nightmare if the documentation production system
> > didn't handle lots and lots of magic for you (like weaving in the right
> > footers, css, etc. -- oh wait, that's ht2html!).
>
> Sure, and some people hate using whitespace for block structure.
A more proper analogy would be people who hate braces and parentheses.
You have to type so many more < and > characters (not to mention &s
and ;s) to make happy-joy html than you have to type \s and {s and }s to
make nice-nice latex.
> > Maybe it's just because I came in late on this thread, but what exactly
> > is broken about the current LaTeX documentation?
>
> Checked the python-list archives lately?
That's a joke, right?
> If you google c.l.python for the
> word "documentation", you'll find recent megathreads with subjects like
> "bitching about the documentation", "opensource documentation problems"
> and "python documentation should be better" among the top hits. But if
> you check the bug and patch trackers, you don't find many contributions.
> Something's definitely broken.
I'm not convinced it's the toolchain though. People hate writing
documentation. Getting people to contribute documentation is worse than
pulling teeth. If people can't install the required toolchain and
they're still highly motivated to write Python documentation, then we
already recommend they just write it in plain text and "someone" will
mark it up.
Heck, I wouldn't mind an xml2latex converter so those that like a
different kind of pain (writing xml vs. installing latex) can still
contribute documentation and we can convert it to back to latex.
-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] status of development documentation
Barry Warsaw wrote:
> > Sure, and some people hate using whitespace for block structure.
>
> A more proper analogy would be people who hate braces and parentheses.
> You have to type so many more < and > characters (not to mention &s
> and ;s) to make happy-joy html than you have to type \s and {s and }s to
> make nice-nice latex.
so what's *your* excuse for not using emacs? ;-)
(if you don't have sgml/html support in your editor, I recommend that you
borrow my swedish keyboard, and see if you really prefer \ { } ` etc over
< > & ...)
> > If you google c.l.python for the
> > word "documentation", you'll find recent megathreads with subjects like
> > "bitching about the documentation", "opensource documentation problems"
> > and "python documentation should be better" among the top hits. But if
> > you check the bug and patch trackers, you don't find many contributions.
> > Something's definitely broken.
>
> I'm not convinced it's the toolchain though. People hate writing
> documentation. Getting people to contribute documentation is worse
> than pulling teeth.
fwiw, I seem to get more contributions to effbot.org via my really silly
HTML useredit feature than python.org gets via the patch tracker...
> If people can't install the required toolchain and they're still highly
> motivated to write Python documentation, then we already recommend
> they just write it in plain text and "someone" will mark it up.
and how motivating is it to have to wait days or weeks to be able to
see how your contribution looks after formatting?
"I had to get up in the morning at four o'clock, travel on train for eight
hours with my punch cards in a shoebox, wait twenty-nine hours for the
control data mainframe to finish, and drink a cup of sulphuric acid, ..."
___
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] status of development documentation
A.M. Kuchling wrote:
> On Wed, Dec 21, 2005 at 07:55:42PM +0100, Walter Dörwald wrote:
>>> reST is a possibility, though I don't think anyone has worked on
>>> building the required toolchain. Fred has a LaTeX-to-XML-format
>>> converter kicking around somewhere,
>> Is this available somewhere?
>
> Docs/tools/sgmlconv/, I think. The code's age is apparent from the
> README saying "Python 2.0 is required."
Hmm, I get the following:
$ make -f tools/sgmlconv/Makefile
for DIR in api dist ext lib mac ref ; do \
(cd $DIR && make -f ../tools/sgmlconv/make.rules TOOLSDIR=../tools
xml) || exit $? ; done
../tools/sgmlconv/latex2esis.py abstract.tex abstract.esis1
../tools/sgmlconv/docfixer.py abstract.esis1 abstract.esis
Traceback (most recent call last):
File "../tools/sgmlconv/docfixer.py", line 1073, in ?
main()
File "../tools/sgmlconv/docfixer.py", line 1064, in main
convert(ifp, ofp)
File "../tools/sgmlconv/docfixer.py", line 1012, in convert
fixup_descriptors(doc, fragment)
File "../tools/sgmlconv/docfixer.py", line 168, in fixup_descriptors
find_and_fix_descriptors(doc, section)
File "../tools/sgmlconv/docfixer.py", line 177, in
find_and_fix_descriptors
rewrite_descriptor(doc, child)
File "../tools/sgmlconv/docfixer.py", line 242, in rewrite_descriptor
sig = methodline_to_signature(doc, children[pos])
File "../tools/sgmlconv/docfixer.py", line 276, in
methodline_to_signature
methodline.removeAttribute("name")
File
"/Library/Frameworks/Python.framework/Versions/2.4/lib/python2.4/site-packages/_xmlplus/dom/minidom.py",
line 762, in removeAttribute
raise xml.dom.NotFoundErr()
xml.dom.NotFoundErr: Node does not exist in this context
Applying the following patch:
===
--- tools/sgmlconv/docfixer.py (revision 41780)
+++ tools/sgmlconv/docfixer.py (working copy)
@@ -273,7 +273,10 @@
signature.appendChild(doc.createTextNode("\n"))
name = doc.createElement("name")
name.appendChild(doc.createTextNode(methodline.getAttribute("name")))
-methodline.removeAttribute("name")
+try:
+ methodline.removeAttribute("name")
+except xml.dom.NotFoundErr:
+ pass
signature.appendChild(name)
if len(methodline.childNodes):
args = doc.createElement("args")
gives me this error:
Traceback (most recent call last):
File "../tools/sgmlconv/docfixer.py", line 1076, in ?
main()
File "../tools/sgmlconv/docfixer.py", line 1067, in main
convert(ifp, ofp)
File "../tools/sgmlconv/docfixer.py", line 1044, in convert
write_esis(fragment, ofp, knownempty)
File "../tools/sgmlconv/docfixer.py", line 978, in write_esis
write_esis(node, ofp, knownempty)
File "../tools/sgmlconv/docfixer.py", line 978, in write_esis
write_esis(node, ofp, knownempty)
File "../tools/sgmlconv/docfixer.py", line 978, in write_esis
write_esis(node, ofp, knownempty)
File "../tools/sgmlconv/docfixer.py", line 978, in write_esis
write_esis(node, ofp, knownempty)
File "../tools/sgmlconv/docfixer.py", line 968, in write_esis
raise ValueError, \
ValueError: declared-empty node has children
Commenting out the node.hasChildNodes() check in docfixer.write_esis()
gives me:
Traceback (most recent call last):
File "../tools/sgmlconv/docfixer.py", line 1076, in ?
main()
File "../tools/sgmlconv/docfixer.py", line 1067, in main
convert(ifp, ofp)
File "../tools/sgmlconv/docfixer.py", line 1032, in convert
if fragment.lastChild.data[-1:] == "\n":
AttributeError: Element instance has no attribute 'data'
Is there any change of getting this to work?
Bye,
Walter Dörwald
___
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] status of development documentation
Laura Creighton wrote: > Whenever people have demanded that I write documentation in html > I have always done this: > > > all my documentation, as output from a text editor. > > All subsequent formatting to be done by somebody else who doesn't > find dealing with html as excruciatingly painful as I do. > > > I suspect there are lots of people who have concluded that this > is all the html that you really need. The question is, are you > willing to put up with documentation like this from people? > Well the existing system can cope with that style, but for some reason the oft-repeated advice that plain text markup is an acceptable format for documentation contributions doesn't seem to have escaped the gravity field. So that's just as good for the existing docs as anything that replaces them (if anything does). regards Steve -- Steve Holden +44 150 684 7255 +1 800 494 3119 Holden Web LLC www.holdenweb.com PyCon TX 2006 www.python.org/pycon/ ___ 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] status of development documentation
Phillip J. Eby wrote: > And where characters like '<' and '>' occur frequently as part of the text, > especially in showing Python interactions like this: > > >>> print "hello world" > hello world > > I can't imagine trying to author the above in an HTML/XML based format, it's spelled >>> print "hello world" hello world in HTML. ___ 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] status of development documentation
Fredrik Lundh wrote: > - could a cronjob that does this be set up on some python.org machine > (or on some volunteer's machine) My understanding is: not easily. Somebody would have to invest time, of course. And then there is the issue of the build failing due to syntax errors in the input. > - is it perhaps time to start investigating using "lighter" tools for the core > documentation ? Not my time, definitely. It's a larger task than I could afford to tackle for the next, say, five years. 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] status of development documentation
Phillip J. Eby wrote: > 1. Fredrik doesn't want to have to install a LaTeX toolchain in order to > get an HTML version of the documentation > > 2. Fredrik likes using whatever tools he has for editing HTML better than > whatever he has for editing LaTeX > > 3. Fredrik believes that more people would participate in updating Python > documentation if it didn't require a LaTeX toolchain or LaTeX-friendly editor. > > (Of course, these are equally arguments for using other formats besides > HTML, especially formats that are closer to plain text.) Except, of course, for any other format (than HTML), you would have to substitute "Fredrik" by somebody promoting that other format. > By the way, I'm not sure I see what the problem with authoring Python > documentation with reST would be. Really not? How do we get from where we are to where you would like us to be? With this, I mean both technically (but perhaps I'm unaware of some tool that does the conversion automatically and lossless) and emotionally (but perhaps everybody but Fredrik and Barry could agree to switch to reST). 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] status of development documentation
At 01:40 AM 12/22/2005 +0100, Martin v. Löwis wrote: >Phillip J. Eby wrote: > > 1. Fredrik doesn't want to have to install a LaTeX toolchain in order to > > get an HTML version of the documentation > > > > 2. Fredrik likes using whatever tools he has for editing HTML better than > > whatever he has for editing LaTeX > > > > 3. Fredrik believes that more people would participate in updating Python > > documentation if it didn't require a LaTeX toolchain or LaTeX-friendly > editor. > > > > (Of course, these are equally arguments for using other formats besides > > HTML, especially formats that are closer to plain text.) > >Except, of course, for any other format (than HTML), you would have to >substitute "Fredrik" by somebody promoting that other format. To be clear: I don't advocate a switch; I'm okay with the current tools, since I have managed to get LaTeX to work on both Cygwin and Linux, which is enough for my needs. I'm endeavoring only to point out that the arguments being advanced for HTML seem shaky to me. > > By the way, I'm not sure I see what the problem with authoring Python > > documentation with reST would be. > >Really not? How do we get from where we are to where you would like >us to be? Again, I'm not advocating a switch. I'm only questioning the statements people have brought up about reST not being adequate. I'm curious to know what features are lacking, and whether this is an accurate assessment or just a general impression. If there are specific issues with reST, it would be good to know what they are. >With this, I mean both technically (but perhaps I'm unaware >of some tool that does the conversion automatically and lossless) >and emotionally (but perhaps everybody but Fredrik and Barry could agree >to switch to reST). I don't advocate a switch, for precisely the reasons you are bringing up here. Fredrik is the one advocating a switch. If there *is* to be a switch, however, I would advocate that reST be the format in the absence of compelling reasons otherwise. Since Barry and I think one other person mentioned issues with reST, I would like to know what they are. I don't think it's appropriate to have a "reST isn't adequate" meme being propagated without some definition of *how* it is considered inadequate, such as what features are missing or what misfeatures are present. This would be helpful for the docutils team, I'm sure, and in any case in the event there was a PEP to decide on a new format, it would need to specifically address any rationale for why reST should *not* be used. And I'm personally just curious as well. I've done some fairly substantive work in both the existing LaTeX-based tools: http://svn.eby-sarna.com/*checkout*/PyProtocols/docs/ref/libprotocols.tex?rev=184&content-type=text%2Fplain and using reST: http://svn.python.org/projects/sandbox/trunk/setuptools/setuptools.txt And I didn't encounter any deficiencies of reST, so I'm genuinely curious to know what it is I'm missing. It's true that the simplest standalone reST tools don't support very sophisticated indexing, but I had the impression that the more advanced tools (and certainly the docutils libraries themselves) had considerable flexibility in this regard. If someone has examples of actual "Pythondoc" markup that don't translate to reST, I'd be really interested in seeing them, just for my own education. Of course, I'd also be curious how common such constructs are. ___ 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] status of development documentation
Fredrik> If you google c.l.python for the word "documentation", you'll Fredrik> find recent megathreads with subjects like "bitching about the Fredrik> documentation", "opensource documentation problems" and "python Fredrik> documentation should be better" among the top hits. But if you Fredrik> check the bug and patch trackers, you don't find many Fredrik> contributions. Something's definitely broken. People find it easier to complain than to contribute. Maybe we should fix that problem... Skip ___ 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] status of development documentation
On Wednesday 21 December 2005 17:15, Barry Warsaw wrote: > I'm not convinced it's the toolchain though. People hate writing > documentation. Getting people to contribute documentation is worse than > pulling teeth. I don't think it's the toolchain either. While most people don't have it, it's easier and easier to get a decent toolchain on Linux; TeX just isn't as hard to have around as it used to be. I suspect that part of the problem is that there's no need to write documentation to scratch itches: once you know what to write, your itch has been scratched (you're already able to make the changes needed to your own code); nobody is relying on the updated documentation to be released to use what they figured out, even if they noted that the documentation was lacking to start with. -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
[Python-Dev] Next PyPy Sprint: Palma de Mallorca (Spain) 23rd - 29th January 2006
Palma de Mallorca PyPy Sprint: 23rd - 29th January 2006 The next PyPy sprint is scheduled to take place January 2006 in Palma De Mallorca, Balearic Isles, Spain. We'll give newcomer-friendly introductions and the focus will mainly be on current JIT work, garbage collection, alternative threading models, logic programming and on improving the interface with external functions. To learn more about the new Python-in-Python implementation look here: http://codespeak.net/pypy Goals and topics of the sprint -- In Gothenburg we have made some first forays into the interesting topics of Just-in-Time compilation. In Mallorca we will continue that and have the following ideas: - Further work/experimentation toward Just-In-Time Compiler generation, which was initiated with the Abstract Interpreter started in Gothenburg. - Integrating our garbage collection toolkit with the backends and the code generation. - Heading into the direction of adding logic programming to PyPy. - Optimization work: our threading implementation is still incredibly slow, we need to work on that. Furthermore there are still quite some slow places in the interpreter that could be improved. - getting the socket module to a more complete state (it is already improved but still far from complete) - generally improving the way we interface with external functions. - whatever participants want to do with PyPy (please send suggestions to the mailing list before to allow us to plan and give feedback) Location & Accomodation The sprint will be held at the Palma University (UIB - Universitat de les Illes Balears), in their GNU/Linux lab (http://mnm.uib.es/phpwiki/AulaLinux). We are hosted by the Computer Science department and Ricardo Galli is our contact person there, helping with arranging facilities. The University is located 7 km away from the central Palma. Busses to the University departs from "Plaza de España" (which is a very central location in Palma). Take bus 19 to the UIB campus. A ticket for one urban trip costs 1 euro. You can also buy a card that is valid for 10 trips and costs 7.51 euros. Information about bus timetables and routes can be found on: http://www.a-palma.es A map over the UIB campus are can be found on: http://www.uib.es/imagenes/planoCampus.html The actual address is: 3r pis de l'Anselm Turmeda which can be found on the UIB Campus map. At "Plaza de España" there is a hostel (Hostal Residencia Terminus) which has been recommended to us. It's cheap (ca 50 euros/double room with bathroom). Some more links to accomodations (flats, student homes and hotels): http://www.lodging-in-spain.com/hotel/town/Islas_Baleares,Mallorca,Palma_de_Mallorca,1/ http://www.uib.es/fuguib/residencia/english/index.html http://www.homelidays.com/EN-Holidays-Rental/110_Search/SearchList.asp?DESTINATION=Palma%20de%20Mallorca&ADR_PAYS=ES&ADR_ LOCALISATION=ES%20ISLASBALEARES%20MALLORCA If you want to find a given street, you can search here: http://www.callejeando.com/Pueblos/pueblo7_1.htm To get to Palma De Mallorca almost all low fare airlines and travel agencies have cheap tickets to get there. Information about Mallorca and Palma (maps, tourist information, local transports, recommended air lines, ferries and much more) can be found on: http://www.palmademallorca.es/portalPalma/home.jsp Comments on the weather: In January it is cold and wet on Mallorca Average temperature: 8,4 degrees Celsius Lowest temperature: 2 degrees Celsius Highest temperature: 14,5 degrees Celsius Average humidity rate: 77,6 % So more time for coding and less time for sunbathing and beaches ;-) Exact times --- The public PyPy sprint is held Monday 23rd - Sunday 29th January 2006. Hours will be from 10:00 until people have had enough. It's a good idea to arrive a day before the sprint starts and leave a day later. In the middle of the sprint there usually is a break day and it's usually ok to take half-days off if you feel like it. For this particular break day, Thursday, we are invited to the studio of Ginés Quiñonero, a local artist and painter. Ginés have also been the person helping us getting connections to UIB and providing much appreciated help regarding accommodation and other logistical information. For those of you interested - here is his website where there also are paintings showing his studio: http://www.hermetex4.com/damnans/ For those interested in playing collectable card games, this will also be an opportunity to get aquainted with V:TES which will be demoed by Ginés and Beatrice and Sten Düring. For more information on this cardgame - see: http://www.white-wolf.com/vtes/index.php. (The Mallorca
[Python-Dev] status of development documentation
[Fredrik wrote] > - could a cronjob that does this be set up on some python.org machine > (or on some volunteer's machine) I bit: http://trentm.com/python/ 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] status of development documentation
"Fredrik Lundh" <[EMAIL PROTECTED]> wrote:
>
> Barry Warsaw wrote:
>
> > > Sure, and some people hate using whitespace for block structure.
> >
> > A more proper analogy would be people who hate braces and parentheses.
> > You have to type so many more < and > characters (not to mention &s
> > and ;s) to make happy-joy html than you have to type \s and {s and }s to
> > make nice-nice latex.
>
> so what's *your* excuse for not using emacs? ;-)
>
> (if you don't have sgml/html support in your editor, I recommend that you
> borrow my swedish keyboard, and see if you really prefer \ { } ` etc over
> < > & ...)
Speaking of optimizing documentation for an individual ;)
- Josiah
___
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] status of development documentation
Fredrik Lundh wrote: >>Maybe it's just because I came in late on this thread, but what exactly >>is broken about the current LaTeX documentation? > > > Checked the python-list archives lately? If you google c.l.python for the > word "documentation", you'll find recent megathreads with subjects like > "bitching about the documentation", "opensource documentation problems" > and "python documentation should be better" among the top hits. But if > you check the bug and patch trackers, you don't find many contributions. > Something's definitely broken. This is somewhat tangential to this discussion, but I did have the Python documentation in mind as a potential future target for Commentary: http://pythonpaste.org/comment/commentary/ -- which would allow more casual contributions that seem to work well for other projects. -- 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
