Re: [Docutils-users] Re: Default role

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

 > David Goodger wrote:
 >> I don't see any need to "hook" the markup currently used for
 >> literal blocks (i.e. "default directive"), block quotes, or inline
 >> literals (let alone any other basic markup).  Without a clear and
 >> persuasive need, I don't see the point.

[Felix Wiemann]
 > When writing documents about mathematics or physics, you could want
 > math equations without explicitly specifying it each time.  So
 > instead of ::
 >
 >     Pythagoras's theorem says:
 >
 >     .. latex-math::
 >
 >        a^2 + b^2 = c^2
 >
 > I'd want to write ::
 >
 >     Pythagoras's theorem says:
 >
 >         a^2 + b^2 = c^2
 >
 > You can probably find other use cases as well.

-1.  Too implicit for my taste ("explicit is better than..."), and not
compelling.

 >> The :role:``literal`` syntax [is] an interesting and potentially
 >> useful idea for additional functionality [...].  Rather than having
 >> some roles work with `single backquotes` and others work with
 >> ``double``, I think all roles should work with both.  The choice
 >> would be up to the author, depending on the content and desired
 >> processing.
 >
 > The roles which expect literal text (say, the math role) can't
 > process a node tree (and a node tree is what you'd eventually get,
 > at the latest when there's nested inline markup).

Not necessarily.  Depends on the when the nested parsing takes place:
before the role code is called, or after/during (i.e., nested parsing
initiated *by* the role code).  I'd say that because of this issue,
the role code *must* initiate the nested parse.

 > So you'd *have* to use :math:``somemath``, and :math:`somemath`
 > would be forbidden.

IMO, such a restriction would place an unneccessary burden on the
author.  Custom roles based on the "raw" role work fine with
single-backquotes now, and should continue to work in future.

 > OTOH when we have a typewriter role, the author should be able to
 > use both :tt:``some *literal \text`` as well as :tt:`text with
 > *emphasis*`.

Right.  That's the author's choice, because :tt: can handle both
cases.

 > So roles should probably specify whether they expect a node list or
 > literal text; and if a role takes a node list, the reST parser can
 > helpfully allow :role:``literal *text`` and convert it to a single
 > Text node before passing it to the role handler.

Rather than specifying what they expect, roles should process their
content appropriately.  Think outside-in instead of inside-out.  No
"helpful conversion" required or desired, I think.

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