[Docutils-develop] Re: reST includes first cut (long...)

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

[David]
>> You almost had me convinced.  But after looking at the existing
>> directive code, I saw a problem.  Directives that have options,
>> like "image" or "contents", use the options dictionary returned by
>> "docutils.utils.extract_extension_options" to update another
>> dictionary, either "option_presets" or "pending.details".  In the
>> case of "image", the "option_presets" parameter contains an "alt"
>> entry, a filename to be used as the last-resort default for the
>> "alt" option.  Setting default option values for unspecified
>> options means that the dict.update code would have to become very
>> nasty.  *That's* where the lack of defaults pays off: a
>> ``presets.update(options)`` operation doesn't clobber legitimate
>> presets with bogus defaults.

[Dethe]
> But in this case, aren't the presets the defaults?

Yes, but only if there *are* presets (they're rare), and only if
defaults *always* make sense (they don't).  Take a look at a
substitution definition which uses an "image" directive::

    .. |symbol| image:: symbol.png
       :height: 50
       :width: 100

This will produce the following pseudo-XML::

    <substitution_definition name="symbol">
        <image alt="symbol" height="50" uri="symbol.png" width="100">

The "alt" attribute comes from the substitution name (bracketed by
"|").  With a straight "image" directive (not in a substitution
definition), what should the default "alt" option be?  We rejected the
URL as a default long ago.  The only default that would make sense
would be some form of "no value", like ``None``.  But then the code
would have to special-case a ``None`` value, removing the option at
some point.  Seems like a lot more work than checking for dictionary
keys before accessing them.

And what if there are *no* options? ::

    .. |symbol| image:: symbol.png

What should the default values be for the "height" and "width"
options?  The directive code would have to go through the options
dictionary and remove any that don't make sense (like ``{'height':
None, 'width': None}``).  Here's a perfect example of "not specified"
being different from "default value".

> Wouldn't making the presets act specifically as defaults make the
> code simpler rather than more complicated?  Or am I just not getting
> it?

When you began this thread, I had a "won't work" feeling, but didn't
know exactly why.  During the thread, you almost convinced me twice.
But the feeling never went away and every time I examined the existing
code and examples, I've rediscovered cases where it would be a lot
*more* work to go the defaults route.  It just seems so much simpler
the way it is, and I don't see much benefit from using defaults.  Have
I convinced you yet?  :-)

If not, please code up a solution using defaults and convince me with
proof, not words. ;-)

> Sorry to be so blockheaded on such a relatively trivial matter.

Not at all.  Such questions help us examine assumptions that were
made, often without sufficient initial thought.  Why did I implement
this the way I did?  Straight answer: it made sense at the time.  But
now I have to justify the decision.  Sometimes examining the decision
in detail invalidates it, sometimes it reinforces its validity.
Either way, asking the questions benefits the project.

For example, Dmitry's "sectnum" directive/transform hinted at a
weakness in the transform priority system.  The weakness was fully
exposed by the "target-notes" directive/transform I implemented for
PEPs.  It just goes to show that we can't cling to our code or ideas;
we have to be willing to throw them away if and when they're shown to
be deficient in some way.  But that's not always easy to do.

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