Re: [Python-Dev] [Doc-SIG] that library reference, again
On 1/26/06, Robey Pointer [EMAIL PROTECTED] wrote: [quoting /F] moving all of (or parts of) the reference documentation in to the library source code would be an alternative, of course [1], but that would basically mean starting over from scratch. Bad idea. Putting the full docs in the source adds more coupling between the files and makes it harder instead of easier to edit the docs, especially for C code. Also, the needs for interactive help are different from those for off-line docs. Also note that several object types (e.g. lists and dicts, like used for sys.path and sys.modules) don't have __doc__ properties so documenting them in the source is problematic. The list goes on; e.g. the source code ordering may not be the same as the ideal documentation ordering; where do you put subsection introductions, etc. I think that would be a good thing to do no matter what markup is used. It always irritates me when I do 'help(sys.something)' and get one line of ASCII art that's probably useful to the module author but nobody else. Wrong guess. That string was put there by the author specifically so that it shows up in help(sys.whatever), and the author probably (mistakenly) though that whatever he wrote was sufficient. If you ever find a docstring that is IYO insufficient, please submit a patch or bug. Until we have a better mechanism, simply submitting the new text of the docstring, without bothering to make it into a context-diff or to use the proper markup, is fine. -- --Guido van Rossum (home page: http://www.python.org/~guido/) ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] [Doc-SIG] that library reference, again
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 ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] [Doc-SIG] that library reference, again
On 29 Dec 2005, at 23:13, Fredrik Lundh wrote: Robey Pointer wrote: [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? but epydoc is a docstring-based format, right? I'm trying to put together a light-weight alternative to the markup used for, primarily, the current library reference. moving all of (or parts of) the reference documentation in to the library source code would be an alternative, of course [1], but that would basically mean starting over from scratch. I think that would be a good thing to do no matter what markup is used. It always irritates me when I do 'help(sys.something)' and get one line of ASCII art that's probably useful to the module author but nobody else. robey ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] [Doc-SIG] that library reference, again
On 30 Dec 2005, at 18:29, Christopher Armstrong wrote: On 12/30/05, Robey Pointer [EMAIL PROTECTED] wrote: 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. Err... no, I haven't. But I may be using a more recent version than you were (I'm using 2.1). It's not perfect, and occasionally annoying, but much better than anything else I've found. Sounds like there's some political reason it's hated, but thought I would bring it up anyway. robey ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] [Doc-SIG] that library reference, again
Donovan Baarda wrote:
No, it's a fundamental goal: to support light-weight generation of rendered
markup directly from source code, to enable simple tools (CGI scripts, etc)
to be able to render reference documentation.
Python is run-time interpreted, but I don't think we need its
documentation to be.
Are you sure ?
help(help)
From the pythondoc/lib goal list:
Support tighter (and 2-way) integration between the library reference
and help tools (pydoc, help, inspect, etc) and documentation generators
(epydoc, pythondoc, etc).
trivial is a relative term.
When I say trivial in this context, I mean that any programmer should
be capable of writing a Python tool that does some kind of basic processing
of the source format from scratch. The easier it is to do this, the more
likely it is that someone will come up with a new way to use the information
(Web 2.0, you know...)
As a some-times developer not really interested in writing
documentation, I must admit I really like ReST. It looks like plain
text, so I can write and use it as plain text, but it also can magically
transform to other formats and look pretty good.
Lots of looks like plain text if you squint formats can produce output
that looks pretty good.
The problem is semantics; I haven't seen any format that looks like plain
text but provides the amount of machine-readable semantic information
that we have today. And I want more semantics, not less.
I hate writing XML/HTML, and my only experience with LaTex was brief and
painful too. If I was forced to choose, I'd probably pick LaTex even
though I don't know it as well as XML/HTML (I'd rather face an unknown
evil than that particular devil I know).
Familiarity breeds contempt ? We're not talking about well-formed XML
here, nor 1996-era hand-rolled web sites. If you look at typical Java-
Doc or PythonDoc markup, or the translated samples, you'll notice that
the source code contains very few HTML tags.
(I seriously doubt that your problems with XML/HTML is the use of in-
stead of {...)
I'm not going to write docs for stuff I didn't write myself. I'm not
going to submit patches to Javadoc, LaTex or XML/HTML, but I might post
vague change this to... bug reports.
Writing good documentation is hard (which is why I prefer to leave it to
others if I can), but fixing almost good documentation doesn't have to
be /.../
Since I'm focussed on the library reference, I'm a lot more interested in
the fixers than the essay writers. Give people a way to find things to fix,
and a way to fix it, and they will.
It's the workflow that's the real problem here, but you cannot fix the
workflow
without fixing the markup.
I must say I disagree with this statement... changing the markup will
not change the workflow at all, just shave 3-6 mins off the compile-test
step. I don't do this enough to really know if that's worth it.
Do you think wikipedia would be what it is today if the edit/save process
included a 3-6 minute regenerate site pass ?
Heck, I've discovered dozens of bogosities in the current library reference
while working on the translation tools, and I have the sources and full SVN
access, but I find that the overhead discourages me from doing anything
about them (maybe later). I simply don't have time to fix anything but
very minor typos within a standard 15-minute let's improve python time
slot, and I sure don't think I'm unique in this respect.
/F
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] [Doc-SIG] that library reference, again
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 ;-) /F ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] [Doc-SIG] that library reference, again
M.-A. Lemburg wrote: 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. anyone knows anything about support for semantic markup ? (afaict, the current moinmoin wiki would solve 80% of the issues involved here; I'm aiming for those 80% plus 80% of the remaining 20%). /F ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] [Doc-SIG] that library reference, again
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 | [EMAIL PROTECTED] | http://blog.ianbicking.org ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] [Doc-SIG] that library reference, again
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/doccomponen 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 ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] [Doc-SIG] that library reference, again
Nick Coghlan 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/doccomponent=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 | [EMAIL PROTECTED] | http://blog.ianbicking.org ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] [Doc-SIG] that library reference, again
[David Goodger] Could be. I don't see HTML+PythonDoc as a significant improvement over LaTeX. [Fredrik Lundh] Really? Yes, really. Your reply makes it obvious that you don't understand the issues involved here, nor how the goals address them. (Snipping heavily below due to lack of time; if you want some other argument refuted, you have to repost and wait until next week.) Another goal is highly biased toward XML-style markup: * Make it trivial to do basic rendering to HTML (a few re.sub calls should suffice), to enable simple tools (CGI scripts, etc) to be able to render reference documentation. This is the tail wagging the dog. No, it's a fundamental goal: to support light-weight generation of rendered markup directly from source code, to enable simple tools (CGI scripts, etc) to be able to render reference documentation. The issue this is addressing is that the current workflow is way too heavy; when I made my first post, it typically took 3-6 months for a contribution to the documentation to appear on python.org. Thanks to Trent and Neal, the situation is a bit better today, but it's far from ideal. (More on this below). The second sentence lacks a rationale. What's wrong with -- dashes? What's silly about ``quotes''? I'd say that the fact that you're asking this should disqualify you from ever working on documentation tools again... don't you know *anything* about typography ? The reference to ReST is wrong here; ReST certainly can know the semantics of a given identifier. I don't think you understand ReST except superficially. That's why I'm listening to people who've tried to use ReST for this pur- pose. They've all failed. Maybe they also only understood ReST super- ficially. Or maybe it's because ReST is created by people who have a very shallow understanding of the issues involved in writing structured reference documentation. Your guess is as good as mine. My bias is simple: I am against wasting the time and effort required to replace one form of verbose markup with a different but equivalent form. The proposed solution is no better than the status quo. Support for quick turnaround, edit via the web, richer semantic information, and a larger existing toolbase isn't better than the status quo ? Sounds more like a ReSTian sour-grapes (or scorched-earth) approach than a serious argument from someone who's interested in improving the Python documentation. IMO, the markup itself is almost irrelevant. As others have stated, writing good documentation is hard. People will latch on to any excuse to avoid it, and markup is convenient. But even if the docs had no markup whatsoever, if they were written in plain text like RFCs, I doubt there would be significantly more patch contributions. The problem is that the WORKFLOW doesn't work. Quoting from an earlier post (you have read the earlier discussion, right?): If an ordinary user finds a minor issue, a typo, or an error in the documentation, the current user workflow is: 1) (optionally) cut and paste the text to an editor, edit, and save to disk 2) go to the sourceforge site, and locate the python project 3) (optionally) sign up for a sourceforge account 4) log in to your sourceforge account 5) open a new bug or patch issue, and attach your suggestion 6) wait 3-6 months for someone to pick up your patch, and for the next documentation release to appear on the site to which can be added: If a developer finds a minor issue, a typo, or an error in the documentation, the current developer workflow is: If logged in to a machine with a full Python development environment: 1) sync the project 2) locate the right source file 3) edit, and save to disk 4) (optionally) regenerate the documentation and inspect it (3-6 minutes if you have the toolchain installed) 5) commit the change (alternatively, generated a patch; see 2-5 above) 6) wait up to 12 hours for the updated text to appear on the developer staging area on python.org, and 3-6 months for the next documentation release to appear on the site If no access to a Python development environment: 1) (optionally) cut and paste the text to an editor, edit, and save to disk 2) write note or mail to self (or generated a patch; see user instructions above) 3) at an unspecified later time, try to remember what you did, and follow the developer instructions above. wait 3-6 months for the next doc release to appear on the site. I'm not arguing that a change of markup will solve this; I'm saying that a a light-weight toolchain will make it possible to cut this down to 3-6 seconds (plus optional moderation overhead for ordinary users). If people get feedback, they contribute. The need for a light-weight markup language follows from this; to eliminate as much overhead as possible, - the semantic model
Re: [Python-Dev] [Doc-SIG] that library reference, again
I've been dodging this thread because I don't really have much to add, apart from a documentation end user point of view... On Fri, 2005-12-30 at 09:25 +0100, Fredrik Lundh wrote: [...] Another goal is highly biased toward XML-style markup: * Make it trivial to do basic rendering to HTML (a few re.sub calls should suffice), to enable simple tools (CGI scripts, etc) to be able to render reference documentation. This is the tail wagging the dog. No, it's a fundamental goal: to support light-weight generation of rendered markup directly from source code, to enable simple tools (CGI scripts, etc) to be able to render reference documentation. Python is run-time interpreted, but I don't think we need its documentation to be. trivial is a relative term. From my point of view, provided I can apt-get one or to not-too-esoteric packages then do something like make html, it's trivial enough for me. The issue this is addressing is that the current workflow is way too heavy; when I made my first post, it typically took 3-6 months for a contribution to the documentation to appear on python.org. Thanks to Trent and Neal, the situation is a bit better today, but it's far from ideal. (More on this below). [...] That's why I'm listening to people who've tried to use ReST for this pur- pose. They've all failed. Maybe they also only understood ReST super- ficially. Or maybe it's because ReST is created by people who have a very shallow understanding of the issues involved in writing structured reference documentation. Your guess is as good as mine. As a some-times developer not really interested in writing documentation, I must admit I really like ReST. It looks like plain text, so I can write and use it as plain text, but it also can magically transform to other formats and look pretty good. I hate writing XML/HTML, and my only experience with LaTex was brief and painful too. If I was forced to choose, I'd probably pick LaTex even though I don't know it as well as XML/HTML (I'd rather face an unknown evil than that particular devil I know). My bias is simple: I am against wasting the time and effort required to replace one form of verbose markup with a different but equivalent form. The proposed solution is no better than the status quo. Support for quick turnaround, edit via the web, richer semantic information, and a larger existing toolbase isn't better than the status quo ? [...] I'm not going to write docs for stuff I didn't write myself. I'm not going to submit patches to Javadoc, LaTex or XML/HTML, but I might post vague change this to... bug reports. As an end user, one of the best things about Python is the on-line documentation... the status-quo looks pretty good from here. ...but I'm not the person doing it... remember I'm providing a documentation end-user POV here :-) IMO, the markup itself is almost irrelevant. As others have stated, writing good documentation is hard. People will latch on to any excuse to avoid it, and markup is convenient. But even if the docs had no markup whatsoever, if they were written in plain text like RFCs, I doubt there would be significantly more patch contributions. Writing good documentation is hard (which is why I prefer to leave it to others if I can), but fixing almost good documentation doesn't have to be, and for that, the markup used can make a difference. As an end user that spots a problem, I'll look at the source, and if it's in a language I know well enough to fix the problem, I'll submit a patch. If I find it's in a language I don't know and can't grok well enough to see how to fix the problem in 10 minutes, I'm going to submit a verbal description as a bug. If this is the 5+ time I've stalled on this language, I might consider learning it so I can do a patch next time. However, in this case the language in question is a documentation language and I want to be a software programmer, not a document publisher, so I'll probably just submit bugs every time, and after the 2+ time I won't even bother looking at the source. It's the workflow that's the real problem here, but you cannot fix the workflow without fixing the markup. I must say I disagree with this statement... changing the markup will not change the workflow at all, just shave 3-6 mins off the compile-test step. I don't do this enough to really know if that's worth it. If the markup is changed to something more widely known and/or simple, more people might participate in the generate patch workflow rather than the submit bug workflow, and maybe that will make things easier for the big picture update and release docs workflow. But the speed of the tool-chain has little to do with this, only the documentation language popularity among the developers and users. ...and if the LaTeX guys don't mind fixing bugs instead of applying patches and are handling the load... the status quo is fine by me, I'm happy not to do
Re: [Python-Dev] [Doc-SIG] that library reference, again
[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 http://python.net/~goodger signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] [Doc-SIG] that library reference, again
I haven't followed the thread, so many I'm repeating things. Has anyone considered using e.g. MediaWiki (the wiki used for Wikipedia) for Python documentation ? I'm asking because this wiki has proven to be ideally suited for creating complex documentation tasks and offers many features which would make Python documentation a lot easier and more accessible: * people wouldn't have to learn LaTeX to commit doc-patches * it's easy to monitor and revert changes, discuss changes * there's version history available * new docs would be instantly available on the web * builtin search facility, categories and all the other nifty wiki stuff * it's one of the more popular wikis around and due to Wikipedia it's here to stay * conversion to XML and DocBook is possible, providing entry points for conversion to other formats (including LaTeX) * more following means more tools (over time) Just a thought. Thanks, -- Marc-Andre Lemburg eGenix.com Professional Python Services directly from the Source (#1, Dec 30 2005) Python/Zope Consulting and Support ...http://www.egenix.com/ mxODBC.Zope.Database.Adapter ... http://zope.egenix.com/ mxODBC, mxDateTime, mxTextTools ...http://python.egenix.com/ ::: Try mxODBC.Zope.DA for Windows,Linux,Solaris,FreeBSD for free ! ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] [Doc-SIG] that library reference, again
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/doccomponent=docs -- heck, we all know SF bug tracking sucks, this is a good chance to experiment with a different tracker, and documentation has softer requirements other parts of Python. -- Ian Bicking / [EMAIL PROTECTED] / http://blog.ianbicking.org ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] [Doc-SIG] that library reference, again
On 12/30/05, Robey Pointer [EMAIL PROTECTED] wrote: On 29 Dec 2005, at 18:58, David Goodger wrote: [Fredrik Lundh] I'm beginning to fear that I've wasted my time on a project that nobody's interested in. [David Goodger] Could be. I don't see HTML+PythonDoc as a significant improvement over LaTeX. [Fredrik Lundh] Really? Yes, really. Just out of curiosity (really -- not trying to jump into the flames) why not just use epydoc? If it's good enough for 3rd-party python libraries, isn't that just a small step from being good enough for the builtin libraries? It's not really even good enough for a lot of my usage without some seriously evil hacks. The fundamental design decision of epydoc to import code, plus some other design decisions on the way it figures types and identity seriously hinder its utility. Ever notice how trying to document your third-party-library-using application will *also* document that third party library, for example? Or how it'll blow up when you're trying to document your gtk-using application on a remote server without an X server running? Or how it just plain blows right up with most Interface systems? etc. -- Twisted | Christopher Armstrong: International Man of Twistery Radix|-- http://radix.twistedmatrix.com | Release Manager, Twisted Project \\\V/// |-- http://twistedmatrix.com |o O|| wvw-+ ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] [Doc-SIG] that library reference, again
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/doccomponent=docs -- heck, we all know SF bug tracking sucks, this is a good chance to experiment with a different tracker, and documentation has softer requirements other parts of Python. While I quite like this idea, would it make it more difficult when the bug tracking for the main source code is eventually migrated off SF? And what would happen to existing documentation bug reports/patches on the SF trackers? Is it possible to do something similar for the online version of the current docs, simply pointing them at the SF tracker? (I know this doesn't help people without an SF account. . .) Cheers, Nick. -- Nick Coghlan | [EMAIL PROTECTED] | Brisbane, Australia --- http://www.boredomandlaziness.org ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] [Doc-SIG] that library reference, again
On 12/29/05, Fredrik Lundh [EMAIL PROTECTED] 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 http://python.net/~goodger ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] [Doc-SIG] that library reference, again
David Goodger 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. Really? Have you read my list of goals? Does LaTeX address all of them? Does ReST? 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. All I've seen from the ReST camp is handwaving, there's nothing in the documentation that indicates that semantic markup has ever been a design goal in ReST, and nobody I've talked to who've tried using ReST for rich semantic markup considers it to be an alternative. This isn't about bias, this is about technical suitability. If you think otherwise, I suggest you put pick a couple of typical document pages and show how they would look in ReST, how the corresponding semantic model will look (and when I say semantic, I mean in Python terms, not in ReST presentation terms), and how to get from LaTeX to ReST+semantics and HTML+ semantics without having to rewrite everything from scratch. We know that you have big hats over in ReST-land; now show us some cattle. /F ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] [Doc-SIG] that library reference, again
[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 http://python.net/~goodger signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] [Doc-SIG] that library reference, again
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? robey ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] [Doc-SIG] that library reference, again
Robey Pointer wrote: [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? but epydoc is a docstring-based format, right? I'm trying to put together a light-weight alternative to the markup used for, primarily, the current library reference. moving all of (or parts of) the reference documentation in to the library source code would be an alternative, of course [1], but that would basically mean starting over from scratch. (but tighter integration is on my list; with a better semantic markup, you can import reference documentation into a module's docstrings at runtime, the builtin help can point you directly to the documentation for a given class, etc.). /F 1) I'm using a mix of wiki-based introductions and machine generated markup for e.g. the Tkinter manual; an example: http://effbot.org/tkinterbook/listbox.htm ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
