Show name of compiler options when linking

Show name of compiler options when linking

[Peter Olsson]

Hello,

I often want to link to specific compiler options in your online docs
but the problem is that the named anchors are placed after the name of
the option so when the link is clicked it will only show the
description.

Example:
  https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html#index-Wshadow
  Will show the description for -Wshadow but not the name -Wshadow itself.

I think it would be very useful to be able to link in such a way that
the name of the option also becomes visible. If this somehow breaks
backwards compatibility you could introduce new ones that refers to
the name and let the old ones refer to the description like it is
today.

Best Regards,

Peter

A big fan

Re: Show name of compiler options when linking

[Jonathan Wakely]

On Thu, 4 Apr 2019 at 10:56, Peter Olsson wrote:
>
> Hello,
>
> I often want to link to specific compiler options in your online docs
> but the problem is that the named anchors are placed after the name of
> the option so when the link is clicked it will only show the
> description.
>
> Example:
>   https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html#index-Wshadow
>   Will show the description for -Wshadow but not the name -Wshadow itself.
>
> I think it would be very useful to be able to link in such a way that
> the name of the option also becomes visible. If this somehow breaks
> backwards compatibility you could introduce new ones that refers to
> the name and let the old ones refer to the description like it is
> today.

Yes, it's annoying. The HTML is auto-generated by the makeinfo
program, so as far as I know we don't have much control over the
placement of those anchors.

Re: Show name of compiler options when linking

[Jonathan Wakely]

On Thu, 4 Apr 2019 at 11:10, Jonathan Wakely wrote:
>
> On Thu, 4 Apr 2019 at 10:56, Peter Olsson wrote:
> >
> > Hello,
> >
> > I often want to link to specific compiler options in your online docs
> > but the problem is that the named anchors are placed after the name of
> > the option so when the link is clicked it will only show the
> > description.
> >
> > Example:
> >   https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html#index-Wshadow
> >   Will show the description for -Wshadow but not the name -Wshadow itself.
> >
> > I think it would be very useful to be able to link in such a way that
> > the name of the option also becomes visible. If this somehow breaks
> > backwards compatibility you could introduce new ones that refers to
> > the name and let the old ones refer to the description like it is
> > today.
>
> Yes, it's annoying. The HTML is auto-generated by the makeinfo
> program, so as far as I know we don't have much control over the
> placement of those anchors.

Maybe it's because we have @opindex entries after the @item e.g.

@item -Wfatal-errors
@opindex Wfatal-errors
@opindex Wno-fatal-errors

But I don't know texinfo or makeinfo well enough to be sure, or if we
can do it differently.

Re: Show name of compiler options when linking

[David Malcolm]

On Thu, 2019-04-04 at 10:12 +0000, Jonathan Wakely wrote:
> On Thu, 4 Apr 2019 at 11:10, Jonathan Wakely wrote:
> > 
> > On Thu, 4 Apr 2019 at 10:56, Peter Olsson wrote:
> > > 
> > > Hello,
> > > 
> > > I often want to link to specific compiler options in your online
> > > docs
> > > but the problem is that the named anchors are placed after the
> > > name of
> > > the option so when the link is clicked it will only show the
> > > description.
> > > 
> > > Example:
> > >   https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html#index-W
> > > shadow
> > >   Will show the description for -Wshadow but not the name
> > > -Wshadow itself.
> > > 
> > > I think it would be very useful to be able to link in such a way
> > > that
> > > the name of the option also becomes visible. If this somehow
> > > breaks
> > > backwards compatibility you could introduce new ones that refers
> > > to
> > > the name and let the old ones refer to the description like it is
> > > today.
> > 
> > Yes, it's annoying. The HTML is auto-generated by the makeinfo
> > program, so as far as I know we don't have much control over the
> > placement of those anchors.
> 
> Maybe it's because we have @opindex entries after the @item e.g.
> 
> @item -Wfatal-errors
> @opindex Wfatal-errors
> @opindex Wno-fatal-errors
> 
> But I don't know texinfo or makeinfo well enough to be sure, or if we
> can do it differently.

FWIW I started a discussion related to this on the help-texinfo list
here a couple of months ago:
  http://lists.gnu.org/archive/html/help-texinfo/2019-02/msg00000.html

It may be that there's a way of fixing this from the GCC side (either
by changing our macros, or by changing our .texi source), but I'm not
expert enough at texinfo to figure that out.

Dave