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

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

Dethe Elza wrote:
>> The concept of "optional" is useful.  I'm using the XML idea of
>> #IMPLIED attributes, rather than defaults in the DTD (or in the
>> attribute parsing code, in our case).  I've always found it more
>> flexible for the downstream parts of the processing chain to make the
>> decisions; keep your options open.  If you put in default values
>> early, you lose the information that the attribute just *wasn't
>> specified*, and that can be valuable information lost.
>
> I think that this complicates processing by the user (programmer) of
> a directive.  When searching for a value, we'll always have to test
> whether the value is set or not.  Note, that the #IMPLIED vs. DTD
> default isn't what I'm arguing here--that's an implementation
> detail.  If you're parsing HTML or another known format and the spec
> says that htmlOption.selected returns a boolean, you want to get a
> boolean whether the option was set explicitly <option
> selected="false"/> or not <option/>.

But directives are *not* XML tags.  I think that the now-obsolete
"attribute" terminology was misleading.  Calling them "options" is
much better.  Let's drop the name "attribute" altogether.

> If all we want to know is, 'was this set?' we can initialize to
> false (0) and pass the exists function ('def exists(arg): return
> 1).  If we need to know existence as well as value, then return a
> tuple (def existsInt(arg): return (1, int(arg)).  Again, this is
> explicit vs. implicit, and it allows you to change things like:
>
> if attributes.has_key('selected') and attributes['selected']:
> else:
>     do_if_true()
> else:
>   do_if_false()
>
> to:
>
> if attributes['selected']:
>   do_if_true()
> else:
>   do_if_false()
>
> Which looks cleaner to me.  I guess there's some question of whether
> this is a valid usecase.  Personally, I would rather know that I can
> access an attribute and get a value back consistently, without
> having to test for it.  I guess it depends on where and how often we
> need to know whether a value has not been set at all.

I first thought up a hypothetical use case counterargument, but it
wasn't convincing:

    Say there's a global-impact directive with an option which sets
    some persistent parameter, and this directive can occur multiple
    times.  Subsequent occurrences should use the previous directive's
    option settings by default (i.e., don't override the persistent
    parameter unless the option was explicitly set).  The second time
    the directive occurs, if there's a default value for the option,
    there's no way to know that the option wasn't explicitly set, and
    the default from the first directive's option will be lost.
    Perhaps all we have to do is to use an invalid default value (like
    ``None``), and check for that before resetting the persistent
    parameter.

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.

I don't find testing for the existence of dictionary keys particularly
onerous.  And in this case, the solution seems to be much worse than
the problem.

Unless there's another solution?

>> Modelling directives on shell commands works well.  Let's
>> go with it.
>
> Does it?

For me, yes.  Can't speak for everybody. :-)

But at least it's an established standard that many people are
familiar with.  And directives *are* commands; they're commands to the
parser from inside the document.  Again, they're *not* XML elements.

> I find shell command options to be really difficult to remember,
> after ten years of steady use.

Details are always hard to remember.  I don't know that we can do more
than standardize the directive interface (into arguments, options, and
content, which we're doing now), choose good names for options, and
document it all well.  Directives are always going to be "power user"
tools.

> And shell commands are inherently verbs, making their options
> adverbs, if you will.  Documents are inherently nouns, making their
> option/attributes adjective, to stretch a metaphor.

I'd say that directives are verbs too, although most are named after
nouns.  The directive syntax should be read as "do X" or "make an X".
But the syntax is easily ignored.

>> Out of curiosity, what would a Zope/ZReST URL look like?
...
> In other words, the URI paths are turned into object refernces in
> the ZODB (Zope Object Database) and the default action is taken on
> them (call, if it's a method, transform into HTML if it's data,
> etc.)  It's a rich and complex environment, with a bit too much
> magic going on behind the scenes for my taste.

I see.  Thanks for the explanation!

>> * ".. raw:: format" + either:
>>
>>   - a second, optional "filepath" argument, or
>>   - a "source" (or equivalent) option, or
>>   - (perhaps best?) *two* options, one for a filesystem path source,
>>     the other for a URL source (and we can't use both in one
>>     directive)
>
> There's actually a usecase for including both.  It's the same as
> using both PUBLIC and SYSTEM identifiers for a DTD.  Basically, it
> says, get it from this URL if available, or this file if you can't
> get to the URL for some reason.  A fallback option, in other words.

I don't know if we're ever "gonna need it", but go ahead if you're
keen.

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