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)?
Although there *is* a difference in output as well as semantics between
@code and @samp in Texinfo (@samp quotes the output in some cases where
@code does not, I think), I'm not convinced the GCC manuals actually make
much distinction between the two.
> (Again, I'm aware that the .texi files aren't perfect here, and @code/@var
> also seems a bit forced :) )
@var is a metasyntactic variable (the text inside @var is converted to
uppercase for info output), completely different in usage from @code.
It's @code/@samp where there isn't much consistency (and other cases such
as e.g. whether @option or @samp is used for a sequence of more than one
option).
> (I'm not proposing we go the full extreme of semantic markup that docbook
> tries, but the other end of the spectrum, i.e. markdown/rst with only
> presentation markup, also doesn't seem very well fitting)
Presumably we could add our own roles (:gcc:our_own_role:`something`) and
directives with custom Python code to implement them, whenever we want to
keep semantics that aren't covered by the default Sphinx-flavoured reST?
However, I don't know how easy it is to keep such code (and manuals)
compatible with a wide range of Sphinx versions. Documentation requiring
the latest version of Sphinx to build cleanly is a pain, I'd prefer to aim
for e.g. working with any Sphinx release from the past five years.
--
Joseph S. Myers
jos...@codesourcery.com
