From amk at amk.ca Tue Dec 6 17:39:31 2005 From: amk at amk.ca (A.M. Kuchling) Date: Tue, 6 Dec 2005 11:39:31 -0500 Subject: [Doc-SIG] c.l.p post on docs Message-ID: <20051206163931.GC3845@rogue.amk.ca> I just posted a lengthy message to comp.lang.python/python-list about Python's docs; the title is "Documentation suggestions". A short summary of the post is: "The RefGuide is hard to read and hard to keep updated. Do we need a friendly language description? If we do that, should the existing RefGuide be abandoned or maintained?" See the post for the full argument. (Hey, the post just showed up in Google Groups: ) I suggest further discussion on this issue take place in c.l.py. --amk From goodger at python.org Wed Dec 7 00:33:24 2005 From: goodger at python.org (David Goodger) Date: Tue, 06 Dec 2005 18:33:24 -0500 Subject: [Doc-SIG] PyCon Message-ID: <43961FC4.50302@python.org> PyCon TX 2006 is coming up, Feb. 24-26, in Addison/Dallas Texas USA. http://www.python.org/pycon/2006/ Registration is now open, and early-bird pricing is in effect until Dec. 31: http://www.python.org/pycon/2006/register.html Be sure to book your room at the conference hotel: http://www.stayatmarriott.com/Pycon2006/ There will be three Docutils-related talks: * Docutils Developers Tutorial: Architecture, Extending, and Embedding (David Goodger & Felix Wiemann) * Easy Slide Shows With reStructuredText & S5 (David Goodger) * What is Nabu? (Martin Blais) List of talks with summaries: http://wiki.python.org/moin/PyCon2006/Talks I will be giving a tutorial on the day before the conference, Feb. 23, in the morning: Text & Data Processing (http://wiki.python.org/moin/PyCon2006/Tutorials/TextProcessing). List of tutorials: http://wiki.python.org/moin/PyCon2006/Tutorials We will hold a Docutils sprint in the four days following the conference: http://wiki.python.org/moin/PyCon2006/Sprints/DocutilsSprint . Other sprints & info: http://wiki.python.org/moin/PyCon2006/Sprints Tell your user group. Tell your friends, classmates, and colleagues. I hope to see many of you there! -- David Goodger -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 249 bytes Desc: OpenPGP digital signature Url : http://mail.python.org/pipermail/doc-sig/attachments/20051206/b558db29/signature.pgp From skip at pobox.com Thu Dec 8 19:57:03 2005 From: skip at pobox.com (skip@pobox.com) Date: Thu, 8 Dec 2005 12:57:03 -0600 Subject: [Doc-SIG] Eliding most of distutils and Carbon from the global module index Message-ID: <17304.33279.366139.638706@montanaro.dyndns.org> The global module index contains around 360 entries. 46 of them are for various modules in the distutils package. Another 24 are for Carbon (Mac) modules. I think almost all those references come from lines in Doc/dist/dist.tex or Doc/mac/toolbox.tex like: \declaremodule{standard}{distutils.core} or \declaremodule{standard}{Carbon.CF} I think many/most of those modules could be omitted from the module index without major problems. The question is how to do that? Should I * remove the \declaremodule lines from the .tex files * redefine the \declaremodule macro to accept an optional arg that can suppress the generation of an index entry * define a new macro (\declaremodulenoindex?) that does everything the current one does except the index entry dance ? I'd like to do something. Take a look at the docs for distutils.debug: http://www.python.org/dev/doc/devel/dist/module-distutils.debug.html and these for Carbon.CF: http://www.python.org/dev/doc/devel/mac/module-Carbon.CF.html Hardly seems worth mentioning in the module index at all, let alone on par with sys, os, math, etc. Point me in the right direction and I'll take care of the rest. Skip From fdrake at acm.org Wed Dec 14 16:27:14 2005 From: fdrake at acm.org (Fred L. Drake, Jr.) Date: Wed, 14 Dec 2005 10:27:14 -0500 Subject: [Doc-SIG] Eliding most of distutils and Carbon from the global module index In-Reply-To: <17304.33279.366139.638706@montanaro.dyndns.org> References: <17304.33279.366139.638706@montanaro.dyndns.org> Message-ID: <200512141027.14434.fdrake@acm.org> On Thursday 08 December 2005 13:57, skip at pobox.com wrote: > The global module index contains around 360 entries. 46 of them are for > various modules in the distutils package. Another 24 are for Carbon (Mac) > modules. I think almost all those references come from lines in > Doc/dist/dist.tex or Doc/mac/toolbox.tex like: > > \declaremodule{standard}{distutils.core} > > or > > \declaremodule{standard}{Carbon.CF} That's correct. That's not the only thing these lines are used to do, however. > I think many/most of those modules could be omitted from the module index > without major problems. The question is how to do that? Should I > > * remove the \declaremodule lines from the .tex files No. > * redefine the \declaremodule macro to accept an optional arg that can > suppress the generation of an index entry No. > * define a new macro (\declaremodulenoindex?) that does everything > the current one does except the index entry dance No. > ? I'd like to do something. Take a look at the docs for distutils.debug: > > http://www.python.org/dev/doc/devel/dist/module-distutils.debug.html > > and these for Carbon.CF: > > http://www.python.org/dev/doc/devel/mac/module-Carbon.CF.html > > Hardly seems worth mentioning in the module index at all, let alone on par > with sys, os, math, etc. It should be easy to remove the distutils modules simply by editing the command used to generate html/modindex.html in Doc/Makefile. Dealing with the Carbon modules may be more difficult. Perhaps adding an "exclude" filter to Doc/tools/mkmodindex would be sufficient. It would need to be set from the command line. In the long run, though, we really just need to complete the documentation for those modules without sufficient documentation. Patches welcome. :-) -Fred -- Fred L. Drake, Jr. From fdrake at acm.org Wed Dec 21 19:35:09 2005 From: fdrake at acm.org (Fred L. Drake, Jr.) Date: Wed, 21 Dec 2005 13:35:09 -0500 Subject: [Doc-SIG] [Python-Dev] status of development documentation In-Reply-To: <20051221095628.BE79.JCARLSON@uci.edu> References: <20051221095628.BE79.JCARLSON@uci.edu> Message-ID: <200512211335.09433.fdrake@acm.org> [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. From skip at pobox.com Wed Dec 21 20:24:56 2005 From: skip at pobox.com (skip@pobox.com) Date: Wed, 21 Dec 2005 13:24:56 -0600 Subject: [Doc-SIG] [Python-Dev] status of development documentation In-Reply-To: References: <20051221095628.BE79.JCARLSON@uci.edu> <200512211335.09433.fdrake@acm.org> Message-ID: <17321.44040.97252.894883@montanaro.dyndns.org> 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 From ianb at colorstudy.com Wed Dec 21 20:43:21 2005 From: ianb at colorstudy.com (Ian Bicking) Date: Wed, 21 Dec 2005 13:43:21 -0600 Subject: [Doc-SIG] [Python-Dev] status of development documentation In-Reply-To: <17321.44040.97252.894883@montanaro.dyndns.org> References: <20051221095628.BE79.JCARLSON@uci.edu> <200512211335.09433.fdrake@acm.org> <17321.44040.97252.894883@montanaro.dyndns.org> Message-ID: <43A9B059.9060900@colorstudy.com> skip at pobox.com 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 / ianb at colorstudy.com / http://blog.ianbicking.org From lac at strakt.com Wed Dec 21 21:26:19 2005 From: lac at strakt.com (Laura Creighton) Date: Wed, 21 Dec 2005 21:26:19 +0100 Subject: [Doc-SIG] [Python-Dev] status of development documentation In-Reply-To: Message from Ian Bicking of "Wed, 21 Dec 2005 13:43:21 CST." <43A9B059.9060900@colorstudy.com> References: <20051221095628.BE79.JCARLSON@uci.edu> <200512211335.09433.fdrake@acm.org> <17321.44040.97252.894883@montanaro.dyndns.org> <43A9B059.9060900@colorstudy.com> Message-ID: <200512212026.jBLKQJWZ027961@theraft.strakt.com> 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? Laura From steve at holdenweb.com Wed Dec 21 21:49:26 2005 From: steve at holdenweb.com (Steve Holden) Date: Wed, 21 Dec 2005 20:49:26 +0000 Subject: [Doc-SIG] [Python-Dev] status of development documentation In-Reply-To: <200512212026.jBLKQJWZ027961@theraft.strakt.com> References: <20051221095628.BE79.JCARLSON@uci.edu> <200512211335.09433.fdrake@acm.org> <17321.44040.97252.894883@montanaro.dyndns.org> <43A9B059.9060900@colorstudy.com> <200512212026.jBLKQJWZ027961@theraft.strakt.com> Message-ID: 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/ From fredrik at pythonware.com Wed Dec 21 21:53:30 2005 From: fredrik at pythonware.com (Fredrik Lundh) Date: Wed, 21 Dec 2005 21:53:30 +0100 Subject: [Doc-SIG] status of development documentation References: <17321.44040.97252.894883@montanaro.dyndns.org> <20051221095628.BE79.JCARLSON@uci.edu><200512211335.09433.fdrake@acm.org> <17321.44040.97252.894883@montanaro.dyndns.org> <43A9B059.9060900@colorstudy.com> <5.1.1.6.0.20051221150745.03d1aa38@mail.telecommunity.com> Message-ID: 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. From ianb at colorstudy.com Thu Dec 22 06:17:30 2005 From: ianb at colorstudy.com (Ian Bicking) Date: Wed, 21 Dec 2005 23:17:30 -0600 Subject: [Doc-SIG] [Python-Dev] status of development documentation In-Reply-To: References: <20051221095628.BE79.JCARLSON@uci.edu> <20051221105132.BE7C.JCARLSON@uci.edu> <1135196162.14495.15.camel@geddy.wooz.org> Message-ID: <43AA36EA.2090302@colorstudy.com> 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 | ianb at colorstudy.com | http://blog.ianbicking.org From mike at pcblokes.com Thu Dec 22 11:19:32 2005 From: mike at pcblokes.com (Michael Foord) Date: Thu, 22 Dec 2005 10:19:32 +0000 Subject: [Doc-SIG] [Python-Dev] status of development documentation In-Reply-To: References: <20051221095628.BE79.JCARLSON@uci.edu> <200512211335.09433.fdrake@acm.org> <17321.44040.97252.894883@montanaro.dyndns.org> <43A9B059.9060900@colorstudy.com> <200512212026.jBLKQJWZ027961@theraft.strakt.com> Message-ID: <43AA7DB4.7020305@pcblokes.com> Steve Holden wrote: > 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). Hmmm... I submitted some plain text (might have been reST actually) docs as a suggested addition to urllib2. The response from the maintainer) was that I ought to submit it as patches against the original Tex document. Now admittedly what I submitted *does* need breaking into smaller sections to make it easier to add to fit into the docs. (IIRC the error classes are barely documented in urllib2 - vital information is missing from the docs). *However* - there was no implication that the maintainer was happy to work with plain text submissions. All the best, Fuzzyman http://www.voidspace.org.uk/python/index.shtml > regards > Steve From mike at pcblokes.com Thu Dec 22 12:38:39 2005 From: mike at pcblokes.com (Michael Foord) Date: Thu, 22 Dec 2005 11:38:39 +0000 Subject: [Doc-SIG] Python Tutorial - urllib2 Message-ID: <43AA903F.3010908@pcblokes.com> By the way (and in the vain (sic) of shameless self-promotion...) there was a suggestion on Dobbs Python-URL that the inclusion of some of my material on urllib2 would be welcome in the tutorial. http://groups.google.com/group/comp.lang.python/browse_frm/thread/1d52898f07b7dfcd/d015de23ad6818fa My tutorial is at : http://www.voidspace.org.uk/python/urllib2.shtml The most appropriate sections to include would be on fetching URLs and handling errors, and possibly the basic authentication example. It probably fits best in the 'Brief tour of the standard library'. Would that be welcomed ? It is currently in rest format - and html of course ;-) Is reST acceptable for *someone* to add this material - and if so, what should I do about it ? By the way my vote is -1 on moving to html as the standard markup format and +1 on working on docutils to turn that into an usable input format. Additionally - having a wiki version, or a version that accepts user commentary would be a very useful way of gathering additional information. Of course someone has to maintain this... I think AMK did a simple implementation of this a while ago - although it had usability issues and the resulting data didn't seem to be used. I guess this is all part of the ongoing discussion. All the best, Fuzzyman http://www.voidspace.org.uk/python/index.shtml From mike at pcblokes.com Thu Dec 22 12:48:35 2005 From: mike at pcblokes.com (Michael Foord) Date: Thu, 22 Dec 2005 11:48:35 +0000 Subject: [Doc-SIG] Python Tutorial - urllib2 In-Reply-To: <43AA903F.3010908@pcblokes.com> References: <43AA903F.3010908@pcblokes.com> Message-ID: <43AA9293.1040406@pcblokes.com> Michael Foord wrote: > By the way (and in the vain (sic) of shameless self-promotion...) there > was a suggestion on Dobbs Python-URL that the inclusion of some of my > material on urllib2 would be welcome in the tutorial. > > http://groups.google.com/group/comp.lang.python/browse_frm/thread/1d52898f07b7dfcd/d015de23ad6818fa > > My tutorial is at : http://www.voidspace.org.uk/python/urllib2.shtml > Oops... correction : http://www.voidspace.org.uk/python/articles/urllib2.shtml Sorry about that. I *would* be interested in helping with the Python tutorial (and docs where appropriate). it's a question of knowing where to begin... All the best, Fuzzyman http://www.voidspace.org.uk/python/index.shtml > The most appropriate sections to include would be on fetching URLs and > handling errors, and possibly the basic authentication example. It > probably fits best in the 'Brief tour of the standard library'. > > Would that be welcomed ? It is currently in rest format - and html of > course ;-) > > Is reST acceptable for *someone* to add this material - and if so, what > should I do about it ? > > By the way my vote is -1 on moving to html as the standard markup format > and +1 on working on docutils to turn that into an usable input format. > Additionally - having a wiki version, or a version that accepts user > commentary would be a very useful way of gathering additional > information. Of course someone has to maintain this... I think AMK did a > simple implementation of this a while ago - although it had usability > issues and the resulting data didn't seem to be used. I guess this is > all part of the ongoing discussion. > > All the best, > > Fuzzyman > http://www.voidspace.org.uk/python/index.shtml > _______________________________________________ > Doc-SIG maillist - Doc-SIG at python.org > http://mail.python.org/mailman/listinfo/doc-sig > > > From fredrik at pythonware.com Thu Dec 22 13:28:22 2005 From: fredrik at pythonware.com (Fredrik Lundh) Date: Thu, 22 Dec 2005 13:28:22 +0100 Subject: [Doc-SIG] Python Tutorial - urllib2 References: <43AA903F.3010908@pcblokes.com> Message-ID: Michael Foord wrote: > By the way my vote is -1 on moving to html as the standard markup format > and +1 on working on docutils to turn that into an usable input format. so how to you plan to achieve the required level of semantic markup in ReST? From amk at amk.ca Thu Dec 22 15:22:06 2005 From: amk at amk.ca (A.M. Kuchling) Date: Thu, 22 Dec 2005 09:22:06 -0500 Subject: [Doc-SIG] documentation comments In-Reply-To: References: <20051221095628.BE79.JCARLSON@uci.edu> <20051221105132.BE7C.JCARLSON@uci.edu> <1135196162.14495.15.camel@geddy.wooz.org> <17322.83.459862.800945@montanaro.dyndns.org> Message-ID: <20051222142206.GB15340@rogue.amk.ca> On Thu, Dec 22, 2005 at 09:27:06AM +0000, Steve Holden wrote: > Could the PSF help here by offering annual prizes for the best > contributions to the documentation, or wouldn't that be an adequate > motivator? I think the most effective thing would be to award a grant to someone to build a real comment-on-the-docs system. There were a few Summer of Code proposals for this sort of thing; one was funded but the developer decided to do a KDE project instead. I had lunch with Fred the other day, and he was worried about whether anyone would garden the comments to remove spam. That is indeed an issue, but I think we can cope with that problem once a system is built. Another worry is versioning. Once lots of people have made comments on Python 2.4.0's documentation, what do you do when 2.4.1 is released? Do you move the comments to the new docs, or leave them attached to 2.4.0 and start 2.4.1 with a clean slate? (Perhaps the system could work a little like a bug tracking system; comments could be marked as 'applied', and applied comments don't get moved from 2.4.0 to 2.4.1 because their content is now in the docs.) --amk From fdrake at acm.org Thu Dec 22 15:16:30 2005 From: fdrake at acm.org (Fred L. Drake, Jr.) Date: Thu, 22 Dec 2005 09:16:30 -0500 Subject: [Doc-SIG] [Python-Dev] documentation comments In-Reply-To: <20051222142206.GB15340@rogue.amk.ca> References: <20051221095628.BE79.JCARLSON@uci.edu> <20051222142206.GB15340@rogue.amk.ca> Message-ID: <200512220916.30516.fdrake@acm.org> On Thursday 22 December 2005 09:22, A.M. Kuchling wrote: > I had lunch with Fred the other day, and he was worried about whether > anyone would garden the comments to remove spam. That is indeed an > issue, but I think we can cope with that problem once a system is > built. > > Another worry is versioning. Once lots of people have made comments > on Python 2.4.0's documentation, what do you do when 2.4.1 is > released? Do you move the comments to the new docs, or leave them > attached to 2.4.0 and start 2.4.1 with a clean slate? This was actually a big part of my gardening concern: comments from the release X.Y.Z docs need to be handled before releasing X.Y.Z+1 or X.Y+1.*, or they aren't being used to improve the documentation at all. > (Perhaps the > system could work a little like a bug tracking system; comments could > be marked as 'applied', and applied comments don't get moved from > 2.4.0 to 2.4.1 because their content is now in the docs.) I'd be more inclined to see that comments are handled (even if handling them is a matter of determining that they aren't actually interesting), and just toss comments for a new release. A patch release would be an occaission to turn off commenting on the previous releases for the same X.Y version (though comments would still exist in the older version). -Fred -- Fred L. Drake, Jr. From fdrake at acm.org Thu Dec 22 15:35:40 2005 From: fdrake at acm.org (Fred L. Drake, Jr.) Date: Thu, 22 Dec 2005 09:35:40 -0500 Subject: [Doc-SIG] [Python-Dev] status of development documentation In-Reply-To: <43AA7DB4.7020305@pcblokes.com> References: <43AA7DB4.7020305@pcblokes.com> Message-ID: <200512220935.40820.fdrake@acm.org> On Thursday 22 December 2005 05:19, Michael Foord wrote: > Hmmm... I submitted some plain text (might have been reST actually) docs > as a suggested addition to urllib2. The response from the maintainer) > was that I ought to submit it as patches against the original Tex > document. Did you submit this as a documentation issue on the SF tracker? If this is still outstanding, please point me to the submission. > *However* - there was no implication that the maintainer was happy to > work with plain text submissions. This sounds like a specific individual isn't interested in converting to LaTeX, which isn't surprising (though unfortunate). We'll have to find a better way to handle this, since I don't want to be turning away plain text contributions due to format. I hope it wasn't me, in a moment of madness. :-/ -Fred -- Fred L. Drake, Jr. From mike at pcblokes.com Thu Dec 22 15:40:36 2005 From: mike at pcblokes.com (Michael Foord) Date: Thu, 22 Dec 2005 14:40:36 +0000 Subject: [Doc-SIG] [Python-Dev] status of development documentation In-Reply-To: <200512220935.40820.fdrake@acm.org> References: <43AA7DB4.7020305@pcblokes.com> <200512220935.40820.fdrake@acm.org> Message-ID: <43AABAE4.70305@pcblokes.com> Fred L. Drake, Jr. wrote: > On Thursday 22 December 2005 05:19, Michael Foord wrote: > > Hmmm... I submitted some plain text (might have been reST actually) docs > > as a suggested addition to urllib2. The response from the maintainer) > > was that I ought to submit it as patches against the original Tex > > document. > > Did you submit this as a documentation issue on the SF tracker? If this is > still outstanding, please point me to the submission. > I submitted it as a patch in the documentation category. (probably hence the response which effectively says 'this isn't a patch'). https://sourceforge.net/tracker/?func=detail&atid=305470&aid=1216942&group_id=5470 > > *However* - there was no implication that the maintainer was happy to > > work with plain text submissions. > > This sounds like a specific individual isn't interested in converting to > LaTeX, which isn't surprising (though unfortunate). We'll have to find a > better way to handle this, since I don't want to be turning away plain text > contributions due to format. > > I hope it wasn't me, in a moment of madness. :-/ > No - I would have responded privately. It was John J Lee - who does a sterling job of maintaining the code he creates. I'm happy to do more work on making the document suitable for inclusion. All the best, Fuzzyman http://www.voidspace.org.uk/python/index.shtml > > -Fred > From aahz at pythoncraft.com Thu Dec 22 15:57:51 2005 From: aahz at pythoncraft.com (Aahz) Date: Thu, 22 Dec 2005 06:57:51 -0800 Subject: [Doc-SIG] Python Tutorial - urllib2 In-Reply-To: <43AA903F.3010908@pcblokes.com> References: <43AA903F.3010908@pcblokes.com> Message-ID: <20051222145751.GA12735@panix.com> On Thu, Dec 22, 2005, Michael Foord wrote: > > Is reST acceptable for *someone* to add this material - and if so, what > should I do about it ? Submit in reST or plain-text and someone will do any necessary conversions. Really, don't worry about it, Just Do It. -- Aahz (aahz at pythoncraft.com) <*> 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) From blais at furius.ca Thu Dec 22 16:06:48 2005 From: blais at furius.ca (Martin Blais) Date: Thu, 22 Dec 2005 10:06:48 -0500 Subject: [Doc-SIG] Python Tutorial - urllib2 In-Reply-To: <43AA903F.3010908@pcblokes.com> References: <43AA903F.3010908@pcblokes.com> Message-ID: <8393fff0512220706j9c90ce0kfb401c7d2f97aeba@mail.gmail.com> On 12/22/05, Michael Foord wrote: > By the way (and in the vain (sic) of shameless self-promotion...) there > was a suggestion on Dobbs Python-URL that the inclusion of some of my > material on urllib2 would be welcome in the tutorial. > > http://groups.google.com/group/comp.lang.python/browse_frm/thread/1d52898f07b7dfcd/d015de23ad6818fa > > My tutorial is at : http://www.voidspace.org.uk/python/urllib2.shtml > > The most appropriate sections to include would be on fetching URLs and > handling errors, and possibly the basic authentication example. It > probably fits best in the 'Brief tour of the standard library'. > > Would that be welcomed ? It is currently in rest format - and html of > course ;-) Your tutorial is great. Read it a while ago. Would love to see it along the other tutorials or even in the library docs for the module (as the urllib2 docs are a bit thin on explanations). > Is reST acceptable for *someone* to add this material - and if so, what > should I do about it ? Convert it to LaTeX (it's easy) and submit it. > By the way my vote is -1 on moving to html as the standard markup format > and +1 on working on docutils to turn that into an usable input format. > Additionally - having a wiki version, or a version that accepts user > commentary would be a very useful way of gathering additional > information. Of course someone has to maintain this... I think AMK did a > simple implementation of this a while ago - although it had usability > issues and the resulting data didn't seem to be used. I guess this is > all part of the ongoing discussion. There was a long and detailed discussion about using ReST as an input format for documentation a while ago. The consensus was that ReST does not allow sufficient markup for technical documentation, which is necessary for this kind of document. The LaTeX input format using the macros from the python docs is very simple. Converting your document should be easy. cheers, From mike at pcblokes.com Thu Dec 22 16:21:01 2005 From: mike at pcblokes.com (Michael Foord) Date: Thu, 22 Dec 2005 15:21:01 +0000 Subject: [Doc-SIG] Python Tutorial - urllib2 In-Reply-To: <8393fff0512220706j9c90ce0kfb401c7d2f97aeba@mail.gmail.com> References: <43AA903F.3010908@pcblokes.com> <8393fff0512220706j9c90ce0kfb401c7d2f97aeba@mail.gmail.com> Message-ID: <43AAC45D.2020200@pcblokes.com> Martin Blais wrote: > On 12/22/05, Michael Foord wrote: > >>By the way (and in the vain (sic) of shameless self-promotion...) there >>was a suggestion on Dobbs Python-URL that the inclusion of some of my >>material on urllib2 would be welcome in the tutorial. >> >>http://groups.google.com/group/comp.lang.python/browse_frm/thread/1d52898f07b7dfcd/d015de23ad6818fa >> >>My tutorial is at : http://www.voidspace.org.uk/python/urllib2.shtml >> >>The most appropriate sections to include would be on fetching URLs and >>handling errors, and possibly the basic authentication example. It >>probably fits best in the 'Brief tour of the standard library'. >> >>Would that be welcomed ? It is currently in rest format - and html of >>course ;-) > > > Your tutorial is great. Read it a while ago. Would love to see it > along the other tutorials or even in the library docs for the module > (as the urllib2 docs are a bit thin on explanations). > > > >>Is reST acceptable for *someone* to add this material - and if so, what >>should I do about it ? > > > Convert it to LaTeX (it's easy) and submit it. > One of the docutils output forms is LayTeX - but the Python documentation LayTeX is pretty specific ? Anyway, that *aside* - it looks like Fred has taken on 'TeXifying' the relevant part I submitted as a patch to the urllib2 docs. (Many thanks). I'll probably wait and see how that reads and evaluate if a longer entry in the tutorial is appropriate. If it *is* then I'll customise appropriately. If I was to do this - what *is* the appropriate way to submit ? Via sourceforge ? > > >>By the way my vote is -1 on moving to html as the standard markup format >>and +1 on working on docutils to turn that into an usable input format. >>Additionally - having a wiki version, or a version that accepts user >>commentary would be a very useful way of gathering additional >>information. Of course someone has to maintain this... I think AMK did a >>simple implementation of this a while ago - although it had usability >>issues and the resulting data didn't seem to be used. I guess this is >>all part of the ongoing discussion. > > > There was a long and detailed discussion about using ReST as an input > format for documentation a while ago. The consensus was that ReST > does not allow sufficient markup for technical documentation, which is > necessary for this kind of document. > Doesn't currently - or can't ? I thought it was just the current state that was a problem. I'd be disappointed if it was never likely to be possible to create the python docs with reST. All the best, Fuzzyman http://www.voidspace.org.uk/python/index.shtml > The LaTeX input format using the macros from the python docs is very > simple. Converting your document should be easy. > > cheers, > > > From amk at amk.ca Thu Dec 22 17:34:24 2005 From: amk at amk.ca (A.M. Kuchling) Date: Thu, 22 Dec 2005 11:34:24 -0500 Subject: [Doc-SIG] Python Tutorial - urllib2 In-Reply-To: <8393fff0512220706j9c90ce0kfb401c7d2f97aeba@mail.gmail.com> References: <43AA903F.3010908@pcblokes.com> <8393fff0512220706j9c90ce0kfb401c7d2f97aeba@mail.gmail.com> Message-ID: <20051222163424.GA15471@rogue.amk.ca> On Thu, Dec 22, 2005 at 10:06:48AM -0500, Martin Blais wrote: > Your tutorial is great. Read it a while ago. Would love to see it > along the other tutorials or even in the library docs for the module > (as the urllib2 docs are a bit thin on explanations). There's also the Doc/howto directory. It's not part of the standard documentation set yet, but it already includes one reST document (unicode.rst), so your tutorial could just be added as a urllib2 HOWTO without any conversion. (At that point we probably *should* be thinking of building the HOWTOs as part of the docset.) --amk From blais at furius.ca Thu Dec 22 16:47:15 2005 From: blais at furius.ca (Martin Blais) Date: Thu, 22 Dec 2005 10:47:15 -0500 Subject: [Doc-SIG] Python Tutorial - urllib2 In-Reply-To: <43AAC45D.2020200@pcblokes.com> References: <43AA903F.3010908@pcblokes.com> <8393fff0512220706j9c90ce0kfb401c7d2f97aeba@mail.gmail.com> <43AAC45D.2020200@pcblokes.com> Message-ID: <8393fff0512220747ub975079o183fe47a9c7c59db@mail.gmail.com> > >>By the way my vote is -1 on moving to html as the standard markup format > >>and +1 on working on docutils to turn that into an usable input format. > >>Additionally - having a wiki version, or a version that accepts user > >>commentary would be a very useful way of gathering additional > >>information. Of course someone has to maintain this... I think AMK did a > >>simple implementation of this a while ago - although it had usability > >>issues and the resulting data didn't seem to be used. I guess this is > >>all part of the ongoing discussion. > > > > > > There was a long and detailed discussion about using ReST as an input > > format for documentation a while ago. The consensus was that ReST > > does not allow sufficient markup for technical documentation, which is > > necessary for this kind of document. > > > > Doesn't currently - or can't ? I thought it was just the current state > that was a problem. I'd be disappointed if it was never likely to be > possible to create the python docs with reST. Well, be disappointed. It does not currently, and most likely won't. As much as we all would like some kind of magic silver bullet text format that just "knows" what we mean and want to express, it is rather unlikely that ReST develops to become that for every kind of domain. ReST does a fair amount of *generic* structure inference, and that is its scope. The amount of ugly directives and markup being regularly proposed on the docutils mailing-list indicates that ReST may have already reached its potential in terms of automatically guessing structure from simple text files. Even if this is not the case, extending ReST to include keywords for functions, variables, classes, lists of arguments, etc. would render it into just an equally ugly form of input equivalent to the current LaTeX sources, ... and without the power of expression of TeX macros! You see, for the technical docs we NEED to indicate the nature of the identifiers, not just to render them consistently, but for generating indexes, and cross-references, and for plenty of fother reasons. You can't do that in ReST (well, the interpreted roles do take you part of the way, but not enough). At some point you have to tell the computer all the information that is in your head, and the ReST format simply does not stretch that far, and LaTeX is a great tool for this at the moment. What sucks now is the inflexibliity of the produced document: the tools to convert from the LaTeX sources to other formats are nothing short of wizardry (i.e. LaTeX2html). What would be great IMO is if we could obtain some kind of meaningful intermediate representation from the source, from which we could then generate various output formats (a bit like how docutils is structured). I saw some project like that a while ago, generating XML from LaTeX sources, never had time to check it out more seriously. cheers, From mike at pcblokes.com Thu Dec 22 17:08:16 2005 From: mike at pcblokes.com (Michael Foord) Date: Thu, 22 Dec 2005 16:08:16 +0000 Subject: [Doc-SIG] Python Tutorial - urllib2 In-Reply-To: <20051222163424.GA15471@rogue.amk.ca> References: <43AA903F.3010908@pcblokes.com> <8393fff0512220706j9c90ce0kfb401c7d2f97aeba@mail.gmail.com> <20051222163424.GA15471@rogue.amk.ca> Message-ID: <43AACF70.7090700@pcblokes.com> A.M. Kuchling wrote: > On Thu, Dec 22, 2005 at 10:06:48AM -0500, Martin Blais wrote: > >>Your tutorial is great. Read it a while ago. Would love to see it >>along the other tutorials or even in the library docs for the module >>(as the urllib2 docs are a bit thin on explanations). > > > There's also the Doc/howto directory. It's not part of the standard > documentation set yet, but it already includes one reST document > (unicode.rst), so your tutorial could just be added as a urllib2 HOWTO > without any conversion. (At that point we probably *should* be > thinking of building the HOWTOs as part of the docset.) > My source document uses some macros - e.g. to colorize the python code examples. I'm happy to clean it up for inclusion as a "HOWTO Fetch Internet Resources Using urllib2". I don't have unrestricted internet access here (ironically enough) - so could you email me the unicode.rst source so I can give it a similar format. Should I privately email you the result for you to assess ? I could probably complete this tonight... The risk it that it will duplicate some of the material which should be (soon) included in the urllib2 documentation. Again, I could wait until Fred has done this and see if a fuller tutorial is appropriate ? Many Thanks Fuzzyman http://www.voidspace.org.uk/python/index.shtml > --amk > _______________________________________________ > Doc-SIG maillist - Doc-SIG at python.org > http://mail.python.org/mailman/listinfo/doc-sig > > > From fdrake at acm.org Thu Dec 22 17:19:49 2005 From: fdrake at acm.org (Fred L. Drake, Jr.) Date: Thu, 22 Dec 2005 11:19:49 -0500 Subject: [Doc-SIG] Python Tutorial - urllib2 In-Reply-To: <8393fff0512220706j9c90ce0kfb401c7d2f97aeba@mail.gmail.com> References: <43AA903F.3010908@pcblokes.com> <8393fff0512220706j9c90ce0kfb401c7d2f97aeba@mail.gmail.com> Message-ID: <200512221119.49924.fdrake@acm.org> On Thursday 22 December 2005 10:06, Martin Blais wrote: > Convert it to LaTeX (it's easy) and submit it. Or just submit as ReST, and request conversion. I like spending my time in XEmacs. :-) > The LaTeX input format using the macros from the python docs is very > simple. Converting your document should be easy. This is mostly true; some LaTeXishness can be subtle. If someone does want to do their own LaTeX, that's fine, and I try to make the documentation for the Python-specific macros fairly complete ("Documenting Python": http://docs.python.org/doc/doc.html). If there are questions after reading that, I'm glad to answer them and improve that document as well. -Fred -- Fred L. Drake, Jr. From fdrake at acm.org Thu Dec 22 17:15:02 2005 From: fdrake at acm.org (Fred L. Drake, Jr.) Date: Thu, 22 Dec 2005 11:15:02 -0500 Subject: [Doc-SIG] Python Tutorial - urllib2 In-Reply-To: <20051222145751.GA12735@panix.com> References: <43AA903F.3010908@pcblokes.com> <20051222145751.GA12735@panix.com> Message-ID: <200512221115.03169.fdrake@acm.org> On Thursday 22 December 2005 09:57, Aahz wrote: > Submit in reST or plain-text and someone will do any necessary > conversions. Really, don't worry about it, Just Do It. For the record, I've assigned Fuzzyman's issue to myself, but we should make it easier for other Python project members to refer issues to the LaTeX-willing as needed. At least better document the policy in general and make sure project members know how to get someone to handle TeXification. -Fred -- Fred L. Drake, Jr. From fdrake at acm.org Thu Dec 22 17:31:45 2005 From: fdrake at acm.org (Fred L. Drake, Jr.) Date: Thu, 22 Dec 2005 11:31:45 -0500 Subject: [Doc-SIG] Python Tutorial - urllib2 In-Reply-To: <8393fff0512220747ub975079o183fe47a9c7c59db@mail.gmail.com> References: <43AA903F.3010908@pcblokes.com> <43AAC45D.2020200@pcblokes.com> <8393fff0512220747ub975079o183fe47a9c7c59db@mail.gmail.com> Message-ID: <200512221131.45829.fdrake@acm.org> On Thursday 22 December 2005 10:47, Martin Blais wrote: > Well, be disappointed. > It does not currently, and most likely won't. Yes and no. Docutils provides support for creating new directives ("dot-dot things") and interpreted text roles (":colon: things"). These would go a long way to doing what we want, and some experimentation was done toward this specifically to support documenting Python modules in a style similar to the standard library documentation. This is somewhere in the docutils sandbox. > guessing structure from simple text files. Even if this is not the > case, extending ReST to include keywords for functions, variables, > classes, lists of arguments, etc. would render it into just an > equally ugly form of input equivalent to the current LaTeX sources, > ... and without the power of expression of TeX macros! Whether :function:`os.popen()` is any uglier than \function{os.popen()} is largely a matter of what you're used to. I will note that the LaTeX version is one character shorter. :-) I think there are appealing qualities to both the TeX macros and the availability of the docutils document object model. Both allow for lots of neat things. > What sucks now is the inflexibliity of the produced document: the > tools to convert from the LaTeX sources to other formats are nothing > short of wizardry (i.e. LaTeX2html). What would be great IMO is if we > could obtain some kind of meaningful intermediate representation from Yes, that is the biggest source of pain. > the source, from which we could then generate various output formats > (a bit like how docutils is structured). I saw some project like that > a while ago, generating XML from LaTeX sources, never had time to > check it out more seriously. I should get back to that; as someone else noted, the code is really old, and doesn't support everything in the current LaTeX markup. -Fred -- Fred L. Drake, Jr. From blais at furius.ca Thu Dec 22 17:53:21 2005 From: blais at furius.ca (Martin Blais) Date: Thu, 22 Dec 2005 11:53:21 -0500 Subject: [Doc-SIG] Python Tutorial - urllib2 In-Reply-To: <200512221131.45829.fdrake@acm.org> References: <43AA903F.3010908@pcblokes.com> <43AAC45D.2020200@pcblokes.com> <8393fff0512220747ub975079o183fe47a9c7c59db@mail.gmail.com> <200512221131.45829.fdrake@acm.org> Message-ID: <8393fff0512220853p45f99766l9c105a9851ad3eaf@mail.gmail.com> On 12/22/05, Fred L. Drake, Jr. wrote: > On Thursday 22 December 2005 10:47, Martin Blais wrote: > > Well, be disappointed. > > It does not currently, and most likely won't. > > Yes and no. > > Docutils provides support for creating new directives ("dot-dot things") and > interpreted text roles (":colon: things"). These would go a long way to > doing what we want, and some experimentation was done toward this > specifically to support documenting Python modules in a style similar to the > standard library documentation. This is somewhere in the docutils sandbox. It would still not be significantly better than using LaTeX. if it's not better, why change? > > guessing structure from simple text files. Even if this is not the > > case, extending ReST to include keywords for functions, variables, > > classes, lists of arguments, etc. would render it into just an > > equally ugly form of input equivalent to the current LaTeX sources, > > ... and without the power of expression of TeX macros! > > Whether :function:`os.popen()` is any uglier than \function{os.popen()} is > largely a matter of what you're used to. I will note that the LaTeX version > is one character shorter. :-) It's not just that: the LaTeX macro call allows variations (e.g. optional arguments) that the ReST form does not allow. It's more powerful. Also, the dot-dot directives impose constraints on the layout contents (has to be indented), which for some uses can make them awkward to use. The LaTeX model (delimiting with {}, not caring about whitespace) is more flexible. > I think there are appealing qualities to both the TeX macros and the > availability of the docutils document object model. Both allow for lots of > neat things. Apart from the syntax and a little less markup, I would like to know are those qualities is that thing that are better with ReST than in the LaTeX model. The only thing I can see is the ease of conversion. Everything else is less convenient. > > What sucks now is the inflexibliity of the produced document: the > > tools to convert from the LaTeX sources to other formats are nothing > > short of wizardry (i.e. LaTeX2html). What would be great IMO is if we > > could obtain some kind of meaningful intermediate representation from > > Yes, that is the biggest source of pain. > > > the source, from which we could then generate various output formats > > (a bit like how docutils is structured). I saw some project like that > > a while ago, generating XML from LaTeX sources, never had time to > > check it out more seriously. > > I should get back to that; as someone else noted, the code is really old, and > doesn't support everything in the current LaTeX markup. Oh, you did that? What a wizard :-) From fdrake at acm.org Thu Dec 22 18:24:01 2005 From: fdrake at acm.org (Fred L. Drake, Jr.) Date: Thu, 22 Dec 2005 12:24:01 -0500 Subject: [Doc-SIG] reStructuredText v. LaTeX In-Reply-To: <8393fff0512220853p45f99766l9c105a9851ad3eaf@mail.gmail.com> References: <43AA903F.3010908@pcblokes.com> <200512221131.45829.fdrake@acm.org> <8393fff0512220853p45f99766l9c105a9851ad3eaf@mail.gmail.com> Message-ID: <200512221224.01397.fdrake@acm.org> Note the new subject line; it's a not-so-subtle hint that this is a dying thread. :-) On Thursday 22 December 2005 11:53, Martin Blais wrote: > It would still not be significantly better than using LaTeX. > if it's not better, why change? I'm not proposing change. Just noting what's been considered. (I'm also not ruling out change; my priority on the matter is high-quality documentation, not toolchain.) > It's not just that: the LaTeX macro call allows variations (e.g. > optional arguments) that the ReST form does not allow. It's more > powerful. Yes, it is. Sometimes that's good. > Also, the dot-dot directives impose constraints on the layout contents > (has to be indented), which for some uses can make them awkward to > use. The LaTeX model (delimiting with {}, not caring about > whitespace) is more flexible. Yes. I think that's a bigger problem for the Python documentation. > Apart from the syntax and a little less markup, I would like to know > are those qualities is that thing that are better with ReST than in > the LaTeX model. The only thing I can see is the ease of conversion. > Everything else is less convenient. The benefit of ReST is the document object model that's available. Tools can be written to use that to create new features (such as navigational aids). > Oh, you did that? What a wizard :-) Either that, or a lunatic. ;-) -Fred -- Fred L. Drake, Jr. From lac at strakt.com Thu Dec 22 18:25:16 2005 From: lac at strakt.com (Laura Creighton) Date: Thu, 22 Dec 2005 18:25:16 +0100 Subject: [Doc-SIG] Python Tutorial - urllib2 In-Reply-To: Message from Michael Foord of "Thu, 22 Dec 2005 15:21:01 GMT." <43AAC45D.2020200@pcblokes.com> References: <43AA903F.3010908@pcblokes.com> <8393fff0512220706j9c90ce0kfb401c7d2f97aeba@mail.gmail.com> <43AAC45D.2020200@pcblokes.com> Message-ID: <200512221725.jBMHPGYs017761@theraft.strakt.com> Is there a list somewhere of exactly what it is that would need to be added to ReST in order to support writing Python documentation in ReST? Laura From fredrik at pythonware.com Thu Dec 22 19:17:26 2005 From: fredrik at pythonware.com (Fredrik Lundh) Date: Thu, 22 Dec 2005 19:17:26 +0100 Subject: [Doc-SIG] Python Tutorial - urllib2 References: <43AA903F.3010908@pcblokes.com> <43AAC45D.2020200@pcblokes.com><8393fff0512220747ub975079o183fe47a9c7c59db@mail.gmail.com> <200512221131.45829.fdrake@acm.org> Message-ID: Fred L. Drake, Jr. wrote: > Whether :function:`os.popen()` is any uglier than \function{os.popen()} is > largely a matter of what you're used to. I will note that the LaTeX version > is one character shorter. :-) javadoc's {@link os.popen} is even shorter. hmm. maybe a combination of rest/html/whatever and pythondoc markup would be the ultimate tool for the library reference... From blais at furius.ca Thu Dec 22 19:28:31 2005 From: blais at furius.ca (Martin Blais) Date: Thu, 22 Dec 2005 13:28:31 -0500 Subject: [Doc-SIG] Python Tutorial - urllib2 In-Reply-To: References: <43AA903F.3010908@pcblokes.com> <43AAC45D.2020200@pcblokes.com> <8393fff0512220747ub975079o183fe47a9c7c59db@mail.gmail.com> <200512221131.45829.fdrake@acm.org> Message-ID: <8393fff0512221028w42a694aeua38123dec0837ec0@mail.gmail.com> On 12/22/05, Fredrik Lundh wrote: > Fred L. Drake, Jr. wrote: > > > Whether :function:`os.popen()` is any uglier than \function{os.popen()} is > > largely a matter of what you're used to. I will note that the LaTeX version > > is one character shorter. :-) > > javadoc's > > {@link os.popen} > > is even shorter. > > hmm. maybe a combination of rest/html/whatever and pythondoc markup > would be the ultimate tool for the library reference... <* heavy clapping sound of my footsteps while running away screaming in fear *> From fredrik at pythonware.com Thu Dec 22 19:44:55 2005 From: fredrik at pythonware.com (Fredrik Lundh) Date: Thu, 22 Dec 2005 19:44:55 +0100 Subject: [Doc-SIG] Python Tutorial - urllib2 References: <43AA903F.3010908@pcblokes.com> <43AAC45D.2020200@pcblokes.com><8393fff0512220747ub975079o183fe47a9c7c59db@mail.gmail.com><200512221131.45829.fdrake@acm.org> <8393fff0512221028w42a694aeua38123dec0837ec0@mail.gmail.com> Message-ID: Martin Blais wrote: > > javadoc's > > > > {@link os.popen} > > > > is even shorter. > > > > hmm. maybe a combination of rest/html/whatever and pythondoc markup > > would be the ultimate tool for the library reference... > > <* heavy clapping sound of my footsteps while running away screaming in fear *> really? so what's so problematic with Converts a Python tuple or a Fault instance to an XML-RPC request. @def dumps(params, **options) @param params A tuple or {@link Fault} instance. @keyparam methodname If given, create a methodCall request for this method name. @keyparam methodresponse If given, create a methodResponse packet. If used with a tuple, the tuple must be a singleton (that is, it must contain exactly one element). @keyparam encoding The encoding to use for this request. Defaults to UTF-8. @return A string containing marshalled data. compared to \begin{funcdesc}{dumps}{params\optional{, methodname\optional{, methodresponse\optional{, encoding}}}} Convert \var{params} into an XML-RPC request. or into a response if \var{methodresponse} is true. \var{params} can be either a tuple of arguments or an instance of the \exception{Fault} exception class. If \var{methodresponse} is true, only a single value can be returned, meaning that \var{params} must be of length 1. \var{encoding}, if supplied, is the encoding to use in the generated XML; the default is UTF-8. \end{funcdesc} given that the former can be trivially converted to a well-defined information model: dumps Convert a Python tuple or a Fault instance to an XML-RPC request. Convert a Python tuple or a Fault instance to an XML-RPC request. dumps(params, **options) A tuple or Fault instance. If given, create a methodCall request for this method name. If given, create a methodResponse packet. If used with a tuple, the tuple must be a singleton (that is, it must contain exactly one element). The request encoding. Defaults to UTF-8. A string containing marshalled data. for further processing, while the latter results in a nice
dumps( params[, methodname[, methodresponse[, encoding] ] ])

Convert params into an XML-RPC request. or into a response if methodresponse is true. params can be either a tuple of arguments or an instance of the Fault exception class. If methodresponse is true, only a single value can be returned, meaning that params must be of length 1. encoding, if supplied, is the encoding to use in the generated XML; the default is UTF-8.

tag soup. From aahz at pythoncraft.com Thu Dec 22 20:33:55 2005 From: aahz at pythoncraft.com (Aahz) Date: Thu, 22 Dec 2005 11:33:55 -0800 Subject: [Doc-SIG] status of development documentation In-Reply-To: References: <43A9B059.9060900@colorstudy.com> <5.1.1.6.0.20051221150745.03d1aa38@mail.telecommunity.com> Message-ID: <20051222193355.GA2691@panix.com> On Wed, Dec 21, 2005, Fredrik Lundh wrote: > 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. What about XHTML? -- Aahz (aahz at pythoncraft.com) <*> 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) From fredrik at pythonware.com Thu Dec 22 21:19:39 2005 From: fredrik at pythonware.com (Fredrik Lundh) Date: Thu, 22 Dec 2005 21:19:39 +0100 Subject: [Doc-SIG] status of development documentation References: <43A9B059.9060900@colorstudy.com><5.1.1.6.0.20051221150745.03d1aa38@mail.telecommunity.com> <20051222193355.GA2691@panix.com> Message-ID: Aahz wrote: > >> >>> 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. > > What about XHTML? same thing. not that I understand why anyone would author in XHTML, though. From bronger at physik.rwth-aachen.de Thu Dec 22 21:40:08 2005 From: bronger at physik.rwth-aachen.de (Torsten Bronger) Date: Thu, 22 Dec 2005 21:40:08 +0100 Subject: [Doc-SIG] status of development documentation References: <43A9B059.9060900@colorstudy.com> <5.1.1.6.0.20051221150745.03d1aa38@mail.telecommunity.com> <20051222193355.GA2691@panix.com> Message-ID: <87fyokeuhj.fsf@wilson.rwth-aachen.de> Hall?chen! "Fredrik Lundh" writes: > [...] > > not that I understand why anyone would author in XHTML, though. Because you can use XSLT on it. Tsch?, Torsten. -- Torsten Bronger, aquisgrana, europa vetus ICQ 264-296-646 From fredrik at pythonware.com Thu Dec 22 21:50:44 2005 From: fredrik at pythonware.com (Fredrik Lundh) Date: Thu, 22 Dec 2005 21:50:44 +0100 Subject: [Doc-SIG] status of development documentation References: <43A9B059.9060900@colorstudy.com><5.1.1.6.0.20051221150745.03d1aa38@mail.telecommunity.com> <20051222193355.GA2691@panix.com> <87fyokeuhj.fsf@wilson.rwth-aachen.de> Message-ID: Torsten Bronger wrote: > > not that I understand why anyone would author in XHTML, though. > > Because you can use XSLT on it. tidy -asxml -n source | xsltengine From bronger at physik.rwth-aachen.de Thu Dec 22 22:07:19 2005 From: bronger at physik.rwth-aachen.de (Torsten Bronger) Date: Thu, 22 Dec 2005 22:07:19 +0100 Subject: [Doc-SIG] status of development documentation References: <43A9B059.9060900@colorstudy.com> <5.1.1.6.0.20051221150745.03d1aa38@mail.telecommunity.com> <20051222193355.GA2691@panix.com> <87fyokeuhj.fsf@wilson.rwth-aachen.de> Message-ID: <87bqz8et88.fsf@wilson.rwth-aachen.de> Hall?chen! "Fredrik Lundh" writes: > Torsten Bronger wrote: > >>> not that I understand why anyone would author in XHTML, though. >> >> Because you can use XSLT on it. > > tidy -asxml -n source | xsltengine I would have to add that to every processing line in my batch scripts. Just to avoid some slashes? Anyway ... a minor question. Tsch?, Torsten. -- Torsten Bronger, aquisgrana, europa vetus ICQ 264-296-646 From fredrik at pythonware.com Thu Dec 22 22:46:13 2005 From: fredrik at pythonware.com (Fredrik Lundh) Date: Thu, 22 Dec 2005 22:46:13 +0100 Subject: [Doc-SIG] status of development documentation References: <43A9B059.9060900@colorstudy.com><5.1.1.6.0.20051221150745.03d1aa38@mail.telecommunity.com> <20051222193355.GA2691@panix.com> <87fyokeuhj.fsf@wilson.rwth-aachen.de> <87bqz8et88.fsf@wilson.rwth-aachen.de> Message-ID: Torsten Bronger wrote: > I would have to add that to every processing line in my batch > scripts. Just to avoid some slashes? no, to avoid unnecessary syntax errors in your XSLT processor. a HTML parser is more tolerant than an XML parser, and tidy is more tolerant than an ordinary HTML parser. From fdrake at acm.org Fri Dec 23 00:58:49 2005 From: fdrake at acm.org (Fred L. Drake, Jr.) Date: Thu, 22 Dec 2005 18:58:49 -0500 Subject: [Doc-SIG] [Python-Dev] documentation comments In-Reply-To: References: <20051221095628.BE79.JCARLSON@uci.edu> <20051222142206.GB15340@rogue.amk.ca> Message-ID: <200512221858.49521.fdrake@acm.org> On Thursday 22 December 2005 13:44, Neal Norwitz wrote: > I would help assuming this is easy--meaning a single click to remove a > comment. It looks like the system the MySQL folks are using makes it easy, but I've not tried polluting their documentation with tests, just in case. :-) In general, my worry is less with dealing with spam than with ensuring integration of content enhancements before release candidates go out. -Fred -- Fred L. Drake, Jr. From fredrik at pythonware.com Mon Dec 26 19:53:27 2005 From: fredrik at pythonware.com (Fredrik Lundh) Date: Mon, 26 Dec 2005 19:53:27 +0100 Subject: [Doc-SIG] that library reference, again Message-ID: as seen on the doc-sig: > > > javadoc's > > > > > > {@link os.popen} > > > > > > is even shorter. > > > > > > hmm. maybe a combination of rest/html/whatever and pythondoc markup > > > would be the ultimate tool for the library reference... > > > > <* heavy clapping sound of my footsteps while running away screaming in fear *> > > really? since everything that has people running in fear is worth investigating further, I've spent a few hours putting together a first iteration of a "python.org library reference to a javadoc-ish source format converter". more info here: http://effbot.org/zone/pythondoc-lib.htm including goals, non-goals, and 2.5 megabytes of converted (but not yet properly rendered) library pages. From goodger at python.org Wed Dec 28 16:08:17 2005 From: goodger at python.org (David Goodger) Date: Wed, 28 Dec 2005 10:08:17 -0500 Subject: [Doc-SIG] PyCon TX 2006: Early-bird registration ends Dec. 31! Message-ID: <43B2AA61.2030603@python.org> Early bird registration for PyCon TX 2006 ends on December 31st, so there are only a few days LEFT. To register, please visit: http://us.pycon.org/TX2006/Registration You can still register after Dec. 31st, but the cost will go up by US$65 (US$25 for students). This year PyCon will feature a day of tutorials before the three days of regular presentations. Course outlines for all the tutorials have been posted; see http://wiki.python.org/moin/PyCon2006/Tutorials All of the PyCon tutorials are still open for new registrations, but space is limited, and we suspect they'll all be filled up by the time early-bird registration closes. Don't forget to book your hotel room, too. PyCon TX 2006 is being held at a Dallas/Addison hotel, and we have negotiated a special low rate: http://us.pycon.org/Addison/Hotels We hope to see you in Texas! -- David Goodger (on behalf of A.M. Kuchling, Chair, PyCon 2006) -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 249 bytes Desc: OpenPGP digital signature Url : http://mail.python.org/pipermail/doc-sig/attachments/20051228/c3bc46aa/signature.pgp From jerdonek at gmail.com Wed Dec 28 20:36:18 2005 From: jerdonek at gmail.com (Chris Jerdonek) Date: Wed, 28 Dec 2005 11:36:18 -0800 Subject: [Doc-SIG] new to documenting python Message-ID: <71c52463ee884f9206fc7f3bf4131283@gmail.com> Hi, I'm new to this list. I read in "Documenting Python" that you're discussing/starting to migrate from LaTeX markup to XML. If I'm interested in learning to write documentation for a Python application, does it still make sense for me to learn using your LaTeX approach? When do you expect being able to generate PDFs from XML? Thanks, --Chris PS - the link to the Linux Documentation Project is broken here and here: http://www.python.org/sigs/doc-sig/ http://mail.python.org/mailman/listinfo/doc-sig From aahz at pythoncraft.com Wed Dec 28 23:52:01 2005 From: aahz at pythoncraft.com (Aahz) Date: Wed, 28 Dec 2005 14:52:01 -0800 Subject: [Doc-SIG] new to documenting python In-Reply-To: <71c52463ee884f9206fc7f3bf4131283@gmail.com> References: <71c52463ee884f9206fc7f3bf4131283@gmail.com> Message-ID: <20051228225201.GA9795@panix.com> On Wed, Dec 28, 2005, Chris Jerdonek wrote: > > I read in "Documenting Python" that you're discussing/starting to > migrate from LaTeX markup to XML. If I'm interested in learning to > write documentation for a Python application, does it still make sense > for me to learn using your LaTeX approach? When do you expect being > able to generate PDFs from XML? Switching away from LaTeX is still pie-in-the-sky. But you certainly don't need to use LaTeX for your own application -- pick whatever suits you. -- Aahz (aahz at pythoncraft.com) <*> http://www.pythoncraft.com/ "Given that C++ has pointers and typecasts, it's really hard to have a serious conversation about type safety with a C++ programmer and keep a straight face. It's kind of like having a guy who juggles chainsaws wearing body armor arguing with a guy who juggles rubber chickens wearing a T-shirt about who's in more danger." --Roy Smith From fredrik at pythonware.com Thu Dec 29 15:11:58 2005 From: fredrik at pythonware.com (Fredrik Lundh) Date: Thu, 29 Dec 2005 15:11:58 +0100 Subject: [Doc-SIG] that library reference, again References: Message-ID: I wrote: > since everything that has people running in fear is worth investigating > further, I've spent a few hours putting together a first iteration of a > "python.org library reference to a javadoc-ish source format converter". > > more info here: > > http://effbot.org/zone/pythondoc-lib.htm > > including goals, non-goals, and 2.5 megabytes of converted (but not > yet properly rendered) library pages. I've spent a few more hours tweaking the converter, and I'm now very close to a point where the entire library reference can be handled by a combination of this tool and a reasonable manual cleanup effort. overview: http://effbot.org/zone/pythondoc-lib.htm sample pages (with visible preliminary markup): http://effbot.org/lib however, given that the discussion that led up to this has been dead for almost a week, I'm beginning to fear that I've wasted my time on a project that nobody's interested in. are we stuck with latex for the foreseeable future? From goodger at python.org Thu Dec 29 21:38:15 2005 From: goodger at python.org (David Goodger) Date: Thu, 29 Dec 2005 15:38:15 -0500 Subject: [Doc-SIG] that library reference, again In-Reply-To: References: Message-ID: <4335d2c40512291238l6b1d44b7vaf0963b631f3bd89@mail.gmail.com> On 12/29/05, Fredrik Lundh wrote: > however, given that the discussion that led up to this has been dead for > almost a week, You mean since Christmas? > I'm beginning to fear that I've wasted my time on a project > that nobody's interested in. Could be. I don't see HTML+PythonDoc as a significant improvement over LaTeX. Yes, I'm biased. So are you. > are we stuck with latex for the foreseeable future? Until we have something clearly and significantly better, yes. -- David Goodger From goodger at python.org Fri Dec 30 03:58:00 2005 From: goodger at python.org (David Goodger) Date: Thu, 29 Dec 2005 21:58:00 -0500 Subject: [Doc-SIG] that library reference, again In-Reply-To: References: <4335d2c40512291238l6b1d44b7vaf0963b631f3bd89@mail.gmail.com> Message-ID: <43B4A238.2030101@python.org> [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. > Have you read my list of goals? Yes, and I mostly agree with most of them. One is worded in a very slanted way: * Build on existing non-Python-specific documentation standards and tools, where possible (basic html, javadoc, xhtml modules, etc). It seems that this goal is specifically written to exclude ReST. Javadoc is only a standard in the Java world. LaTeX *is* an existing language-independent standard, and has a much longer history than javadoc. I'd re-write the above goal as: * Build on existing documentation standards and tools, where possible. 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. This item is under-specified: * Make is easy to do advanced rendering to HTML, XHTML or XML models (e.g. typographic issues, navigation, dynamic styling, etc.). No more -- dashes and silly ``quotes''. The second sentence lacks a rationale. What's wrong with "-- dashes"? What's "silly" about "``quotes''"? Your list is missing an important goal: * Easy to read. The final paragraph of the "Project Goals" section lacks context and contains a false statement: The semantic model should be simple, python-oriented, and more detailed than today. For example, while a ReST-based solution knows that open in a given context should be rendered in bold, and a LaTeX-based solution knows that the given open is a function, the PythonDoc model also knows that it refers to the os.open function, rather than the built-in open function. The reference to ReST is wrong here; ReST certainly can know the semantics of a given identifier. I'd like to see an example of how the HTML+PythonDoc markup indicates that a particular "open" is os.open and not __builtins__.open. > Does LaTeX address all of them? Perhaps not. So? It works well enough. > Does ReST? Not currently, but so what? I didn't propose ReST as an alternative to LaTeX for Python's documentation. All I'm saying is that the proposed HTML+PythonDoc markup is not significantly better than the status quo. I don't think there's enough benefit to make leaving LaTeX worthwhile. IOW: -1 on replacing LaTeX with HTML+PythonDoc. > If not, can you explain why they're not important. > >> Yes, I'm biased. So are you. > > I don't think you understand the problem, so your bias is > irrelevant. This is all about semantics, not presentation markup. I don't think you understand ReST except superficially. In any case, ReST is irrelevant to this discussion. I do not consider ReST a suitable replacement for LaTeX in Python's docs at present. 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. I agree with the people who have stated that they find the direct writing of HTML painful. 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. Plain text patches are already accepted; perhaps this fact needs more emphasis, but that's all. > We know that you have big hats over in ReST-land; now show us some > cattle. Moo. Or would you prefer the Buddhist "mu"? What *are* you talking about? -- David Goodger -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 249 bytes Desc: OpenPGP digital signature Url : http://mail.python.org/pipermail/doc-sig/attachments/20051229/6adae0ba/signature.pgp From chad at zetaweb.com Fri Dec 30 15:03:49 2005 From: chad at zetaweb.com (Chad Whitacre) Date: Fri, 30 Dec 2005 09:03:49 -0500 Subject: [Doc-SIG] what about OpenDocument? Message-ID: Dear all, Here's a crazy idea: what would it look like to maintain the Python documentation in OpenDocument format? Pros ==== - robust authoring environment: OpenOffice - drastically lower barrier to entry for authors - custom markup == custom OOo stylesheet (!) - open XML-based format means easy-to-write tools - trivial PDF conversion - powerful typesetting - nice boost for ODF/OOo Cons ==== - HTML version would take work; default not good enough - harder to diff/version? - um ..., um ... "Hey, I'd like to write documentation for my new Python module." "Ok, download the OOo template from python.org and go to it!" chad From goodger at python.org Fri Dec 30 17:27:20 2005 From: goodger at python.org (David Goodger) Date: Fri, 30 Dec 2005 11:27:20 -0500 Subject: [Doc-SIG] that library reference, again In-Reply-To: References: <4335d2c40512291238l6b1d44b7vaf0963b631f3bd89@mail.gmail.com> <43B4A238.2030101@python.org> Message-ID: <43B55FE8.1040401@python.org> [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 -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 249 bytes Desc: OpenPGP digital signature Url : http://mail.python.org/pipermail/doc-sig/attachments/20051230/b6af558a/signature.pgp From chad at zetaweb.com Fri Dec 30 18:23:41 2005 From: chad at zetaweb.com (Chad Whitacre) Date: Fri, 30 Dec 2005 12:23:41 -0500 Subject: [Doc-SIG] what about OpenDocument? In-Reply-To: References: Message-ID: <43B56D1D.9020405@zetaweb.com> Dear All, Attached is the documentation for the random module in ODT format. The file includes paragraph, character, and list styles for Python objects. Also attached is a script for playing with this ODT documentation. Here are my conclusions from this brief foray: - Once we had a stylesheet, ODT would make it *much* easier to write documentation: everyone knows how to use a word processor. - However, the stylesheet itself is almost too easy to change. Any tools would depend on it for their API, so it needs to be stable. - OOo is not super-flexible when it comes to styles. I don't see that you can nest paragraph-level styles, e.g. - The way that OOo stores information is not the easiest to work with: e.g.: foo([foo]) rather than: foo([foo]) Bottom line: this is a hacked-up, watered-down, non-robust version of an XML solution. Too easy for authors, and too hard for tool-smiths. I'd say it might be an improvement over the status quo, but not enough of one to warrant switching. chad -------------- next part -------------- An embedded and charset-unspecified text was scrubbed... Name: Doc.py Url: http://mail.python.org/pipermail/doc-sig/attachments/20051230/d4295340/Doc-0001.asc -------------- next part -------------- A non-text attachment was scrubbed... Name: random.odt Type: application/vnd.oasis.opendocument.text Size: 17523 bytes Desc: not available Url : http://mail.python.org/pipermail/doc-sig/attachments/20051230/d4295340/random-0001.bin From mal at egenix.com Fri Dec 30 18:31:26 2005 From: mal at egenix.com (M.-A. Lemburg) Date: Fri, 30 Dec 2005 18:31:26 +0100 Subject: [Doc-SIG] [Python-Dev] that library reference, again In-Reply-To: References: <4335d2c40512291238l6b1d44b7vaf0963b631f3bd89@mail.gmail.com> <43B4A238.2030101@python.org> <51A7717B-3832-477E-BED5-3C36DCA20336@lag.net> Message-ID: <43B56EEE.9090904@egenix.com> 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 ! :::: From skip at pobox.com Fri Dec 30 18:50:51 2005 From: skip at pobox.com (skip@pobox.com) Date: Fri, 30 Dec 2005 11:50:51 -0600 Subject: [Doc-SIG] what about OpenDocument? In-Reply-To: <43B56D1D.9020405@zetaweb.com> References: <43B56D1D.9020405@zetaweb.com> Message-ID: <17333.29563.856535.264060@montanaro.dyndns.org> Chad> Attached is the documentation for the random module in ODT Chad> format... I've never heard of OpenDocument or ODT before. You mentioned "word processor". Is it somehow related to OpenOffice? Skip From chad at zetaweb.com Fri Dec 30 18:55:34 2005 From: chad at zetaweb.com (Chad Whitacre) Date: Fri, 30 Dec 2005 12:55:34 -0500 Subject: [Doc-SIG] what about OpenDocument? In-Reply-To: <17333.29563.856535.264060@montanaro.dyndns.org> References: <43B56D1D.9020405@zetaweb.com> <17333.29563.856535.264060@montanaro.dyndns.org> Message-ID: <43B57496.4090004@zetaweb.com> Skip, Yes, sorry. You'll see that I mention OpenOffice (OOo) in my first post, although I didn't define ODT explicitly. From Wikipedia: The OpenDocument format (ODF), short for the OASIS Open Document Format for Office Applications, is an open document file format for saving and exchanging editable office documents such as text documents (including memos, reports, and books), spreadsheets, charts, and presentations. This standard was developed by the OASIS industry consortium, based upon the XML-based file format originally created by OpenOffice.org. http://en.wikipedia.org/wiki/OpenDocument ODT stands for "OpenDocument Text." chad skip at pobox.com wrote: > Chad> Attached is the documentation for the random module in ODT > Chad> format... > > I've never heard of OpenDocument or ODT before. You mentioned "word > processor". Is it somehow related to OpenOffice? > > Skip > _______________________________________________ > Doc-SIG maillist - Doc-SIG at python.org > http://mail.python.org/mailman/listinfo/doc-sig > From ianb at colorstudy.com Fri Dec 30 20:48:25 2005 From: ianb at colorstudy.com (Ian Bicking) Date: Fri, 30 Dec 2005 13:48:25 -0600 Subject: [Doc-SIG] [Python-Dev] that library reference, again In-Reply-To: <43B55FE8.1040401@python.org> References: <4335d2c40512291238l6b1d44b7vaf0963b631f3bd89@mail.gmail.com> <43B4A238.2030101@python.org> <43B55FE8.1040401@python.org> Message-ID: <43B58F09.6090803@colorstudy.com> 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 / ianb at colorstudy.com / http://blog.ianbicking.org From scryingstone at hotmail.com Fri Dec 30 23:32:20 2005 From: scryingstone at hotmail.com (Bruce Thomson) Date: Sat, 31 Dec 2005 09:32:20 +1100 Subject: [Doc-SIG] unsurscribe Message-ID: Dear Sir/madam I have made a mistake and would like to unsurscribe. Would someone please send me the link in order to do this. Sincerely Bruce Thomson From flori at n-schlachter.de Fri Dec 30 23:53:08 2005 From: flori at n-schlachter.de (Florian Schlachter) Date: Fri, 30 Dec 2005 23:53:08 +0100 Subject: [Doc-SIG] unsurscribe In-Reply-To: References: Message-ID: <43B5BA54.5040702@n-schlachter.de> -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Bruce Thomson wrote: > Would someone please send me the link in order to do this. See the header of every mail: List-Id: Python Documentation Special Interest Group List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cheers, Florian - -- [Florian Schlachter [mailto:|http://]flori[@|a]n-schlachter.de] [0x14172268 2181 6150 EF7C 88B8 C8BD F760 C5AB A7EC 1417 2268] -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.2 (GNU/Linux) iD8DBQFDtbpUxaun7BQXImgRAjnaAJ4o38HwecKM+uw+IPQq6qnEfiiJgACdGaRt RmP8QNRXoLoZv+2psUlYY2k= =YMSe -----END PGP SIGNATURE----- From lac at strakt.com Sat Dec 31 02:37:27 2005 From: lac at strakt.com (Laura Creighton) Date: Sat, 31 Dec 2005 02:37:27 +0100 Subject: [Doc-SIG] what about OpenDocument? In-Reply-To: Message from Chad Whitacre of "Fri, 30 Dec 2005 12:55:34 EST." <43B57496.4090004@zetaweb.com> References: <43B56D1D.9020405@zetaweb.com> <17333.29563.856535.264060@montanaro.dyndns.org> <43B57496.4090004@zetaweb.com> Message-ID: <200512310137.jBV1bRXa030225@theraft.strakt.com> So it is a binary file format? If so, that will be a problem. Anything that produces output you cannot run through unix tools such as grep, and anything that you cannot edit in your favourite text editor will be a problem. Laura In a message of Fri, 30 Dec 2005 12:55:34 EST, Chad Whitacre writes: >Skip, > >Yes, sorry. You'll see that I mention OpenOffice (OOo) in my first post, > although I didn't define ODT explicitly. From Wikipedia: > > The OpenDocument format (ODF), short for the OASIS Open Document > Format for Office Applications, is an open document file format for > saving and exchanging editable office documents such as text documents > (including memos, reports, and books), spreadsheets, charts, and > presentations. This standard was developed by the OASIS industry > consortium, based upon the XML-based file format originally created by > OpenOffice.org. > > http://en.wikipedia.org/wiki/OpenDocument > >ODT stands for "OpenDocument Text." > > > >chad > > > > >skip at pobox.com wrote: >> Chad> Attached is the documentation for the random module in ODT >> Chad> format... >> >> I've never heard of OpenDocument or ODT before. You mentioned "word >> processor". Is it somehow related to OpenOffice? >> >> Skip >> _______________________________________________ >> Doc-SIG maillist - Doc-SIG at python.org >> http://mail.python.org/mailman/listinfo/doc-sig >> > >_______________________________________________ >Doc-SIG maillist - Doc-SIG at python.org >http://mail.python.org/mailman/listinfo/doc-sig From radeex at gmail.com Sat Dec 31 03:19:34 2005 From: radeex at gmail.com (Christopher Armstrong) Date: Sat, 31 Dec 2005 13:19:34 +1100 Subject: [Doc-SIG] what about OpenDocument? In-Reply-To: <200512310137.jBV1bRXa030225@theraft.strakt.com> References: <43B56D1D.9020405@zetaweb.com> <17333.29563.856535.264060@montanaro.dyndns.org> <43B57496.4090004@zetaweb.com> <200512310137.jBV1bRXa030225@theraft.strakt.com> Message-ID: <60ed19d40512301819o2e8efed5t3c71ae5db44e3377@mail.gmail.com> On 12/31/05, Laura Creighton wrote: > So it is a binary file format? If so, that will be a problem. Anything > that produces output you cannot run through unix tools such as grep, and > anything that you cannot edit in your favourite text editor will be a > problem. Well, all it is is a zip file that contains some XML files and some subdirectories. content.xml is fairly easy to extract from the zip, munge, and put back. -- Twisted | Christopher Armstrong: International Man of Twistery Radix | -- http://radix.twistedmatrix.com | Release Manager, Twisted Project \\\V/// | -- http://twistedmatrix.com |o O| | w----v----w-+ From radeex at gmail.com Sat Dec 31 03:29:34 2005 From: radeex at gmail.com (Christopher Armstrong) Date: Sat, 31 Dec 2005 13:29:34 +1100 Subject: [Doc-SIG] [Python-Dev] that library reference, again In-Reply-To: <51A7717B-3832-477E-BED5-3C36DCA20336@lag.net> References: <4335d2c40512291238l6b1d44b7vaf0963b631f3bd89@mail.gmail.com> <43B4A238.2030101@python.org> <51A7717B-3832-477E-BED5-3C36DCA20336@lag.net> Message-ID: <60ed19d40512301829q7a0df01bv3ed782fe28cbcf7a@mail.gmail.com> On 12/30/05, Robey Pointer 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| | w----v----w-+ From lac at strakt.com Sat Dec 31 03:42:36 2005 From: lac at strakt.com (Laura Creighton) Date: Sat, 31 Dec 2005 03:42:36 +0100 Subject: [Doc-SIG] what about OpenDocument? In-Reply-To: Message from Christopher Armstrong of "Sat, 31 Dec 2005 13:19:34 +1100." <60ed19d40512301819o2e8efed5t3c71ae5db44e3377@mail.gmail.com> References: <43B56D1D.9020405@zetaweb.com> <17333.29563.856535.264060@montanaro.dyndns.org> <43B57496.4090004@zetaweb.com> <200512310137.jBV1bRXa030225@theraft.strakt.com> <60ed19d40512301819o2e8efed5t3c71ae5db44e3377@mail.gmail.com> Message-ID: <200512310242.jBV2gaG4031929@theraft.strakt.com> Yes, this is precisely what many of us dislike. When we are working on a project, and somebody changes the docs, we want a nice readable svn checkin with the diffs, something that we can glance at any say 'yes that's correct' or 'oops, that's wrong'. When instead you get 'binary file, no diffs available' your documentation starts living in a world of its own, a world that you have to visit periodically and do work to keep up with. Laura In a message of Sat, 31 Dec 2005 13:19:34 +1100, Christopher Armstrong writes: >On 12/31/05, Laura Creighton wrote: >> So it is a binary file format? If so, that will be a problem. Anythin >g >> that produces output you cannot run through unix tools such as grep, an >d >> anything that you cannot edit in your favourite text editor will be a >> problem. > >Well, all it is is a zip file that contains some XML files and some >subdirectories. content.xml is fairly easy to extract from the zip, >munge, and put back. > >-- > Twisted | Christopher Armstrong: International Man of Twistery > Radix | -- http://radix.twistedmatrix.com > | Release Manager, Twisted Project > \\\V/// | -- http://twistedmatrix.com > |o O| | >w----v----w-+ From chad at zetaweb.com Sat Dec 31 05:36:07 2005 From: chad at zetaweb.com (Chad Whitacre) Date: Fri, 30 Dec 2005 23:36:07 -0500 Subject: [Doc-SIG] what about OpenDocument? In-Reply-To: <200512310242.jBV2gaG4031929@theraft.strakt.com> References: <43B56D1D.9020405@zetaweb.com> <17333.29563.856535.264060@montanaro.dyndns.org> <43B57496.4090004@zetaweb.com> <200512310137.jBV1bRXa030225@theraft.strakt.com> <60ed19d40512301819o2e8efed5t3c71ae5db44e3377@mail.gmail.com> <200512310242.jBV2gaG4031929@theraft.strakt.com> Message-ID: <43B60AB7.60108@zetaweb.com> Laura, Thanks for the feedback. You are correct that ODT is functionally a binary format from the point of view of the Unix toolset, and you'll notice that I mention "harder to diff/version?" as a con in my original post. The decision I am seeing out of this is between a manual markup language and an automated one. Examples of the former would be LaTeX, ReST, HTML+PythonDoc: in these formats the doc authors directly manipulate the documentation source. ODT would be an example of the latter, which require a specialized authoring environment. The problem with the former is that some folks don't like manually coding markup, and so we then look for a balance between light markup and adequacy to the task. The OpenOffice idea was a stab at solving the problem in a different way: by not manually coding markup at all. Besides the translucency of the format, my beef is that the markup it gives us is inadequate, both in terms of encoding information and accessing it. chad Laura Creighton wrote: > Yes, this is precisely what many of us dislike. When we are working > on a project, and somebody changes the docs, we want a nice readable > svn checkin with the diffs, something that we can glance at any say > 'yes that's correct' or 'oops, that's wrong'. When instead you get > 'binary file, no diffs available' your documentation starts living in > a world of its own, a world that you have to visit periodically and do > work to keep up with. > > Laura > > In a message of Sat, 31 Dec 2005 13:19:34 +1100, Christopher Armstrong writes: > >>On 12/31/05, Laura Creighton wrote: >> >>>So it is a binary file format? If so, that will be a problem. Anythin >> >>g >> >>>that produces output you cannot run through unix tools such as grep, an >> >>d >> >>>anything that you cannot edit in your favourite text editor will be a >>>problem. >> >>Well, all it is is a zip file that contains some XML files and some >>subdirectories. content.xml is fairly easy to extract from the zip, >>munge, and put back. >> >>-- >> Twisted | Christopher Armstrong: International Man of Twistery >> Radix | -- http://radix.twistedmatrix.com >> | Release Manager, Twisted Project >> \\\V/// | -- http://twistedmatrix.com >> |o O| | >>w----v----w-+ > > _______________________________________________ > Doc-SIG maillist - Doc-SIG at python.org > http://mail.python.org/mailman/listinfo/doc-sig > From chad at zetaweb.com Sat Dec 31 06:19:35 2005 From: chad at zetaweb.com (Chad Whitacre) Date: Sat, 31 Dec 2005 00:19:35 -0500 Subject: [Doc-SIG] proposal: a process for solving the Python Documentation Problem Message-ID: Dear All, Here is an attempt to outline a process by which we might clarify and solve the "Python Documentation Problem." The attempt here is to work from the outside in, starting with the end result we want to see, and working backwards from there to find the best solution. 0. Agree on a problem-solving process. :^) 1. Decide what documentation is in scope: Library Reference only? Language Reference as well? Everything? 2. Brainstorm the end-user formats we might possibly want to read documentation in: HTML, PDF, plain text, etc. 3. Prioritize formats. 4. Crop the list to three or fewer primary target formats. 5. Define the information that needs to be encoded to support the given formats. 6. Identify the storage format that best balances ease of migration, maintenance, and authoring with adequacy to the task of encoding and making accessible the necessary information. 7. Build, borrow, or buy the tools to migrate, maintain, author, access, and transform the information. 8. Migrate, maintain, author, access, and transform the information. chad From ncoghlan at gmail.com Sat Dec 31 06:41:50 2005 From: ncoghlan at gmail.com (Nick Coghlan) Date: Sat, 31 Dec 2005 15:41:50 +1000 Subject: [Doc-SIG] [Python-Dev] that library reference, again In-Reply-To: <43B58F09.6090803@colorstudy.com> References: <4335d2c40512291238l6b1d44b7vaf0963b631f3bd89@mail.gmail.com> <43B4A238.2030101@python.org> <43B55FE8.1040401@python.org> <43B58F09.6090803@colorstudy.com> Message-ID: <43B61A1E.9080300@gmail.com> 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 | ncoghlan at gmail.com | Brisbane, Australia --------------------------------------------------------------- http://www.boredomandlaziness.org From bronger at physik.rwth-aachen.de Sat Dec 31 09:42:31 2005 From: bronger at physik.rwth-aachen.de (Torsten Bronger) Date: Sat, 31 Dec 2005 09:42:31 +0100 Subject: [Doc-SIG] what about OpenDocument? References: <43B56D1D.9020405@zetaweb.com> <17333.29563.856535.264060@montanaro.dyndns.org> <43B57496.4090004@zetaweb.com> <200512310137.jBV1bRXa030225@theraft.strakt.com> <60ed19d40512301819o2e8efed5t3c71ae5db44e3377@mail.gmail.com> <200512310242.jBV2gaG4031929@theraft.strakt.com> <43B60AB7.60108@zetaweb.com> Message-ID: <877j9l64js.fsf@wilson.rwth-aachen.de> Hall?chen! Not that I think ODT is a viable alternative but ... Chad Whitacre writes: > [...] The OpenOffice idea was a stab at solving the problem in a > different way: by not manually coding markup at all. Besides the > translucency of the format, Can't the main XML file be checked-in parallelly? Can OOo calculate a diff between two arbitrary versions? > my beef is that the markup it gives us is inadequate, both in > terms of encoding information and accessing it. Well, OOo separates visual and structural markup very thoroughly, so I don't understand the issue here. Tsch?, Torsten. -- Torsten Bronger, aquisgrana, europa vetus ICQ 264-296-646 From lac at strakt.com Sat Dec 31 18:09:52 2005 From: lac at strakt.com (Laura Creighton) Date: Sat, 31 Dec 2005 18:09:52 +0100 Subject: [Doc-SIG] proposal: a process for solving the Python Documentation Problem In-Reply-To: Message from Chad Whitacre of "Sat, 31 Dec 2005 00:19:35 EST." References: Message-ID: <200512311709.jBVH9q5j025230@theraft.strakt.com> In a message of Sat, 31 Dec 2005 00:19:35 EST, Chad Whitacre writes: >Dear All, > >Here is an attempt to outline a process by which we might clarify and >solve the "Python Documentation Problem." The attempt here is to work >from the outside in, starting with the end result we want to see, and >working backwards from there to find the best solution. > > >0. Agree on a problem-solving process. :^) This is a great step 0. Alas, I think things will all fall apart here. My problem with your solution is that it is a technical solution to a technical problem. I think our problem is a social problem and needs a social solution. >1. Decide what documentation is in scope: Library Reference only? > Language Reference as well? Everything? Everything, especially since people will want to use it for their own documentation purposes. >2. Brainstorm the end-user formats we might possibly want to read > documentation in: HTML, PDF, plain text, etc. I don't think this is priority at all. People who already like one format or another already write tools to convert one to another. And here we cut to a deep philosophical difference. When you look at documents, it matters a great deal whether you think that the control of how it should be presented should lie with the _readers_ or with the _writers_. Commercial pressure has forced a current outcome where the _writers_ more or less get to say what the readers get to read. This leads to the situation where the _logical information about the stucture of the document_ is mixed up in some sort of stew with the _rendering information about how to print it on your rendering device_. And some people think this is all well and good because the rendering information is important information that belongs with the document. Other people, including myself, think that this is pure evil because the rendering information should exist with the readers, not with the writers. (Of course they should be free to send out their suggested format). So depending on where you sit on this philosophical devide, you will soon end up wanting either: A _really low level markup language_ which allows you lots and lots of control over how to render stuff, or A _really high level document parser_ which can take any plain text file, one that has no markup at all, and can conclude what its structure is, leaving you free to render that however you like. So people go off and do this and they end up in different sorts of messes. The low level language people end up with text that can only be read or understood _rendered_. Often it is hard to search. And you often destroy the logical structure that people use when thinking about documents. You cannot search for the third paragraph, but only the fifth line break, which becomes the fourteenth when paragraph two gets a list inserted. Eventually you need some sort of authoring tool to create text, because you just cannot read the markup-gloop any more. The document parser people find that there are some times when plain text is not enough, and you really need to include some markup somewhere. If they stick it in the document, they have started down the road where they make their input text easier to parse. You can end up with markup-gloop this way too, even if it is only structural markup you are inserting. If you stick it in a companion document, then the two get out of sync, and somebody always loses one. >3. Prioritize formats. > >4. Crop the list to three or fewer primary target formats. > >5. Define the information that needs to be encoded to support the given > formats. > >6. Identify the storage format that best balances ease of migration, > maintenance, and authoring with adequacy to the task of encoding and > making accessible the necessary information. I don't think we are ever going to agree on this one. >7. Build, borrow, or buy the tools to migrate, maintain, author, access, > and transform the information. > >8. Migrate, maintain, author, access, and transform the information. > > >chad And here we are already at disagreements because I think you are solving a different problem than the one that is causing our problem. I think that Fredrik Lundh just did this as well, so you are in good company. Now I need to go out and see the fireworks. Then it is time to cook the already-prepared New Years Dinner. Which means I will be too drunk later to consider writing my steps of solution to our documentation problem, which I perceive differently. We will have the same step 0 ... and none of the rest. But thank you for writing, and Gott Nytt ?r to all of you. Laura From lac at strakt.com Sat Dec 31 18:12:52 2005 From: lac at strakt.com (Laura Creighton) Date: Sat, 31 Dec 2005 18:12:52 +0100 Subject: [Doc-SIG] [Python-Dev] that library reference, again In-Reply-To: Message from Nick Coghlan of "Sat, 31 Dec 2005 15:41:50 +1000." <43B61A1E.9080300@gmail.com> References: <4335d2c40512291238l6b1d44b7vaf0963b631f3bd89@mail.gmail.com> <43B4A238.2030101@python.org> <43B55FE8.1040401@python.org> <43B58F09.6090803@colorstudy.com> <43B61A1E.9080300@gmail.com> Message-ID: <200512311712.jBVHCqPD025298@theraft.strakt.com> In a message of Sat, 31 Dec 2005 15:41:50 +1000, Nick Coghlan writes: >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&componen >t=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 bu >g >tracking for the main source code is eventually migrated off SF? And what > >would happen to existing documentation bug reports/patches on the SF trac >kers? > >Is it possible to do something similar for the online version of the curr >ent >docs, simply pointing them at the SF tracker? (I know this doesn't help p >eople >without an SF account. . .) > >Cheers, >Nick. Not if the problem is that documentation changes are not 'patches' and 'bugs' and the sourceforge bug tracker, which isn't even particularly good at tracking bugs is particularly ill-suited for the collaborative sharing of documents. Laura From chad at zetaweb.com Sat Dec 31 22:51:20 2005 From: chad at zetaweb.com (Chad Whitacre) Date: Sat, 31 Dec 2005 16:51:20 -0500 Subject: [Doc-SIG] what about OpenDocument? In-Reply-To: <877j9l64js.fsf@wilson.rwth-aachen.de> References: <43B56D1D.9020405@zetaweb.com> <17333.29563.856535.264060@montanaro.dyndns.org> <43B57496.4090004@zetaweb.com> <200512310137.jBV1bRXa030225@theraft.strakt.com> <60ed19d40512301819o2e8efed5t3c71ae5db44e3377@mail.gmail.com> <200512310242.jBV2gaG4031929@theraft.strakt.com> <43B60AB7.60108@zetaweb.com> <877j9l64js.fsf@wilson.rwth-aachen.de> Message-ID: <43B6FD58.2000000@zetaweb.com> Torsten, Thanks for jumping in. > Can't the main XML file be checked-in parallelly? Theoretically, yes. But that's an ugly hack, IMO, and we already have one of those. :^) > Can OOo calculate a diff between two arbitrary versions? I'm not sure what OOo's versioning capabilities are, although I suspect that versioning info would be stored in a separate part of the ODT and not in the "main XML file" (which I take to refer to content.xml). >>my beef is that the markup it gives us is inadequate, both in >>terms of encoding information and accessing it. > > Well, OOo separates visual and structural markup very thoroughly, so > I don't understand the issue here. Sure, but my idea was to overload OOo's standard markup to encode Python-documentation-specific information, like function definitions and parameter lists. But when you use an OOo stylesheet to define what amounts to a custom markup language, then the only hook you get within their actual markup is a single attribute -- text:style-name -- on only about four different tags -- text:p, text:span, etc. Again, just another ugly hack. chad From ianb at colorstudy.com Sat Dec 31 23:05:22 2005 From: ianb at colorstudy.com (Ian Bicking) Date: Sat, 31 Dec 2005 16:05:22 -0600 Subject: [Doc-SIG] [Python-Dev] that library reference, again In-Reply-To: <43B61A1E.9080300@gmail.com> References: <4335d2c40512291238l6b1d44b7vaf0963b631f3bd89@mail.gmail.com> <43B4A238.2030101@python.org> <43B55FE8.1040401@python.org> <43B58F09.6090803@colorstudy.com> <43B61A1E.9080300@gmail.com> Message-ID: <43B700A2.70701@colorstudy.com> Nick Coghlan 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? I think the requirements for documentation are a bit lighter, so it's not as big a deal. E.g., the history of bug reports on documentation isn't as important, either the ones from SF, or if all of Python moves to a new system then the history of the transitional system. Documentation is mostly self-describing. > 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. . .) Perhaps; I haven't played with the SF interface at all, so I don't know if you can prefill fields. But it's still a pain, since logging into SF isn't seemless (since you don't get redirected back to where you started from). Also, I don't know if the requirements for documentation match the code generally. Being able to follow up on documentation bugs isn't as important, so if you don't always collect the submitters email address it's not that big a deal. Doc maintainers may be willing to filter through a bit more spam if it means that they get more submissions, and so forth. The review process probably isn't as important. So I think it could be argued that code and documentation shouldn't even be on the same tracker. (I'm not really arguing that, but at least it doesn't seem like a big a deal if they aren't on the same system) -- Ian Bicking | ianb at colorstudy.com | http://blog.ianbicking.org