Re: [Docutils-users] Parsed inline literals?

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

Gavin Sinclair wrote:
 > Forgive me for banging on about applying formatting to literal
 > strings,

No need to ask forgiveness; speaking up & asking questions is how to
learn about and possibly effect change in this kind of project.  To
definitely effect change, nothing beats contributing :-).

 > but this time I want to do it inside a paragraph.  Specifically, I
 > want italic monospace.  Everything I've read so far leads me to
 > believe this can't be done, but I'd like to think otherwise.

Can't be done out of the box, but there are ways to do it.  Before we
get to them, though, some considerations:

First, you have to unlearn what you have learned ;-).  Saying "italic
monospace" isn't very useful; that's just dumb formatting.  What does
that formatting *mean* in your docs?  Perhaps it's something like
"user input" or "variable"?  Those terms are much more useful.  What
it actually looks like is a minor consideration.  We're aiming at
semantic markup as much as possible.

Second, please provide examples.  Do you really need full-blown
"parsed inline literals" (implying complex and varied markup within a
single inline literal)?  Or is a simple variation on inline literals
enough?

I can think of two solutions off the bat.  The first is a custom
interpreted text role, something like ":variable:`text`".  That would
handle the simple markup case.  There are a bunch of ideas at
<http://docutils.sf.net/spec/notes.html#interpreted-text>,
specifically <http://docutils.sf.net/spec/notes.html#role-bindings>.

The other solution is to parse nested inline markup, which has been
talked about a lot but has never been implemented.  Summary here:
<http://docutils.sf.net/spec/rst/alternatives.html#nested-inline-markup>.
If implemented, this might become possible::

     *emphasized ``literal`` and |substitution ref| and link_*

Note that the inverse is *not* possible.  "``literal *emphasized*``"
will never work, because literals (block or inline) don't parse their
content.  If you needed that, an interpreted text role might do the
trick::

     :parsed-literal:`literal *emphasized*`

Any solution requires someone motivated enough to implement it.  Not
me at present.

-- 
David Goodger    http://starship.python.net/~goodger
For hire: http://starship.python.net/~goodger/cv
Docutils: http://docutils.sourceforge.net/
(includes reStructuredText: http://docutils.sf.net/rst.html)