[Doc-SIG] Clarification: interpreted text vs. directives vs. substitutions

[David Goodger]

Alan Jaffray wrote:
> 1) Does the "indirect directive" have access to the substitution
>    reference text?

I assume you mean the substitution name, the text between the "`/" and "/`"?
Currently no, it doesn't. I don't see why it would need any such access.

>    Can it take a block argument?

The directive part of the substitution can take a block argument, that's
up to the directive::

    Here's a contrived `/example/`.

    .. /example/ contrived-directive::
       The directive does something with all this text.
       Don't ask me what.
       23 17 5 ... hut!

>    How exactly does this work?

The substitution construct is recognized, which triggers the recognition
of an embedded directive (it's an error if there is no directive). The
directive's code is run, and the result becomes the contents of the
substitution. A transform later replaces any matching substitution
references with said contents.

> 2) I dislike the slashes.  To me they mean either "italics" or "path"
>    or "regex".  The latter two are also sources of ambiguity.  I can't
>    think of a *good* syntax, but I think `` `|text here|` `` and
>    ``.. |text here| directive:: args`` would be better.

Decent alternative. I'll take it under advisement. (Now I've got judiciary
delusions!)

Another possibility is `[name]`. Each of `/name/` and `[name]` and `|name|`
effectively limit (albeit only slightly) interpreted text though. Other
(more radical) alternatives?

> 3) "Directive references" and "directive targets" were the terms I used
>    in my revised proposal.  We're certainly way past "substitution" now.

Perhaps. I'd have to add "inline" though: "inline directive references" &
"inline directive targets". "Targets" doesn't seem right though, perhaps
"definitions" instead. I'll have a go through my thesaurus (an invaluable
reference on my techref shelf), see if anything else rings true.

Both the syntax and the name of substitutions (& references) may change.

> 4) I dislike the double-colon after the directive name - we already
>    know that it's a directive name, it's part of a directive target.
>    I'd remove it or make it optional.

They're a useful reminder of what's intended. Think of it as the
"/subname/" being wedged into an existing directive.

>    However, I expect everyone else will disagree. :-)

Bingo!

-- 
David Goodger    goodger@users.sourceforge.net    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net