[Doc-SIG] Docutils update: "interpreted text" reimplemented

[Paul Moore]

David Goodger <goodger@python.org> writes:

>> Looks nice. One useful addition would be a bit more explanation of
>> the title-reference role - the other 2 (PEP & RFC) make immediate
>> sense to me, and I see what they will do in practice, but with the
>> title role I'm left with no immediate impression of how it will
>> look when processed. (I realise it's probably writer-dependent, but
>> at least an example would be nice...)
>
> Explanation & an example added.  Please take a look.

OK, that looks a lot better.

> The final rendering *is* writer- and stylesheet-dependent, but will
> usually be italics.

It probably helps to say something, as an example if nothing else. You
mention the HTML <cite> tag, but I missed it first time in the
description of what *not* to do. How about the following::

    The :title-reference: role is used to describe the titles of
    books, periodicals, and other materials. It is the equivalent of
    the HTML "cite" element (and will often be rendered using this
    element by HTML writers).

    Since title references are typically rendered with italics, they
    are often marked up using *emphasis*, which is misleading and
    vague. The "title_reference" element provides accurate and
    unambiguous descriptive markup.

Basically what you wrote, but split into 2 paragraphs and with a brief
note on the expected rendering.

Paul.
-- 
This signature intentionally left blank