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
--
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+unsubscr...@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.
