> Cc: jos...@codesourcery.com, gcc@gcc.gnu.org, gcc-patc...@gcc.gnu.org > From: Martin Liška <mli...@suse.cz> > Date: Wed, 30 Jun 2021 12:11:03 +0200 > > > (Admittedly, Emacs by default hides some of the text of a > > cross-reference, but not hiding them in this case produces an even > > less legible text.) > > If I'm correct, it's exactly what's documented in Sphinx FAQ here: > https://www.sphinx-doc.org/en/master/faq.html#displaying-links > > and there's a suggested Emacs code snippet that should help with links. > Does it help?
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’ ---- ---- The quotes around the option values don't help. Also, using the method proposed by Sphinx FAQ would need a change in Emacs, which will take time to propagate. So my suggestion is to minimize the use of such "inline" hyperlinks. > > ‘@`file'’ > > > > Read command-line options from ‘`file'’. The options read are > > inserted in place of the original ‘@`file'’ option. If ‘`file'’ > > does not exist, or cannot be read, then the option will be treated > > literally, and not removed. > > I can confirm that, so e.g. > Show :samp:`Samp with a {variable}.` > > is transformed into: > Show @code{Samp with a @emph{variable}.} > > Default info formatting is selected as: > > @definfoenclose strong,`,' > @definfoenclose emph,`,' > > 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? > > 4. Menus lost the short descriptions of the sub-sections. Example: > > > > * Designated Initializers > > * Case Ranges > > * Cast to a Union Type > > * Mixed Declarations, Labels and Code > > * Declaring Attributes of Functions > > > > vs > > > > * Designated Inits:: Labeling elements of initializers. > > * Case Ranges:: 'case 1 ... 9' and such. > > * Cast to Union:: Casting to union type from any member of the > > union. > > * Mixed Declarations:: Mixing declarations and code. > > * Function Attributes:: Declaring that functions have no side effects, > > or that they can never return. > > > > Looks like some bug to me. > > > > Note also that nodes are now called by the same name as the section, > > which means node names generally got much longer. Is that really a > > good idea? > > Well, I intentionally removed these and used simple TOC tree links > which take display text for a section title. I would suggest to discuss these decisions first, perhaps on the Texinfo mailing list? I'm accustomed to these short descriptions, but I'm not sure how important they are for others.