Docutils: Documentation Utilities

On 2009-11-13, David Goodger wrote:
> On Wed, Nov 11, 2009 at 06:58,  <milde@...> wrote:
>> New function filter_settings_spec
>> Return a copy of `settings_spec` excluding the specified settings.

> What is the purpose of this new function?

Enable code inheritance.

Up to now, a writer inheriting from another one (like the S5/HTML
Slideshow Writer, can replace the parents `settings_spec` or append to it
but not modify it:

append:
 -1 settings without effect keep turning up in the --help output.

replace: 
 -1 code duplication.

modify:
 !  settings_spec is a tuple of tuples,
 !  settings_spec is *very* compact an complex.

With the new function, it is possible to specify a modified version of
the parent's settings_spec:

  Return a copy of `settings_spec` excluding/replacing some settings.

  `settings_spec` is a tuple of configuration settings with a structure
  described for docutils.SettingsSpec.settings_spec.

  Optional positional arguments are names of to-be-excluded settings.
  Keyword arguments are option specification replacements.
  (See the html4strict writer for an example.)

> Why did you add it?

To make it easier for Docutils users and developers to create writer
variants based on the writers that ship with Docutils.

There is a concrete usage case for the html4strict writer (in the
sandbox) and intended use for the upcoming "xelatex" writer (support for
the Unicode-aware LaTeX variant XeLaTeX).

Please advise, if there is a more suitable place for this functionality.

Thanks,

Günter

2009/11/16 Guenter Milde <milde@...>:
> On 2009-11-13, David Goodger wrote:
>> On Wed, Nov 11, 2009 at 06:58,  <milde@...> wrote:
>>> New function filter_settings_spec
>>> Return a copy of `settings_spec` excluding the specified settings.
>
>> What is the purpose of this new function?

Thanks for the explanation.

> Please advise, if there is a more suitable place for this functionality.

The problem was that the function was added to the core before any
mention of it existed anywhere else, so it appeared to be junk code
from the start. I hate junk code, especially *new* junk code.

I think it would have been better in the sandbox adjacent to where
it's used. Let such code prove itself where it's used and needed. Then
(and *only* then) if it ends up being useful for other code, promote
it to the core.

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

On 2009-11-16, David Goodger wrote:
> 2009/11/16 Guenter Milde <milde@...>:
>> On 2009-11-13, David Goodger wrote:
>>> On Wed, Nov 11, 2009 at 06:58,  <milde@...> wrote:

>>>> New function filter_settings_spec
...
>> Please advise, if there is a more suitable place for this functionality.

> The problem was that the function was added to the core before any
> mention of it existed anywhere else, so it appeared to be junk code
> from the start. I hate junk code, especially *new* junk code.

Fair enough.

> I think it would have been better in the sandbox adjacent to where
> it's used. Let such code prove itself where it's used and needed. Then
> (and *only* then) if it ends up being useful for other code, promote
> it to the core.

Shall I move it to the html4strict writer than, or just leave in this
case?

Günter

On Mon, Nov 16, 2009 at 10:18, Guenter Milde <milde@...> wrote:
> On 2009-11-16, David Goodger wrote:
>> I think it would have been better in the sandbox adjacent to where
>> it's used. Let such code prove itself where it's used and needed. Then
>> (and *only* then) if it ends up being useful for other code, promote
>> it to the core.
>
> Shall I move it to the html4strict writer than, or just leave in this
> case?

At this point I don't care -- the pain is past.

But in future, please consider the gatekeeper!

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