From chad at zetaweb.com Sun Jan 1 04:13:02 2006 From: chad at zetaweb.com (Chad Whitacre) Date: Sat, 31 Dec 2005 22:13:02 -0500 Subject: [Doc-SIG] proposal: a process for solving the Python Documentation Problem In-Reply-To: <200512311709.jBVH9q5j025230@theraft.strakt.com> References: <200512311709.jBVH9q5j025230@theraft.strakt.com> Message-ID: <43B748BE.8000902@zetaweb.com> Laura, Thanks for giving me an opportunity to clarify my proposal. I more or less agree with you that mixing "logical" and "rendering" information is "pure evil." However, the real world use case for this documentation is that it end up in several rendered formats. My suggestion is that explicitly identifying the most important rendered formats will help flush out the true requirements for the base (i.e., "logical" or semantic) format. On the other hand, I confess that I don't follow your suggestion that separation of "logical" and "rendered" information leads to a plain text base format, one without any markup. Why exclude markup that is semantic rather than presentational? Also, you hint that it might be helpful to define the problem itself more clearly, and I agree. The problem I want to see solved is Fredrik's: how do we cut the documentation workflow cycle down from 3-6 months to, say, 3-6 days? chad From chad at zetaweb.com Sun Jan 1 05:28:15 2006 From: chad at zetaweb.com (Chad Whitacre) Date: Sat, 31 Dec 2005 23:28:15 -0500 Subject: [Doc-SIG] much smaller idea Message-ID: Hey all, I've started experimenting with a full-on XML documentation solution, i.e., a Python documentation DTD, etc., and have started to feel the weight of what that would take to implement. By contrast, LaTeX doesn't seem so bad. As has been mentioned, the markup itself is fairly light. So then I had this idea for a potentially easy way to speed up the workflow a bit: What about adding a comment form to the bottom of every page on docs.python.org that posts directly to the SF bug tracker? I envision an SF login specifically for this system. Hidden fields on the form could record what page the comment refers to, etc. It seems like this could be an easy way to streamline workflow for small documentation bugs, at least. chad From lac at strakt.com Tue Jan 3 02:17:13 2006 From: lac at strakt.com (Laura Creighton) Date: Tue, 03 Jan 2006 02:17:13 +0100 Subject: [Doc-SIG] Improving the documenting process. Message-ID: <200601030117.k031HDu8022385@ratthing-b246.strakt.com> Chad suggested I post this reply to him back to doc-sig, and see if there are others like me who think that the python documentation problem centres around 'not enough good documentation being produced' and a process that is opaque, has bottlenecks, and excludes the very people who would be best at writing good documentation, because they aren't python-language developers. I thought to shorten it, and then thought, what the heck, maybe some other people would be interested in what I was doing in the 80s. Sorry that this will bore some others. Happy New Year, Laura ------- Forwarded Message Laura Creighton wrote: > In a message of Sat, 31 Dec 2005 22:13:02 EST, Chad Whitacre writes: > >>Laura, >> >>Thanks for giving me an opportunity to clarify my proposal. > > >>On the other hand, I confess that I don't follow your suggestion that >>separation of "logical" and "rendered" information leads to a plain text >>base format, one without any markup. Why exclude markup that is semantic >>rather than presentational? > > > Oh yes. This may not be well-known. I keep forgetting. > > Because authoring is an art. What you need are tools that support > the process of composing excellent prose. All of the structural > markup greatly hinders the process. In exactly the same way that > all the curly-braces-and-semi-colon junk in languages we know and > hate, all there for the benefit of the compiler, detract from writing > well. The more intrusive the markup, the worse the prose. (Which > has been measured in places like the lab I worked in in the 80s.) > > There is still hot debate in some circles as to exactly why this is > so, but the prevailing theory is that good prose is dependant on using > the part of your brain that listens. So most people really have to > 'hear the words in their heads' as they write in order to create the > best prose. (And some do not. Why this is so is unknown.) But when > they start fiddling around with the presentation details at the same > time as they are writing the text in first place, their attention is > divided and the texts are significantly worse. > > So, when we stuck people into our labs and measured them, our standard > for 'how people write' was 'using emacs or vi and the MS macro > packages for troff'. And it was clear that people were producing > pretty rotten texts. So we measured how well they wrote if they > just used vi or emacs, and skipped the markup. And for most people > this produced a significant improvement. At this point, believing I > was onto something, I went out and founded a computer company, SoftQuad, > with a bunch of friends of mine in the publishing business. Device > Independent Troff was new, laser printers were new, bitmapped displays > were new, and Apple was promising this thing called the Macintosh. We > thought that we had the killer app. A WYSIWYG editor, though I don't > think we called it that. Without evidence, we were convinced that we > knew why it was that people wrote poorer text when using troff, and > that had to do with it being hard to use the macro packages. > > And this goes to show that 'it ain't the stuff you don't know but > the stuff you know that ain't so' that really hurts you. Because this > was one of the more spectacular cases of 'completely getting it wrong'. > We made an editor (actually two -- a moded one which we gave the vi > bindings and a modeless one which we gave the emacs bindings) and then > took our usual suspects of university students in the humanities who > already knew vi or emacs and had them go at it. > > They were very happy to not have to learn the MS macro set. But to our > dismay, the prose still ended up rotten. We'd solved the wrong problem. > And the very best results were still being had by authors that used > whatever text editor they liked best to compose text, and then handed > the work to somebody else -- a compositor if they were dealing with > our Dead-Tree-Printing Office, or the secretaries of the Political > Economics department if you were a student or a professor there. > Making the thing look good on paper -- or on the screen, was then > somebody else's job. But even if you composed the text first, and > then made a second pass after you got the text down correct you would > end up with a better result than if you composed and composited > simultaneously. Next we discovered that most people wrote better > if they wrote with somebody else. (For non-fiction. For fiction we > couldn't come to any conclusions except that we needed to study the > cognitive process of writing fiction more.) On the other hand, documents > designed by committee almost never were well written unless the > committee met, decided on the structure of the document and what > its content was to be, and then let one or two people actually write > the thing. > > >>Also, you hint that it might be helpful to define the problem itself >>more clearly, and I agree. The problem I want to see solved is >>Fredrik's: how do we cut the documentation workflow cycle down from 3-6 >>months to, say, 3-6 days? > > > This is a fine goal. But I think our problem is that we do not have > enough high-quality documentation, and that the people who find problems > with the documentation do not have an easy way to discuss this with > other people who are interested. Submitting a bug report only means > that people who are reading the bug tracker get to be informed. This > excludes the bulk of interested people. > > If you haven't read the Kruger Dunning Report _Unskilled and Unaware of It_ > http://www.apa.org/journals/features/psp7761121.pdf I suggest you go read > it now. It applies with particular vengeance to authoring skills, most > especially in people who are writing in their native language. Ability > in language usage it not particularly bell-curved. Both ends have > relatively large numbers when compared to the population at large. > Excellent writing ability is something that people have selected for > to such an extent that the right end is greatly increased, while > non-native speakers, and people with learning disabilities end up making > the left end chunkier as well. > > Which sadly means that the it is not just the lowest octile of language > users who lack the cognative abilities to judge their performance. In > our labs we found it remarkably easy to produce samples of people where > 80% of the people in the room did not write very well, according to the > judgement of the top 2%, but nearly all of that 80% believed that they > wrote 'rather well'. > > This makes the whole process of criticise-and-rewrite even harder than > it already is, which is hard enough in the first place, and makes a > bug tracker a particularly difficult place to raise your issues. There > is no particular good way to say 'could I have a different python > developer to discuss this with? This one is not skilled enough to > understand me'. The more confused you are, and the harder time you > have expressing and understanding your confusion, the worse it becomes. > (It is hard on the unskilled python developer, as well. He really has > no way to tell the difference between things he cannot understand because > he lacks the skills, and things he cannot understand because the person > who posted the idea lacks the skills, and plain old bad ideas.) > > One of the more frustrating things that I have seen happen again and again > is where some new person, who doesn't understand how to do something, > complains about the documentation. All too often the response that this > person gets centres around 'explaining to the newbie how the code > really works and how the newbie should have solved his problem'. This > drives the newbie, who already has solved his problem up the wall. > He doesn't want help in learning things, he wants different and > better documentation. > > He may even have a fix. But the fix is often going to be poor. It > may solve this problem, but it leaves things more confusing for others > in some way. This does not mean that the existing documentation is > adequate. It means that somebody who is both aware of the code > involved, and who is aware of the newbies problems in comprehension, > needs to rewrite the documentation. > > Now it may be that such people are rare in general. I think they are > rarer among computer progammers than in the population at large. But > I think that our structure exacerbates our problem. If you re-read > http://mail.python.org/pipermail/doc-sig/2005-December/003466.html > you will see Fred Drake assert that: > > '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' > > which is either trivially true, or the indication of a larger problem. > This looks to me as if documentation releases are delayed until every > (a large number? enough?) comments are handled, which strikes me > as a very large bottleneck. Wikipedia is proving that you can do > continuous updates on documentation. Do we need them? Would we > get more people working on improving the documents if the live > version was a mediawiki? > > I think the question of 'what do we need in order to share and > collaboratively work on documents more effectively' is the one that > we need to solve if we want more rapid turnover. So I would say > that our workflow doesn't need _shortening_ so much as _transforming > altogether_. And I don't think I understand exactly all the steps > we have now, so it would be nice if somebody who knows this very well > would post them. Then we could analyse them, and see why it is that > we perform the way we do. > > Laura ------- End of Forwarded Message From janssen at parc.xerox.com Tue Jan 3 03:12:34 2006 From: janssen at parc.xerox.com (Bill Janssen) Date: Mon, 2 Jan 2006 18:12:34 PST Subject: [Doc-SIG] proposal: a process for solving the Python Documentation Problem In-Reply-To: Your message of "Sat, 31 Dec 2005 09:09:52 PST." <200512311709.jBVH9q5j025230@theraft.strakt.com> Message-ID: <06Jan2.181241pst."58633"@synergy1.parc.xerox.com> > 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. Some of the original document formats developed at PARC in the 70's for use on the Alto and Dorado computers used plain text plus markup. There was a plain-text body, followed by a zero octet (or perhaps two, I don't remember), followed by a binary section that included the markup. Most text processors of the time would simply trim off the binary section when presenting the document, so what you saw in a text editor was just the plain text. WYSIWYG document editors, however, would also read the markup and interpret it appropriately for editing purposes. The two didn't get out-of-sync because they were in the same file. Bill From ncoghlan at gmail.com Tue Jan 3 05:00:35 2006 From: ncoghlan at gmail.com (Nick Coghlan) Date: Tue, 03 Jan 2006 14:00:35 +1000 Subject: [Doc-SIG] Improving the documenting process. In-Reply-To: <200601030117.k031HDu8022385@ratthing-b246.strakt.com> References: <200601030117.k031HDu8022385@ratthing-b246.strakt.com> Message-ID: <43B9F6E3.7010303@gmail.com> Laura Creighton wrote: >> I think the question of 'what do we need in order to share and >> collaboratively work on documents more effectively' is the one that >> we need to solve if we want more rapid turnover. So I would say >> that our workflow doesn't need _shortening_ so much as _transforming >> altogether_. Something which hasn't come up so far is the difference in the nature of coupling between code and documentation. When code is broken, the right place and right way to fix it is usually (not always) fairly obvious. When it isn't obvious, that's one of the things python-dev is for: discussing where and how the problem should be addressed. For documentation, the free-form nature of the prose means that there are *many* right ways, meaning discussion is necessary much more often. The current setup is *not* geared towards facilitating that discussion and bringing it to a close (indeed, I believe it makes it difficult to get the discussion going in the first place). >> And I don't think I understand exactly all the steps >> we have now, so it would be nice if somebody who knows this very well >> would post them. Then we could analyse them, and see why it is that >> we perform the way we do. Even with the updates Trent and Neal have made to automate the documentation update and posting process, it's still fairly disjointed. a. Someone tries to figure out why some code of theirs isn't working by looking at the documentation. We'll assume they eventually find the answer, but they think a simple tweak to the "most obvious place" would have made their search much simpler [1]. b. The online doc page they're looking at contains no obvious link regarding where to send comments on that page. There is only a little "about this document" link squirreled away in the footnotes. c. We'll assume our potential contributor has found that little note, and has gone to the about page [2]. d. General questions/comments are directed towards the email address "docs at python.org". I'm not sure *who* ends up getting those, but I'm a little surprised it doesn't simply redirect to "doc-sig at python.org". (I could be wrong here - it may actually do this already, or else it may go to the doc-sig moderators for approval before being sent on to the wider list). e. If our submitter has an SF account, they may go to SF and log a bug report (and possibly even attach some suggested text). Again, however, discussion is *not* facilitated - the SF bug tracker UI bites, even for discussing code changes, let alone changes to documentation prose. Other things that are missing in terms of facilitating dicussion: - documentation pages don't have associated comments, making it difficult for users to see what observations have already been made regarding particular pages, and making it harder to review comments in light of the original text (there's a significant disjoint between the email of SF tracker comment and the original documentation text - source code at least has the luxury of filenames and line numbers as an indexing system). - domain experts can't subscribe just to areas of particular interest to them, in order to be automatically notified when changes are made or comments are added to those specific areas I think Laura is right in saying that the semantic and layout markup is a side issue - those are really there to aid the toolchain, more so than to aid the end user. Wiki's (particularly full-featured ones like MediaWiki or Atlassian's Confluence, which permit comments that are separate from the main text of the wiki page) are designed not only to allow collaborative production of content, but also to facilitate discussion about and review of that content. And it's that latter part we currently seem to be struggling with. Cheers, Nick. [1] Step a. isn't helped by the surfeit of documentation URL's at python.org: docs.python.org (last stable release) www.python.org/doc () docs.python.org/dev (new automatically built docs) www.python.org/dev/doc/devel (manually updated development version) www.python.org/dev/doc/maint24 (manually updated 2.4 maintenance version) Also, only www.python.org/doc seems to provide access to old versions. The obvious "docs.python.org/2.4.2" doesn't work, but "www.python.org/doc/2.4.2" does. Lastly, the index page from the actual documentation set (which I find quite pleasant and easy to read) is done away with for the stable versions of the documentation, replacing it with a python.org page that uses a simple list, rather than the clean tabular layout of the actual index page. [2] http://docs.python.org/dev/lib/about.html -- Nick Coghlan | ncoghlan at gmail.com | Brisbane, Australia --------------------------------------------------------------- http://www.boredomandlaziness.org From jerdonek at gmail.com Tue Jan 3 05:03:19 2006 From: jerdonek at gmail.com (Chris Jerdonek) Date: Mon, 2 Jan 2006 20:03:19 -0800 Subject: [Doc-SIG] Improving the documenting process. In-Reply-To: <200601030117.k031HDu8022385@ratthing-b246.strakt.com> References: <200601030117.k031HDu8022385@ratthing-b246.strakt.com> Message-ID: <938f120ea09b731b17e76dc2914c2d88@gmail.com> On Jan 2, 2006, at 5:17 PM, Laura Creighton wrote: > Chad suggested I post this reply to him back to doc-sig, and see > if there are others like me who think that the python documentation > problem centres around 'not enough good documentation being > produced' and a process that is opaque, has bottlenecks, and > excludes the very people who would be best at writing good > documentation, because they aren't python-language developers. I really appreciate reading the thoughts Laura has expressed over the last couple e-mails. I've only been on this list for about a week. I'm in the camp of not being a python-language developer, but I can't say yet whether this qualifies me as being good at writing documentation... Some thoughts below. >> Next we discovered that most people wrote better >> if they wrote with somebody else. (For non-fiction. For fiction we >> couldn't come to any conclusions except that we needed to study the >> cognitive process of writing fiction more.) On the other hand, >> documents >> designed by committee almost never were well written unless the >> committee met, decided on the structure of the document and what >> its content was to be, and then let one or two people actually write >> the thing. >> ... >> Wikipedia is proving that you can do >> continuous updates on documentation. Do we need them? Would we >> get more people working on improving the documents if the live >> version was a mediawiki? The contrast here is interesting. Do these observations conflict in any way? Do wikis have more or less in common with "writing by committee"? I wonder how wiki documentation compares to the best individually-written Python documentation -- if the style gets watered-down in the community process at all, and whether this dissuades any writers. >> I think the question of 'what do we need in order to share and >> collaboratively work on documents more effectively' is the one that >> we need to solve if we want more rapid turnover. Backing up here, how does the documentation group judge success, or what is its purpose? Is it about creating an authoritative manuscript, or facilitating learning by more people? Also, there's one thing I'm still confused about. Where do people fit in who are interested in creating documentation for a specialized Python module that's not part of Python's core? Ideally, would the documentation group supply and empower that person with the tools needed to write and disseminate documentation on their own, or would they become de facto members of the Python documentation group, contributing to the official body of Python documentation (albeit to a small corner of it)? --Chris From ianb at colorstudy.com Tue Jan 3 08:08:26 2006 From: ianb at colorstudy.com (Ian Bicking) Date: Tue, 03 Jan 2006 01:08:26 -0600 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: <43BA22EA.5010603@colorstudy.com> I've put an instance of Commentary up against the full 2.4 documentation: http://pythonpaste.org/comment/python24/ It writes to a Subversion repository so you can see what the backend data looks like: http://pythonpaste.org/comment/svn/python24/ -- not much there yet. Obviously things like notification and reports would be useful, but I don't know what the state of the art for Subversion is either, so potentially these tools already exist. But last I really looked at the tools for Subversion, I wasn't overly impressed. Things like self-signup for pages you were interested in would be useful. But anyway, there's nothing too difficult about those features. Anyway, it's just meant as a demo for now, but give it a look, and if you have problems or suggestions write a ticket: http://pythonpaste.org/commentary/trac/newticket Cheers. -- Ian Bicking | ianb at colorstudy.com | http://blog.ianbicking.org From priest at sfu.ca Tue Jan 3 09:57:33 2006 From: priest at sfu.ca (David Priest) Date: Tue, 3 Jan 2006 00:57:33 -0800 Subject: [Doc-SIG] Improving the documenting process. In-Reply-To: <938f120ea09b731b17e76dc2914c2d88@gmail.com> References: <200601030117.k031HDu8022385@ratthing-b246.strakt.com> <938f120ea09b731b17e76dc2914c2d88@gmail.com> Message-ID: On 2-Jan-06, at 8:03 PM, Chris Jerdonek wrote, in part: > I wonder how wiki documentation compares to the best > individually-written Python documentation -- if the style gets > watered-down in the community process at all, and whether this > dissuades any writers. Using the wiki for documentation will only work well if there is a structure for allowing a select group of editorial assistants to control the "Real Documentation" (as opposed to the marginalia/ discussion/questions/suggestions/etc part that would be somehow closely related to the "Real" -- perhaps via a Talk page, a la Wikipedia; perhaps via some Plone-like construct.) In other words, we need a way that presents the official, well- written, well-presented material *separate* from the public noise; and we need editors who will actively take the good stuff from that noise and use it in improving the official text. From mike at pcblokes.com Tue Jan 3 15:17:10 2006 From: mike at pcblokes.com (Michael Foord) Date: Tue, 03 Jan 2006 14:17:10 +0000 Subject: [Doc-SIG] Improving the documenting process. In-Reply-To: References: <200601030117.k031HDu8022385@ratthing-b246.strakt.com> <938f120ea09b731b17e76dc2914c2d88@gmail.com> Message-ID: <43BA8766.8050407@pcblokes.com> David Priest wrote: > On 2-Jan-06, at 8:03 PM, Chris Jerdonek wrote, in part: > >>I wonder how wiki documentation compares to the best >>individually-written Python documentation -- if the style gets >>watered-down in the community process at all, and whether this >>dissuades any writers. > > > Using the wiki for documentation will only work well if there is a > structure for allowing a select group of editorial assistants to > control the "Real Documentation" (as opposed to the marginalia/ > discussion/questions/suggestions/etc part that would be somehow > closely related to the "Real" -- perhaps via a Talk page, a la > Wikipedia; perhaps via some Plone-like construct.) > > In other words, we need a way that presents the official, well- > written, well-presented material *separate* from the public noise; > and we need editors who will actively take the good stuff from that > noise and use it in improving the official text. I've been resisting replying to this thread, because I don't want to just add more noise. However I think we *can* sort the workflow, and that is a different question to what markup format is used. I think that in order to improve documentation, encourage more contribution, and get that contribution into the final docs we need : 1) An online system for contributing changes in *any markup* [#]_ 2) Editors who take responsibility for specific areas of the documentation 3) Assistance for editors who need help turning user comments into LayTeX I'm not just adding noise here - I'm happy to help by taking on responsibility for *some documentation* and evaluating user additions. This means that (1) *ought* to email the person responsible when a new comment is made. It *ought* to include a system for marking comments as accepted or rejected. Possibly allowing the administrator for a section of documentation to delete rejected comments will be enough. It also needs a login system (simple) to reduce spam. For the sake of simplicity I would suggest that when a new version is released old comments are *not* automatically migrated. Either they fall by the wayside and can be re-submitted, or the documentation maintainer can add them. An admin interface to allow migrating of comments from old docs to new docs would be nice - but may or may not ever happen... To facilitate (2) *someone* needs to break the documentation down into areas and we need to sign up editors. They don't need to be the same person who maintains the code. But they need to be approved by the BDFL of the documentation (Fred L. Drake ?). 3) Can be done via this forum. I hope this is helpful. I'm sure we can use Ian Bickings commentary system as it stands - though with the changes I've suggested above. (Some of which he's working on anyway). I'm happy to help, although I don't yet know LaTeX I do have writing skills that I'd love to contribute. This leaves markup as a separate question - but provides a good way of getting user input to the docs. It's not really anything new, but let's get it happening. All the best, Fuzzyman http://www.voidspace.org.uk/python/index.shtml .. [#] Actually we probably ought to restrict it to plain text, reST or LayTeX. > _______________________________________________ > Doc-SIG maillist - Doc-SIG at python.org > http://mail.python.org/mailman/listinfo/doc-sig > > > From jerdonek at gmail.com Tue Jan 3 23:45:38 2006 From: jerdonek at gmail.com (Chris Jerdonek) Date: Tue, 3 Jan 2006 14:45:38 -0800 Subject: [Doc-SIG] Improving the documenting process. In-Reply-To: <43B9F6E3.7010303@gmail.com> References: <200601030117.k031HDu8022385@ratthing-b246.strakt.com> <43B9F6E3.7010303@gmail.com> Message-ID: On Jan 2, 2006, at 8:00 PM, Nick Coghlan wrote: > d. General questions/comments are directed towards the email address > "docs at python.org". I'm not sure *who* ends up getting those, but I'm a > little > surprised it doesn't simply redirect to "doc-sig at python.org". (I could > be > wrong here - it may actually do this already, or else it may go to the > doc-sig > moderators for approval before being sent on to the wider list). I sent a question about *creating documentation* to docs at python.org on November 30, and got the below automatic message back. I didn't get a human response (Fred) until December 20 (though in fairness I didn't send an additional e-mail after a week like the message says to). I still don't know the answer. --Chris This message is being sent in response to your message to the Python documentation maintainers (docs at python.org). Your message will be handled by a human, but this message serves to answer the most common questions sent to this address. You will only receive this message if it has not been sent to you for at least three months. If your question is answered below, you may not receive an additional message from the documentation maintainers. If you feel the answers below are not sufficient and you do not receive an additional response within a week, please do send a note letting us know that your question has not been properly answered, and be specific regarding what additional information you are looking for. -Fred Frequently Asked Questions about the Python Documentation --------------------------------------------------------- 1. Can I download HTML/PDF/PostScript versions of the docs? 2. Where can I download Python? 3. I can't unpack a downloaded copy on Windows; what should I do? 4. I can't unpack a downloaded copy on Mac OS; what should I do? 5. What can I use Python for? 6. How do I use module/function/whatever XXX? 7. What about JPython? 8. I found a bug in the documentation, who should I tell? 9. Can I get an algorithm to do THIS in language THAT? 10. How do I decode an XXX file from my email on a YYY computer? 11. Acrobat Reader won't print the PDF. What's wrong? 12. Where can I find documentation in my native language? 13. Why is Python installed on my computer? Answers to the Questions ------------------------ 1. Can I download HTML/PDF/PostScript/ versions of the docs? Yes. These are available via the Web and traditional FTP. For Web access to the latest version, see: http://www.python.org/doc/ For FTP access to the latest version and archives of previous versions, see: ftp.python.org:/pub/python/doc/ 2. Where can I download Python? You can get Python in source form and as a Windows installer from the main Python website. You can also find information about pre-built packages for other platforms there as well. Downloading information at the website is at the URL: http://www.python.org/download/ The sources and Windows installer can be downloaded from the FTP site as well: ftp://ftp.python.org/pub/python/ 3. I can't unpack a downloaded archive on Windows; what should I do? Make sure the archive was saved with the .tgz extension; you may need to watch carefully when telling the browser where to save the file, as the default may change the extension to .tar or even .exe. Once you're sure the file has the right extension, use a recent version of WinZip to upack the file (version 7.0 works). Get WinZip from: http://www.winzip.com/ 4. I can't unpack a downloaded archive on Mac OS; what should I do? Stuffit Expander 4.5 (and probably other versions) cannot handle the "tar" archive, although it can decompress it from the .tgz file. Expander Enhancer, which you have to pay for, can handle the tar archive. 5. What can I use Python for? Python is a general purpose programming language. See the Python home page at http://www.python.org/ for more information; introductory material is available at: http://www.python.org/doc/Intros.html 6. How do I use module/function/whatever XXX? Start by reading the documentation for XXX. If the documentation doesn't make sense or seems incomplete, please file a specific bug report to docs at python.org (the address you sent your question to). Otherwise, you probably sent your question to the wrong place (which does not preclude an answer, if I know it). If you're looking for examples or tutorial information on how to use a particular Python library component, check the Demo/ directory of the source distribution or Windows installation; there might be an example. If that doesn't help, point your Web browser to http://www.python.org/doc/ and look around; there may be a link to some interesting examples online. After that, try searching the Python Web site at http://www.python.org/search/. If your question still hasn't been answered, you may send your query to the Python newsgroup (comp.lang.python) or the mailing list (see http://www.python.org/mailman/listinfo/python-list). If you'd rather not send you message to a public forum, you can try sending it to python-help at python.org. (This is typically slower than sending your question to the public list, however.) 7. What about Jython and JPython? If your question is specific to Jython or JPython, you should consult the Jython website at: http://www.jython.org/ Chances are very good that the person who answers questions posted to docs at python.org doesn't use Jython very often, and won't be able to give you a meaningful answer beyond "Look at the Jython website." Sorry, I don't have *all* the answers! 8. I found a bug in the documentation, who should I tell? If you're reading this, you've found the right address! Send all documentation bug reports to docs at python.org. If you prefer to use a Web-based reporting mechanism, you can use the bug database at http://www.python.org/python-bugs/. 9. Can I get an algorithm to do THIS in language THAT? If THAT is Python, look in the standard library. If THAT isn't Python, use your favorite Internet search engine. 10. How do I decode an XXX file from my email on a YYY computer? I really, honestly do not know. I don't even know why this question gets asked here. Since I don't have a YYY computer, I couldn't even try a few things out for you. 11. Acrobat Reader won't print the PDF. What's wrong? Adobe has reportedly admitted that there is a bug Acrobat Reader 5.0 which causes it not to print at least some PDF files generated by pdfTeX. This software is used to produce the PDF version of the Python documentation, and our documents definately trigger this bug in Acrobat Reader. To print the PDF files, use Acrobat Reader 4.x, ghostscript, or xpdf. Information on ghostscript can be found at: http://www.ghostscript.com/ Information on xpdf can be found at: http://www.foolabs.com/xpdf/ 12. Where can I find documentation in my native language? There is a lot of contributed documentation in languages other than English. Some of the documents are translations of English documents, and others were originally authored in other languages. If we know about it, it will be listed at: http://www.python.org/doc/NonEnglish.html 13. Why is Python installed on my computer? We're increasingly seeing Python being installed on computers as delivered by vendors. For more information on why, and whether it's safe to remove, see the "Why is Python Installed on my Computer?" FAQ, found at: http://www.python.org/doc/faq/installed.html From fredrik at pythonware.com Sun Jan 8 15:22:31 2006 From: fredrik at pythonware.com (Fredrik Lundh) Date: Sun, 8 Jan 2006 15:22:31 +0100 Subject: [Doc-SIG] proposal: a process for solving the Python Documentation Problem References: Message-ID: Chad Whitacre wrote: > 0. Agree on a problem-solving process. :^) I'll check back in 2020 ;-) In the meantime, using a small number of 15-minute slots, I'll implement a first draft of a pythondoc/edit-through-the-web solution for a wider audience. An outline follows: > 1. Decide what documentation is in scope: Library Reference only? > Language Reference as well? Everything? Library reference plus relevant portions of the language reference. > 2. Brainstorm the end-user formats we might possibly want to read > documentation in: HTML, PDF, plain text, etc. HTML (in this iteration). > 3. Prioritize formats. Done. > 4. Crop the list to three or fewer primary target formats. Done. > 5. Define the information that needs to be encoded to support the given > formats. Done. > 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. Done ;-) > 7. Build, borrow, or buy the tools to migrate, maintain, author, access, > and transform the information. In progress. I'll let you all know when there's something to play with. From fredrik at pythonware.com Sun Jan 8 22:02:19 2006 From: fredrik at pythonware.com (Fredrik Lundh) Date: Sun, 8 Jan 2006 22:02:19 +0100 Subject: [Doc-SIG] that library reference, again References: <4335d2c40512291238l6b1d44b7vaf0963b631f3bd89@mail.gmail.com> <43B4A238.2030101@python.org> <51A7717B-3832-477E-BED5-3C36DCA20336@lag.net><43B56EEE.9090904@egenix.com> Message-ID: > anyone knows anything about support for semantic markup ? http://meta.wikimedia.org/wiki/Semantic_MediaWiki not sure a full-blown RDF-in-wiki-syntax is really that optimal, though ;-) From aahz at pythoncraft.com Mon Jan 9 00:04:00 2006 From: aahz at pythoncraft.com (Aahz) Date: Sun, 8 Jan 2006 15:04:00 -0800 Subject: [Doc-SIG] that library reference, again In-Reply-To: References: <43B4A238.2030101@python.org> Message-ID: <20060108230400.GC26118@panix.com> [removing python-dev from cross-posting] On Sun, Jan 08, 2006, Fredrik Lundh wrote: > >> anyone knows anything about support for semantic markup ? > > http://meta.wikimedia.org/wiki/Semantic_MediaWiki > > not sure a full-blown RDF-in-wiki-syntax is really that optimal, > though ;-) Maybe I'm missing something, but this doesn't seem to provide semantic markup for sections within a document/article. -- Aahz (aahz at pythoncraft.com) <*> http://www.pythoncraft.com/ "19. A language that doesn't affect the way you think about programming, is not worth knowing." --Alan Perlis From fredrik at pythonware.com Mon Jan 9 13:38:30 2006 From: fredrik at pythonware.com (Fredrik Lundh) Date: Mon, 9 Jan 2006 13:38:30 +0100 Subject: [Doc-SIG] that library reference, again References: <4335d2c40512291238l6b1d44b7vaf0963b631f3bd89@mail.gmail.com> <43B4A238.2030101@python.org> <43B55FE8.1040401@python.org> <43B58F09.6090803@colorstudy.com><43B61A1E.9080300@gmail.com> <43B700A2.70701@colorstudy.com> Message-ID: Ian Bicking wrote: > 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. fwiw, I'm not convinced that we need a tracker at all. A mailing list and a way to link to documentation constructs (with links that can be read and written and followed by humans, and identified by com- puters) might be good enough. e.g. From: someone Subject: ancient browser references in cgi docs http://docs.python.org/ref/cgi mentioning grail is perhaps cute, but the talk about the "latest addition is to support a netscape 2.0 feature" feels a bit odd... or From: someone Subject: confused by anydbm docs The text starts by mentioning that if the given file does not exist, whichdb is used to pick a module (from the set "listed above"). It then goes on to say that the default flag is "r" (open existing file only). Does anydbm really attempt to import other modules in this case, or is it that only done for "c" and "n"? What happens if the file exists and the flag is set to "n" ? http://docs.python.org/ref/anydbm.open etc. From fredrik at pythonware.com Mon Jan 9 14:54:42 2006 From: fredrik at pythonware.com (Fredrik Lundh) Date: Mon, 9 Jan 2006 14:54:42 +0100 Subject: [Doc-SIG] that library reference, again References: <4335d2c40512291238l6b1d44b7vaf0963b631f3bd89@mail.gmail.com> <43B4A238.2030101@python.org> <43B55FE8.1040401@python.org> <43B58F09.6090803@colorstudy.com><43B61A1E.9080300@gmail.com><43B700A2.70701@colorstudy.com> Message-ID: > http://docs.python.org/ref/anydbm.open make that http://docs.python.org/lib/anydbm.open From ianb at colorstudy.com Mon Jan 9 17:44:45 2006 From: ianb at colorstudy.com (Ian Bicking) Date: Mon, 09 Jan 2006 10:44:45 -0600 Subject: [Doc-SIG] that library reference, again In-Reply-To: References: <4335d2c40512291238l6b1d44b7vaf0963b631f3bd89@mail.gmail.com> <43B4A238.2030101@python.org> <43B55FE8.1040401@python.org> <43B58F09.6090803@colorstudy.com><43B61A1E.9080300@gmail.com> <43B700A2.70701@colorstudy.com> Message-ID: <43C292FD.2070209@colorstudy.com> Fredrik Lundh wrote: >>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. > > > fwiw, I'm not convinced that we need a tracker at all. A mailing list > and a way to link to documentation constructs (with links that can > be read and written and followed by humans, and identified by com- > puters) might be good enough. I think there needs to be at least some workflow, some way to indicate what comments have been acted upon and which ones have not. How else can multiple people maintain the documentation? There's no collaborative way to track the status of email messages. Anyway, setting up a Trac instance and dumping comments into that (from whatever source) isn't particularly hard. -- Ian Bicking / ianb at colorstudy.com / http://blog.ianbicking.org From ianb at colorstudy.com Mon Jan 9 21:22:19 2006 From: ianb at colorstudy.com (Ian Bicking) Date: Mon, 09 Jan 2006 14:22:19 -0600 Subject: [Doc-SIG] that library reference, again In-Reply-To: <368a5cd50601091215n78aa209dq68f61d58bc9fd459@mail.gmail.com> References: <43B4A238.2030101@python.org> <43B55FE8.1040401@python.org> <43B58F09.6090803@colorstudy.com> <43B61A1E.9080300@gmail.com> <43B700A2.70701@colorstudy.com> <43C292FD.2070209@colorstudy.com> <368a5cd50601091215n78aa209dq68f61d58bc9fd459@mail.gmail.com> Message-ID: <43C2C5FB.6010207@colorstudy.com> Fredrik Lundh wrote: > (I'm not sure if it's python.org or gmane.org that has trouble right now, > but something's wrong somewhere. let's see if this works better) > > Ian Bicking wrote: > > >>>fwiw, I'm not convinced that we need a tracker at all. A mailing list >>>and a way to link to documentation constructs (with links that can >>>be read and written and followed by humans, and identified by com- >>>puters) might be good enough. >> >>I think there needs to be at least some workflow, some way to indicate >>what comments have been acted upon and which ones have not. How else >>can multiple people maintain the documentation? There's no >>collaborative way to track the status of email messages. > > > I somehow assumed that the maintainers would use email to report back to the > list ;-) > > the problem here is to strike a balance between tracking and discussing; trac > and roundup etc are great tools if you want to track progress for > distinct issues, > but they're not that great for discussions, especially when you don't > know up front > if the discussion is going to result in a single issue, a dozen > issues, or nothing > at all... Roundup is pretty good for discussions, since it has an email gateway. I think Roundup would be just as good a choice as Trac. A gateway doesn't deal with the case when a single discussions involves many tickets (or vice versa), but I think ad hoc ways to deal with that (e.g., create a new expansive ticket, or just track it manually) are generally fine. That said, I've also seen people usefully discuss things on trackers, it's just not the default. The main workflow issue I see is how to defer work without forgetting it. I know I personally am horrible at doing this with email -- if I don't handle it right away I forget about it. Assignment can be quite useful in collaboration, when you want to either say "I am working on it", or "you should work on it", and doing that in email is also hard, especially more than once (you have to find the latest assignment-related email to figure out who has the ball). Also, discussion doesn't seem primary to this. Most comments can probably be acted on directly with no discussion. So optimizing for discussion seems wrong. -- Ian Bicking / ianb at colorstudy.com / http://blog.ianbicking.org From Felix.Wiemann at gmx.net Mon Jan 9 22:03:29 2006 From: Felix.Wiemann at gmx.net (Felix Wiemann) Date: Mon, 09 Jan 2006 22:03:29 +0100 Subject: [Doc-SIG] Released: Docutils 0.4 Message-ID: <87irsti066.fsf@news2.ososo.de> ======================= Docutils 0.4 Released ======================= Docutils 0.4 has been released. You can download it from . What Is Docutils? ================= Docutils is a system for processing plaintext documentation into various useful formats, such as HTML or LaTeX. It includes reStructuredText, the easy to read, easy to use, what-you-see-is-what-you-get plaintext markup language. Major Changes Since The Previous Release (0.3.9) ================================================ * Added an S5/HTML writer and the rst2s5.py front end: multi-platform, multi-browser HTML slide shows. See and . * The newlatex2e writer is nearing completion. * Added a DocTree reader, ``publish_doctree`` and ``publish_from_doctree`` convenience functions, for document tree extraction and reprocessing. * Added directives: "container" (generic block-level container), "default-role" (role used for `backtick` syntax), "title" (document title metadata), and "date" (generate the current local date, for substitution definitions). See . * Length units are now supported for image sizes; see . * Added standard definition files for special characters etc.; see . * Added Japanese and Simplified Chinese language mappings, and support for double-width CJK-characters in tables and section titles. * Added a guide for distributors (http://docutils.sf.net/docs/dev/distributing.html) and a guide for developers (http://docutils.sf.net/docs/dev/hacking.html). * Added significant Emacs support for reST; see . * Added a --strip-comments option; see . * --embed-stylesheet is now the default for the HTML writer (rather than --link-stylesheet). Compatibility Note ================== Docutils 0.4.x is the last version that will support Python 2.1. Docutils 0.5 will *not* be compatible with Python 2.1; Python 2.2 or later will be required. Docutils 0.4.x is the last version that will make compromises in its HTML output for Netscape Navigator 4. Docutils 0.5 will require more up-to-date browsers (the exact definition is to be determined). -- Felix Wiemann -- http://www.ososo.de/ From Felix.Wiemann at gmx.net Wed Jan 11 20:19:55 2006 From: Felix.Wiemann at gmx.net (Felix Wiemann) Date: Wed, 11 Jan 2006 20:19:55 +0100 Subject: [Doc-SIG] PyCon References: <43961FC4.50302@python.org> Message-ID: <87irsqa7xg.fsf@news2.ososo.de> David Goodger wrote: > Registration is now open, and early-bird pricing is in effect until > Dec. 31: http://www.python.org/pycon/2006/register.html Actually, early-bird registration is possible till Jan. 15 (according to http://www.python.org/). So if you haven't registered yet, do it now! :-) -- For private mail please ensure that the header contains 'Felix Wiemann'. "the number of contributors [...] is strongly and inversely correlated with the number of hoops each project makes a contributing user go through." -- ESR From john_sips_tea at yahoo.com Mon Jan 16 18:51:47 2006 From: john_sips_tea at yahoo.com (John M. Gabriele) Date: Mon, 16 Jan 2006 09:51:47 -0800 (PST) Subject: [Doc-SIG] Installing Python modules doc -- please add a few items Message-ID: <20060116175147.4470.qmail@web80903.mail.scd.yahoo.com> I just sent the following {see below} message to docs at python.org, but then discovered this ML, subscribed, and am re-sending it to this list: Request for possible additions to the "Installing Python Modules" doc: 1. When I want to install a package in 2 steps, first building in a separate build dir (--build-base=~/temp/foo) then install in my own packages directory (--home=~/python_pkgs), please mention in the doc how setup.py knows I've already run the build. That is, when I tell setup.py to install, how does it know that I previously ran a build, and where those build products are waiting? 2. At the very beginning of the doc, you might mention the difference between installing a single module, and installing a package containing a number of modules. That is, do developers use distutils when they are providing only one module (as opposed to a package full of modules)? 3. It might also be beneficial to note in the doc why you run the command as "python setup.py" instead of "./setup.py". 4. It would be nice to have a comment about what lands in your '--build-base' when you've got a package that only contains some pure Python modules. I guess setup.py simply copies the .py files to the build directory? I could make these changes/additions myself, but would need to know: A. Where to get the source from, and B. The answers to the above questions. :) BTW, I don't know if this message is going to a ML or not. If it is, and I need to subscribe to get a reply, please point me in the right direction. Thanks, ---John __________________________________________________ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com From john_sips_tea at yahoo.com Mon Jan 16 19:18:33 2006 From: john_sips_tea at yahoo.com (John M. Gabriele) Date: Mon, 16 Jan 2006 10:18:33 -0800 (PST) Subject: [Doc-SIG] regarding the current state of Python docs Message-ID: <20060116181833.14311.qmail@web80908.mail.scd.yahoo.com> Hi, I've just joined this list, and judging from some of the posts I've seen in the archives, there seems to be some concern about a problem with the current way Python is documented. My guess is that the current system looks something like this: 1. checkout the doc source 2. make changes 3. commit changes Personally, I think the best way document Python (outside of the built-in docstrings) is a wiki but with only a select group of folks with edit privileges. That is, only after you've been around for a little while (or otherwise shown that you can write good docs and want to help) are you given edit access. Nothing too strict. Just limited to folks who actually want to help, and who can show they're fairly good at it. The same way you grant committer access on any free software project. It seems like it wouldn't *too* be much trouble to simply take all the docs as they currently are and export them to a new wiki, wholesale. That is, create a "sister" wiki to the one we already have. Put the whole enchilada on there. The library reference, the language reference. Everything. Editing a wiki page is *way* easier than doing the checkout- edit-commit procedure as outlined above. Sometimes I've only got 5 or 10 minutes, and really would like to see a small clarification in the docs. If it were wikified, I could make that change (say, on my slashdo^H^H^H lunch break). If I'm at work, and had to do a checkout, etc, ... no way would I bother. It would have to wait 'til I get home -- then with the wife and kids wanting some family time, the edits might not even happen. How hard is it to convert html to suitable moinmoin wiki text input? Is there already a tool for this? Maybe someone needs to just jump on it, pull the starter on the chainsaw, just go for it, and let the chips fall where they may. :) ---J __________________________________________________ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com From fredrik at pythonware.com Mon Jan 16 21:01:47 2006 From: fredrik at pythonware.com (Fredrik Lundh) Date: Mon, 16 Jan 2006 21:01:47 +0100 Subject: [Doc-SIG] regarding the current state of Python docs References: <20060116181833.14311.qmail@web80908.mail.scd.yahoo.com> Message-ID: John M. Gabriele wrote: > I've just joined this list, and judging from some of the > posts I've seen in the archives, there seems to be some > concern about a problem with the current way Python is > documented. > > My guess is that the current system looks something like > this: > > 1. checkout the doc source > 2. make changes > 3. commit changes it's actually more like (quoting from an earlier post): If logged in to a machine with a full Python development environment: 1) sync the project 2) locate the right source file 3) edit, and save to disk 4) (optionally) regenerate the documentation and inspect it (3-6 minutes if you have the toolchain installed) 5) commit the change (alternatively, generate a patch) 6) wait up to 12 hours for the updated text to appear on the developer staging area on python.org, and 3-6 months for the next documentation release to appear on the site If no access to a Python development environment: 1) (optionally) cut and paste the text to an editor, edit, and save to disk 2) write note or mail to self (or generate a patch) 3) at an unspecified later time, try to remember what you did, and follow the developer instructions above. wait 3-6 months for the next doc release to appear on the site. > Personally, I think the best way document Python (outside > of the built-in docstrings) is a wiki but with only a select > group of folks with edit privileges. Absolutely, but we want good semantic markup, and no wiki format I've seen makes it easy to get the semantics right. That doesn't mean that we cannot use an existing wiki engine, but I don't think any existing wiki format will cut it. > How hard is it to convert html to suitable moinmoin wiki > text input? Is there already a tool for this? Maybe someone > needs to just jump on it, pull the starter on the chainsaw, > just go for it, and let the chips fall where they may. :) I've spent a week hacking away with a small axe in my spare spare time: http://effbot.org/zone/pyref.htm http://effbot.org/lib/ (output snapshots) http://online.effbot.org/ (look for documentation posts) if some wiki engine and/or python framework hacker wants to start playing with an edit-through-the-web frontend for the new structured documentation format, drop me a line. ajax and css tinkerers are also welcome. From fredrik at pythonware.com Mon Jan 16 21:07:40 2006 From: fredrik at pythonware.com (Fredrik Lundh) Date: Mon, 16 Jan 2006 21:07:40 +0100 Subject: [Doc-SIG] Installing Python modules doc -- please add a few items References: <20060116175147.4470.qmail@web80903.mail.scd.yahoo.com> Message-ID: John M. Gabriele wrote: > I could make these changes/additions myself, but would > need to know: > > A. Where to get the source from, and > B. The answers to the above questions. :) comp.lang.python (or the distutils-sig) might help you sort out B. once you've done that, see: http://www.python.org/dev/doc/ From john_sips_tea at yahoo.com Mon Jan 16 22:54:48 2006 From: john_sips_tea at yahoo.com (John M. Gabriele) Date: Mon, 16 Jan 2006 13:54:48 -0800 (PST) Subject: [Doc-SIG] regarding the current state of Python docs In-Reply-To: Message-ID: <20060116215448.48485.qmail@web80901.mail.scd.yahoo.com> --- Fredrik Lundh wrote: > John M. Gabriele wrote: >[snip] > > > Personally, I think the best way document Python (outside > > of the built-in docstrings) is a wiki but with only a select > > group of folks with edit privileges. > > Absolutely, but we want good semantic markup, and no wiki format I've > seen makes it easy to get the semantics right. That doesn't mean that > we cannot use an existing wiki engine, but I don't think any existing wiki > format will cut it. I've only poked around a little bit so far, but it looks like the python wiki of choice seems to be moinmoin. What sort of output are you looking for that moinmoin cannot provide? Just curious. Lots of sites use plain wiki software for their docs, and I've always found them to be satisfactory. Perhaps there's a plug-in of some sort for that wiki that will give you what you're looking for? Maybe more info here: http://moinmoin.wikiwikiweb.de/MoinMoinExtensions > > How hard is it to convert html to suitable moinmoin wiki > > text input? Is there already a tool for this? Maybe someone > > needs to just jump on it, pull the starter on the chainsaw, > > just go for it, and let the chips fall where they may. :) > > I've spent a week hacking away with a small axe :) > in my spare spare time: > > http://effbot.org/zone/pyref.htm > http://effbot.org/lib/ (output snapshots) > http://online.effbot.org/ (look for documentation posts) So, I'm not quite sure what I'm looking at there. Have you been taking the doc source (LaTeX) and converting it to input suitable for moinmoin, or are you writing your own wiki engine with its own markup style? I mean this as a compliment: those links point to pages that look pretty much like normal wiki pages. :) > if some wiki engine and/or python framework hacker wants to start playing > with an edit-through-the-web frontend for the new structured documentation > format, drop me a line. What's "the new documentation format"? > ajax and css tinkerers are also welcome. > > > Thanks, ---J __________________________________________________ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com From fredrik at pythonware.com Wed Jan 18 12:51:28 2006 From: fredrik at pythonware.com (Fredrik Lundh) Date: Wed, 18 Jan 2006 12:51:28 +0100 Subject: [Doc-SIG] regarding the current state of Python docs References: <20060116215448.48485.qmail@web80901.mail.scd.yahoo.com> Message-ID: John M. Gabriele wrote: >> in my spare spare time: >> >> http://effbot.org/zone/pyref.htm >> http://effbot.org/lib/ (output snapshots) >> http://online.effbot.org/ (look for documentation posts) > > So, I'm not quite sure what I'm looking at there. Have > you been taking the doc source (LaTeX) and converting it > to input suitable for moinmoin, or are you writing your own > wiki engine with its own markup style? I prefer to model things as a collection of components, and leave the overall architecture open for as long as possible. The links above dis- cusses converters, a reference-specific markup format (based on java- doc), a reference-specific naming model (targets), and renderers. You can use these with a full-blown wiki as the editor and cms, or you can use something else. I'm open for all ideas. The only things I'll keep ignoring are unqualified vetos ;-) From john_sips_tea at yahoo.com Wed Jan 25 18:29:50 2006 From: john_sips_tea at yahoo.com (John M. Gabriele) Date: Wed, 25 Jan 2006 09:29:50 -0800 (PST) Subject: [Doc-SIG] regarding the current state of Python docs In-Reply-To: Message-ID: <20060125172950.69771.qmail@web80902.mail.scd.yahoo.com> --- Fredrik Lundh wrote: > John M. Gabriele wrote: Sorry to take so long to get back to this thread (not that it's really kicking anymore, but it's still at least twitching for me. :). It's partly because I hardly understood what Fredrik wrote, but also b/c work got (and still is) crazy for me this past week. I'd really like to understand this though, and think the python community will benefit not only from Fredrik's work, but also from understanding it better, so I'm posting. > >> in my spare spare time: > >> > >> http://effbot.org/zone/pyref.htm > >> http://effbot.org/lib/ (output snapshots) > >> http://online.effbot.org/ (look for documentation posts) > > > > So, I'm not quite sure what I'm looking at there. Have > > you been taking the doc source (LaTeX) and converting it > > to input suitable for moinmoin, or are you writing your own > > wiki engine with its own markup style? > > I prefer to model things as a collection of components, and leave the > overall architecture open for as long as possible. No idea what you mean by that in this context. In general I agree though. Could you briefly outline the different components and what they envision them doing? > The links above dis- > cusses converters, Hm. Converting from some text markup language to things like html. ok... > a reference-specific markup format (based on java- > doc), Ah. So-called "PythonDoc". http://effbot.org/zone/pythondoc.htm Dunno what you mean by "reference-specific" though. Seems like there would be some confusion between PythonDoc and doc strings. In your code, where do you put your docs, in the doc strings or in PythonDoc comments? > a reference-specific naming model (targets), and renderers. Ok, I'm lost there. :) > You can use these with a full-blown wiki as the editor and cms, or you > can use something else. I'm open for all ideas. The only things I'll keep > ignoring are unqualified vetos ;-) > > > I see that there's also this "ReST" markup that looks pretty readable even in plain text (with the markup still in it). So, is your idea to write Python docs in ReST, or write them in PythonDoc? (Though, I'm guessing that you'd only use PythonDoc to document your code, not to write the Python reference manual with.) Thanks, ---J __________________________________________________ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com From edloper at gradient.cis.upenn.edu Fri Jan 27 13:55:01 2006 From: edloper at gradient.cis.upenn.edu (Edward Loper) Date: Fri, 27 Jan 2006 07:55:01 -0500 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> <60ed19d40512301829q7a0df01bv3ed782fe28cbcf7a@mail.gmail.com> Message-ID: <43DA1825.8060608@gradient.cis.upenn.edu> Robey Pointer wrote: On 30 Dec 2005, at 18:29, Christopher Armstrong wrote: >> [epydoc] is 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. [...] As a side note, I've done a significant amount of work on a newer version of epydoc that supports both inspection & source-code parsing (and can merge the info from both sources, if they're available). Hopefully this new version will address some of these concerns (and some other issues I've heard raised). But I haven't had time to work on it in a while -- I need to concentrate on getting my phd thesis done. If anyone is interested in working on this new version, just let me know. :) -Edward