[Docutils-users] :term:s in plural

[Erik Bernoth]

Hi,

is it possible in any reasonable way to mark a restructured Text :term: as
plural?

E.g. you want to write somewhere in your docs :term:`test` but you don't
describe one test, you describe many. But if you write :term:`tests` it will
be a completely new term. You can not write :term:`test`s because that would
not be parsed. So in the end you have to write :term:`tests<test>` which
will be deeply annoying after having done this many times and with longer terms.

Also see
http://stackoverflow.com/questions/19403972/writing-terms-in-plural-without-the-redundancy

Best Wishes,
Erik

[David Goodger]

Post by Erik Bernoth
Hi,
is it possible in any reasonable way to mark a restructured Text :term: as
plural?
E.g. you want to write somewhere in your docs :term:`test` but you don't
describe one test, you describe many. But if you write :term:`tests` it will
be a completely new term. You can not write :term:`test`s because that would
not be parsed. So in the end you have to write :term:`tests<test>` which
will be deeply annoying after having done this many times and with longer terms.
Also see
http://stackoverflow.com/questions/19403972/writing-terms-in-plural-without-the-redundancy
Best Wishes,
Erik

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. 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.

Alternatively, set up a substitution:

.. |tests| replace:: :term:`tests <test>`

Then whenever you need the plural, just use the |tests| substitution.

[Erik Bernoth]

Hi David,

Post by David Goodger
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.

Post by David Goodger
But just on general reST principles (and guessing that
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. Do you know where I can inform myself why it is like that?

Post by David Goodger
.. |tests| replace:: :term:`tests <test>`

I think I will learn replace. Seems to be a flexible feature for many
things. Thanks!

[David Goodger]

Post by Erik Bernoth
Hi David,

Post by David Goodger
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 doc-***@python.org, although that's very
low-traffic these days.

Post by Erik Bernoth

Post by David Goodger
But just on general reST principles (and guessing that
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

Post by Erik Bernoth
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

Post by Erik Bernoth

Post by David Goodger
.. |tests| replace:: :term:`tests <test>`

I think I will learn replace. Seems to be a flexible feature for many
things. Thanks!

[Erik Bernoth]

Got it, thanks!

Post by David Goodger

Post by Erik Bernoth
Hi David,

Post by David Goodger
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
low-traffic these days.

Post by Erik Bernoth

Post by David Goodger
But just on general reST principles (and guessing that
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

Post by Erik Bernoth
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

Post by Erik Bernoth

Post by David Goodger
.. |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>