Re: [Docutils-develop] Directives Howto (in progress)

[Dethe E. <Dad...@li...>]

OK, I've finally got the directives ready for comment and I've updated
the HOWTO based on Aahz's feedback.  Aahz brings up a good point, which
I didn't catch the first time, which is the question of whether
parse_directive is called by the directive implementation, or the
directive implementation is called by parse_directive.

Right now, the directive calls parse_directive, but this is boilerplate
code and it could easily be reversed (with some savings in repetitive
coding).  Currently the directive passes in a dictionary of option
handlers to parse_directive, but these could just as easily be
registered when the directive itself is registered.

One possible way to make directives even easier to implement (besides
the above refactoring) would be to allow the parse_directive have even
more information about the expected result (i.e., do we expect a
non-empty content block, multiple arguments, mandator "options",
etc.?), rather than the current state of putting the burden of checking
values on the directive implementation.  On the other hand, the
directive is where this is known, and it's possible to make the
parse_directive *too* general, spending time and creating complexity to
what is basically trivial to determine in the directive implementation.

Other opinions?

--Dethe

On Tuesday, September 17, 2002, at 11:47 AM, Aahz wrote:

> On Thu, Aug 29, 2002, Dethe Elza wrote:
>>
>> Define Directive
>> ----------------
>>
>> The directive signature itself should follow this template:
>
> Shouldn't that be "template::"?
>
> Also, you should explain that a directive is a plain function (a
> callback), not a method.
>
>>     def my_directive(match, type_name, data, state, state_machine,
>> option_presets):
>
> Reformat to shorter lines?
>
>> Define Options
>> --------------
>>
>> You will have to define the options your directive requires.  This is
>> a
>> dictionary of name, conversion pairs which are applied to each option
>> value to
>> convert it to an expected type.  Python's built-in conversion are
>> often usable
>> for this, for example, str, int, float.  Other useful types would be
>> bool
>> (included in python 1.3) and exists (to test for existence of an
>> option when
>> you don't care about the value or the option has no value).
>
> Python 2.3, right?
>
> Again shorter lines would be better, I think.
>
>> Parse Directive
>> ---------------
>>
>> You'll want to use the parse_directive method, which has returns a
>> 4-tuple
>> (arguments, options, content, blank_finish) and has the following
>> signature:
>
> Method of what?  What does "use" mean?  (I.e., I believe the writer of
> a
> directive doesn't actually call parse_directive(); parse_directive()
> calls the my_directive() callback.  Whether I'm right or wrong, clarity
> is needed.)
>
> (Yes, examples will help, but the text should also be correct and
> complete.)
> -- 
> Aahz (aa...@py...)           <*>
> http://www.pythoncraft.com/
>
> Project Vote Smart: http://www.vote-smart.org/
>