Re: [Docutils-users] "settings directive

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

[David Goodger]
>> I like your idea of adding the config section as the directive
>> argument; that's a good solution that nicely leverages the config
>> file model.  The argument should be optional though, with no
>> argument equivalent to "general".

On 3/8/07, Felix Wiemann <Fel...@os...> wrote:
> Let's go over the general settings to check what settings we need
> the "general" 'section' for (the long lists of settings in this post
> are not meant to be persuasive but mostly to clear my own head):

I don't understand your concerns or direction.  You seem to be
assuming that individual settings will need to be implemented
individually for this directive.  They won't.  We'll just reuse the
existing settings mechanism, adding a few exceptions for security.  In
other words, I'm saying we should allow *all* settings to be affected
by the "settings" directive, except for a specific few.  You seem to
be saying that we should only allow a few, specific,
individually-chosen settings.  That way lies madness, and a lot of
debate, and a lot of maintenance work.  No.

You glibly say "move to a transform", but I don't think that would be
so easy or even desirable.  Do we *want* to expose transforms to the
setting mechanism?  I think not.  That would expose transforms to the
user interface (i.e. they'd show up as sections in --help output).
Bad idea.  In any case, it's a separate issue.

We're talking about a "settings" directive.  Let's deal with settings
as they stand currently, without a simultaneous grand reorganization
of the entire mechanism.  If you want to do such a grand
reorganization, let's talk about it separately.  If such a grand
reorganization is necessary for this directive, let's handle that
first, then come back to the directive.  It is counter-productive to
discuss them at the same time.

>> Parser settings should also be allowed.
>
> Let's look at the use cases for changing reST parser settings:
>
> Security: file_insertion_enabled, raw_enabled
> Too late to change at run-time (with current implementation):
> tab_width

Counter-example: change tab-width before the "include" directive.  Of
course this particular case should be implemented as a directive
option, but it isn't now, and disallowing such settings places
artificial and unnecessary limits.

> Changing parser settings at run-time is more fragile than changing
> writer or transform settings.  Allowing it adds complexity because
> we need to have a white-list of changeable parser options.

Why?  I say we should have a black-list instead.

> I don't see enough benefit for the added complexity now.  I'm sure
> one can come up with valid use cases (e.g. changing directive
> behavior, or adding syntax constructs at run-time), but as long as
> we don't have an actual use-case for that, I don't think we should
> bother.  We can still implement it later.

No, we can't.  I'm promoting a completely different approach than
yours, and they're incompatible.  Further debate is useless, so:

Pronouncement: any "settings" directive will behave identically to the
existing runtime settings mechanism: configuration files and
command-line options.  All settings will be accessible through this
directive, with exceptions only for security.

Let's keep it as simple as possible.

> (The standalone reader only has doctitle_xform and
> sectsubtitle_xform, which both apply to transforms.  So no need to
> allow changing reader settings for now either.)

Here I disagree strongly.  These are *perfect* examples of
document-specific settings.

> How about these use cases:
>
>       .. settings:: SectionSubTitle transform
>       .. settings:: StripComments transform
>       .. settings:: StripClassesAndElements
>          :classes: class-one class-two
>          :elements: class-three class-four

This exposes too much of the implementation to the user.  Bad idea.
The more I think about it, the more I realize that putting settings on
transforms is NOT a good thing to do.

In any case, I completely disagree with the approach in the example
above.  The first two don't even specify any settings!

>>> Options like "--[no-]section-numbering" would need to go out of
>>> the general option space into the SectNum transform
>>>
>>> [so make Transform a SettingsSpec]
>>
>> Hyper-generalization.  YAGNI.
>
> My SectNum example is bad, but when you provide a transform as a
> plugin, you do need some way to add settings.

I don't know. I'd want to see a valid example first.

>> One tricky point about the implementation: document settings should
>> override defaults & config file settings, but they should be
>> overridden by command-line settings.
>
> I beg to differ, for two reasons:
>
> First, it's kindof hard to implement as you point out (and may cause
> a headache when we try to define the correct behavior).

So what?  Implementation difficulty doesn't matter.  Doing the right
thing is what matters.

> Second, document settings can be more specific than command line
> options, since command line options can apply to several documents
> (examples: buildhtml, Python source reader, large document support),
> and document settings are document-specific.

But command-line options are more immediate and dynamic.

The right thing is for document settings to be higher priority than
defaults & config files, but lower than command-line options.

>> Question: should misspelled settings in the "settings" directive
>> trigger errors?
>
> Yes, definitely!  It's really unfortunate [3]_ that error-checking
> is not possible for config files right now; I definitely wanna have
> that feature in a "settings" directive.
>
> .. [3] E.g. "language: de" (instead of "language_code: de") took me a
>     while. :-)

We could add some error-checking for config files.

>> This would mean that the config section argument would be
>> *required* in some cases.
>
> Yes, sounds right.

Actually, that sounds extremely fragile to me.  If I have this in my
doc:

    .. settings::

       :compact-lists: on

It will run fine through rst2html.py, but crash with rst2latex.py due
to an unknown setting.  I know, the reponse will be "require config
sections / component names", as in:

    .. settings:: html4css1 writer

       :compact-lists: on

I will go on record now to say that this is far too complex and is not
an acceptable user interface.  We will not require authors to jump
through such hoops.

Instead of requiring component names, the settings directive should be
forgiving.  If it encounters any unknown settings, it should issue a
warning only, and ignore that setting.  It's easy to check for
settings, because document.settings is just a dictionary, so just
check for existing keys.  The warning could say "setting unknown:
either misspelled or not applicable to the current Docutils
components; see
<http://docutils.sf.net/docs/ref/directives.html#settings>" (or some
other suitable URL).

(Note: I'm not sure whether to implement the settings themselves as
directive options or as content.  If the latter, a blank line will be
required before the field list.  If the former, the implementation
may be very tricky.)

-- 
David Goodger <http://python.net/~goodger>