Docutils: Documentation Utilities

On Tue, Nov 25, 2008 at 15:34, Georg Brandl <g.brandl@...> wrote:
> in order to get more people porting and testing things on Python 3000,
> I want to start by getting Sphinx running on it.  That requires having
> Docutils.
>
> I'd like to port the Docutils to Python 3000.  Assuming you all are OK
> with that,

I am.

> how should we organize that?  Since the Docutils have quite
> strict compatibility requirements,

What do you mean?

> it is very probably not sensible to
> use the "on codebase from which the 3000 version is converted by 2to3"
> strategy.

I don't know if that will work or not -- it might!

> Therefore, I propose the Python model: a separate branch in
> the repository into which new changes in the trunk are merged with the
> svnmerge tool.  If that's fine, should the branch be in /branches/, or
> in /trunk/sandbox/?

If we need a branch, I think /branches/ would be best.

-- 
David Goodger <http://python.net/~goodger>

David Goodger schrieb:
> On Tue, Nov 25, 2008 at 15:34, Georg Brandl <g.brandl@...> wrote:
>> in order to get more people porting and testing things on Python 3000,
>> I want to start by getting Sphinx running on it.  That requires having
>> Docutils.
>>
>> I'd like to port the Docutils to Python 3000.  Assuming you all are OK
>> with that,
> 
> I am.
 >
>> how should we organize that?  Since the Docutils have quite
>> strict compatibility requirements,
> 
> What do you mean?
 >
>> it is very probably not sensible to
>> use the "on codebase from which the 3000 version is converted by 2to3"
>> strategy.
> 
> I don't know if that will work or not -- it might!

The website says that Python 2.2 is still supported. Since the "single
codebase" strategy relies on the 2to3 conversion doing everything needed
to make it run on 3k, the more backwards compatible you have to stay,
the more impossible this is.  It works best for code that only needs to
run on 2.6, which is of course not possible for Docutils.

There might be a way to do it, using two converters: one to 2.x, one to
3.x code.

>> Therefore, I propose the Python model: a separate branch in
>> the repository into which new changes in the trunk are merged with the
>> svnmerge tool.  If that's fine, should the branch be in /branches/, or
>> in /trunk/sandbox/?
> 
> If we need a branch, I think /branches/ would be best.

Ok.

Georg

Just a comment on this thread.

Some time ago I wanted docutils on Python 3.0.
At the time the 2to3 tool was not working for me,
so I did it by hand.  It took about an hour
to get it working well enough for my purposes then.
Almost all the changes were trivial.

Working from memory, there were the following
problems.
- change print to function
- a small number of places required changing
   the exception handling to the new syntax
- a few places where unicode string handling
   had to be changed
- one change in package name in the standard library

Almost all of this should be trivial for the 2to3 tool.
There might be a few places for minor changes to help
the tool along.  Unfortunately there was some subtlety
with unicode string handling at one point, but I'd
have to dig back to figure out what it was.

Bottom line: I suspect it is quite feasible to make
some cosmetic changes to the code base and then
just work with the 2to3 tool.

fwiw,
Alan Isaac

Georg Brandl schrieb:
> Hi,
> 
> in order to get more people porting and testing things on Python 3000,
> I want to start by getting Sphinx running on it.  That requires having
> Docutils.

OK, after the encouraging post from Alan I'll try to find a way to let
2to3 do all the work.  It may also be possible to write custom fixers
for 2to3 that fix things the stock tool can't generally do.

I'll send patches for some changes that can be made without breaking any
compatibility.

The first removes all unnecessary use of the "types" module whose trivial
attributes like StringType are gone in 3k.

Usage of ClassType remains however and must (ATM) be fixed manually.

Georg

Georg Brandl schrieb:
> Hi,
> 
> in order to get more people porting and testing things on Python 3000,
> I want to start by getting Sphinx running on it.  That requires having
> Docutils.

Second (shorter) patch: get rid of os.path.walk.

Georg

Georg Brandl schrieb:
> Hi,
> 
> in order to get more people porting and testing things on Python 3000,
> I want to start by getting Sphinx running on it.  That requires having
> Docutils.

Third, even more trivial patch: return a boolean from __nonzero__.

Georg

On Thu, 27 Nov 2008, Georg Brandl wrote:

> Georg Brandl schrieb:
>> Hi,
>> 
>> in order to get more people porting and testing things on Python 3000,
>> I want to start by getting Sphinx running on it.  That requires having
>> Docutils.
>
> OK, after the encouraging post from Alan I'll try to find a way to let
> 2to3 do all the work.  It may also be possible to write custom fixers
> for 2to3 that fix things the stock tool can't generally do.
>
> I'll send patches for some changes that can be made without breaking any
> compatibility.
>
> The first removes all unnecessary use of the "types" module whose trivial
> attributes like StringType are gone in 3k.
>
> Usage of ClassType remains however and must (ATM) be fixed manually.

in python2.2 slice is a built-in function i guess that is why
it says 'TypeError: isinstance() arg 2 must be a class, type, or tuple of 
classes and types'

you could post the patches to sourceforge maybe , then we have a clearer 
subject line (and we might get bigger numbers on the change counters). but 
this is up to you

cheers


--

On Thu, 27 Nov 2008, Georg Brandl wrote:

> Georg Brandl schrieb:
>> Hi,
>> 
>> in order to get more people porting and testing things on Python 3000,
>> I want to start by getting Sphinx running on it.  That requires having
>> Docutils.
>
> OK, after the encouraging post from Alan I'll try to find a way to let
> 2to3 do all the work.  It may also be possible to write custom fixers
> for 2to3 that fix things the stock tool can't generally do.
>
> I'll send patches for some changes that can be made without breaking any
> compatibility.
>
> The first removes all unnecessary use of the "types" module whose trivial
> attributes like StringType are gone in 3k.
>
> Usage of ClassType remains however and must (ATM) be fixed manually.

add SliceType to this.

the rest is committed.

thanks

--

On Thu, 27 Nov 2008, Georg Brandl wrote:

> Georg Brandl schrieb:
>> Hi,
>> 
>> in order to get more people porting and testing things on Python 3000,
>> I want to start by getting Sphinx running on it.  That requires having
>> Docutils.
>
> Second (shorter) patch: get rid of os.path.walk.

2.2 does not have os.walk, i did put some try/except into fro 2.2.

cheers

--

On Thu, 27 Nov 2008, Georg Brandl wrote:

> Georg Brandl schrieb:
>> Hi,
>> 
>> in order to get more people porting and testing things on Python 3000,
>> I want to start by getting Sphinx running on it.  That requires having
>> Docutils.
>
> Third, even more trivial patch: return a boolean from __nonzero__.

committed all three (as far as possible)

cheers
--

grubert@... schrieb:
> On Thu, 27 Nov 2008, Georg Brandl wrote:
> 
>> Georg Brandl schrieb:
>>> Hi,
>>> 
>>> in order to get more people porting and testing things on Python 3000,
>>> I want to start by getting Sphinx running on it.  That requires having
>>> Docutils.
>>
>> OK, after the encouraging post from Alan I'll try to find a way to let
>> 2to3 do all the work.  It may also be possible to write custom fixers
>> for 2to3 that fix things the stock tool can't generally do.
>>
>> I'll send patches for some changes that can be made without breaking any
>> compatibility.
>>
>> The first removes all unnecessary use of the "types" module whose trivial
>> attributes like StringType are gone in 3k.
>>
>> Usage of ClassType remains however and must (ATM) be fixed manually.
> 
> in python2.2 slice is a built-in function i guess that is why
> it says 'TypeError: isinstance() arg 2 must be a class, type, or tuple of 
> classes and types'

OK, I didn't test that here. Maybe I really should build a Python 2.2 :-)

Related question: For how long will the 2.2 compatibility requirement be
upheld?

> you could post the patches to sourceforge maybe , then we have a clearer 
> subject line (and we might get bigger numbers on the change counters). but 
> this is up to you

I will if you insist, but I thought I'd spare everyone the trouble that is
using SourceForge ;-)

Georg

-- 
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.

Hello all,

Georg Brandl asked Sunday, 30.11.2008 at 11:52:
...
> OK, I didn't test that here. Maybe I really should build a Python 2.2 :-)
> 
> Related question: For how long will the 2.2 compatibility requirement be
> upheld?

Disclaimer: I can't speak for the docutils development, because I
didn't contribute anything here during the last years.

I'm working as a software developer since 1986.  With my personal
experience I would say that keeping backward compatibility has
been proven to be a very worthwhile good which shouldn't be dropped
lightheaded.

My company has still customers out there running rather old systems
where Python 1.5.2 was the default /usr/bin/python included with the
OS distribution.  ;-)  Fortunately we are using doc-utils only inhouse
and the oldest server in use with has already Python 2.4.3.

As general rules of thumb for packages trying to gain good platform 
portability I would suggest the following: 

 * Don't rely on any new programming language features, unless
   they were available eight years ago.

 * Don't rely on operating system features, unless they were available
   ten years ago.

Of course there is always the option to work around such self imposed
restrictions by creating and distributing emulation layers or converters 
together with a package in order to cover any hastles introduced due 
to new concepts for any people needing to use the packages on old systems.  

As docutils is OSS, people needing this backward compatibility should also
be willing to provide patches providing such things.  

Regards, Peter
-- 
Peter Funk, Oldenburger Str.86, D-27777 Ganderkesee, Germany; office: 
ArtCom GmbH, Lise-Meitner-Str. 5, D-28359 Bremen, Germany, tel: +49-421-20419-0
<http://www.artcom-gmbh.de/>

On Sun, 30 Nov 2008, Georg Brandl wrote:

> grubert@... schrieb:
>> On Thu, 27 Nov 2008, Georg Brandl wrote:
>>
>>> Georg Brandl schrieb:
>>>> Hi,
>>>>
>>>> in order to get more people porting and testing things on Python 3000,
>>>> I want to start by getting Sphinx running on it.  That requires having
>>>> Docutils.
>>>
>>> OK, after the encouraging post from Alan I'll try to find a way to let
>>> 2to3 do all the work.  It may also be possible to write custom fixers
>>> for 2to3 that fix things the stock tool can't generally do.
>>>
>>> I'll send patches for some changes that can be made without breaking any
>>> compatibility.
>>>
>>> The first removes all unnecessary use of the "types" module whose trivial
>>> attributes like StringType are gone in 3k.
>>>
>>> Usage of ClassType remains however and must (ATM) be fixed manually.
>>
>> in python2.2 slice is a built-in function i guess that is why
>> it says 'TypeError: isinstance() arg 2 must be a class, type, or tuple of
>> classes and types'
>
> OK, I didn't test that here. Maybe I really should build a Python 2.2 :-)

run the tests now and then against 2.2 to 2.6.
i will do it more often if need arises or someone requests

> Related question: For how long will the 2.2 compatibility requirement be
> upheld?

no idea. the longer the better i think.

>> you could post the patches to sourceforge maybe , then we have a clearer
>> subject line (and we might get bigger numbers on the change counters). but
>> this is up to you
>
> I will if you insist, but I thought I'd spare everyone the trouble that is
> using SourceForge ;-)

it is not mandatory in this project, if you dont wantg to, patches might 
get lost easier in email.

all the best
--

On Sun, Nov 30, 2008 at 05:52, Georg Brandl <g.brandl@...> wrote:
> Related question: For how long will the 2.2 compatibility requirement be
> upheld?

We could drop Python 2.2 compatibility for Docutils 0.6+. Any objections?

>> you could post the patches to sourceforge maybe , then we have a clearer
>> subject line (and we might get bigger numbers on the change counters). but
>> this is up to you
>
> I will if you insist, but I thought I'd spare everyone the trouble that is
> using SourceForge ;-)

Patches that are sent to mailing lists are sometimes lost. We should
use the same rules as python-dev.

And SF isn't *that* bad. ;-)

-- 
David Goodger <http://python.net/~goodger>

On Sun, Nov 30, 2008, David Goodger wrote:
> On Sun, Nov 30, 2008 at 05:52, Georg Brandl <g.brandl@...> wrote:
>>
>> Related question: For how long will the 2.2 compatibility requirement be
>> upheld?
> 
> We could drop Python 2.2 compatibility for Docutils 0.6+. Any objections?

Works for me: 2.2 was released 12/2001 and 2.3 was released 7/2003.
-- 
Aahz (aahz@...)           <*>         http://www.pythoncraft.com/

"It is easier to optimize correct code than to correct optimized code."
--Bill Harlan

David Goodger schrieb:
> On Sun, Nov 30, 2008 at 05:52, Georg Brandl <g.brandl@...> wrote:
>> Related question: For how long will the 2.2 compatibility requirement be
>> upheld?
> 
> We could drop Python 2.2 compatibility for Docutils 0.6+. Any objections?

So, can I assume this to be decided?  I'll remove the compatibility workarounds
then and continue :)

Georg

-- 
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.

On Mon, 15 Dec 2008, Georg Brandl wrote:

> David Goodger schrieb:
>> On Sun, Nov 30, 2008 at 05:52, Georg Brandl <g.brandl@...> wrote:
>>> Related question: For how long will the 2.2 compatibility requirement be
>>> upheld?
>>
>> We could drop Python 2.2 compatibility for Docutils 0.6+. Any objections?
>
> So, can I assume this to be decided?  I'll remove the compatibility workarounds
> then and continue :)

I would remove things that are in the way, and leave anything else

engelbert

--

On Mon, Dec 15, 2008 at 04:08, Georg Brandl <g.brandl@...> wrote:
> David Goodger schrieb:
>> On Sun, Nov 30, 2008 at 05:52, Georg Brandl <g.brandl@...> wrote:
>>> Related question: For how long will the 2.2 compatibility requirement be
>>> upheld?
>>
>> We could drop Python 2.2 compatibility for Docutils 0.6+. Any objections?
>
> So, can I assume this to be decided?

Yes. Docutils 0.6+ will require Python 2.3+.

> I'll remove the compatibility workarounds then and continue :)

Please proceed with caution. :-)

-- 
David Goodger <http://python.net/~goodger>