On 7/1/21 5:06 PM, Michael Matz wrote:
Hello,
On Thu, 1 Jul 2021, Martin Liška wrote:
On 7/1/21 3:33 PM, Eli Zaretskii wrote:
Cc: jos...@codesourcery.com, gcc@gcc.gnu.org, gcc-patc...@gcc.gnu.org
From: Martin Liška <mli...@suse.cz>
Date: Thu, 1 Jul 2021 14:44:10 +0200
It helps some, but not all of the issues disappear. For example,
stuff like this is still hard to read:
To select this standard in GCC, use one of the options -ansi
-----
-std.‘=c90’ or -std.‘=iso9899:1990’
---- ----
If I understand the notes correct, the '.' should be also hidden by e.g.
Emacs.
No, it doesn't. The actual text in the Info file is:
*note -std: f.‘=iso9899:1990’
and the period after " f" isn't hidden. Where does that "f" come from
and what is its purpose here? can it be removed (together with the
period)?
It's name of the anchor used for the @ref. The names are automatically
generated
by makeinfo. So there's an example:
This is the warning level of @ref{e,,-Wshift-overflow3} and …
becomes in info:
This is the warning level of *note -Wshift-overflow3: e. and …
I can ask the question at Sphinx, the Emacs script should hide that.
Not everyone reads info within Emacs; even if there's an emacs solution to
postprocess info pages to make them nicer we can't rely on that.
Sure. What's new is that Sphinx can generate much more cross references, like
option references from option listing.
It must
look sensible without that. In this case it seems that already the
generated .texinfo input to makeinfo is bad, where does the 'e' (or 'f')
come from? The original texinfo file simply contains:
These are auto-numbered. Theoretically one can use the verbose anchor names:
@anchor{demo cmdoption-Wshift-overflow3}@anchor{e}@anchor{demo
cmdoption-wshift-overflow3}@anchor{f}
@deffn {Option} @w{-}Wshift@w{-}overflow3=n, @w{-}Wshift@w{-}overflow3
Default option value for @ref{e,,-Wshift-overflow3}.
But these would lead to even longer '*note -Wshift-overflow3: demo
cmdoption-wshift-overflow3' output.
@option{-std=iso9899:1990}
so that's what perhaps should be generated, or maybe the anchor in @ref is
optional and could be left out if it doesn't provide any info (a single
character as anchor doesn't seem very useful)?
Yes, we can theoretically block emission of @refs for options.
Martin
We can adjust 'emph' formatting to nil, what do you think?
Something like that, yes. But the problem is: how will you format it
instead? The known alternatives, _foo_ and *foo* both use punctuation
characters, which will get in the way similarly to the quotes. Can
you format those in caps, like makeinfo does?
You are fully right, info is very simple format and it uses wrapping for
the formatting
purpose (by default * and _). So, I don't have any elegant solution.
Well, it sounds from another mail that you did find a solution: to
up-case the string in @var.
I don't know. Some of them can be e.g. keywords and using upper-case
does not seem to me feasible.
Then that needs to be different already in the input, so that the
directive that (in info) capitalizes is only used in contexts where that
makes sense. People reading info pages will know that an all-caps word
often means a syntactic variable/placeholder, so that should be preserved.
Ciao,
Michael.
