On 4/7/21 7:40 PM, Joseph Myers wrote:
On Wed, 7 Apr 2021, Michael Matz wrote:
Random snippet for what I mean: the .texi contains:
"The @code{access} attribute specifies that a function to whose
by-reference arguments the attribute applies accesses the referenced
object according to @var{access-mode}. The @var{access-mode} argument is
required and must be"
the .rst has:
"The ``access`` attribute specifies that a function to whose by-reference
arguments the attribute applies accesses the referenced object according
to :samp:`{access-mode}`. The :samp:`{access-mode}` argument is required
and must be"
So, @code{}/@var{} vs. `` `` / :samp:``. Keeping in mind that
@var in Texinfo is orthogonal to whether something is literal code. It
looks like Sphinx's equivalent is {} inside :samp:`` (so not supporting
the use case of @var outside literal code)?
Hello.
Yes, as Joseph says, it's equivalent to {var} within a :samp: directive as
documented
here:
https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-samp
To be honest, if we really want, we can easily come up with even more roles.
But I don't think we would benefit from it.
...
One other practical concern: it seems there's a one-to-one correspondence
of .rst files and (web)page. Do we really want to maintain hundreds (or
how many?) .rst files, instead of 60 .texi files?
Well, based what I know about RST and Sphinx, it's pretty natural that one HTML
page
corresponds to a single RST file.
Looking at famous users for Sphinx, I can see the following stats:
linux/Documentation> find . -name '*.rst' | wc -l
2807
godot-docs> find . -name '*.rst' | wc -l
1030
Martin
