docutils-develop — For developer discussions of the implementation.

[Docutils-develop] Building the Docutils community

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

I came across this thought-provoking quote via an article found on Slashdot:

    Anyway, it's an design pattern: "good ideas and bad code build
    communities, the other three combinations do not". This is
    extremely hard to understand, it's probably the most
    counter-intuitive thing about open source dynamics.

    Stefano Mazzocchi,
<http://archives.real-time.com/pipermail/cocoon-devel/2000-October/003023.ht
ml>

In order to build a more active community around Docutils, should I be
writing sloppier code?  I can see the relation: bad code in a good
project generates bug reports and patches from potential contributors,
and provides a gradual path to greater involvement.

Or is my code bad enough already?

;)

-- 
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-develop] Re: Copyright and licensing

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

[David Goodger]
>> It's up to you.  Please put a copyright line in each file, and add a
>> license file if necessary.  Please read this first:
>> <http://docutils.sf.net/spec/notes.html#copyrights-and-licensing>

[Aahz]
> Uh, that's bogus.

What's bogus about it?  It simply expresses my intentions for the project.

> Once something is in the public domain, you can't revert it

You should say, once something is in the public domain, it can never be
*removed* from the public domain.  It *can* be modified and copyrighted
though, by anybody.  For examples, look at all the Disney films that are
derivative works of public domain fairy tales.  In fact, anyone could just
take the Docutils code as-is, just replace the public domain declaration
lines in each file with their own copyright, and charge a million dollars
for it.  Nobody would buy it though, because the PD edition remains and
cannot be undone.  Our only loss would be that we wouldn't be able to use
any of the changes made by someone who slapped a copyright on.

In any case, so what?  It's not my intention to ever revert anything.  It
*is* my intention to release my code to the public without encumbrance of
any kind.  I don't even ask that people keep my name or copyright notice
intact.  (If they do, that's nice and I appreciate it, but I don't require
it.)  That's the essence of public domain.  It's so free that anybody can do
absolutely anything with their copy, including copyrighting it.  All they
can't do is slap a copyright on *my* copy or *yours*.

> (but as Tim Peters has pointed out numerous times, it's almost
> impossible to actually stick something in the public domain).

Hmm.  Lawrence Lessig's Creative Commons seems to contradict this:

    http://creativecommons.org/licenses/publicdomain

> You should change that page to "Python-style license".

No, I shouldn't, because that's not my intention.  If and when the
PythonLabs crew decides to integrate all or part of Docutils into the Python
distribution, they're free (and welcome!) to slap their own copyright on it
if they like.  And any contributor can choose their own license terms.  I
chose public domain, and ask that contributors consider it, that's all.
What's bogus about that?

-- 
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-develop] Copyright and licensing

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

On Mon, Jan 06, 2003, David Goodger wrote:
>
> It's up to you.  Please put a copyright line in each file, and add a
> license file if necessary.  Please read this first:
> <http://docutils.sf.net/spec/notes.html#copyrights-and-licensing>

Uh, that's bogus.  Once something is in the public domain, you can't
revert it (but as Tim Peters has pointed out numerous times, it's almost
impossible to actually stick something in the public domain).  You
should change that page to "Python-style license".
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

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

Re: [Docutils-develop] Plain HTML writer "complete"

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

Bill Bumgarner wrote:
> Now:  How do you fire up the docstrings parser (pysource)?

First, you write it.  Or at least finish it, 'cause it ain't ready.
Or you wait until it is. :)

> On Monday, Jan 6, 2003, at 19:47 US/Eastern, David Goodger wrote:
>> Under what conditions are you releasing the code?  There's no
>> copyright statement I can find.  Please consider public domain.
> 
> I typically use the MIT license.  Basically, public domain with a
> "don't even think about suing me" clause.

It's up to you.  Please put a copyright line in each file, and add a
license file if necessary.  Please read this first:
<http://docutils.sf.net/spec/notes.html#copyrights-and-licensing>

-- 
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-develop] Plain HTML writer "complete"

[Bill B. <bb...@co...>]

BTW:  I conversed with Guido on the subject and the python-dev group is 
now aware of the plain HTML writer, as well.

Now:  How do you fire up the docstrings parser (pysource)?

On Monday, Jan 6, 2003, at 19:47 US/Eastern, David Goodger wrote:
> Under what conditions are you releasing the code?  There's no
> copyright statement I can find.  Please consider public domain.

I typically use the MIT license.  Basically, public domain with a 
"don't even think about suing me" clause.

b.bum

Re: [Docutils-develop] Plain HTML writer "complete"

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

Bill Bumgarner wrote:
> The DocArticle plain HTML writer found in the bbum/ sandbox now
> successfully process test.txt

Great!  I'll try to give it a good look soon, but I'm busy for a
while.

Under what conditions are you releasing the code?  There's no
copyright statement I can find.  Please consider public domain.

> (save for the five errors that look like they are not a part of the
> writer).

The errors are intentional, to test & show error output.

> The settings are still broken-- I ripped 'em out and need to add
> them back-- but, outside of that, it seems to work fairly well.

Please let me know if you need any help.

-- 
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-develop] Plain HTML writer "complete"

[Bill B. <bb...@co...>]

The DocArticle plain HTML writer found in the bbum/ sandbox now 
successfully process test.txt (save for the five errors that look like 
they are not a part of the writer).

The output isn't visually optimal and may not be 100% pure x.x HTML 
compliant, but it works and works well enough to be readable.

The settings are still broken-- I ripped 'em out and need to add them 
back-- but, outside of that, it seems to work fairly well.   Works for 
me, anyway.

b.bum

[Docutils-develop] Re: Handling interpreted text

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

[Jason Diamond]
>>> But you're letting people create new node types just by making up new
>>> role names?

[David Goodger]
>> No, not arbitrarily.  Authors would have to choose from a
>> pre-determined set of roles, each having pre-existing software
>> support.  For instance, your acronym example would have to have
>> support in the parser, to create the "acronym" elements and associate
>> "title" attributes from a lookup table.
>> 
>> Interpreted text with unknown roles would generate errors.

[Aahz]
> -1 unless it's easier than the current system for adding new directives.

Ease of implementation isn't even on the radar at this point.  Correctness
is dead center.  For most interpreted text processing, it is *wrong* to
delay processing (interpretation) until the Writer.  It is *absolutely
correct* to handle the processing (at least the initial stage) in the
Parser.

I apologize that I can't explain interpreted text any better than I already
have, in the markup spec (spec/rst/reStructuredText.txt), PEP 258,
spec/pysource.txt, previous posts, and this one (I *was* planning to go to
bed early tonight... so please read carefully).  While I'm sure my mental
model will have to adapt as the implementation unfolds (it's a process of
discovery), I'm pretty confident of its foundation.

The current state of the implementation is a red herring.  It's going to
change, because it's a half-assed, incomplete, and totally *wrong*
implementation.

But feel free to try to convince me otherwise.  :)

> Currently to handle a directive you need support in both parser and
> writer, but for interpreted text you only need support in the writer.

You only need Writer support for a directive if the directive introduces a
new element into the DTD.  Some do: the directives whose only reason for
being is to allow the creation of these elements (like "image" and "meta").
Most interesting ones don't though (like "contents" or "include"); they just
insert standard elements into the doctree.

In most cases there's nothing Writer-specific about interpreted text.
Interpreted text is entirely a reStructuredText markup construct, a way to
get around built-in limitations of the medium.  No other form of markup
would require anything resembling an "<interpreted>" element.

> While I understand what you want to do (and it would make certain parts
> of what I want to do with interpreted text easier), I'm concerned about
> adding complexity.

If an author wants an "acronym" element, they should get one.  A real
acronym element, not an <interpreted role="acronym"> surrogate.  If we allow
the surrogate and take that line of reasoning to the extreme, all we'd need
for a DTD is this bogosity ::

    <!ELEMENT element (element|PCDATA)*>
    <!ATTLIST element
        name     NMTOKEN   #REQUIRED
        attlist  CDATA     #IMPLIED>

(Which BTW is essentially what DOM is, but it has good reason.)

My reasoning is that all supported interpreted text roles must be known by
the Parser.  There's no guarantee that an arbitrary role will be supported
by the eventual Writer.  Adding a new role is tantamount to adding a new
element to the DTD, may require extensive support, and shouldn't be taken
lightly.  However, there should be a limited number of such roles.  Allowing
different Writers to support different elements would fragment the system
beyond repair.  It must remain a unified whole.  The only place where
variation is acceptable is at the start, at the Reader/Parser interface
(with possible transforms inserted *by* the Reader).  Once past the
Transformer, no variation from standard Docutils doctree is possible.

On the other hand, most new elements won't require Writer support, because
they will be Reader-specific extensions to the DTD, and will be converted to
standard elements by Reader-specific transforms.  Case in point: the Python
Source Reader, which will use interpreted text extensively.  The default
role will be "Python identifier", which will be further interpreted by
namespace context into <class>, <method>, <module>, <attribute>, etc.
elements (see spec/pysource.dtd), which will be transformed into standard
hyperlink references, which will be processed by the various Writers.  The
point is that no Writer will need to have any knowledge of the Python-Reader
origin of these elements.

(I'm sorry if this gives you a sinking feeling, like "all my work is going
to waste".  Rest assured, it won't.  If you check in your code into your
sandbox, all the good ideas will eventually migrate into the main tree.  The
eventual form these ideas take may be very different from the current form
though.)

> Because I know you're going to ask ;-), the current use I'm making of
> interpreted text is chapter/figure/list references::
> 
>     To understand better how mutable and immutable objects work, see
>     code listings :list:`mutable.py` and :list:`immutable.py`, as well
>     as figures :figure:`mutable.eps` and :figure:`immutable.eps`.
>     You'll also want to read :chapter:`Data`.

Thanks for answering without me having to ask. :)  The obvious follow-up
questions are: how should all of that be processed and rendered?  What is
the purpose and semantics?  Why not just use standard hyperlink references?
(I could guess, but I'd rather not.)

I hope this all makes sense.  Good night!

-- 
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-develop] Handling interpreted text

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

On Sat, Jan 04, 2003, David Goodger wrote:
> Jason Diamond wrote:
>>
>> But you're letting people create new node types just by making up new
>> role names?
> 
> No, not arbitrarily.  Authors would have to choose from a
> pre-determined set of roles, each having pre-existing software
> support.  For instance, your acronym example would have to have
> support in the parser, to create the "acronym" elements and associate
> "title" attributes from a lookup table.
>
> Interpreted text with unknown roles would generate errors.

-1 unless it's easier than the current system for adding new directives.

Currently to handle a directive you need support in both parser and
writer, but for interpreted text you only need support in the writer.
While I understand what you want to do (and it would make certain parts
of what I want to do with interpreted text easier), I'm concerned about
adding complexity.

Because I know you're going to ask ;-), the current use I'm making of
interpreted text is chapter/figure/list references::

    To understand better how mutable and immutable objects work, see
    code listings :list:`mutable.py` and :list:`immutable.py`, as well
    as figures :figure:`mutable.eps` and :figure:`immutable.eps`.
    You'll also want to read :chapter:`Data`.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

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

Re: [Docutils-develop] HTML Acronyms

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

I wrote:
> What happens when an attribute without a lookup table entry comes along?
                       ^^^^^^^^^ acronym

-- David Goodger  <go...@py...>

Re: [Docutils-develop] HTML Acronyms

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

Jason Diamond wrote:
> I want to translate "`reST`:acronym:" into "<acronym
> title='reStructuredText'>reST</acronym>". The value of the title
> attribute has to be defined out-of-band since you can't parameterize
> interpreted text. Right now I have them in a separate file but I'm
> experimenting with creating a directive that will use some form of reST
> syntax to let you define them.

I understand.  Sounds reasonable.  What happens when an attribute without a
lookup table entry comes along?

> So instead of an `interpreted` node, I'll have an `acronym` node? I'll
> be moving my code to `visit_acronym` and `depart_acronym`?

Yes.

> But you're letting people create new node types just by making up new
> role names?

No, not arbitrarily.  Authors would have to choose from a pre-determined set
of roles, each having pre-existing software support.  For instance, your
acronym example would have to have support in the parser, to create the
"acronym" elements and associate "title" attributes from a lookup table.

Interpreted text with unknown roles would generate errors.

> Won't that make defining the DTD difficult?

It would be impossible, which is a good indication that it's a bad approach
;).

> I like the interpreted/role approach. It would be nice if the walk/walkabout
> methods looked for the role attribute on intrepreted nodes, though. They could
> invoke `visit_interpreted_acronym` or `visit_interpreted_index_entry`
> depending on the role attribute and fall back to `visit_interpreted` in case
> the extended method doesn't exist.

Interesting idea.  In the scheme I'm considering though, there won't be any
"interpreted" elements left in the doctree by the time the Writer sees it.

Interpreted text is just syntax; the semantics haven't been finalized or
implemented yet.  The current "interpreted" element is merely a placeholder
for testing purposes and will disappear.  It's like the directive syntax.
Originally there was a generic "directive" element (before there was support
for directive processing in the parser), but it's gone now.  It's the same
situation for interpreted text.

> How about this::
> 
>     `interpreted text`:role1:role2:
> 
> Could we parameterize roles like this::
> 
>     `interpreted text`:role1(foo=bar):role2(baz=quux):
> 
> Yes, it's ugly. Just a different kind of ugly compared to XML.

These are possibilities, and I'll note them.  But they're too complex for my
liking.  I really want to avoid complex inline markup.

> The reason I was thinking about parameters (or attributes) was to
> "override" a defined acronym::
> 
>     `CSS`:acronym:
> 
> could produce::
> 
>     <acronym title="Cascading Style Sheets">CSS</acronym>
> 
> by default but::
> 
>     `CSS`:acronym(title=Content Scrambling System):
> 
> could produce::
> 
>     <acronym title="Content Scrambling System">CSS</acronym>
> 
> when writing about DVDs and copy protection.

My first inclination would be to use the existing substitution/directive
mechanism for something like this::

    `CSS`:acronym: is used for HTML, and |CSS| is used for DVDs.

    .. |CSS| acronym:: Content Scrambling System

> I'm not really pushing for these--

Good!

> just thought I'd throw them out there to see what you might think.

The effort is appreciated.

> I'd like to see reST stay simple but still
> be powerful enough to get most of what I'd like to do done.

I don't mind if directives are used for the gnarly stuff, but I'm loathe to
reduce readability by adding inline markup complexity.

-- 
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-develop] HTML Acronyms

[Jason D. <ja...@in...>]

On Fri, 2003-01-03 at 17:13, David Goodger wrote:
> [David Goodger]
> >> A quick & dirty way to implement what you want would be to indicate
> >> the role of each acronym like this: "`reST`:acronym:" or
> >> "`reST`:a:".  This will put the role into a doctree node attribute,
> >> which is easy to check for in code.  But the text is butt-ugly and
> >> this approach become obsolete (read on).
>                 ^
>                 I meant to say "*may* become obsolete"
> 
> [Jason Diamond]
> > This is what I did. It is ugly but not as much as in HTML. At least
> > the titles can be defined elsewhere.
> 
> (By "titles" I assume you mean roles [as in `interpreted text`:role:].
> Correct?  If not, please explain what you do mean.)

I want to translate "`reST`:acronym:" into "<acronym
title='reStructuredText'>reST</acronym>". The value of the title
attribute has to be defined out-of-band since you can't parameterize
interpreted text. Right now I have them in a separate file but I'm
experimenting with creating a directive that will use some form of reST
syntax to let you define them.

> That's fine, but please be aware that the current internal
> representation will probably be ripped out and replaced before long.

So instead of an `interpreted` node, I'll have an `acronym` node? I'll
be moving my code to `visit_acronym` and `depart_acronym`?

> >> An application (or document or processing run) could specify a
> >> default role, so a ":role:" prefix or suffix wouldn't be required;
> >> plain `backquotes` would be sufficient.
> >> 
> >> Ideally and eventually, the "interpreted" element will disappear
> >> from the Docutils doctree.  In its place will be a customizable set
> >> of inline elements including "acronym" and "index_entry", directly
> >> created by the parser.
> > 
> > How will that work? Will acronyms and index entries use a different
> > syntax to differentiate themselves from each other?
> 
> No, they'll still use interpreted text syntax.  I meant that
> internally, acronyms will be <acronym> elements and index entries will
> be <index_entry> elements; there will be no <interpreted role="...">
> elements.  I don't plan on adding new syntax.

But you're letting people create new node types just by making up new
role names? Won't that make defining the DTD difficult? I like the
interpreted/role approach. It would be nice if the walk/walkabout
methods looked for the role attribute on intrepreted nodes, though. They
could invoke `visit_interpreted_acronym` or
`visit_interpreted_index_entry` depending on the role attribute and fall
back to `visit_interpreted` in case the extended method doesn't exist.

> > What if an acronym was also an index entry?
> 
> That's a tough one.  We're approaching the limitations of
> reStructuredText now.  Inline markup cannot be nested, so you would
> either have to choose one of the roles, or make up a new combined
> "acronym-index-entry" role.  The latter case could easily become quite
> complicated.
> 
> I suppose the interpreted text syntax *could* be extended for multiple
> roles, something like this::
> 
>     `interpreted text`:role1,role2:
> 
> But at first glance that seems exceedingly ugly to me.  Basically, if
> a document is so complex as to require nested inline markup, perhaps
> another markup system should be considered.  reStructuredText does not
> have the flexibility of XML (by design).

How about this::

    `interpreted text`:role1:role2:

Could we parameterize roles like this::

    `interpreted text`:role1(foo=bar):role2(baz=quux):

Yes, it's ugly. Just a different kind of ugly compared to XML.

The reason I was thinking about parameters (or attributes) was to
"override" a defined acronym::

    `CSS`:acronym:

could produce::

    <acronym title="Cascading Style Sheets">CSS</acronym>

by default but::

    `CSS`:acronym(title=Content Scrambling System):

could produce::

    <acronym title="Content Scrambling System">CSS</acronym>

when writing about DVDs and copy protection.

I'm not really pushing for these--just thought I'd throw them out there
to see what you might think. I'd like to see reST stay simple but still
be powerful enough to get most of what I'd like to do done.

Jason

Re: [Docutils-develop] HTML Acronyms

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

[David Goodger]
>> A quick & dirty way to implement what you want would be to indicate
>> the role of each acronym like this: "`reST`:acronym:" or
>> "`reST`:a:".  This will put the role into a doctree node attribute,
>> which is easy to check for in code.  But the text is butt-ugly and
>> this approach become obsolete (read on).
                ^
                I meant to say "*may* become obsolete"

[Jason Diamond]
> This is what I did. It is ugly but not as much as in HTML. At least
> the titles can be defined elsewhere.

(By "titles" I assume you mean roles [as in `interpreted text`:role:].
Correct?  If not, please explain what you do mean.)

That's fine, but please be aware that the current internal
representation will probably be ripped out and replaced before long.

>> An application (or document or processing run) could specify a
>> default role, so a ":role:" prefix or suffix wouldn't be required;
>> plain `backquotes` would be sufficient.
>> 
>> Ideally and eventually, the "interpreted" element will disappear
>> from the Docutils doctree.  In its place will be a customizable set
>> of inline elements including "acronym" and "index_entry", directly
>> created by the parser.
> 
> How will that work? Will acronyms and index entries use a different
> syntax to differentiate themselves from each other?

No, they'll still use interpreted text syntax.  I meant that
internally, acronyms will be <acronym> elements and index entries will
be <index_entry> elements; there will be no <interpreted role="...">
elements.  I don't plan on adding new syntax.

> Are are you saying the default role will specify that all
> interpreted text is a certain type of element?

Yes, all interpreted text *without an explicit role* will take on the
default implicit role.  There will be one default interpreted text
role per run.  The most-used role should become the default.

I don't know how this will be implemented yet though.

> What if you wanted to identify both acronyms and index entries in
> the same document?

If acronyms were the default role, then index entries would have to be
marked up explicitly.  Or vice-versa.  If the default role was neither
of these, they would both have to be marked up explicitly.

> What if an acronym was also an index entry?

That's a tough one.  We're approaching the limitations of
reStructuredText now.  Inline markup cannot be nested, so you would
either have to choose one of the roles, or make up a new combined
"acronym-index-entry" role.  The latter case could easily become quite
complicated.

I suppose the interpreted text syntax *could* be extended for multiple
roles, something like this::

    `interpreted text`:role1,role2:

But at first glance that seems exceedingly ugly to me.  Basically, if
a document is so complex as to require nested inline markup, perhaps
another markup system should be considered.  reStructuredText does not
have the flexibility of XML (by design).

-- 
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-develop] 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/

Re: [Docutils-develop] HTML Acronyms

[Jason D. <ja...@in...>]

On Sun, 2002-12-29 at 09:04, David Goodger wrote: 

> A quick & dirty way to implement what you want would be to indicate the role
> of each acronym like this: "`reST`:acronym:" or "`reST`:a:".  This will put
> the role into a doctree node attribute, which is easy to check for in code.
> But the text is butt-ugly and this approach become obsolete (read on).

This is what I did. It is ugly but not as much as in HTML. At least the
titles can be defined elsewhere.

> An application (or document or processing run) could specify a default role,
> so a ":role:" prefix or suffix wouldn't be required; plain `backquotes`
> would be sufficient.
> 
> Ideally and eventually, the "interpreted" element will disappear from the
> Docutils doctree.  In its place will be a customizable set of inline
> elements including "acronym" and "index_entry", directly created by the
> parser.

How will that work? Will acronyms and index entries use a different
syntax to differentiate themselves from each other? Are are you saying
the default role will specify that all interpreted text is a certain
type of element? What if you wanted to identify both acronyms and index
entries in the same document? What if an acronym was also an index
entry?

Jason

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

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

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-develop] 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-develop] 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/

Re: [Docutils-develop] Duplicate subsection names

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

On Tue, Dec 31, 2002, David Goodger wrote:
> Aahz wrote:
>>
>> Should it be a bug to prohibit this::
> 
> Duplicate section names aren't prohibited, but they can't be linked to by
> name.  IIRC, level-1 (INFO) system messages are produced, but normally they
> are filtered out of the output.
> 
> I'll make a leap and guess that your OpenOffice XML Writer doesn't filter
> system messages.  The code that does the filtering is in the Writer,
> although perhaps it ought to be in a separate transform (note to future
> self: think about this).  Here's the applicable filter code from
> html4css1.py::
> 
>     def visit_system_message(self, node):
>         if node['level'] < self.document.reporter['writer'].report_level:
>             # Level is too low to display:
>             raise nodes.SkipNode

Ah.  Hmmmm....  I'm thinking I've seen some other useful INFO messages,
but perhaps they were level-2.  Anyway, just to be safe, I've done this::

    def visit_system_message(self, node):
        print node.astext()

This way I won't miss anything.  (Previously, I didn't implement
``visit_system_message()``, so it got bumped to ``unknown_visit()`` and
an exception.)
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

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

Re: [Docutils-develop] Duplicate subsection names

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

Aahz wrote:
> Should it be a bug to prohibit this::

Duplicate section names aren't prohibited, but they can't be linked to by
name.  IIRC, level-1 (INFO) system messages are produced, but normally they
are filtered out of the output.

I'll make a leap and guess that your OpenOffice XML Writer doesn't filter
system messages.  The code that does the filtering is in the Writer,
although perhaps it ought to be in a separate transform (note to future
self: think about this).  Here's the applicable filter code from
html4css1.py::

    def visit_system_message(self, node):
        if node['level'] < self.document.reporter['writer'].report_level:
            # Level is too low to display:
            raise nodes.SkipNode

-- 
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-develop] 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/

[Docutils-develop] Duplicate subsection names

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

Should it be a bug to prohibit this::

    Section A
    =========

    Subsection Foo
    --------------

    Section B
    =========

    Subsection Foo
    --------------

(It's currently making my life slightly annoying that it's prohibited,
but I can work around it.  No, I haven't tested with the latest CVS yet;
I'm too close to a production milestone.)
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

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

Re: [Docutils-develop] languages; all keys lowercase...

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

Bill Bumgarner wrote:
> To make a document more readable in raw form, I naturally used :Author:
> as opposed to :author:.
> 
> The document failed to parse, as a result.

Works for me in either form.  Please show us the exact command line and
input you're using, the output you're seeing, and the OS, Python, and
Docutils versions you're using.

> Looking at the implementation, is there any reason not to use lower()
> when looking up a name in the Languages dictionary/module?

At that point in the code (in the Writer), the name should already be in
lowercase.  That should have been handled by the bibliographic field list
transform.

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