docutils-develop Mailing List for Docutils: Documentation Utilities (Page 410)

On Tue, Oct 22, 2002, David Goodger wrote:
> Aahz wrote:
>>
>> I've got the following kludge::
> 
> Sorry, I can't make out what you want.  Could you show us before &
> after pictures of the data?  Use tools/publish.py to get pseudo-xml
> (the "before"), then show us what OpenOffice XML you're getting now
> (the current "after"), and what you *want* to get (the ideal "after";
> edit it manually if you have to).  We can't help if we don't know
> what output you want.

Here's the XML output::

    <paragraph>
        Guido's coding style is published in PEP 8
        <footnote_reference auto="1" id="id1" refid="pep">
            1
        , which you can find on
        <literal>
            http://www.python.org
        .
    <footnote auto="1" backrefs="id1" id="pep" name="pep">
        <label>
            1
        <paragraph>
            PEP stands for "Python Enhancement Proposal", and is part
            of the semi-formal process for the Python project.  See
            <literal>
                http://www.python.org/peps/

Here's what my script currently outputs (which is correct "after", just
hacked up in ``visit_footnote_reference()`` -- the only thing I'm not
getting in my output is the literal text in the footnote)::

    <text:p text:style-name=".body">
    Guido's coding style is published in PEP 8 
    <text:footnote text:id="id1">
    <text:footnote-citation text:string-value="1"/>
    <text:footnote-body>
    <text:p text:style-name=".body">
    PEP stands for "Python Enhancement Proposal", and is part
    of the semi-formal process for the Python project.  See
    http://www.python.org/peps/
    </text:p>
    </text:footnote-body>
    </text:footnote>, 
    , which you can find on <text:span text:style-name="code">http://www.python.org</text:span>
    </text:p>

Here's what I'd get with the literal text in the footnote::

    <text:p text:style-name=".body">
    Guido's coding style is published in PEP 8 
    <text:footnote text:id="id1">
    <text:footnote-citation text:string-value="1"/>
    <text:footnote-body>
    <text:p text:style-name=".body">
    PEP stands for "Python Enhancement Proposal", and is part
    of the semi-formal process for the Python project.  See
    <text:span text:style-name="code">" rel="nofollow">http://www.python.org/peps/</text:span>
    </text:p>
    </text:footnote-body>
    </text:footnote>
    , which you can find on <text:span text:style-name="code">http://www.python.org</text:span>
    </text:p>

> And please check in your current code, so we can read it in context.

Done.

>> What I really ought to do is call for a walkabout on the footnote
>> node, but I can't quite figure out how to do that.
> 
> I assume you're already *doing* a walkabout.  Just let it continue.
> You're short-circuiting the process artificially.  The internal
> document tree is well-formed: an end-tag (depart_tag) for every
> start-tag (visit_tag), and all elements arranged as the DTD describes.
> (If they're not, it's a bug.)  Trust in the docree.

Well, I suppose what I *really* ought to do is transform the doctree to
replace the footnote_reference with the actual footnote node.  Then
everything would work magically (modulo the issue of the
<text:footnote-body> tag).
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/

Aahz wrote:
> I've got the following kludge::

Sorry, I can't make out what you want.  Could you show us before &
after pictures of the data?  Use tools/publish.py to get pseudo-xml
(the "before"), then show us what OpenOffice XML you're getting now
(the current "after"), and what you *want* to get (the ideal "after";
edit it manually if you have to).  We can't help if we don't know
what output you want.

And please check in your current code, so we can read it in context.

> What I really ought to do is call for a walkabout on the footnote
> node, but I can't quite figure out how to do that.

I assume you're already *doing* a walkabout.  Just let it continue.
You're short-circuiting the process artificially.  The internal
document tree is well-formed: an end-tag (depart_tag) for every
start-tag (visit_tag), and all elements arranged as the DTD describes.
(If they're not, it's a bug.)  Trust in the docree.

> There's also the issue of figuring out how to sequence in the
> <text:footnote-body> tag -- adding it as part of depart_label() just
> doesn't appeal to me.

Personal appeal don't enter into it!  When converting from one XML
structure to another, you have to use whatever cues and features are
available.  If an output element has to begin where an input element
ends, so be it. 

> The flip side is that what I've currently got isn't picking up
> intra-paragraph formatting.  <sigh>

You mean inline markup?  That's because you're forcing the flow
unnaturally.  The essence of the Visitor pattern (and any tree
traversal) is that each node be left to do its part -- no more and no
less.  Some nodes will do very little or nothing, but that's what
they're meant to do.  Don't force a parent node to handle its
children; they're big enough to handle themselves.

-- 
David Goodger  <go...@us...>  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/

I've got the following kludge::

    def visit_footnote_reference(self, node):
        name = node['refid']
        id = node['id']
        number = node['auto']
        for footnote in self.document.autofootnotes:
            if name == footnote['name']:
                break
        self.body.append('<text:footnote text:id="%s">\n' % id)
        self.body.append('<text:footnote-citation text:string-value="%s"/>\n' % number)
        self.body.append('<text:footnote-body>\n')
        self.body.append(self.start_para % '.body')
        for child in footnote.children:
            if isinstance(child, nodes.paragraph):
                self.body.append(child.astext())
        self.body.append(self.end_para)
        self.body.append('</text:footnote-body>\n')
        self.body.append('</text:footnote>')
        raise nodes.SkipNode

What I really ought to do is call for a walkabout on the footnote node,
but I can't quite figure out how to do that.  There's also the issue of
figuring out how to sequence in the <text:footnote-body> tag -- adding
it as part of depart_label() just doesn't appeal to me.

The flip side is that what I've currently got isn't picking up
intra-paragraph formatting.  <sigh>
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/

Greg Ward wrote:
> OK, I finally got around to cvs up'ing my docutils installation.
> nsgmls happily validates all of the Quixote documentation
> (http://www.mems-exchange.org/software/quixote/doc/), with one
> exception.

The docs look good.  Please note that if you regenerate the docs with
the latest Docutils (which I recommend you do, to take advantage of
the improvements to the HTML produced), you should also replace the
stylesheet.  It looks like you've made some modifications to the stock
stylesheet, which is fine.  To keep your modifications *and* get the
benefit of the recent improvements, without having to edit the
stylesheet each time, I recommend extracting your modifications into a
separate .css file and using the "@import" statement to cascade the
stylesheets.  See http://docutils.sf.net/docs/tools.html#stylesheets
for details.

BTW, how about a plug?  If you run html.py with the --generator option
(or add "generator: 1" to your docutils.conf file), you'll get a discrete
"Generated by Docutils" credit at the bottom of the file.  I'll say no
more. :-)

> If I run nsgmls on the whole HTML file, I get:
> 
> $ nsgmls -wxml -c /www/misc/sgml/xhtml.soc web-services.html > /dev/null
> nsgmls:web-services.html:26:14:E: there is no attribute "colwidth"
> 
> Line 26 is the first "<col>" tag inside "<colgroup>".

A typo, fixed now.  The HTML attribute is "width", not "colwidth".  I
must have just copied the attribute from the the Docutils internal
table model, where the attribute *is* "colwidth", without realizing.
(Docutils uses a slightly customized "OASIS XML Exchange Table Model",
based on CALS tables; DTD in spec/soextblx.dtd.)

That bugfix actually solves a minor problem with HTML table rendering
(the width suggestions weren't being heeded), which I had forgotten
about.  Thanks!

> Oh yeah, the /www/misc/sgml/xhtml.soc file is just something I need
> to pass to nsgmls to stop it from spewing bazillions of meaningless
> (to me) errors.  I'm no SGML/XML expert, so that's the limit of my
> understanding.

The .soc extension is used on "SGML Open Catalog" files.  They provide
local mappings from PUBLIC ID (start with "-//W3C//DTD..." in
xhtml.soc) to SYSTEM IDs (local filesystem paths).  I thought XML
didn't use them, but it could be a legacy thing since nsgmls was an
SGML parser before XML existed.

-- 
David Goodger  <go...@us...>  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/

<html>
<head>
</head>
<body>
<p align="center"><font style="font-size: 11pt" face="Courier">NEW ISSUE - Volume 6, Issue 37 - October 2002</font></p>
<p align="center"><b><a href="CLICK" rel="nofollow">http://www.globalwebcollective.net/New_Issue.htm">CLICK HERE</a></b></p>
<p align="center"><img border="0" src="
" rel="nofollow">http://www.globalwebcollective.net/WSBE_Issue37.jpg"></p>
<p align="left">&nbsp;</p>
<p align="left">&nbsp;</p>
<p align="center"><font size="2">I no longer wish to receive your newsletter <a href="mailto:not...@gl...?subject=takeoff"><b>click here</b></a></font></p>
</body>
</html>

tqupstntpacgqybqvguncvauomaq

On 08 October 2002, David Goodger said:
> That was just a thinko.  I thought the word "SYSTEM" was needed there,
> but it isn't.  I had the same bug with the XML writer
> (docutils_xml.py), fixed recently.  I've fixed the DOCTYPE header for
> HTML; please try it again with the latest snapshot.

OK, I finally got around to cvs up'ing my docutils installation.  nsgmls
happily validates all of the Quixote documentation
(http://www.mems-exchange.org/software/quixote/doc/), with one
exception.

In particular, this reStructuredText snippet:

"""
... The xmlrpclib module, part of the Python 2.2
standard library and available separately from
http://www.pythonware.com/products/xmlrpc/, converts between Python's
standard data types and the XML-RPC data types.

==============  =====================
XML-RPC Type	Python Type or Class
--------------  ---------------------
<int>		int
[...]
==============  =====================
"""

generates this HTML:

"""
The xmlrpclib module, part of the Python 2.2
standard library and available separately from
<a class="reference" href="http://www.pythonware.com/products/xmlrpc/," rel="nofollow">http://www.pythonware.com/products/xmlrpc/">http://www.pythonware.com/products/xmlrpc/</a>, converts between Python's
standard data types and the XML-RPC data types.</p>
<table class="table" frame="border" rules="all">
<colgroup>
<col colwidth="40%" />
<col colwidth="60%" />
</colgroup>
<tbody valign="top">
<tr><td>XML-RPC Type</td>
<td>Python Type or Class</td>
</tr>
<tr><td>&lt;int&gt;</td>
<td>int</td>
</tr>
<tr><td>&lt;double&gt;</td>
[...]
</tbody>
</table>
"""

If I run nsgmls on the whole HTML file, I get:

$ nsgmls -wxml -c /www/misc/sgml/xhtml.soc web-services.html > /dev/null
nsgmls:web-services.html:26:14:E: there is no attribute "colwidth"

Line 26 is the first "<col>" tag inside "<colgroup>".

Oh yeah, the /www/misc/sgml/xhtml.soc file is just something I need to
pass to nsgmls to stop it from spewing bazillions of meaningless (to me)
errors.  I'm no SGML/XML expert, so that's the limit of my
understanding.

        Greg
-- 
Greg Ward - software developer                gw...@me...
MEMS Exchange                            http://www.mems-exchange.org

[David]
>> Given::
>> 
>>     Here's a paragraph.
>> 
>>     .. index:: paragraph
>> 
>> The directive should produce something like this XML::
>> 
>>     <paragraph>
>>     <index_entry text="paragraph"/>
>>     Here's a paragraph.
>>     </paragraph>

[Aahz]
> Given my lack of knowledge about XML and reST internals, where should I
> look for information about writing this part of the directive?

Just the source for now.  This is the kind of thing that transforms
usually do.  For example, docutils.transforms.peps.Contents inserts a table
of contents placeholder as the second element in the document (after the PEP
field list)::

    self.document.insert(1, pending)

The parts.SectNum tranform inserts section numbers (in "generated" elements)
into section titles.  The frontmatter.DocTitle transform is another good
example.

> That is, how do I go about correctly inserting a node into the tree
> during directive processing?  (Instead of returning a list of nodes.)

Here's some quick & dirty code, based on what's in OOdirectives.py::

    def index_directive(name, arguments, options, content, lineno,
                        content_offset, block_text, state,
                        state_machine):
        nodes = []
        for entry in content:
            nodes.append(index_entry(entry, entry))
        parent = state_machine.node
        last_node = parent[-1]  # add check for empty parent later
        assert isinstance(last_node, nodes.paragraph), \
            ('The "index" directive is only valid after a paragraph, '
             'for now.') # must generalize it later
        last_node.insert(0, nodes)
        return []

It doesn't handle the general case yet.  Left as an exercise...

> BTW, I was able to successfully write my ``include-output`` directive
> quite easily (this is the one that includes the output of a Python
> script). 

Please check in the code!

> Aside from my difficulties with interacting with reST
> internals, I'm pretty happy with the current system for writing
> directives.  The HOW-TO has been quite helpful.

Glad to hear it.  Thanks go to Dethe Elza for getting the ball rolling.

-- 
David Goodger  <go...@us...>  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/

Aahz wrote:
> Here's what I'm actually doing::
> 
>     source = document.current_source
>     if source is None:
>         return os.getcwd()

``document.current_source`` will only be set to ``None`` after parsing
is finished.  If this code is inside a directive function, parsing is
ongoing, so you shouldn't need the test.  If that local ``source`` is
ever ``None``, it would be a bug, and the test above would mask it.

> Now that I understand what's going on, I'm a bit less unhappy, but I
> think that perhaps the names should be changed from
> ``source``/``current_source`` to ``original_source``/``source``.

"source" is the source of the element itself.  It doesn't change.
"current_source" is the source of the line of data currently being
parsed.  This may change, for example if an "include" directive is
used.  The names make sense to me.

> I'm still a bit confused about the distinction between
> ``document.source`` (which is ``None``) and ``document['source']``.

``document.source`` is an internal instance attribute, an
implementation detail, added to get better error/warning output.
``document['source']`` is an external attribute.  All external
attributes are stored in ``element.attributes`` (a dict), get
exported as XML attributes, and are documented in spec/docutils.dtd
and spec/doctree.txt.

> I'm also thinking that the use of ``Element.__getitem__`` needs
> redesign; I can just imagine what Alex Martelli would say about
> getting different kinds of data based on the type of key presented.
> Probably the simplest approach would be to stop using
> ``__getitem__`` as a proxy for ``Element.attributes``.  (I'm not
> going to argue with you, but I can tell you that Alex *WILL* argue
> with you if/when he sees that. ;-)

You know what?  I don't care what Alex would say. :-)

The technique makes sense for this application.  ``element[0]`` gives
the first child, and ``element['name']`` gets the "name" attribute.
It may be a wart to some eyes, but it's a very practical and useful
wart that reduces complexity.  If you don't like it, use
``element.children[0]`` and ``element.attributes['name']``; but they
don't do the extra bookkeeping that ``Element.__setitem__`` and
friends do.

I seem to recall a quote about just this topic, maybe it was Guido
expressing his disgust with a similar convention.  But I can't locate
it now.  Pity.

-- 
David Goodger  <go...@us...>  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/

On Fri, Oct 11, 2002, David Goodger wrote:
> Aahz wrote:
>>
>> I'm assuming I need to run a transform in the writer?
> 
> No.  By the time the document gets to the Writer, it should be in
> final form.  The Writer's job is simply (and only) to translate from
> the Docutils doctree structure to the target format.  Some small
> transforms may be required, but they should be local and
> format-specific.  The "index_entry" node class is not format-specific
> and should become a standard Docutils node/element (i.e. part of
> nodes.py and docutils.dtd).  We can figure out its syntax (attributes
> & content model) later.
> 
>> Or should the directive find its parent/predecessor-sibling during
>> parsing?
> 
> I think so.  Given::
> 
>     Here's a paragraph.
> 
>     .. index:: paragraph
> 
> The directive should produce something like this XML::
> 
>     <paragraph>
>     <index_entry text="paragraph"/>
>     Here's a paragraph.
>     </paragraph>

Given my lack of knowledge about XML and reST internals, where should I
look for information about writing this part of the directive?  That is,
how do I go about correctly inserting a node into the tree during
directive processing?  (Instead of returning a list of nodes.)

BTW, I was able to successfully write my ``include-output`` directive
quite easily (this is the one that includes the output of a Python
script).  Aside from my difficulties with interacting with reST
internals, I'm pretty happy with the current system for writing
directives.  The HOW-TO has been quite helpful.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/

On Fri, Oct 18, 2002, David Goodger wrote:
> Aahz wrote:
>>
>> Given the full path /users/aahz/book/chapter/source.txt, in the
>> context of processing a directive in source.txt, how do I retrieve
>> the value /users/aahz/book/chapter/ ?
>> 
>> I'd have thought state_machine.document.source would have the path
>> (or at least a FileInput object from which it could be retrieved),
>> but it doesn't.
> 
> ``state.document['source']`` has the path of the first source,
> relative to the current directory.  I'd recommend you use
> ``state.document.current_source`` though, since the source may change
> with an "include" directive.  To get the directory of the current
> source, use::
> 
>     os.path.dirname(os.path.abspath(state.document.current_source))

Here's what I'm actually doing::

    source = document.current_source
    if source is None:
        return os.getcwd()
    else:
        dirname = os.path.dirname(os.path.abspath(source))
        if dirname is None:
            return os.getcwd()
        else:
            return dirname

>> I finally found it in state_machine.document.current_source.  I consider
>> this far from obvious.
> 
> You find that an undocumented (except for docstrings) internal
> implementation detail is not obvious?  Good for you.

That was just me being a bit grumpy about what I saw as an arbitrary
change of an attribute name (``source`` gets used in a lot of different
places in the code, so I was using that to track things down).  Now that
I understand what's going on, I'm a bit less unhappy, but I think that
perhaps the names should be changed from ``source``/``current_source`` to
``original_source``/``source``.

I'm still a bit confused about the distinction between ``document.source``
(which is ``None``) and ``document['source']``.

I'm also thinking that the use of ``Element.__getitem__`` needs redesign;
I can just imagine what Alex Martelli would say about getting different
kinds of data based on the type of key presented.  Probably the simplest
approach would be to stop using ``__getitem__`` as a proxy for
``Element.attributes``.  (I'm not going to argue with you, but I can
tell you that Alex *WILL* argue with you if/when he sees that. ;-)
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/

gr...@us... wrote:
> ok, This means, the specification says access language.labels
> directly without checking for existance of the element.

The specification doesn't (or didn't, until spec/howto/i18n.txt) say
anything about this.  The code does.  It's just an implementation
detail.

> i still think this should be put into code not documentation.
> 
> def label(self,internal_name):
>     return self.labels[internal_name)

I don't see the difference.  It looks like unnecessary indirection to
me.

> gives consistant behaviour over all accesses, because i would not
> have read this specification, and definately checked for existance.

I disagree.  Let's move on.

From this and previous discussions, it's obvious to me that we have
different philosopies of programming, or we're misunderstanding each
other.

-- 
David Goodger  <go...@us...>  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/

Aahz wrote:
> Given the full path /users/aahz/book/chapter/source.txt, in the
> context of processing a directive in source.txt, how do I retrieve
> the value /users/aahz/book/chapter/ ?
> 
> I'd have thought state_machine.document.source would have the path
> (or at least a FileInput object from which it could be retrieved),
> but it doesn't.

``state.document['source']`` has the path of the first source,
relative to the current directory.  I'd recommend you use
``state.document.current_source`` though, since the source may change
with an "include" directive.  To get the directory of the current
source, use::

    os.path.dirname(os.path.abspath(state.document.current_source))

Thanks, this showed me that the "include" directive wasn't handling
paths properly.  The path given for the include file should be
interpreted relative to the file it's contained within.  See
docutils/parsers/rst/directives/misc.py, functions "include" and
"raw", for details.

> I finally found it in state_machine.document.current_source.  I consider
> this far from obvious.

You find that an undocumented (except for docstrings) internal
implementation detail is not obvious?  Good for you.

-- 
David Goodger  <go...@us...>  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/

* Improved vertical whitespace issues with HTML output.  This affects
  first and last elements in containers, and removes unnecessary top
  and bottom margins (resp.).  For example, a literal block at the top
  of a table cell won't have a ridiculous top margin.

* Changes to API details that affects client code:

  - Renamed transform method "transform" to "apply".

  - Renamed "options" to "settings" for runtime settings (as set by
    command-line options).  Sometimes "option" (singular) became
    "settings" (plural).  Some variations below:

    - document.options -> document.settings (stored in other objects
      as well)
    - option_spec -> settings_spec (not directives though)
    - OptionSpec -> SettingsSpec
    - cmdline_options -> settings_spec
    - relative_path_options -> relative_path_settings
    - option_default_overrides -> settings_default_overrides
    - core.Publisher.set_options -> core.Publisher.get_settings

  - Renamed core.publish() to core.publish_cmdline(), and added
    placeholders for new publish_string() and publish_file()
    convenience functions.

  Please make corresponding changes to client code.  I'll be happy to
  help if it's non-trivial.  I've updated many of the modules in the
  sandbox, but I may not have changed everything (or I may have
  changed too much).  Individual authors, please test the updated
  code.  Thanks.

  Gunnar, I wasn't able to update DocFactory.  It seemed to be using
  "options" in different ways, doing its own config file parsing, and
  I didn't know which "options" to change to "settings".

* Some bug fixes.

-- 
David Goodger  <go...@us...>  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/

On Thu, Oct 17, 2002, Aahz wrote:
>
> Given the full path /users/aahz/book/chapter/source.txt, in the context
> of processing a directive in source.txt, how do I retrieve the value
> /users/aahz/book/chapter/ ?
> 
> I'd have thought state_machine.document.source would have the path (or
> at least a FileInput object from which it could be retrieved), but it
> doesn't.

I finally found it in state_machine.document.current_source.  I consider
this far from obvious.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/

Hi Trent & Barry,

Thanks for your bug reports, arriving within hours of each other.  I
discovered that bug myself today and squashed it.  Will check in the
fix tonight.

-- 
David Goodger  <go...@us...>  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/

Hi David,

Following the instructions in python/nondist/peps/README.txt I get the
following error building the current PEPs:

    [trentm@pliers ~/tmp/python/nondist/peps]
    $ cvs update
    cvs server: Updating .
    P pep-0008.txt
    [trentm@pliers ~/tmp/python/nondist/peps]
    $ python setup.py pep-0012.txt
    python: can't open file 'setup.py'
    [trentm@pliers ~/tmp/python/nondist/peps]
    $ python pep2html.py pep-0012.txt
    pep-0012.txt (text/x-rst) -> pep-0012.html
    Traceback (most recent call last):
      File "pep2html.py", line 516, in ?
        main()
      File "pep2html.py", line 485, in main
        newfile = make_html(file, verbose=verbose)
      File "pep2html.py", line 368, in make_html
        PEP_TYPE_DISPATCH[pep_type](inpath, input_lines, outfile)
      File "pep2html.py", line 305, in fix_rst_pep
        pub.publish()
      File "/home/trentm/local/ActivePython-2.2.1-223/lib/python2.2/site-packages/docutils/core.py", line 135, in publish
        document = self.reader.read(self.source, self.parser, self.options)
      File "/home/trentm/local/ActivePython-2.2.1-223/lib/python2.2/site-packages/docutils/readers/__init__.py", line 68, in read
        self.input = self.source.read(self)
      File "/home/trentm/local/ActivePython-2.2.1-223/lib/python2.2/site-packages/docutils/io.py", line 216, in read
        if self.options.input_encoding.lower() == 'unicode':
    AttributeError: 'NoneType' object has no attribute 'lower'
    [trentm@pliers ~/tmp/python/nondist/peps]
    $ python -c "import docutils; print docutils.__version__"
    0.2.5

Do I need to get a more recent docutils package?
I haven't really looked into the problem specifics yet. If you are swamped I
can try to do so if you like.


Cheers,
Trent

-- 
Trent Mick
Tr...@Ac...

Given the full path /users/aahz/book/chapter/source.txt, in the context
of processing a directive in source.txt, how do I retrieve the value
/users/aahz/book/chapter/ ?

I'd have thought state_machine.document.source would have the path (or
at least a FileInput object from which it could be retrieved), but it
doesn't.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/

On Wed, 16 Oct 2002, David Goodger wrote:

> [Engelbert]
> >>> Should languages.labels become a function which tries, exact case
> >>> all lower and if both fails returns the passed text ?
>
> [David]
> >> No.  This is another case of "errors should never pass silently".
> >> If the label is missing from the language module, it's a bug.
>
> [Engelbert]
> > but maybe a function label() which does not only give a traceback
> > but a real error with description.
>
> No!  The "real error" here is that some data is missing from the
> mapping, or that the wrong key is being accessed.  A traceback is
> *absolutely* appropriate.  If a traceback occurs, it means there's a
> bug in the *code* that needs to be fixed.  Docutils Reporter
> warnings/errors indicate problems in the *input*.  They're completely
> different (and incompatible) things.

ok, This means, the specification says access language.labels directly
without checking for existance of the element.

i still think this should be put into code not documentation.

def label(self,internal_name):
	return self.labels[internal_name)

gives consistant behaviour over all accesses, because i would not
have read this specification, and definately checked for existance.

>
> >> .. [*] I notice you've just added a German de.py as well.  Great,
> >>    thanks!  Unfortunately, even the en.py file it was based on
> >>    isn't up to date. :-(  I'll fix it, probably tomorrow.  I think
> >>    even this is an example of a "silently passing" exception.  I'll
> >>    add some warnings.
>
> This is done now.

i see into de.

-- 
 BINGO: professionally create virtual services
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

[Engelbert]
>>> Should languages.labels become a function which tries, exact case
>>> all lower and if both fails returns the passed text ?

[David]
>> No.  This is another case of "errors should never pass silently".
>> If the label is missing from the language module, it's a bug.

[Engelbert]
> but maybe a function label() which does not only give a traceback
> but a real error with description.

No!  The "real error" here is that some data is missing from the
mapping, or that the wrong key is being accessed.  A traceback is
*absolutely* appropriate.  If a traceback occurs, it means there's a
bug in the *code* that needs to be fixed.  Docutils Reporter
warnings/errors indicate problems in the *input*.  They're completely
different (and incompatible) things.

>> .. [*] I notice you've just added a German de.py as well.  Great,
>>    thanks!  Unfortunately, even the en.py file it was based on
>>    isn't up to date. :-(  I'll fix it, probably tomorrow.  I think
>>    even this is an example of a "silently passing" exception.  I'll
>>    add some warnings.

This is done now.

> I had to because i could not use labels in writer without, guess "-l
> de" tries to switch the rst part to, so therefore it is needed,
> otherwise one gets the traceback (hate it).

If you hate tracebacks so much, please help get rid of them.  Please
help fix the cause (at least submit a bug report), instead of fixing
the symptom.  What you describe above is a symptom-fix only.  In this
case, fixing the cause is much easier!

> could you make sense of the documentation part ?

OK.  See http://docutils.sf.net/spec/howto/i18n.html .

-- 
David Goodger  <go...@us...>  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/

On Tue, 15 Oct 2002, David Goodger wrote:

> > casesensitivity on directives and or field namings ?
>
> No.  Directive names and field names are converted to the canonical
> key form -- lowercase -- before lookup.  The original case doesn't
> matter.

i recognized, that there is some forth and back, ok.


> > Should languages.labels become a function which tries, exact case
> > all lower and if both fails returns the passed text ?
>
> No.  This is another case of "errors should never pass silently".  If
> the label is missing from the language module, it's a bug.  If the
> ``labels`` dict of a language module is being accessed, it's either
> because the "official" text for a bibliographic field is needed (in
> which case the ``bibliographic_fields`` dict must have already been
> accessed), or because some boilerplace text (such as "!DANGER!")  is
> needed.  In either case, a missing entry means the dict is not up to
> date, or there's some other bug in the code.  Such a bug should
> definitely cause a traceback.

ok. i thought about the function, because i check with has_key
to avoid the traceback.

but maybe a function label() which does not only give a traceback but
a real error with description.


> We currently have English and Swedish directives [*]_
> (docutils/parsers/rst/languages/) and English, Swedish, and German
> labels (docutils/languages/).  Only the English labels module is up to
> date.  Patches/updates welcome!
>
> .. [*] I notice you've just added a German de.py as well.  Great,
>    thanks!  Unfortunately, even the en.py file it was based on isn't
>    up to date. :-(  I'll fix it, probably tomorrow.  I think even
>    this is an example of a "silently passing" exception.  I'll add
>    some warnings.

I had to because i could not use labels in writer without,
guess "-l de" tries to switch the rst part to, so therefore it is needed,
otherwise one gets the traceback (hate it).

could you make sense of the documentation part ?

-- 
 BINGO: Hoeren Sie auf zu mosern!
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

Engelbert Gruber wrote:
> Docutils can be adapted to languages in two sections:

So far, yes.

> casesensitivity on directives and or field namings ?

No.  Directive names and field names are converted to the canonical
key form -- lowercase -- before lookup.  The original case doesn't
matter.

> Should languages.labels become a function which tries, exact case
> all lower and if both fails returns the passed text ?

No.  This is another case of "errors should never pass silently".  If
the label is missing from the language module, it's a bug.  If the
``labels`` dict of a language module is being accessed, it's either
because the "official" text for a bibliographic field is needed (in
which case the ``bibliographic_fields`` dict must have already been
accessed), or because some boilerplace text (such as "!DANGER!")  is
needed.  In either case, a missing entry means the dict is not up to
date, or there's some other bug in the code.  Such a bug should
definitely cause a traceback.

We currently have English and Swedish directives [*]_
(docutils/parsers/rst/languages/) and English, Swedish, and German
labels (docutils/languages/).  Only the English labels module is up to
date.  Patches/updates welcome!

.. [*] I notice you've just added a German de.py as well.  Great,
   thanks!  Unfortunately, even the en.py file it was based on isn't
   up to date. :-(  I'll fix it, probably tomorrow.  I think even
   this is an example of a "silently passing" exception.  I'll add
   some warnings.

-- 
David Goodger  <go...@us...>  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 can be adapted to languages in two sections:

1. directives: This gives a mapping from directives as in the document
   to standard names used inside docutils.

   see ``docutils/parsers/rst/languages``

2. labels, bibliographic fields and author_separators:

   e.g.::

      s = languages.get_language("sv").labels["date"]
      # s is now swedish for date

   see ``docutils/languages``

Attention:

  For usage of languages also the directinves module has to be present.

Question:

  casesensitivity on directives and or field namings ?
  Should languages.labels become a function which tries, exact case
  all lower and if both fails returns the passed text ?


-- 
 BINGO: work smarter
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

On Tue, 15 Oct 2002 5:25 pm, gr...@us... wrote:
> On Tue, 15 Oct 2002, Richard Jones wrote:
> > On Tue, 15 Oct 2002 1:17 am, David Goodger wrote:
> > > One thing to take out of this, is to compare how different tools
> > > generate their collections of files.  Epydoc makes one directory with
> > > a slew of files, some with *very* long names, like
> > > "docutils.parsers.rst.states.EnumeratedList.html".  I'd much prefer to
> > > use the filesystem to organize files hierarchically, as in
> > > "docutils/parsers/rst/states/EnumeratedList.html".  This was one of
> > > the reasons I got interested in auto-documentation in the first place:
> > > pythondoc did the long name thing, and MacOS classic couldn't handle
> > > it with its 38-char filename limit.
>
> what is the difference between
> "docutils.parsers.rst.states.EnumeratedList.html"
> "docutils/parsers/rst/states/EnumeratedList.html"
>
> def create_file( class_name ):
>     fname = class_name . ".html"
>     if not flat:
>         fname.replace(".","/")
>     ensure_directory_exists( fname )
>     return open(fname,"w")
>
> actually on the mac it should look like this.
> "docutils:parsers:rst:states:EnumeratedList.html"

Yes, it should be:

   fname = os.path.join(*class_name.split('.')) + '.html'
   
(someone's been programming Perl lately... class_name . ".html" indeed ;)


     Richard

On Tue, 15 Oct 2002, Richard Jones wrote:

> On Tue, 15 Oct 2002 1:17 am, David Goodger wrote:
> > One thing to take out of this, is to compare how different tools
> > generate their collections of files.  Epydoc makes one directory with
> > a slew of files, some with *very* long names, like
> > "docutils.parsers.rst.states.EnumeratedList.html".  I'd much prefer to
> > use the filesystem to organize files hierarchically, as in
> > "docutils/parsers/rst/states/EnumeratedList.html".  This was one of
> > the reasons I got interested in auto-documentation in the first place:
> > pythondoc did the long name thing, and MacOS classic couldn't handle
> > it with its 38-char filename limit.
what is the difference between
"docutils.parsers.rst.states.EnumeratedList.html"
"docutils/parsers/rst/states/EnumeratedList.html"

def create_file( class_name ):
    fname = class_name . ".html"
    if not flat:
        fname.replace(".","/")
    ensure_directory_exists( fname )
    return open(fname,"w")

actually on the mac it should look like this.
"docutils:parsers:rst:states:EnumeratedList.html"
>
> Note that OSX still has that limit in places (tar, of all things, unless it's
> been fixed in a recent patch release).
>
>
> > So here's a requirement: when splitting files, each split level should
> > generate a new directory rather than another segment of a compound file
> > name.
>
> Seems reasonable enough to me, as long as there's a good TOC :)

-- 
 BINGO: definitive merger agreement
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

On Fri, Oct 11, 2002, David Goodger wrote:
> Aahz wrote:
>> 
>> If people want to see my code, I'm willing to stick it in a sandbox,
> 
> Are you "aahz" on SourceForge?

Yup.  I'm not sure that I can stick on SF myself; I assume plain CVS
works correctly, but I've had too many problems with Lynx vs. SF that
I'm not willing to commit to doing it myself.

>> but I really, really don't want comments about how ugly it is.
> 
> And here you are calling "Bad Design" on *my* code.  You can dish it
> out but can't take it, hmm?  ;-)

I'm not calling my code a Project.  ;-)  It's a dirty hack, plain and
simple.  You want to make snotty comments about my BCD code, that's
another matter.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/