Re: [Docutils-users] :term:s in plural

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

On 21 October 2013 06:27, Erik Bernoth <eri...@gm...> wrote:
> Hi David,
>
> On Fri, Oct 18, 2013 at 11:02 PM, David Goodger <go...@py...> wrote:
>> Note that :term: is a Sphinx-specific role, and as I don't have Sphinx
>> set up right now, I can't test any of this. It may be better to ask on
>> a Sphinx forum.
>
> I see, thanks for the advice. For a newcomer this is all a bit
> confusing, because you are never quite sure which feature comes from
> which project. That's what I love about the packaging developers. They
> all read and write to distutils-sig. So even if you are confused about
> what feature belongs to which tool, on that list you will reach the
> right person. Is there something like this for documentation utilis? I
> thought docutils-users would be like this. That's why I wrote here.

Sphinx uses and builds upon Docutils. Docutils-users is specific to
the Docutils project (although anyone -- including any Sphinx
developer -- is welcome to post or reply to anything relevant). You
may have better luck with do...@py..., although that's very
low-traffic these days.

>> But just on general reST principles (and guessing that
>> these will work):
>>
>> You could write the plural as ":term:`test`\ s". Ugly, but it might work.
>
> Much better already, I think. Although I don't fully understand why
> the structure :foo:`bar` requires a space afterwards to be parsed
> correctly. I think the : and ` characters should be enough information
> for a Tokenizer. But you don't seem to consider the required space a
> bug.

"In reStructuredText, inline markup applies to words or phrases within
a text block. The same whitespace and punctuation that serves to
delimit words in written text is used to delimit the inline markup
syntax constructs."

http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-markup

> Do you know where I can inform myself why it is like that?

See the above link, and
http://docutils.sourceforge.net/docs/dev/rst/problems.html#delimitation-of-inline-markup

>> Alternatively, set up a substitution:
>>
>> .. |tests| replace:: :term:`tests <test>`
>
> I think I will learn replace. Seems to be a flexible feature for many
> things. Thanks!

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