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

[Aahz <aa...@py...>]

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/