> Cc: [email protected], [email protected], [email protected]
> From: Martin Liška <[email protected]>
> 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.
