Re: [Docutils-develop] Source directory?

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

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/