Re: [Python-Dev] status of development documentation

[Fredrik Lundh]

Trent Mick wrote:

> > - could a cronjob that does this be set up on some python.org machine
> > (or on some volunteer's machine)
>
> I bit:
>
> http://trentm.com/python/

you rule!

thanks /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] status of development documentation

[Fredrik Lundh]

Torsten Bronger wrote:

> > [...]  Are there any HTML-to-print converters that are better?
>
> I don't understand exactly how the HTML is to be used for Python but
> I assume that not everything could be done via CSS, so own
> converters will be necessary for perfect output.

If done right, it should be possible to get a "usable" rendering from the raw
HTML+microformat file, but a real online version would of course need some
preprocessing (e.g basic templating and navigation fixup).  Not more than
you could do on the fly, or in a simple cgi script...

For publication work, you need more preprocessing, of course (but I'm not
sure the typical python user cares much about the subtle differences be-
tween latex and openoffice/word formatting...)

> I was disappointed with its rather small semantic vocabulary.

I sometimes doubt that the rest proponents understand the phrase "semantic
vocabulary".  They do sound a lot like Perl proponents, though...

(and strangely enough, there seems to be an almost perfect inverse relation-
ship between the ReST zealousness and the amount of text and code they
have contributed to the core distribution.  oh well.)





___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] status of development documentation

[Fredrik Lundh]

Fred L. Drake, Jr. wrote:

>  > I'm not convinced it's the toolchain though.  People hate writing
>  > documentation.  Getting people to contribute documentation is worse than
>  > pulling teeth.
>
> I don't think it's the toolchain either.  While most people don't have it,
> it's easier and easier to get a decent toolchain on Linux; TeX just isn't as
> hard to have around as it used to be.
>
> I suspect that part of the problem is that there's no need to write
> documentation to scratch itches: once you know what to write, your itch has
> been scratched (you're already able to make the changes needed to your own
> code);

If an ordinary user finds a minor issue, a type, 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

If the documentation had been placed in a wiki:

1) click edit, fix the text, and click save

If the documentation had been connected to a discussion board (PHP-style)

1) click post new message, write a note, and click save

With a "user edit" mechanism (connected either to a mailing list, or roundup),
and documentation regularily updated from the trunk, the workflow is:

1) click edit, update the text, preview, and click submit
2) wait a few days for someone to pick up your patch, and a day for
   the documentation to be regenerated.

On the maintainer side, wikis and discussion boards require regular monitoring
to avoid abuse.  A user edit mechanism requires about the same work as today
(except that an edit mechanism with preview tends to result in patches that are
a lot more "ready for use", in my experience).

> nobody is relying on the updated documentation to be released to use what
> they figured out, even if they noted that the documentation was lacking to
> start with.

I know what you mean here, but read the wrong way, that sentence is so com-
pletely off the track so I don't know where to start.  People love to contribute
bits of information, especially when they get feedback (this is of course what
powers places like python-list, not to mention the entire blog universe).  Let's
use this human feature to our advantage.





___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Sets are mappings?

[Nick Coghlan]

Aahz wrote:
> On Wed, Dec 21, 2005, Michael Chermside wrote:
>> So I have a counter-proposal. Let's NOT create a hierarchy of abstract
>> base types for the elementary types of Python. (Even basestring feels
>> like a minor wart to me, although for now it seems like we need
>> it.) If the core problem is "how do you create a canonical ordering
>> for objects that survives serialization and deserialization into a
>> different VM?", then somehow abstract base types doesn't seem like
>> the most obvious solution. And if that's not the problem we're trying
>> to solve here, then what IS? Because I don't know of very many ACTUAL
>> (as opposed to theoretical) use cases for abstract base classes of
>> fundamental types.
> 
> You've got a good point, but the documentation issue still exists; that's
> what I was more interested in.  Clearly lists, tuples, and strings are
> sequences; clearly dicts are a mapping; the question is whether sets get
> tossed in with dicts.  Overall, I think it's pretty clear that the answer
> is "no", particularly given that sets don't support __getitem__().

Like Aahz, my interest is more pedagogic than practical. Python's slightly 
unusual in that the behaviour of sequences and multi-dimensional arrays (or 
any kind of mapping, really) is more a matter of convention than anything 
enforced by the language  - whether or not a container understands slices or a 
tuple of slices is the closest thing I've found to a reliable indicator as to 
whether or not something is a sequence or multiarray rather than a simple 
mapping.

So in looking for a defining characteristic for those two terms (sequence, in 
particular, is a term that gets thrown around a lot without being really well 
defined), those are the main features I'd pick.

In practice, as MC said in his other email, "just try it and see what happens" 
is generally a far better approach. To answer MC's other point in that email, 
I actually agree it's perfectly possible to have a mapping which is not a 
container, so the structure of the taxonomy should be eliminated entirely. 
Whether or not something is a container and whether or not it is a mapping are 
independent questions.

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] status of development documentation

[Steve Holden]

[EMAIL PROTECTED] wrote:
> Fredrik> If you google c.l.python for the word "documentation", you'll
> Fredrik> find recent megathreads with subjects like "bitching about the
> Fredrik> documentation", "opensource documentation problems" and "python
> Fredrik> documentation should be better" among the top hits.  But if you
> Fredrik> check the bug and patch trackers, you don't find many
> Fredrik> contributions.  Something's definitely broken.
> 
> People find it easier to complain than to contribute.  Maybe we should fix
> that problem...
> 
I very much agree that we should, and *not* by making it more difficult 
to complain ;-)

Could the PSF help here by offering annual prizes for the best 
contributions to the documentation, or wouldn't that be an adequate 
motivator?

regards
  Steve
-- 
Steve Holden   +44 150 684 7255  +1 800 494 3119
Holden Web LLC www.holdenweb.com
PyCon TX 2006  www.python.org/pycon/

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] status of development documentation

[Walter Dörwald]

Phillip J. Eby wrote:

> [...] 
> 
> If someone has examples of actual "Pythondoc" markup that don't translate 
> to reST, I'd be really interested in seeing them, just for my own 
> education.  Of course, I'd also be curious how common such constructs are.

I'm using XML markup for our packages. Examples can be found at 
http://www.livinglogic.de/Python/xist/xsc/index_module.py (for 
docstrings) or at 
http://www.livinglogic.de/viewcvs/index.cgi/LivingLogic/Python/xist/HOWTO.xml?rev=2.110&content-type=text/vnd.viewcvs-markup
 
for doc files. Possible output is:

* HTML: http://www.livinglogic.de/Python/xist/Howto.html

* Plain text (by piping a special HTML output through w3m): 
http://www.livinglogic.de/Python/xist/Howto.txt. It might probably be 
possible to extend this, so that the output is reST.

* XSL-FO: http://www.livinglogic.de/Python/xist/Howto.fo

* PDF (generated with FOP): http://www.livinglogic.de/Python/xist/Howto.pdf

The source is definitely wordier than reST, but adding new markup is 
trivial. Take a look at 
http://www.livinglogic.de/Python/xist/Download.html and at the source at 
http://www.livinglogic.de/Python/xist/Download.htmlxsc. The download 
element automatically determines the size of the package. Source can be 
found here 
http://www.livinglogic.de/viewcvs/index.cgi/LivingLogic/WWW-Python/site/Python_xmlns.py?rev=1.43&content-type=text/vnd.viewcvs-markup
(search for "class download"). Would something like this be possible 
with reST?

Bye,
Walter Dörwald

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] status of development documentation

[skip]

>> http://trentm.com/python/

Fredrik> you rule!

Actually, I think Trent rocks.  Guido rules. 

Skip
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] Sets are mappings?

[Michael Hudson]

Michael Chermside <[EMAIL PROTECTED]> writes:

> So I have a counter-proposal. Let's NOT create a hierarchy of abstract
> base types for the elementary types of Python.

+1

Cheers,
mwh

-- 
   how are the jails in israel?
   well, the one I was in was pretty nice
-- from Twisted.Quotes
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] status of development documentation

[Michael Hudson]

"Fredrik Lundh" <[EMAIL PROTECTED]> writes:

> Checked the python-list archives lately?  If you google c.l.python for the
> word "documentation", you'll find recent megathreads with subjects like
> "bitching about the documentation", "opensource documentation problems"
> and "python documentation should be better" among the top hits.  But if
> you check the bug and patch trackers, you don't find many contributions.
> Something's definitely broken.

Hmm, it's this discussion again!  Let me make my point again!

Writing good documentation is hard.

And sometimes the problem is that the document isn't really structured
right, or it has been hastily updated to cover too many changes that
it's a dogs breakfast, or some other 'global' problem and these
*really* take time to fix.  I really, really don't think the
formatting tools make that much difference in the grand scheme of
things.  I think streamlining the process of getting a patch in would
help a lot more (and not just for the documentation, obviously) but
still not *that* much.

Cheers,
mwh
(another one in the 'hates editing HTML' camp, if anyone's counting)

-- 
  The ability to quote is a serviceable substitute for wit.
-- W. Somerset Maugham
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] status of development documentation

[Fredrik Lundh]

Ian Bicking wrote:

> This is somewhat tangential to this discussion, but I did have the
> Python documentation in mind as a potential future target for
> Commentary: http://pythonpaste.org/comment/commentary/ -- which would
> allow more casual contributions that seem to work well for other projects.

indeed.

Commentary worked better this time than last time I tinkered with it.  a few
notes:

- it would be nice to be able to cancel a new note by double-clicking again
in the same spot (at least as long as the note is empty)

- IE support seems to be a little shaky; klicking and entering text works fine,
but when I click "save", nothing happens.  in IE, that is.  if I look at the 
site in
Firefox, the note is there.

- if you click "edit this comment" on an existing note, and then click cancel,
the note disappears (in Firefox).  double-clicking on the associated block no
longer works, after that, so the note is still in there somewhere...

- many notes added to the same place may squeeze the original text into a
very narrow column.  note sure how to address that, but some kind of "mini-
mize" or "hide" feature could be nice.

 



___
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] documentation comments

[A.M. Kuchling]

On Thu, Dec 22, 2005 at 09:27:06AM +, Steve Holden wrote:
> Could the PSF help here by offering annual prizes for the best 
> contributions to the documentation, or wouldn't that be an adequate 
> motivator?

I think the most effective thing would be to award a grant to someone
to build a real comment-on-the-docs system.  There were a few Summer
of Code proposals for this sort of thing; one was funded but the
developer decided to do a KDE project instead.  

I had lunch with Fred the other day, and he was worried about whether
anyone would garden the comments to remove spam.  That is indeed an
issue, but I think we can cope with that problem once a system is
built.

Another worry is versioning.  Once lots of people have made comments
on Python 2.4.0's documentation, what do you do when 2.4.1 is
released?  Do you move the comments to the new docs, or leave them
attached to 2.4.0 and start 2.4.1 with a clean slate?  (Perhaps the
system could work a little like a bug tracking system; comments could
be marked as 'applied', and applied comments don't get moved from
2.4.0 to 2.4.1 because their content is now in the docs.)

--amk
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] status of development documentation

[Michael Chermside]

Steve Holden writes:
> Could the PSF help here by offering annual prizes for the best
> contributions to the documentation, or wouldn't that be an adequate
> motivator?

Money is not a very effective motivator for this sort of work. (Well,
in sufficient quantities it is, but the quantities required are
quite large.) Offering *credit* is more effective -- a mention within
a contributors list perhaps. Even more effective is offering the
chance to make a difference: immediate feedback (seeing your edit in
place). Thus, I'm a big fan of amk's suggestion:

> I think the most effective thing would be [...]
> to build a real comment-on-the-docs system.

But I agree strongly with Fred's concerns:
> he was worried about whether
> anyone would garden the comments to remove spam.

and as Michael Hudson put it:
> Writing good documentation is hard.
>
> And sometimes the problem is that the document isn't really structured
> right, or it has been hastily updated to cover too many changes that
> it's a dogs breakfast, or some other 'global' problem and these
> *really* take time to fix.

My own favorite idea is to create a comment-on-the-docs mechanism
allowing both COMMENTS, and PROPOSED EDITS. The proposed edits would
need to be reviewed by one of a small number of skilled and dedicated
editors (Fred Drake... you're a hero!) before being officially
incorporated. That's not all that different from the current system
(submit a patch to sourceforge), except that the format for entering
the change would be simpler.

Of course, the person who REALLY gets to decide how it works isn't me;
it's whoever decides to spend the time to BUILD this system.

-- Michael Chermside

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] documentation comments

[Fred L. Drake, Jr.]

On Thursday 22 December 2005 09:22, A.M. Kuchling wrote:
 > I had lunch with Fred the other day, and he was worried about whether
 > anyone would garden the comments to remove spam.  That is indeed an
 > issue, but I think we can cope with that problem once a system is
 > built.
 >
 > Another worry is versioning.  Once lots of people have made comments
 > on Python 2.4.0's documentation, what do you do when 2.4.1 is
 > released?  Do you move the comments to the new docs, or leave them
 > attached to 2.4.0 and start 2.4.1 with a clean slate?  

This was actually a big part of my gardening concern: comments from the 
release X.Y.Z docs need to be handled before releasing X.Y.Z+1 or X.Y+1.*, or 
they aren't being used to improve the documentation at all.

 > (Perhaps the 
 > system could work a little like a bug tracking system; comments could
 > be marked as 'applied', and applied comments don't get moved from
 > 2.4.0 to 2.4.1 because their content is now in the docs.)

I'd be more inclined to see that comments are handled (even if handling them 
is a matter of determining that they aren't actually interesting), and just 
toss comments for a new release.  A patch release would be an occaission to 
turn off commenting on the previous releases for the same X.Y version (though 
comments would still exist in the older version).


  -Fred

-- 
Fred L. Drake, Jr.   
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] status of development documentation

[Fred L. Drake, Jr.]

On Thursday 22 December 2005 08:50, Michael Chermside wrote:
 > Money is not a very effective motivator for this sort of work. (Well,
 > in sufficient quantities it is, but the quantities required are
 > quite large.) Offering *credit* is more effective -- a mention within
 > a contributors list perhaps. 

There is a credits list for the documentation, and it's included in the HTML 
version of the formatted result as well.  Extra credit if you know where it 
is without looking, though.

 > My own favorite idea is to create a comment-on-the-docs mechanism
 > allowing both COMMENTS, and PROPOSED EDITS. The proposed edits would
 > need to be reviewed by one of a small number of skilled and dedicated

I'm unclear on what you buy with having these two labels; are comments things 
that (presumably) get ignored by the documentation editor, or are the 
proposed edits simply more specific?  If the later, I'm not sure having the 
labels helps.

(I'm also concerned that the whole thing could end up being misused as a help 
desk, littering the docs with questions about application problems.)

 > Of course, the person who REALLY gets to decide how it works isn't me;
 > it's whoever decides to spend the time to BUILD this system.

The builder certainly determines what they build, but in the longer term, 
whoever is using it to incorporate changes into the documentation will likely 
have something to say about it, since that's who determines if it actually 
gets used to improve the documentation.


  -Fred

-- 
Fred L. Drake, Jr.   
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] status of development documentation

[Facundo Batista]

2005/12/21, Phillip J. Eby <[EMAIL PROTECTED]>:

> 3. Fredrik believes that more people would participate in updating Python
> documentation if it didn't require a LaTeX toolchain or LaTeX-friendly editor.

I'm sure he's right. I'm not talking about any random user that finds
a doc bug and wants to generate a patch, here I'm talking of my own
experience:

I had to correct a few lines in the almost perfect documentation that
Raymond generated for Decimal. I fighted with my Linux (at that time,
FC1) to be able to compile the docs, and couldn't do it.

I ended touching the XML by hand. It worked, but

  a) Took some time.
  b) Wasn't really sure that it was well corrected.

So, I really think that a more human friendly format will help here.

What I do NOT know, if the effort of converting the whole docs to
another format is worth it, and that effort should be deviated to
something that will help more other users to help with docs (for
example, that the official docs could be annotatted, a la MySQL (AMK
did something like this, right?)).

Regards,

.Facundo

Blog: http://www.taniquetil.com.ar/plog/
PyAr: http://www.python.org/ar/
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] status of development documentation

[Phillip J. Eby]

At 10:27 AM 12/22/2005 +0100, Walter Dörwald wrote:
>Phillip J. Eby wrote:
>
> > [...]
> >
> > If someone has examples of actual "Pythondoc" markup that don't translate
> > to reST, I'd be really interested in seeing them, just for my own
> > education.  Of course, I'd also be curious how common such constructs are.
>
>I'm using XML markup for our packages. Examples can be found at
>[snip]

By "Pythondoc", I mean the LaTeX-based markup system being used for the 
official Python documentation, not arbitrary methods of documentation for 
Python code.


>The source is definitely wordier than reST, but adding new markup is
>trivial. Take a look at
>http://www.livinglogic.de/Python/xist/Download.html and at the source at
>http://www.livinglogic.de/Python/xist/Download.htmlxsc. The download
>element automatically determines the size of the package. Source can be
>found here
>http://www.livinglogic.de/viewcvs/index.cgi/LivingLogic/WWW-Python/site/Python_xmlns.py?rev=1.43&content-type=text/vnd.viewcvs-markup
>(search for "class download"). Would something like this be possible
>with reST?

The docutils toolchain converts reST input into a DOM, and allows arbitrary 
transformation phases to be added to processing before conversion to 
output.  This includes processing of "directives", e.g. commands like:

.. include:: filename

And of interpreted text "roles",  e.g. `Foobar`:class:.

It is not, however, a general XML transformation toolkit, if that's what 
you're asking.  However, if you wanted to be able to use XML input as part 
of a docutils DOM, you could certainly do that.  For that matter, you could 
take a reST document and simply transform it to XML for use with the rest 
of your toolset.

But this isn't particularly relevant to the discussion about *Python's* 
documentation, and I'm not even advocating that Python switch, let alone 
arbitrary other projects.

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

[Python-Dev] Patch to make unittest.TestCase easier to subclass

[Collin Winter]

Hello all!

I just submitted Patch #1388073, designed to make unittest's TestCase
class easier to subclass, and I'd appreciate a review of/feedback on
the code there.

While recently working on a subclass of unittest.TestCase to support
TODO-tests, I found a large number of __-prefixed attributes in
TestCase. The presence of these attributes meant that I had to copy
several methods over to my new subclass in order for things to work.

The patch I've provided converts these __-prefixed attributes to
_-prefixed attributes, making it much simpler to subclass TestCase.
The patch is against unittest.py from SVN revision 41775.

Included with the patch are "before" and "after" versions of my
subclass showing the impact of the change to unittest.TestCase.

Thanks,
Collin Winter
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

[Python-Dev] timeout options in high-level networking modules

[Jim Fulton]

Yesterday, I needed to make a web request in a program (actually a test)
that could block indefinately, so I needed to set a socket timeout.
Unfortunately, AFAICT none of urllib, urllib2, httplib provide options to set
the timeout on the sockets they use.  I ended up having to roll my own
code to make the request.

It would be nice if high-level network modules, like the ones mentioned
above, had options to provide a timeout.  (For example, urlopen could
grow an optional timout argument.)

Thoughts?

If we think this is a good idea, then someone who has time could start chipping
away at it.  I'm happy to work on this *if* I can find time.  This would make
a nice easy sprint project at PyCon too.

Jim

-- 
Jim Fulton   mailto:[EMAIL PROTECTED]   Python Powered!
CTO  (540) 361-1714http://www.python.org
Zope Corporation http://www.zope.com   http://www.zope.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] timeout options in high-level networking modules

[Jeremy Hylton]

Yup.  I just went through a similar exercise with urllib2.  It wasn't
too hard to plumb through a different HTTPHandler that set the
timeout, but it would be much nicer as a default option.  It seems
like a 30 minute project; might fit in an "odds and ends" sprint.

Jeremy

On 12/22/05, Jim Fulton <[EMAIL PROTECTED]> wrote:
>
> Yesterday, I needed to make a web request in a program (actually a test)
> that could block indefinately, so I needed to set a socket timeout.
> Unfortunately, AFAICT none of urllib, urllib2, httplib provide options to set
> the timeout on the sockets they use.  I ended up having to roll my own
> code to make the request.
>
> It would be nice if high-level network modules, like the ones mentioned
> above, had options to provide a timeout.  (For example, urlopen could
> grow an optional timout argument.)
>
> Thoughts?
>
> If we think this is a good idea, then someone who has time could start 
> chipping
> away at it.  I'm happy to work on this *if* I can find time.  This would make
> a nice easy sprint project at PyCon too.
>
> Jim
>
> --
> Jim Fulton   mailto:[EMAIL PROTECTED]   Python Powered!
> CTO  (540) 361-1714http://www.python.org
> Zope Corporation http://www.zope.com   http://www.zope.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/jeremy%40alum.mit.edu
>
___
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] timeout options in high-level networking modules

[Steve Holden]

Jim Fulton wrote:
> Yesterday, I needed to make a web request in a program (actually a test)
> that could block indefinately, so I needed to set a socket timeout.
> Unfortunately, AFAICT none of urllib, urllib2, httplib provide options to set
> the timeout on the sockets they use.  I ended up having to roll my own
> code to make the request.
> 
> It would be nice if high-level network modules, like the ones mentioned
> above, had options to provide a timeout.  (For example, urlopen could
> grow an optional timout argument.)
> 
> Thoughts?
> 
> If we think this is a good idea, then someone who has time could start 
> chipping
> away at it.  I'm happy to work on this *if* I can find time.  This would make
> a nice easy sprint project at PyCon too.
> 
That's a very good idea. At present the only option one has is to set a 
global socket.defaulttimout() or somehow monkey-patch the modules you 
want to use, and neither of those options are entirely satisfactory.

Basically any method that can create a new TCP connection should acquire 
an optional timeout=None parameter, right?

regards
  Steve
-- 
Steve Holden   +44 150 684 7255  +1 800 494 3119
Holden Web LLC www.holdenweb.com
PyCon TX 2006  www.python.org/pycon/

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] [Doc-SIG] status of development documentation

[Laura Creighton]

Whenever people have demanded that I write documentation in html
I have always done this:


all my documentation, as output from a text editor.

All subsequent formatting to be done by somebody else who doesn't
find dealing with html as excruciatingly painful as I do.


I suspect there are lots of people who have concluded that this
is all the html that you really need.  The question is, are you
willing to put up with documentation like this from people?

Laura
___
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] timeout options in high-level networking modules

[Charles Cazabon]

Steve Holden <[EMAIL PROTECTED]> wrote:
> Jim Fulton wrote:
> > Yesterday, I needed to make a web request in a program (actually a test)
> > that could block indefinately, so I needed to set a socket timeout.
> > Unfortunately, AFAICT none of urllib, urllib2, httplib provide options to 
> > set
> > the timeout on the sockets they use.  I ended up having to roll my own
> > code to make the request.
[...]
> That's a very good idea. At present the only option one has is to set a 
> global socket.defaulttimout() or somehow monkey-patch the modules you 
> want to use, and neither of those options are entirely satisfactory.
> 
> Basically any method that can create a new TCP connection should acquire 
> an optional timeout=None parameter, right?

Yes.  

It might also be nice if the modules that rely on blocking mode being set on
sockets (basically anything using socket.ssl()) actually explicitly set that
first.  Right now, if you do socket.setdefaulttimeout() to a non-None value
and then try to use anything that does SSL (poplib, imaplib), the connections
will quickly die.

Charles
-- 
---
Charles Cazabon   <[EMAIL PROTECTED]>
GPL'ed software available at:   http://pyropus.ca/software/
---
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

[Python-Dev] LaTeX and Python doc contributions

[Fred L. Drake, Jr.]

Just a quick note based on some of the discussion on the Doc-SIG list:

Some people are getting asked to convert their documentation contributions to 
LaTeX themselves, and that *is* a barrier to contribution.  I've generally 
stated that I'm willing to perform conversion, making plain text / ReST 
completely acceptable for documentation contributions.  Others have commonly 
converted plain text to LaTeX as well.

I'd like to make sure that Python committers know that this is reasonable; if 
the only thing holding a contribution back is LaTeXification of 
documentation, feel free to assign it to me for conversion.  I do not want 
LaTeX itself to cause us to lose documentation contributions; the hard part 
for documentation really is getting good content.  Hard workers shouldn't be 
turned away.  :-)


  -Fred

-- 
Fred L. Drake, Jr.   
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] LaTeX and Python doc contributions

[Fred L. Drake, Jr.]

On Thursday 22 December 2005 11:44, Fred L. Drake, Jr. wrote:
 > I've
 > generally stated that I'm willing to perform conversion, making plain text
 > / ReST completely acceptable for documentation contributions.  Others have
 > commonly converted plain text to LaTeX as well.

I've started a list of volunteer TeXnicians for the Python documentation:

http://www.python.org/dev/doc/

If you'd like to be on the list, please add yourself if you have commit 
privileges to the website repository, or ask webmaster at python.org to add 
you.


  -Fred

-- 
Fred L. Drake, Jr.   
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] status of development documentation

[Michael Chermside]

I wrote:
> My own favorite idea is to create a comment-on-the-docs mechanism
> allowing both COMMENTS, and PROPOSED EDITS.

Fred Drake replies:
> I'm unclear on what you buy with having these two labels; are comments things
> that (presumably) get ignored by the documentation editor, or are the
> proposed edits simply more specific?

Things that get ignored by the doc editors.

> (I'm also concerned that the whole thing could end up being misused as a help
> desk, littering the docs with questions about application problems.)

Me too. Specifically, I think if you make it really easy to write notes
on the docs you will get some helpful documentation content. You will
also get lots of things that are too lengthy or exhaustive, to specific
to one person's problem, helpdesk style questions, and probably spam. All
I meant was to allow the contributor to specify which category they think
this particular note belongs to so the doc editors can read only the ones
that people thought ought to be included in the docs.

-- Michael Chermside

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] status of development documentation

[Facundo Batista]

2005/12/22, Michael Chermside <[EMAIL PROTECTED]>:

> > (I'm also concerned that the whole thing could end up being misused as a 
> > help
> > desk, littering the docs with questions about application problems.)
>
> Me too. Specifically, I think if you make it really easy to write notes
> on the docs you will get some helpful documentation content. You will
> also get lots of things that are too lengthy or exhaustive, to specific
> to one person's problem, helpdesk style questions, and probably spam. All

I sent a mail to MySQL folks, asking them some feedback about the
dynamics of their documentation annotation system (regarding this
issues, spam, etc.). Let's see if they answer.

.Facundo

Blog: http://www.taniquetil.com.ar/plog/
PyAr: http://www.python.org/ar/
___
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] LaTeX and Python doc contributions

[skip]

Fred> Some people are getting asked to convert their documentation
Fred> contributions to LaTeX themselves...

Who is asking this of potential contributors?  I know you, Aahz and I have
repeatedly told people on c.l.py that LaTeX knowledge is not necessary.
Plain text is okay.  What do we need to do to squash this meme?

Tony & other python-dev summarizers (and maybe Cameron Laird for the c.l.py
summaries): please make a note of this in your next summary.  The
I-can't-contribute-because-I-don't-know-LaTeX notion has to die, die, die.

Skip
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] status of development documentation

[Fredrik Lundh]

Michael Chermside wrote:¨

> Me too. Specifically, I think if you make it really easy to write notes
> on the docs you will get some helpful documentation content. You will
> also get lots of things that are too lengthy or exhaustive, to specific
> to one person's problem, helpdesk style questions, and probably spam.

fwiw, the effbot.org useredit mechanism results in nice patches, suggestions,
occasional questions, and, in periods, huge amounts of spam (from spammers
who treat it as an ordinary wiki).





___
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] LaTeX and Python doc contributions

[Facundo Batista]

2005/12/22, [EMAIL PROTECTED] <[EMAIL PROTECTED]>:

> Tony & other python-dev summarizers (and maybe Cameron Laird for the c.l.py
> summaries): please make a note of this in your next summary.  The
> I-can't-contribute-because-I-don't-know-LaTeX notion has to die, die, die.

Very interesting. What I don't know here is how to submit patches...

I mean, if they were in LaTeX, a diff file would be enough. But in
plain text (or ReST), how should people specify the corrections, the
position of new paragraphs, etc?

I'm really interested in this, we've been discussing about docs in
Python Argentina and some people were willing to help (and scared
about LaTeX).

Thank you!

.Facundo

Blog: http://www.taniquetil.com.ar/plog/
PyAr: http://www.python.org/ar/
___
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] documentation comments

[Neal Norwitz]

On 12/22/05, A.M. Kuchling <[EMAIL PROTECTED]> wrote:
>
> I had lunch with Fred the other day, and he was worried about whether
> anyone would garden the comments to remove spam.

I would help assuming this is easy--meaning a single click to remove a comment.

n
___
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] timeout options in high-level networking modules

[Jim Fulton]

Steve Holden wrote:
> Jim Fulton wrote:
> 
>>Yesterday, I needed to make a web request in a program (actually a test)
>>that could block indefinately, so I needed to set a socket timeout.
>>Unfortunately, AFAICT none of urllib, urllib2, httplib provide options to set
>>the timeout on the sockets they use.  I ended up having to roll my own
>>code to make the request.
>>
>>It would be nice if high-level network modules, like the ones mentioned
>>above, had options to provide a timeout.  (For example, urlopen could
>>grow an optional timout argument.)
>>
>>Thoughts?
>>
>>If we think this is a good idea, then someone who has time could start 
>>chipping
>>away at it.  I'm happy to work on this *if* I can find time.  This would make
>>a nice easy sprint project at PyCon too.
>>
> 
> That's a very good idea. At present the only option one has is to set a 
> global socket.defaulttimout() or somehow monkey-patch the modules you 
> want to use, and neither of those options are entirely satisfactory.

Dang, I missed that. I could have abused that yesterday. :)

> Basically any method that can create a new TCP connection should acquire 
> an optional timeout=None parameter, right?

Yup, except that None shouldn't be the "I didn't pass anything"
marker, since None is a valid settimeout parameter.

Jim

-- 
Jim Fulton   mailto:[EMAIL PROTECTED]   Python Powered!
CTO  (540) 361-1714http://www.python.org
Zope Corporation http://www.zope.com   http://www.zope.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] LaTeX and Python doc contributions

[A.M. Kuchling]

On Thu, Dec 22, 2005 at 12:23:03PM -0600, [EMAIL PROTECTED] wrote:
> Who is asking this of potential contributors?  I know you, Aahz and I have
> repeatedly told people on c.l.py that LaTeX knowledge is not necessary.

One comment on a bug to this effect was found.  I don't think there's
a point in naming names -- the person in question doubtless just
wasn't aware of this policy.

--amk
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] status of development documentation

[Martin Blais]

On 12/21/05, Barry Warsaw <[EMAIL PROTECTED]> wrote:
> On Wed, 2005-12-21 at 20:36 +0100, Fredrik Lundh wrote:
>
> > I'm not really interested in optimizing for you, I'm interested in 
> > optimizing
> > for everyone else.  They already know HTML.  They don't know ReST, and
> > I doubt they care about it (how many blogs accept ReST for comments?)
>
> Sorry, but HTML and (even more so) XML are not human-writable. :)  Yeah,
> we can all do the simple stuff, but I absolutely hate authoring in HTML,
> and it would be a nightmare if the documentation production system
> didn't handle lots and lots of magic for you (like weaving in the right
> footers, css, etc. -- oh wait, that's ht2html!).
>
> reST is a fine language but it seems more suitable to simpler linear
> documents like wiki pages and PEPs, rather than those with complicated
> nested structure.
>
> Maybe it's just because I came in late on this thread, but what exactly
> is broken about the current LaTeX documentation?
>
> -Barry

Good point.

Nothing is really "broken", but it's just not flexible because there
is no way to get a solid document model from LaTeX to do some
conversion and processing on.  i.e. you convert from LaTeX direct to
the output.  Having the intermediate representation would allow
generating nicer output, and in more formats, without necessarily
having to reparse the input everytime either.

What we need is not necessarily a change of syntax: the problem is not
the input, it's the conversion.  The input is fine--if someone can't
learn the super simple LaTeX macros for the Python docs, I don't want
to imagine what kind of prose they would come up with.  LaTeX is NOT
hard, at least if you limit yourself to the stuff you need to document
Python code.

About ReST:

Somehow there is a recurrent stream of people--include me at some
point-- who think that ReST could express any document structure for
any task, and that if we use that we will be happy ever after.  ReST
does an amazing job of inferring generic document structures from
text, but for documenting source code, you really want to be able to
say "This is a function", "this is an optional argument", etc.  ReST
does not provide this kind of functionality, and if you try to stretch
the interpreted roles to do this you get an equally ugly syntax as
LaTeX input (I would even argue that I prefer the LaTeX source).

Also, ReST has many gotchas: if you will infer structures from
invisible markup, it's very easy to make mistakes, and there are many
cases where it's not clear what the parsed document will be like, you
have to "learn" a lot of how it parses the documents, and the corner
cases, by checking with rst2pseudoxml.py.  I'm facing this problem
with some of my Nabu extractors, which attempts to extract
semantically meaningful chunks out of the docutils tree, for example,
contact information.

If there is a problem it is not the input, it's the toolchain and conversion.
___
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] timeout options in high-level networking modules

[Akradiusz Miskiewicz]

Charles Cazabon wrote:

> It might also be nice if the modules that rely on blocking mode being set
> on sockets (basically anything using socket.ssl()) actually explicitly set
> that
> first.  Right now, if you do socket.setdefaulttimeout() to a non-None
> value and then try to use anything that does SSL (poplib, imaplib), the
> connections will quickly die.
There is a patch for that in python patch tracking system. Just someone
needs to recheck it and apply.

> 
> Charles


___
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] LaTeX and Python doc contributions

[Fred L. Drake, Jr.]

On Thursday 22 December 2005 13:39, Facundo Batista wrote:
 > Very interesting. What I don't know here is how to submit patches...

"Patches" certainly isn't the right word for changes not described as source 
diffs.  I cleaned up some text about that on python.org earlier.

 > I mean, if they were in LaTeX, a diff file would be enough. But in
 > plain text (or ReST), how should people specify the corrections, the
 > position of new paragraphs, etc?

In English is fine.  I'd expect something like: in the section on imaplib, 
before the paragraph starting with "...".  I often get descriptions like this 
when people point out typos to the docs at python.org address; it works well, 
and has almost no barriers to entry at all.

 > I'm really interested in this, we've been discussing about docs in
 > Python Argentina and some people were willing to help (and scared
 > about LaTeX).

Hopefully we can make sure it's easy for everyone to contribute.  I'm 
certainly interested in suggestions, though I make all of them happen.


  -Fred

-- 
Fred L. Drake, Jr.   
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] LaTeX and Python doc contributions

[Fred L. Drake, Jr.]

On Thursday 22 December 2005 13:23, [EMAIL PROTECTED] wrote:
 > Who is asking this of potential contributors?  I know you, Aahz and I have
 > repeatedly told people on c.l.py that LaTeX knowledge is not necessary.
 > Plain text is okay.  What do we need to do to squash this meme?

As Andrew noted, it doesn't really matter who it was.  That person is now 
aware of what's going on, I think.  :-)

I've added a note to the "developer's intro," and there should probably be a 
note in the development FAQ as well.

 > Tony & other python-dev summarizers (and maybe Cameron Laird for the
 > c.l.py summaries): please make a note of this in your next summary.  The
 > I-can't-contribute-because-I-don't-know-LaTeX notion has to die, die, die.

An excellent idea!


  -Fred

-- 
Fred L. Drake, Jr.   
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] documentation comments

[Fred L. Drake, Jr.]

On Thursday 22 December 2005 13:44, Neal Norwitz wrote:
 > I would help assuming this is easy--meaning a single click to remove a
 > comment.

It looks like the system the MySQL folks are using makes it easy, but I've not 
tried polluting their documentation with tests, just in case.  :-)

In general, my worry is less with dealing with spam than with ensuring 
integration of content enhancements before release candidates go out.


  -Fred

-- 
Fred L. Drake, Jr.   
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

[Python-Dev] reST limitations? (was Re: status of development documentation)

[Phillip J. Eby]

At 04:08 PM 12/22/2005 -0500, Martin Blais wrote:
>ReST does an amazing job of inferring generic document structures from
>text, but for documenting source code, you really want to be able to
>say "This is a function", "this is an optional argument", etc.  ReST
>does not provide this kind of functionality, and if you try to stretch
>the interpreted roles to do this you get an equally ugly syntax as
>LaTeX input (I would even argue that I prefer the LaTeX source).

That sounds like a misuse of the tool to me; if you need structured, 
extractable information from a reST document, fields and directives are 
probably going to be the way to go.  Similarly, I'd suggest that 
interpreted roles to identify the context of a name probably isn't the best 
way to go about it either; a link to the definition of the referenced item 
will be more useful and more uniform.  A formatter or intermediate 
processor can then decide whether it should actually be rendered as a 
hyperlink, a fully-qualified name, or just the function/method/class name.

So, definitions of functions, classes, and other structured stuff would 
just use fields under a directive, and references to those definitions 
would just be reST links.


>Also, ReST has many gotchas: if you will infer structures from
>invisible markup, it's very easy to make mistakes, and there are many
>cases where it's not clear what the parsed document will be like, you
>have to "learn" a lot of how it parses the documents, and the corner
>cases, by checking with rst2pseudoxml.py.

Huh?  I've never used rst2pseudoxml.py, so I don't understand how it's a 
requirement.  Do you mean, if you're writing some kind of reST processor 
it's helpful to understand how stuff is parsed?

Can you list some of these "gotchas"?  I've on maybe two occasions had to 
add a backslash to something to prevent it being interpreted as markup, and 
that's about it, although I've written many hundreds of K of Python 
documentation in reST.  (Not the Python core documentation, but other open 
source projects written in Python.)

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] status of development documentation

[Walter Dörwald]

Phillip J. Eby wrote:

> At 10:27 AM 12/22/2005 +0100, Walter Dörwald wrote:
>> Phillip J. Eby wrote:
>>
>> > [...]
>> >
>> > If someone has examples of actual "Pythondoc" markup that don't 
>> translate
>> > to reST, I'd be really interested in seeing them, just for my own
>> > education.  Of course, I'd also be curious how common such 
>> constructs are.
>>
>> I'm using XML markup for our packages. Examples can be found at
>> [snip]
> 
> By "Pythondoc", I mean the LaTeX-based markup system being used for the 
> official Python documentation, not arbitrary methods of documentation 
> for Python code.

OK, I didn't realize that.

I guess the only thing compatible with LaTeX is LaTeX.

I'd really like to see a version of Fred's XML converter that works for 
the current Python documentation.

>> The source is definitely wordier than reST, but adding new markup is
>> trivial. Take a look at
>> http://www.livinglogic.de/Python/xist/Download.html and at the source at
>> http://www.livinglogic.de/Python/xist/Download.htmlxsc. The download
>> element automatically determines the size of the package. Source can be
>> found here
>> http://www.livinglogic.de/viewcvs/index.cgi/LivingLogic/WWW-Python/site/Python_xmlns.py?rev=1.43&content-type=text/vnd.viewcvs-markup
>>  
>>
>> (search for "class download"). Would something like this be possible
>> with reST?
> 
> The docutils toolchain converts reST input into a DOM, and allows 
> arbitrary transformation phases to be added to processing before 
> conversion to output.  This includes processing of "directives", e.g. 
> commands like:
> 
> .. include:: filename
> 
> And of interpreted text "roles",  e.g. `Foobar`:class:.

This sound like it should be possible.

> It is not, however, a general XML transformation toolkit, if that's what 
> you're asking.  However, if you wanted to be able to use XML input as 
> part of a docutils DOM, you could certainly do that.

More the other way around.

> For that matter, 
> you could take a reST document and simply transform it to XML for use 
> with the rest of your toolset.

That's the way I'd like to use docutils: Write docstring in reST and 
transform them via XML tools.

> But this isn't particularly relevant to the discussion about *Python's* 
> documentation, and I'm not even advocating that Python switch, let alone 
> arbitrary other projects.

If we had a way to losslessly convert Python-LaTeX to XML tools for both 
system could live side by side.

Bye,
Walter Dörwald

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] reST limitations? (was Re: status of development documentation)

[Martin Blais]

On 12/22/05, Phillip J. Eby <[EMAIL PROTECTED]> wrote:
> At 04:08 PM 12/22/2005 -0500, Martin Blais wrote:
> >ReST does an amazing job of inferring generic document structures from
> >text, but for documenting source code, you really want to be able to
> >say "This is a function", "this is an optional argument", etc.  ReST
> >does not provide this kind of functionality, and if you try to stretch
> >the interpreted roles to do this you get an equally ugly syntax as
> >LaTeX input (I would even argue that I prefer the LaTeX source).
>
> That sounds like a misuse of the tool to me; if you need structured,
> extractable information from a reST document, fields and directives are
> probably going to be the way to go.  Similarly, I'd suggest that
> interpreted roles to identify the context of a name probably isn't the best
> way to go about it either; a link to the definition of the referenced item
> will be more useful and more uniform.  A formatter or intermediate
> processor can then decide whether it should actually be rendered as a
> hyperlink, a fully-qualified name, or just the function/method/class name.
>
> So, definitions of functions, classes, and other structured stuff would
> just use fields under a directive, and references to those definitions
> would just be reST links.

So you end up with a document with a bunch of custom directives, like::

.. python-class::  MyClass
   :arg: comfobulator
   :arg optional: bliptor

   My Class description.

This does not look significantly better to me than the LaTeX code, and
the docutils directives are not as flexible as the commands provided
by tex/latex.



> >Also, ReST has many gotchas: if you will infer structures from
> >invisible markup, it's very easy to make mistakes, and there are many
> >cases where it's not clear what the parsed document will be like, you
> >have to "learn" a lot of how it parses the documents, and the corner
> >cases, by checking with rst2pseudoxml.py.
>
> Huh?  I've never used rst2pseudoxml.py, so I don't understand how it's a
> requirement.  Do you mean, if you're writing some kind of reST processor
> it's helpful to understand how stuff is parsed?

It is if you're relying on specific document structures to provide
information about your special constructs.  rst2pseudoxml.py just
helps you display that parsed structure.

For example, you could write some kind of processor on the docutils
document tree that looks for definition lists whose "term" starts with
"class" and then assumes some other things about what it will find in
the body of this definition, e.g.

class MyClass
  

(this gets parsed as a ReST definition term/body because of the
indented line right after the "class MyClass" line).

I'm doing this kind of processing, albeit in a limited way, to extract
book reviews, bookmarks, and contact info from a body of text files
that I maintain, using my nabu system (http://furius.ca/nabu/  come to
my talk at PyCon for mode details).  This might be a better way to
hijack ReST than to create a gazillion custom directives, thereby
creating more or less another markup language (with a smaller
userbase, less tested!).


> Can you list some of these "gotchas"?  I've on maybe two occasions had to
> add a backslash to something to prevent it being interpreted as markup, and
> that's about it, although I've written many hundreds of K of Python
> documentation in reST.  (Not the Python core documentation, but other open
> source projects written in Python.)

Lots. No time to go through the whole list now, but here is an example:

-
..
  Some text
-

and

-
..

  Some text
-

Generate the following document structures, respectively:


Some text

and




Some text

One is a comment, the other is an empty comment followed by a block
quote.  Not very obvious to me, unless you know "the rules".  Easy to
make mistakes.  There are *many* other issues just like this one.  
Pop quiz: what does this generate?

-
..
  Some text

  Some other text
-
___
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] LaTeX and Python doc contributions

[Stephen J. Turnbull]

> "Fred" == Fred L Drake, <[EMAIL PROTECTED]> writes:

Fred> On Thursday 22 December 2005 13:23, [EMAIL PROTECTED] wrote:

>> Who is asking this of potential contributors?  I know you, Aahz
>> and I have repeatedly told people on c.l.py that LaTeX
>> knowledge is not necessary.  Plain text is okay.  What do we
>> need to do to squash this meme?

Fred> As Andrew noted, it doesn't really matter who it was.

I interpreted Skip's first question as 100% rhetorical.

I think one aspect of the meme is that projects generally strongly
emphasize standard-format patches to source for code.  But this is
typically less important for documentation, where good and consistent
natural language style probably means that the editor applies the
patch, and then revises in place rather than requesting a revision
from the contributor.

I don't know whether that distinction helps with creating a vaccine,
though.  I don't see an obvious application beyond the suggestion of
saying "patches aren't necessary" more frequently and prominently.

-- 
School of Systems and Information Engineering http://turnbull.sk.tsukuba.ac.jp
University of TsukubaTennodai 1-1-1 Tsukuba 305-8573 JAPAN
   Ask not how you can "do" free software business;
  ask what your business can "do for" free software.
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] status of development documentation

[Nick Coghlan]

Facundo Batista wrote:
> 2005/12/21, Phillip J. Eby <[EMAIL PROTECTED]>:
> 
>> 3. Fredrik believes that more people would participate in updating Python
>> documentation if it didn't require a LaTeX toolchain or LaTeX-friendly 
>> editor.
> 
> I'm sure he's right. I'm not talking about any random user that finds
> a doc bug and wants to generate a patch, here I'm talking of my own
> experience:
> 
> I had to correct a few lines in the almost perfect documentation that
> Raymond generated for Decimal. I fighted with my Linux (at that time,
> FC1) to be able to compile the docs, and couldn't do it.
> 
> I ended touching the XML by hand. It worked, but
> 
>   a) Took some time.
>   b) Wasn't really sure that it was well corrected.
> 
> So, I really think that a more human friendly format will help here.
> 
> What I do NOT know, if the effort of converting the whole docs to
> another format is worth it, and that effort should be deviated to
> something that will help more other users to help with docs (for
> example, that the official docs could be annotatted, a la MySQL (AMK
> did something like this, right?)).

If I remember rightly, the biggest problem I had in the whole exercise was 
getting latex2html to run - I actually had to modify the Perl source to get it 
to work (fortunately, I didn't have to try to *understand* said source first - 
other people had already figured out the necessary incantations, so I was able 
to find out how to fix it via a Google search).

latex/tex weren't a big problem, because they were in the distro archives - 
but latex2html was a definite pain.

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] status of development documentation

[Robey Pointer]

On 22 Dec 2005, at 3:51, Michael Hudson wrote:

> "Fredrik Lundh" <[EMAIL PROTECTED]> writes:
>
>> Checked the python-list archives lately?  If you google c.l.python  
>> for the
>> word "documentation", you'll find recent megathreads with subjects  
>> like
>> "bitching about the documentation", "opensource documentation  
>> problems"
>> and "python documentation should be better" among the top hits.   
>> But if
>> you check the bug and patch trackers, you don't find many  
>> contributions.
>> Something's definitely broken.
>
> Hmm, it's this discussion again!  Let me make my point again!
>
> Writing good documentation is hard.

I can only speak for my own experience, but maybe it will help.  I  
once tried to help fix a piece of the python docs.  The description  
of Py_UNICODE on  was  
-- and still is -- incorrect.

Looking through my mail archives, I sent a patch on 10 October, which  
was apparently taken, but never showed up on the web site.  I emailed  
a few reminders, but was eventually told that I should email a third  
person -- who didn't have an email address.  At that point I passed  
the level of effort I was willing to put in. :)  I think I probably  
put more effort into it than an average person would, so I think the  
barriers of entry are much higher than they should be.

Perhaps something with fast feedback would work a lot better.  It  
seems to work well for Wikipedia.

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