Marking up metasyntactic variables and the like

[Jean Abou Samra]

Hi,

One thing I like a lot with Sphinx is its semantic markup.
However, working with Texinfo in parallel, I find one command
that is miss, which is Texinfo's @var. It serves roughly the
same purpose as what's in curly braces inside :samp: (when
nested inside Texinfo's @code), except that it can be used outside
as well. For instance, assuming that I could write it as
:var:`x`, I might write::

   The syntax for this command is :samp:`\spam {eggs}`, where
   :var:`eggs` is a non-empty set of eggs.

or::

   This property is used as

   .. parsed-literal::

      \badly \frobnicate :var:`stuff`

   Here, :var:`stuff` is ...

Another use case: in the Python documentation at least
(I don't have experience with Sphinx in other
projects), the names of function parameters are
marked up in *italics*. As a perfectionist, I would
in my own documentation prefer to mark them up with
some specific role showing their intent, possibly
enabling different styling in HTML, maybe some form
of underlining. It's true that there may be a point
in making it domain-specific and allowing, for
example, backlinks to the parameter's default,
and annotation if present, especially in function
descriptions with :param: where the argument
appears on its own line separate from the function header.
On the other hand, my own use cases are not for API
documentation with formal objects like functions or
classes, but narrative documentation (is that the
proper term?) that describes tons of elements with
completely different natures, organized by topic
rather than nature of objects. This documentation is
also for projects not primarily used by developers.

In Info output (I don't care about it but some do),
@var ends up in capital letters, unlike italics
which are marked up as _word_. Looking in Sphinx's
code, I don't find anything that would output @var
in the Texinfo writer except for {} sections inside
:samp:.

My question is: is there something for this already?
Should I stop thinking in Texinfo and use something
else? Should I implement it in an extension?

Thanks,
Jean

[Komiya Takeshi]

For now, Sphinx does not have such a mark-up. So you need to create an
extension to realize it.

# Sorry for the direct reply to you. It's not intended. Repost to the
group again.

Thanks,
Takeshi KOMIYA

2022年1月13日(木) 7:46 Jean Abou Samra <je...@abou-samra.fr>:

> --
> You received this message because you are subscribed to the Google Groups "sphinx-users" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/d7184d02-87f5-cc2a-50b3-6913c84f4d6a%40abou-samra.fr.

[Jean Abou Samra]

Le 15/01/2022 à 06:05, Komiya Takeshi a écrit :
> For now, Sphinx does not have such a mark-up. So you need to create an
> extension to realize it.
>
> # Sorry for the direct reply to you. It's not intended. Repost to the
> group again.

As said privately, thank you for your reply. Now my
next question would be: would a PR adding such a role
be welcome? Would it be preferable for it to live in
a PyPI extension at least in a first step? Or actually,
perhaps it could be proposed in Docutils?

Best regards,
Jean

[Fred Drake]

Before the Python documentation was managed in reStructuredText, we used a LaTeX with a large range of specific markup, including \var{varname}.  I don't remember why that didn't get carried into what became the Python domain in Sphinx.

  -Fred

[Jean Abou Samra]

Le 18/01/2022 à 21:11, Fred Drake a écrit :
> Before the Python documentation was managed in reStructuredText, we
> used a LaTeX with a large range of specific markup, including

> *\var{/varname/}*.  I don't remember why that didn't get carried into

> what became the Python domain in Sphinx.

Interesting insight, thank you. With ``:samp:`` not
being part of any domain, I think it would be
reasonable to
- make it format ``{}`` parts with a specific
style defaulting to emphasis,
- add some role to pair it, doing the same formatting
as what's inside a ``{}`` part of ``:samp:``.

I drafted a sketchy implementation (though I haven't
looked into backwards compatibility details yet).

The outstanding issue is: how could we name this
role? Sadly, ``:var:`` is already taken in the C and
C++ domains. ``:meta:`` is conceivable, but ``.. meta::``
is a standard docutils directive, so it might be
confusing. I'm a bit out of ideas ... ``:placeholder:``
maybe?

Regards,
Jean

[Fred Drake]

The outstanding issue is: how could we name this
role? Sadly, ``:var:`` is already taken in the C and
C++ domains. ``:meta:`` is conceivable, but ``.. meta::``
is a standard docutils directive, so it might be
confusing. I'm a bit out of ideas ... ``:placeholder:``
maybe?

If we're talking about a role for marking  a variable or formal parameter name, :var:`varname` would be the right thing.  But that's not what I'd call metasyntactic.

If we're talking about something that really is metasyntactic, I'd be inclined to use something like :metavar:`metavarname`; it's pretty clear.  But it probably belongs outside a domain, unless we want a domain for meta-conceptual bits:  :meta:var:`metavarname`.

  -Fred

[Jean Abou Samra]

Le 18/01/2022 à 23:28, Fred Drake a écrit :
>
> The outstanding issue is: how could we name this
> role? Sadly, ``:var:`` is already taken in the C and
> C++ domains. ``:meta:`` is conceivable, but ``.. meta::``
> is a standard docutils directive, so it might be
> confusing. I'm a bit out of ideas ... ``:placeholder:``
> maybe?
>
>
> If we're talking about a role for marking  a variable or formal

> parameter name, :var:`/varname/` would be the right thing.  But that's

> not what I'd call metasyntactic.
>
> If we're talking about something that really is metasyntactic, I'd be

> inclined to use something like :metavar:`/metavarname/`; it's pretty

> clear.  But it probably belongs outside a domain, unless we want a

> domain for meta-conceptual bits:  :meta:var:`/metavarname/`.



``:metavar:`` sounds good, thanks.

Adding roles for parameter names, etc. to domains
is probably a worthy goal, but given that I am a
newbie to Sphinx internals, I won't set my goal
bar as high for now. I'll see when I have time
to polish ``:metavar:`` and submit it as PR.

Kind regards,
Jean

[Komiya Takeshi]

> Now my next question would be: would a PR adding such a role
> be welcome? Would it be preferable for it to live in
> a PyPI extension at least in a first step?

Basically, the standard role of Sphinx should be widely used by many people.
I'm not sure the :metavar: is a widely used role or not.

So it would be better to publish it as a 3rd party extension at first.

> Or actually, perhaps it could be proposed in Docutils?

Sorry, I can't answer it because I'm not a maintainer of docutils.

Thanks,
Takeshi KOMIYA

2022年1月15日(土) 22:37 Jean Abou Samra <je...@abou-samra.fr>:

[Jean Abou Samra]

Le 23/01/2022 à 18:46, Komiya Takeshi a écrit :
>> Now my next question would be: would a PR adding such a role
>> be welcome? Would it be preferable for it to live in
>> a PyPI extension at least in a first step?
> Basically, the standard role of Sphinx should be widely used by many people.
> I'm not sure the :metavar: is a widely used role or not.
>
> So it would be better to publish it as a 3rd party extension at first.

Here you go:

https://pypi.org/project/sphinx_metavar/

Best regards,
Jean