Mailman 3 December 2005 - Doc-SIG

PyCon
by David Goodger Jan. 11, 2006

Jan. 11, 2006

PyCon TX 2006 is coming up, Feb. 24-26, in Addison/Dallas Texas USA. http://www.python.org/pycon/2006/ Registration is now open, and early-bird pricing is in effect until Dec. 31: http://www.python.org/pycon/2006/register.html Be sure to book your room at the conference hotel: http://www.stayatmarriott.com/Pycon2006/ There will be three Docutils-related talks: * Docutils Developers Tutorial: Architecture, Extending, and Embedding (David Goodger & Felix Wiemann) * Easy Slide Shows With reStructuredText & S5 (David Goodger) * What is Nabu? (Martin Blais) List of talks with summaries: http://wiki.python.org/moin/PyCon2006/Talks I will be giving a tutorial on the day before the conference, Feb. 23, in the morning: Text & Data Processing (http://wiki.python.org/moin/PyCon2006/Tutorials/TextProcessing). List of tutorials: http://wiki.python.org/moin/PyCon2006/Tutorials We will hold a Docutils sprint in the four days following the conference: http://wiki.python.org/moin/PyCon2006/Sprints/DocutilsSprint . Other sprints & info: http://wiki.python.org/moin/PyCon2006/Sprints Tell your user group. Tell your friends, classmates, and colleagues. I hope to see many of you there! -- David Goodger <http://python.net/~goodger>

2 1

Re: [Doc-SIG] that library reference, again
by David Goodger Jan. 9, 2006

Jan. 9, 2006

[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>

4 7

proposal: a process for solving the Python Documentation Problem
by Chad Whitacre Jan. 8, 2006

Jan. 8, 2006

Dear All, Here is an attempt to outline a process by which we might clarify and solve the "Python Documentation Problem." The attempt here is to work from the outside in, starting with the end result we want to see, and working backwards from there to find the best solution. 0. Agree on a problem-solving process. :^) 1. Decide what documentation is in scope: Library Reference only? Language Reference as well? Everything? 2. Brainstorm the end-user formats we might possibly want to read documentation in: HTML, PDF, plain text, etc. 3. Prioritize formats. 4. Crop the list to three or fewer primary target formats. 5. Define the information that needs to be encoded to support the given formats. 6. Identify the storage format that best balances ease of migration, maintenance, and authoring with adequacy to the task of encoding and making accessible the necessary information. 7. Build, borrow, or buy the tools to migrate, maintain, author, access, and transform the information. 8. Migrate, maintain, author, access, and transform the information. chad

2 1

Re: [Doc-SIG] proposal: a process for solving the Python Documentation Problem
by Laura Creighton Jan. 3, 2006

Jan. 3, 2006

In a message of Sat, 31 Dec 2005 00:19:35 EST, Chad Whitacre writes: >Dear All, > >Here is an attempt to outline a process by which we might clarify and >solve the "Python Documentation Problem." The attempt here is to work >from the outside in, starting with the end result we want to see, and >working backwards from there to find the best solution. > > >0. Agree on a problem-solving process. :^) This is a great step 0. Alas, I think things will all fall apart here. My problem with your solution is that it is a technical solution to a technical problem. I think our problem is a social problem and needs a social solution. >1. Decide what documentation is in scope: Library Reference only? > Language Reference as well? Everything? Everything, especially since people will want to use it for their own documentation purposes. >2. Brainstorm the end-user formats we might possibly want to read > documentation in: HTML, PDF, plain text, etc. I don't think this is priority at all. People who already like one format or another already write tools to convert one to another. And here we cut to a deep philosophical difference. When you look at documents, it matters a great deal whether you think that the control of how it should be presented should lie with the _readers_ or with the _writers_. Commercial pressure has forced a current outcome where the _writers_ more or less get to say what the readers get to read. This leads to the situation where the _logical information about the stucture of the document_ is mixed up in some sort of stew with the _rendering information about how to print it on your rendering device_. And some people think this is all well and good because the rendering information is important information that belongs with the document. Other people, including myself, think that this is pure evil because the rendering information should exist with the readers, not with the writers. (Of course they should be free to send out their suggested format). So depending on where you sit on this philosophical devide, you will soon end up wanting either: A _really low level markup language_ which allows you lots and lots of control over how to render stuff, or A _really high level document parser_ which can take any plain text file, one that has no markup at all, and can conclude what its structure is, leaving you free to render that however you like. So people go off and do this and they end up in different sorts of messes. The low level language people end up with text that can only be read or understood _rendered_. Often it is hard to search. And you often destroy the logical structure that people use when thinking about documents. You cannot search for the third paragraph, but only the fifth line break, which becomes the fourteenth when paragraph two gets a list inserted. Eventually you need some sort of authoring tool to create text, because you just cannot read the markup-gloop any more. The document parser people find that there are some times when plain text is not enough, and you really need to include some markup somewhere. If they stick it in the document, they have started down the road where they make their input text easier to parse. You can end up with markup-gloop this way too, even if it is only structural markup you are inserting. If you stick it in a companion document, then the two get out of sync, and somebody always loses one. >3. Prioritize formats. > >4. Crop the list to three or fewer primary target formats. > >5. Define the information that needs to be encoded to support the given > formats. > >6. Identify the storage format that best balances ease of migration, > maintenance, and authoring with adequacy to the task of encoding and > making accessible the necessary information. I don't think we are ever going to agree on this one. >7. Build, borrow, or buy the tools to migrate, maintain, author, access, > and transform the information. > >8. Migrate, maintain, author, access, and transform the information. > > >chad And here we are already at disagreements because I think you are solving a different problem than the one that is causing our problem. I think that Fredrik Lundh just did this as well, so you are in good company. Now I need to go out and see the fireworks. Then it is time to cook the already-prepared New Years Dinner. Which means I will be too drunk later to consider writing my steps of solution to our documentation problem, which I perceive differently. We will have the same step 0 ... and none of the rest. But thank you for writing, and Gott Nytt År to all of you. Laura

3 2

Re: [Doc-SIG] what about OpenDocument?
by Laura Creighton Dec. 31, 2005

Dec. 31, 2005

Yes, this is precisely what many of us dislike. When we are working on a project, and somebody changes the docs, we want a nice readable svn checkin with the diffs, something that we can glance at any say 'yes that's correct' or 'oops, that's wrong'. When instead you get 'binary file, no diffs available' your documentation starts living in a world of its own, a world that you have to visit periodically and do work to keep up with. Laura In a message of Sat, 31 Dec 2005 13:19:34 +1100, Christopher Armstrong writes: >On 12/31/05, Laura Creighton <lac(a)strakt.com> wrote: >> So it is a binary file format? If so, that will be a problem. Anythin >g >> that produces output you cannot run through unix tools such as grep, an >d >> anything that you cannot edit in your favourite text editor will be a >> problem. > >Well, all it is is a zip file that contains some XML files and some >subdirectories. content.xml is fairly easy to extract from the zip, >munge, and put back. > >-- > Twisted | Christopher Armstrong: International Man of Twistery > Radix | -- http://radix.twistedmatrix.com > | Release Manager, Twisted Project > \\\V/// | -- http://twistedmatrix.com > |o O| | >w----v----w-+

3 3

Re: [Doc-SIG] [Python-Dev] that library reference, again
by Laura Creighton Dec. 31, 2005

Dec. 31, 2005

In a message of Sat, 31 Dec 2005 15:41:50 +1000, Nick Coghlan writes: >Ian Bicking wrote: >> Anyway, another even more expedient option would be setting up a >> separate bug tracker (something simpler to submit to than SF) and >> putting a link on the bottom of every page, maybe like: >> http://trac.python.org/trac/newticket?summary=re:+/path/to/doc&componen >t=docs >> -- heck, we all know SF bug tracking sucks, this is a good chance to >> experiment with a different tracker, and documentation has softer >> requirements other parts of Python. > >While I quite like this idea, would it make it more difficult when the bu >g >tracking for the main source code is eventually migrated off SF? And what > >would happen to existing documentation bug reports/patches on the SF trac >kers? > >Is it possible to do something similar for the online version of the curr >ent >docs, simply pointing them at the SF tracker? (I know this doesn't help p >eople >without an SF account. . .) > >Cheers, >Nick. Not if the problem is that documentation changes are not 'patches' and 'bugs' and the sourceforge bug tracker, which isn't even particularly good at tracking bugs is particularly ill-suited for the collaborative sharing of documents. Laura

1 0

Re: [Doc-SIG] [Python-Dev] that library reference, again
by Christopher Armstrong Dec. 31, 2005

Dec. 31, 2005

On 12/30/05, Robey Pointer <robey(a)lag.net> wrote: > > On 29 Dec 2005, at 18:58, David Goodger wrote: > > > [Fredrik Lundh] > >>>> I'm beginning to fear that I've wasted my time on a project > >>>> that nobody's interested in. > > > > [David Goodger] > >>> Could be. I don't see HTML+PythonDoc as a significant improvement > >>> over LaTeX. > > > > [Fredrik Lundh] > >> Really? > > > > Yes, really. > > Just out of curiosity (really -- not trying to jump into the flames) > why not just use epydoc? If it's good enough for 3rd-party python > libraries, isn't that just a small step from being good enough for > the builtin libraries? It's not really even "good enough" for a lot of my usage without some seriously evil hacks. The fundamental design decision of epydoc to import code, plus some other design decisions on the way it figures types and identity seriously hinder its utility. Ever notice how trying to document your third-party-library-using application will *also* document that third party library, for example? Or how it'll blow up when you're trying to document your gtk-using application on a remote server without an X server running? Or how it just plain blows right up with most Interface systems? etc. -- Twisted | Christopher Armstrong: International Man of Twistery Radix | -- http://radix.twistedmatrix.com | Release Manager, Twisted Project \\\V/// | -- http://twistedmatrix.com |o O| | w----v----w-+

1 0

Re: [Doc-SIG] what about OpenDocument?
by Laura Creighton Dec. 31, 2005

Dec. 31, 2005

So it is a binary file format? If so, that will be a problem. Anything that produces output you cannot run through unix tools such as grep, and anything that you cannot edit in your favourite text editor will be a problem. Laura In a message of Fri, 30 Dec 2005 12:55:34 EST, Chad Whitacre writes: >Skip, > >Yes, sorry. You'll see that I mention OpenOffice (OOo) in my first post, > although I didn't define ODT explicitly. From Wikipedia: > > The OpenDocument format (ODF), short for the OASIS Open Document > Format for Office Applications, is an open document file format for > saving and exchanging editable office documents such as text documents > (including memos, reports, and books), spreadsheets, charts, and > presentations. This standard was developed by the OASIS industry > consortium, based upon the XML-based file format originally created by > OpenOffice.org. > > http://en.wikipedia.org/wiki/OpenDocument > >ODT stands for "OpenDocument Text." > > > >chad > > > > >skip(a)pobox.com wrote: >> Chad> Attached is the documentation for the random module in ODT >> Chad> format... >> >> I've never heard of OpenDocument or ODT before. You mentioned "word >> processor". Is it somehow related to OpenOffice? >> >> Skip >> _______________________________________________ >> Doc-SIG maillist - Doc-SIG(a)python.org >> http://mail.python.org/mailman/listinfo/doc-sig >> > >_______________________________________________ >Doc-SIG maillist - Doc-SIG(a)python.org >http://mail.python.org/mailman/listinfo/doc-sig

2 1

unsurscribe
by Bruce Thomson Dec. 30, 2005

Dec. 30, 2005

Dear Sir/madam I have made a mistake and would like to unsurscribe. Would someone please send me the link in order to do this. Sincerely Bruce Thomson

2 1

what about OpenDocument?
by Chad Whitacre Dec. 30, 2005

Dec. 30, 2005

Dear all, Here's a crazy idea: what would it look like to maintain the Python documentation in OpenDocument format? Pros ==== - robust authoring environment: OpenOffice - drastically lower barrier to entry for authors - custom markup == custom OOo stylesheet (!) - open XML-based format means easy-to-write tools - trivial PDF conversion - powerful typesetting - nice boost for ODF/OOo Cons ==== - HTML version would take work; default not good enough - harder to diff/version? - um ..., um ... "Hey, I'd like to write documentation for my new Python module." "Ok, download the OOo template from python.org and go to it!" chad

2 3