docutils-users — General discussions, questions, help requests.

[Docutils-users] Programming reference documentation

[Ian B. <ia...@co...>]

I'm working with the Webware project (webware.sf.net), and we really
need some cohesive reference documentation, aimed particularly at the
public interfaces.  I'm wondering if anyone is using docutils for this
now... if so, I'd like to see how it's working.  It's not entirely clear
to me what docutils status is (I've used reST a lot, but not much else).

Some options I've considered, in order of complexity:
* Writing the whole thing in reST, separate from the code itself.  The 
  writing wouldn't be so bad, but the maintenance would be more 
  difficult.
* Splitting it up into modules, and putting the entire reference 
  documentation in the module docstring.
* Using internal references in those docstrings, so I could effectively
  include the docstrings from other portions of code (classes, methods, 
  etc).

One thing I *don't* like is reference documentation in the style of
pydoc.  To me it's too automatic, and generally too hard to follow.  I
find reference documentation with some framework of text (lead-in
paragraphs, categorization, etc) to be much better.  There are also
methods which, while "public" aren't actually useful, and I don't think
those should be documented -- they are just distracting.

So the last option is the one I like the most.  But I doubt it's in
place.  I've already decided I'm not going to get the reference
documentation done for the next release (there's other documentation
that needs to be written, and documentation is tiring :), so I don't
plan to use this in the short term and I could put some work into
producing a system I like.

My vision for a docstring-based reference documentation would probably
look like:

"""
Module
======

This module does X, Y, Z.  Most work will be done through the class:

.. docstring:: MainClass

In certain cases you may wish to access the functionality separately, 
yada yada yada, and may wish to use:

.. docstring:: some_function
.. docstring:: some_other_function
"""

class MainClass:
    """
    Recursively we continue, now with methods:

    .. docstring:: MainClass.some_method
    """



How far away might this be?  Are there better alternatives already in
place, or planned on?  Does someone experienced in writing reference
documentation think this is the wrong way to go about it?


-- 
Ian Bicking           Colorstudy Web Development
ia...@co...   http://www.colorstudy.com
PGP: gpg --keyserver pgp.mit.edu --recv-keys 0x9B9E28B7
4869 N Talman Ave, Chicago, IL 60625 / (773) 275-7241

Re: [Docutils-users] uncaught exception from buildhtml.py

[David G. <go...@py...>]

Bruce Smith wrote:
> I'm getting an uncaught exception from buildhtml.py in the docutils
> snapshot of Jan 8th evening.

Fixed now I believe.  Please give the latest snapshot a try.

-- David Goodger    http://starship.python.net/~goodger

[Docutils-users] uncaught exception from buildhtml.py

[<br...@or...>]

I'm getting an uncaught exception from buildhtml.py in the docutils
snapshot of Jan 8th evening.

  http://docutils.sf.net/docutils-snapshot.tgz
  
(This is not quite the latest version, but the problem doesn't sound
related to the changes reported on the list since then.)

This is in the python 2.2 that ships with Mac OS X 10.2.3 as /usr/bin/python.

Here's a small input file and the exception it triggers:


% cat bug3.txt
Ways of encoding string length
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. _lengthed-string: `lengthed string`_

.. _unlengthed-string: `unlengthed string`_

.. ### the above might work as external anchors (I don't know yet),
.. # but earlier forms (which have no explicit target but just
.. # precede the targets below) did not work as external anchors,
.. # since the HTML targets used were "The" and "permits".

.. # ... but it turns out that the above forms (might) trigger an uncaught exception!


.. _lengthed string: The_

.. _unlengthed string: permits_

.. # those above links are a kluge! But I don't know a better valid way of
.. # getting what I want, which is an inline target that displays nothing.


The definition of lengthed string is like this.

But use of an unlengthed string permits that.

[end]


% /downloads/python/docutils/tools/buildhtml.py
/// Processing directory: /Users/bruce/Documents
    ::: Processing .txt: bug3.txt
Traceback (most recent call last):
  File "/downloads/python/docutils/tools/buildhtml.py", line 218, in ?
    Builder().run()
  File "/downloads/python/docutils/tools/buildhtml.py", line 162, in run
    os.path.walk(directory, self.visit, recurse)
  File "/usr/lib/python2.2/posixpath.py", line 279, in walk
    func(arg, top, names)
  File "/downloads/python/docutils/tools/buildhtml.py", line 174, in visit
    self.process_txt(directory, name)
  File "/downloads/python/docutils/tools/buildhtml.py", line 193, in process_txt
    settings=settings)
  File "/usr/lib/python2.2/site-packages/docutils/core.py", line 275, in publish_file
    pub.publish()
  File "/usr/lib/python2.2/site-packages/docutils/core.py", line 173, in publish
    self.apply_transforms(document)
  File "/usr/lib/python2.2/site-packages/docutils/core.py", line 157, in apply_transforms
    document.transformer.apply_transforms()
  File "/usr/lib/python2.2/site-packages/docutils/transforms/__init__.py", line 165, in apply_transforms
    transform.apply()
  File "/usr/lib/python2.2/site-packages/docutils/transforms/references.py", line 212, in apply
    self.resolve_indirect_target(target)
  File "/usr/lib/python2.2/site-packages/docutils/transforms/references.py", line 224, in resolve_indirect_target
    self.one_indirect_target(reftarget) # multiply indirect
AttributeError: IndirectHyperlinks instance has no attribute 'one_indirect_target'
Exit 1

%


- Bruce Smith

[Docutils-users] Re: is sf down?

[David G. <go...@py...>]

Anonymous CVS access is still down, but I've fixed the hourly update script
so that it no longer clobbers good snapshots with bad.  I will manually
update the snapshots as required until SF's anon CVS is back up.

-- David Goodger    go...@py...

RE: [Docutils-users] is sf down?

[Mark M. <mar...@mc...>]

[David Goodger]
> Done.  Take a look in <http://docutils.sourceforge.net/tmp/>.

Thank you *so* much!

Cheers,

// m

p.s. I assume the 2002 in the filename is a typo?  Looking in the contents,
it appears so.

-

Re: [Docutils-users] is sf down?

[David G. <go...@py...>]

Mark McEahern wrote:
>> Is sourceforge CVS access down?  How can I get the latest dev snapshot?
> 
> Yes, it appears anonymous CVS access to sf.net is down:
> 
>    http://sourceforge.net/docman/display_doc.php?docid=2352&group_id=1#cvs
> 
> Unfortunately, the latest dev snapshot is an empty file--I assume because
> some cron job creates it from anonymous CVS?

Yes.  It's a shell script that doesn't know when to stop.  Someday it ought
to be rewritten it in Python...

> Can someone with dev access to CVS put a copy of the latest dev snapshot
> here and make it so that's not wiped out by some automated process that
> reads via anonymous CVS (assuming my conjecture is true):

Done.  Take a look in <http://docutils.sourceforge.net/tmp/>.

-- 
David Goodger  <go...@py...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

RE: [Docutils-users] is sf down?

[Mark M. <mar...@mc...>]

[Me]
> Is sourceforge CVS access down?  How can I get the latest dev snapshot?

Yes, it appears anonymous CVS access to sf.net is down:

  http://sourceforge.net/docman/display_doc.php?docid=2352&group_id=1#cvs

Unfortunately, the latest dev snapshot is an empty file--I assume because
some cron job creates it from anonymous CVS?

Can someone with dev access to CVS put a copy of the latest dev snapshot
here and make it so that's not wiped out by some automated process that
reads via anonymous CVS (assuming my conjecture is true):

  http://docutils.sourceforge.net/#the-sandbox

Please.  Pretty please.

The latest dev snapshot is a joy to use--I boneheadedly deleted the original
files and I need to install it in Python 2.1 on a different machine (Zope,
that's right).

Thanks,

// mark

-

[Docutils-users] is sf down?

[Mark M. <ma...@mc...>]

Is sourceforge CVS access down?  How can I get the latest dev snapshot?

Thanks,

// mark
-

[Docutils-users] Docutils update: "interpreted text" reimplemented

[David G. <go...@py...>]

I have checked in a preliminary reimplementation of the interpreted
text system.  A newly-expanded description of the interpreted text
implementation is here:

    http://docutils.sf.net/spec/notes.html#interpreted-text

A description of the "roles" currently supported is here:

    http://docutils.sf.net/spec/rst/interpreted.html

This change will break 3rd-party and sandbox code, as new doctree
elements (node types) have been introduced, with more to come.  The
core HTML writer will be kept up to date.

The snapshot has all the latest code:

    http://docutils.sf.net/docutils-snapshot.tgz

-- 
David Goodger  <go...@py...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Re: [Docutils-users] include errors in buildhtml.py from snapshot, Mac OS X

[David G. <go...@py...>]

Bruce Smith wrote:
> ... during "cd tools; ./buildhtml.py ../" I get some include
> errors -- output is below.
...
> Here are the relevant parts of my shell session, showing the include
> errors (about include4.txt, include5.txt, and include6.txt), and a
> few things I did to look into them. I didn't try to debug this, but
> I'll be glad to supply more info, or to try to debug it if someone
> more central to the project can't reproduce it.

Just pointing out the bug is useful, and your bug report was very
complete.  I had no problem reproducing the bug and it wasn't
difficult to locate or fix it.  It was an off-by-one error on a path
manipulation; fixed now.

> the check for the version of docutils I'm running doesn't work:
> 
> [!120] docutils/tools % ./quicktest.py --version
> Traceback (most recent call last):
...
> AttributeError: 'module' object has no attribute '__version'

Typo in the code, fixed now.

> BTW, Thanks loads for docutils!

You're welcome, and thanks for the bug report!

-- 
David Goodger  <go...@py...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

[Docutils-users] include errors in buildhtml.py from snapshot, Mac OS X

[<br...@or...>]

Hi,

I've just downloaded docutils from the snapshot at

  http://docutils.sf.net/docutils-snapshot.tgz
  
and installed it into the python 2.2 that ships with Mac OS X 10.2.3,
i.e. /usr/bin/python, following the instructions on

  http://docutils.sourceforge.net/README.html

I noticed no problems during the install, and the test suite passes with no
errors, but during "cd tools; ./buildhtml.py ../" I get some include
errors -- output is below. (These occur before the test.txt file with its
intentional errors is mentioned in the output.)

There is also an error in the "./quicktest.py --version" command.

(I took a look at some of the generated HTML and it looks correct to my
untrained eye. See end of file for more pedantic details.)

BTW, Thanks loads for docutils! It looks like it'll help a lot with some
documentation I'm writing right now. (Not about anything related to Python,
unfortunately.)

Here are the relevant parts of my shell session, showing the include errors
(about include4.txt, include5.txt, and include6.txt), and a few things I did
to look into them. I didn't try to debug this, but I'll be glad to supply
more info, or to try to debug it if someone more central to the project
can't reproduce it.


[!100] docutils/test % ./alltests.py
.......................................... [rest of the 624 dots not shown]
----------------------------------------------------------------------
Ran 624 tests in 40.839s

OK
Elapsed time: 46.802 seconds
[!101] docutils/test % cd ../tools

[!105] docutils/tools % ./buildhtml.py ../
/// Processing directory: ../
    ::: Processing .txt: COPYING.txt
    ::: Processing .txt: FAQ.txt
    ::: Processing .txt: HISTORY.txt
    ::: Processing .txt: README.txt
/// Processing directory: ../build
/// Processing directory: ../build/lib
/// Processing directory: ../build/lib/docutils
/// Processing directory: ../build/lib/docutils/languages
/// Processing directory: ../build/lib/docutils/parsers
/// Processing directory: ../build/lib/docutils/parsers/rst
/// Processing directory: ../build/lib/docutils/parsers/rst/directives
/// Processing directory: ../build/lib/docutils/parsers/rst/languages
/// Processing directory: ../build/lib/docutils/readers
/// Processing directory: ../build/lib/docutils/readers/python
/// Processing directory: ../build/lib/docutils/transforms
/// Processing directory: ../build/lib/docutils/writers
/// Processing directory: ../docs
    ::: Processing .txt: tools.txt
/// Processing directory: ../docs/rst
    ::: Processing .txt: quickstart.txt
/// Processing directory: ../docs/rst/images
/// Processing directory: ../docutils
/// Processing directory: ../docutils/languages
/// Processing directory: ../docutils/parsers
/// Processing directory: ../docutils/parsers/rst
/// Processing directory: ../docutils/parsers/rst/directives
/// Processing directory: ../docutils/parsers/rst/languages
/// Processing directory: ../docutils/readers
/// Processing directory: ../docutils/readers/python
/// Processing directory: ../docutils/transforms
/// Processing directory: ../docutils/writers
/// Processing directory: ../spec
    ::: Processing .txt: doctree.txt
    ::: Processing .txt: notes.txt
    ::: Processing .txt: pysource.txt
    ::: Processing .txt: semantics.txt
    ::: Processing .txt: transforms.txt
    ::: Processing PEPs:
pep-0256.txt (text/x-rst) -> pep-0256.html
pep-0257.txt (text/x-rst) -> pep-0257.html
pep-0258.txt (text/x-rst) -> pep-0258.html
pep-0287.txt (text/x-rst) -> pep-0287.html
/// Processing directory: ../spec/howto
    ::: Processing .txt: i18n.txt
    ::: Processing .txt: rst-directives.txt
/// Processing directory: ../spec/rst
    ::: Processing .txt: alternatives.txt
    ::: Processing .txt: directives.txt
    ::: Processing .txt: introduction.txt
    ::: Processing .txt: problems.txt
    ::: Processing .txt: reStructuredText.txt
/// Processing directory: ../test
/// Processing directory: ../test/test_parsers
/// Processing directory: ../test/test_parsers/test_rst
/// Processing directory: ../test/test_parsers/test_rst/test_directives
    ::: Processing .txt: include1.txt
    ::: Processing .txt: include2.txt
    ::: Processing .txt: include3.txt
../test/test_parsers/test_rst/test_directives/include3.txt:3: (SEVERE/4) Problems with "include" directive path:
[Errno 2] No such file or directory: 'test/test_parsers/test_rst/test_directives/includes/include4.txt'.

.. include:: includes/include4.txt
SystemMessage: ../test/test_parsers/test_rst/test_directives/include3.txt:3: (SEVERE/4) Problems with "include" directive path:
[Errno 2] No such file or directory: 'test/test_parsers/test_rst/test_directives/includes/include4.txt'.

.. include:: includes/include4.txt
input line 3
module /usr/lib/python2.2/site-packages/docutils/utils.py, line 172, function system_message
        Error (SystemMessage): ../test/test_parsers/test_rst/test_directives/include3.txt:3: (SEVERE/4) Problems with "include" directive path:
[Errno 2] No such file or directory: 'test/test_parsers/test_rst/test_directives/includes/include4.txt'.

.. include:: includes/include4.txt
    ::: Processing .txt: raw1.txt
/// Processing directory: ../test/test_parsers/test_rst/test_directives/includes
    ::: Processing .txt: include4.txt
../test/test_parsers/test_rst/test_directives/includes/include4.txt:3: (SEVERE/4) Problems with "include" directive path:
[Errno 2] No such file or directory: 'test/test_parsers/test_rst/test_directives/includes/include5.txt'.

.. include:: include5.txt
SystemMessage: ../test/test_parsers/test_rst/test_directives/includes/include4.txt:3: (SEVERE/4) Problems with "include" directive path:
[Errno 2] No such file or directory: 'test/test_parsers/test_rst/test_directives/includes/include5.txt'.

.. include:: include5.txt
input line 3
module /usr/lib/python2.2/site-packages/docutils/utils.py, line 172, function system_message
        Error (SystemMessage): ../test/test_parsers/test_rst/test_directives/includes/include4.txt:3: (SEVERE/4) Problems with "include" directive path:
[Errno 2] No such file or directory: 'test/test_parsers/test_rst/test_directives/includes/include5.txt'.

.. include:: include5.txt
    ::: Processing .txt: include5.txt
../test/test_parsers/test_rst/test_directives/includes/include5.txt:3: (SEVERE/4) Problems with "include" directive path:
[Errno 2] No such file or directory: 'test/test_parsers/test_rst/test_directives/includes/more/include6.txt'.

.. include:: more/include6.txt
SystemMessage: ../test/test_parsers/test_rst/test_directives/includes/include5.txt:3: (SEVERE/4) Problems with "include" directive path:
[Errno 2] No such file or directory: 'test/test_parsers/test_rst/test_directives/includes/more/include6.txt'.

.. include:: more/include6.txt
input line 3
module /usr/lib/python2.2/site-packages/docutils/utils.py, line 172, function system_message
        Error (SystemMessage): ../test/test_parsers/test_rst/test_directives/includes/include5.txt:3: (SEVERE/4) Problems with "include" directive path:
[Errno 2] No such file or directory: 'test/test_parsers/test_rst/test_directives/includes/more/include6.txt'.

.. include:: more/include6.txt
/// Processing directory: ../test/test_parsers/test_rst/test_directives/includes/more
    ::: Processing .txt: include6.txt
/// Processing directory: ../test/test_readers
/// Processing directory: ../test/test_readers/test_pep
/// Processing directory: ../test/test_readers/test_python
/// Processing directory: ../test/test_transforms
/// Processing directory: ../tools
    ::: Processing .txt: test.txt
../tools/test.txt:87: (ERROR/3) Undefined substitution referenced: "problematic".
../tools/test.txt:293: (ERROR/3) Unknown target name: "5".
../tools/test.txt:302: (ERROR/3) Unknown target name: "nonexistent".
../tools/test.txt:327: (ERROR/3) Unknown target name: "hyperlink reference without a target".
../tools/test.txt:340: (ERROR/3) Unknown target name: "duplicate target names".
/// Processing directory: ../tools/stylesheets
[!106] docutils/tools % 

the files reported as missing do appear to be there, however:

[!107] docutils/tools % cd ..
[!108] python/docutils % l test/test_parsers/test_rst/test_directives/includes
total 16
0 ./              0 ../             8 include4.txt    8 include5.txt    0 more/
[!109] python/docutils % 

the check for the version of docutils I'm running doesn't work:

[!119] python/docutils % cd tools
[!120] docutils/tools % ./quicktest.py --version
Traceback (most recent call last):
  File "./quicktest.py", line 211, in ?
    main()
  File "./quicktest.py", line 195, in main
    inputFile, outputFile, outputFormat, optargs = getArgs()
  File "./quicktest.py", line 127, in getArgs
    return posixGetArgs(sys.argv[1:])
  File "./quicktest.py", line 146, in posixGetArgs
    print >>sys.stderr, ('quicktest.py (Docutils %s)'
AttributeError: 'module' object has no attribute '__version'
Exit 1

Pedantic details:

% ls -l docutils-snapshot.gz
-rw-r--r--  1 bruce  admin  407326 Jan  8 19:31 docutils-snapshot.gz

(timezone is PST; modtime is probably the time of downloading)

(The file extension was apparently renamed from .tgz to .gz by Apple's new
browser Safari when it downloaded the file.)

% md5 docutils-snapshot.gz
MD5 (docutils-snapshot.gz) = fd48f2fe3f0ffee04e00ea16cd4846a2

I was worried about long pathnames in the tarball being mangled by Stuffit
Expander, which (so I've read) uses Apple's tar rather than gnutar, but I
would have expected much worse errors if that had happened, and the include
files reported missing are present according to my shell, as shown above.

Just to make sure, I manually unpacked the archive with both tar and gnutar
and got the same-sized results according to du and the exact same results
according to diff -r, and diff -r of that docutils directory with
the one produced by Stuffit Expander (and from which I installed, ran tests,
and ran buildhtml) showed only the kind of extra files I'd expect (.html,
.pyc, alltests.out).

My system has several other pythons installed, but none of them are called
'python' on my shell path, so I don't think they can interfere.

- Bruce Smith

Re: [Docutils-users] Special characters

[David G. <go...@py...>]

Brett g Porter wrote:
> It's probably staring me in the face, but what's the correct reST
> way to get characters like HTML character entities?

Just type the characters into your input file, using whatever extended
character set input mechanism your OS has.  Save the file using
whatever encoding you want (Latin-1, UTF-8, cp1252, unicode-escape,
etc.), and tell the Docutils tool what that encoding is
(-i/--input-encoding option).

The default output encoding, UTF-8, is well-supported and handles all
Unicode characters.

> I can't be the first to want to include "©" or "™" in a
> document.

Unfortunately, there's no 'html-character-entity' codec in the stdlib
[#]_.  If you were to use such a codec though, you'd have to encode
every "&" as "&" (unless it was a forgiving codec).  Does such a
codec exist?

.. [#] There is an "xmlcharrefreplace" error handler in Python 2.3,
   but it only converts characters to "©" forms, not "©",
   and only when encoding.  I don't know of an official codec for
   *decoding* character entities.

> I know that HTML isn't the only output format supported, so I'm not
> surprised that character entities aren't just passed through, I
> guess.

:)

-- 
David Goodger  <go...@py...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

[Docutils-users] Special characters

[Brett g P. <bgp...@ac...>]

It's probably staring me in the face, but what's the correct reST way to get
characters like HTML character entities? I can't be the first to want to
include "©" or "™" in a document. I know that HTML isn't the only
output format supported, so I'm not surprised that character entities aren't
just passed through, I guess.

[Docutils-users] Re: Updates to Docutils

[David G. <go...@py...>]

[David Goodger]
> Fred Drake pointed out that Python 2.1 didn't have the "compiler"
> package as part of the standard library (it was a separate
> install), and that's crucial to the Python Source Reader work
> that's ongoing.  Therefore I've decided to upgrade the minimum
> Python requirement to 2.2 (2.2.2 recommended).  Everything except
> the test suite and the docutils/readers/python code still works
> with Python 2.1 though.

Thanks Fred, Tony, and Benja, for your input.  I agree that Jython
currently at 2.1 presents a strong case for maintaining 2.1
compatibility.  The compiler package was in the Tools/ directory of
the Python source distribution, complete with a Distutils setup.py for
installation.

I wonder, does the compiler package work with Jython at all?  Benja?

Another issue is that I've been using tokenize.py's generate_tokens()
call in docutils/readers/python/moduleparser.py, which uses
generators, which requires Python 2.2.  Although this has been more of
an experiment than a requirement, it was a pleasant experiment and it
would be painful and a waste to reimplement it without iterators and
generators.

I put back the pre-generators difflib.py (used by the test suite) and
added footnotes to the README and the home page saying:

   Python 2.1 may be used providing the compiler package is
   installed.  The compiler package can be found in the Tools/
   directory of Python's source distribution.

[Fred L. Drake, Jr.]
> I've not dug into the alltests.py script yet; perhaps there's a way
> to do something similar to the "skipped tests" idea that we use with
> the Python test suite.  That's probably more a matter of mechanics
> than anything.  I won't have time to look into that for at least a
> few days; if anyone beats me to it I won't complain.  ;-)

Done.  The tests pass but report "test skipped" to stderr, under
Python 2.1.

-- 
David Goodger  <go...@py...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

[Docutils-users] Re: [Doc-SIG] Re: [Docutils-develop] Re: Updates to Docutils

[Fred L. D. Jr. <fd...@ac...>]

Benja Fallenstein writes:
 > My project [http://gzz.info] is using ReST heavily for documentation (we 
 > intend to write all future documentation in it, and have converted some 
 > of the existing). However, since we're a Java project, we use it through 
 > Jython, whose newest version is currently up to par with Python 2.1. 

Jython is a really good reason to maintain Python 2.1 compatibility in
my book.


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>
PythonLabs at Zope Corporation

[Docutils-users] Re: [Docutils-develop] Re: Updates to Docutils

[Benja F. <b.f...@gm...>]

Hi David,

David Goodger wrote:
> I have fixed the remaining (known) bugs related to Python 2.3 and PyXML.
> 
> Fred Drake pointed out that Python 2.1 didn't have the "compiler" package as
> part of the standard library (it was a separate install), and that's crucial
> to the Python Source Reader work that's ongoing.  Therefore I've decided to
> upgrade the minimum Python requirement to 2.2 (2.2.2 recommended).
> Everything except the test suite and the docutils/readers/python code still
> works with Python 2.1 though.

My project [http://gzz.info] is using ReST heavily for documentation (we 
intend to write all future documentation in it, and have converted some 
of the existing). However, since we're a Java project, we use it through 
Jython, whose newest version is currently up to par with Python 2.1. 
Therefore, I'd be much happier if you could formally keep the docutils 
requirement at 2.1 for everything except the Python reader (or say, 
"Requirement: Python 2.2 or Python 2.1 with the compiler package 
installed"). When a 2.2-compliant Jython ever comes out, this won't be 
an issue any more.

Thanks,
- Benja

[Docutils-users] RE: [Docutils-develop] Re: Updates to Docutils

[Tony J I. (Tibs) <to...@ls...>]

David Goodger wrote:
> ...that Python 2.1 didn't have the "compiler" package as
> part of the standard library (it was a separate install), and
> that's crucial to the Python Source Reader work that's ongoing.
> Therefore I've decided to upgrade the minimum Python requirement
> to 2.2 (2.2.2 recommended).

I don't have any personal (!) objection to specifying 2.2, but it's
surely easy enough to require the compiler package, and provide a
reference copy on the docutils site for those who install without the
appropriate bit of source/Tools/whatever.

Whether there was significant *change* in the compiler code in the
interim, though, which might also be influential, I can't remember.

Of course, this might just be that "one thing" that's enough to tip your
decision on which version of Python to go for.

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

[Docutils-users] Re: [Doc-SIG] Re: Updates to Docutils

[Fred L. D. Jr. <fd...@ac...>]

David Goodger writes:
 > I have fixed the remaining (known) bugs related to Python 2.3 and PyXML.

Yee haw!  ;-)

 > Fred Drake pointed out that Python 2.1 didn't have the "compiler" package as
 > part of the standard library (it was a separate install), and that's crucial
 > to the Python Source Reader work that's ongoing.  Therefore I've decided to
 > upgrade the minimum Python requirement to 2.2 (2.2.2 recommended).

It's not clear that this is the right way to deal with this; I'd be
happy that just the one component isn't necessarily available with
Python 2.1.x unless the compiler package is installed.

(I vaguely recall that the compiler package shipped as part of the
source package, but not as part of the standard library, but I'm not
sure offhand.  Maybe it was in the Tools/ directory?)

I've not dug into the alltests.py script yet; perhaps there's a way to
do something similar to the "skipped tests" idea that we use with the
Python test suite.  That's probably more a matter of mechanics than
anything.  I won't have time to look into that for at least a few
days; if anyone beats me to it I won't complain.  ;-)

 > Everything except the test suite and the docutils/readers/python code still
 > works with Python 2.1 though.

Which means the tests need to run, at least for the parts that are
supposed to work!  ;-)


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>
PythonLabs at Zope Corporation

[Docutils-users] Re: Updates to Docutils

[David G. <go...@py...>]

I have fixed the remaining (known) bugs related to Python 2.3 and PyXML.

Fred Drake pointed out that Python 2.1 didn't have the "compiler" package as
part of the standard library (it was a separate install), and that's crucial
to the Python Source Reader work that's ongoing.  Therefore I've decided to
upgrade the minimum Python requirement to 2.2 (2.2.2 recommended).
Everything except the test suite and the docutils/readers/python code still
works with Python 2.1 though.

-- 
David Goodger  <go...@py...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

[Docutils-users] Updates to Docutils

[David G. <go...@py...>]

I just checked in a change to docutils/frontend.py, removing some nasty
internals-fiddling code (in ``ConfigParser.get_section()``) and replacing it
with simpler, correct code (possibly a bit slower, but so what).  This was
prompted by bug reports from Fred Drake and Guido van Rossum (thank you!),
who ran Docutils with the newly-released Python 2.3a1, in which some
ConfigParser internals had changed.

There may be another bug that only shows up with Python 2.3, but I won't be
able to check it until Thursday or Friday.

Anybody using Python 2.3 should definitely get the latest Docutils code from
CVS or from the snapshot: <http://docutils.sf.net/docutils-snapshot.tgz>.

Happy New Year!

-- 
David Goodger  <go...@py...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Re: [Docutils-users] Book titles

[David A. <da...@bo...>]

David Goodger <go...@py...> writes:

> David Abrahams wrote:
>> I'm writing a document with ReST, and I need to insert the titles of
>> several books.  Technically, book titles are supposed to be
>> underlined.
>
> According to whom?  

Some outdated reference I found on the web <wink>.

> *The Chicago Manual of Style*, which I use as my typographical
> bible, says:
>
>     Titles and subtitles of published books, ... are set in italics
>     when they are mentioned in the text or notes.
>
>     (14th edition, section 7.133)

You're right.  I found a more up-to-date reference after I posted.
Sorry for the line noise.

> If you want to indicate "book title" separately from "emphasis",
> which is perfectly valid, that's a different question.  Has to do
> with interpreted text.  There's already a related to-do list entry:
>
>   Perhaps the default implicit role for interpreted text could be
>   "title", as in, "title of a book".  It'd be a text-only reference,
>   no hyperlink.  Idea from Aahz' 2002-05-09 Doc-SIG post.

Eventually, there will be equivalents of every possible XML tag, won't
there <0.5 wink>?

-- 
                       David Abrahams
   da...@bo... * http://www.boost-consulting.com
Boost support, enhancements, training, and commercial distribution

Re: [Docutils-users] Book titles

[David G. <go...@py...>]

David Ascher wrote:
> Pedantically yours,

Pedantic perhaps, but at least consistent:
<http://docutils.sf.net/spec/rst/problems.html#underlining>

-- David Goodger    go...@py...

Re: [Docutils-users] Book titles

[Aahz <aa...@py...>]

PS: it's difficult to keep track of a thread where everyone is named
David...  ;-)
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

"There are three kinds of lies: Lies, Damn Lies, and Statistics."  --Disraeli

Re: [Docutils-users] Book titles

[Aahz <aa...@py...>]

On Mon, Dec 30, 2002, David Abrahams wrote:
> 
> I'm writing a document with ReST, and I need to insert the titles of
> several books.  Technically, book titles are supposed to be
> underlined.  What's the appropriate ReST representation?

I've been using ``*``, which on my system is emitted as italics.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

"There are three kinds of lies: Lies, Damn Lies, and Statistics."  --Disraeli

Re: [Docutils-users] Book titles

[David A. <Da...@Ac...>]

David Goodger wrote:
> David Abrahams wrote:
> 
>>I'm writing a document with ReST, and I need to insert the titles of
>>several books.  Technically, book titles are supposed to be
>>underlined.
> 
> 
> According to whom?  *The Chicago Manual of Style*, which I use as my
> typographical bible, says:
> 
>     Titles and subtitles of published books, ... are set in italics
>     when they are mentioned in the text or notes.
> 
>     (14th edition, section 7.133)

This matches the information I got from typesetting books (back in a previous 
life when I used to deal such things =).

--david