references to individual options in GCC manual

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

references to individual options in GCC manual

Martin Sebor-2
Is there a way to include a reference to a specific option
from within a .info file rather than to the section/node
the option is defined in?

It's cumbersome to use @xref and similar commands, and it's
less not as helpful to point the reader to an entire section
when referring to a specific item/option in that section.
Since each option has its own anchor in the HTML manual,
it seems that it should be possible.

As an example, the aligned attribute is described like so:

   aligned (alignment)

     This attribute specifies a minimum alignment for the function,
     measured in bytes.

     You cannot use this attribute to decrease the alignment of
     a function, only to increase it. However, when you explicitly
     specify a function alignment this overrides the effect of
     the -falign-functions (see Optimize Options) option for this
     function.

In both the HTML and PDF manuals, the phrase "Optimize Options"
is a hyperlink to the beginning of the named section, even though
the reader that follows it is expected (and will want to) read
about -falign-functions.

Martin
Reply | Threaded
Open this post in threaded view
|

Re: references to individual options in GCC manual

Andreas Schwab
On Okt 24 2018, Martin Sebor <[hidden email]> wrote:

> Is there a way to include a reference to a specific option
> from within a .info file rather than to the section/node
> the option is defined in?

You can add an @anchor.

Andreas.

--
Andreas Schwab, SUSE Labs, [hidden email]
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE  1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."
Reply | Threaded
Open this post in threaded view
|

Re: references to individual options in GCC manual

Martin Sebor-2
On 10/25/2018 01:31 AM, Andreas Schwab wrote:
> On Okt 24 2018, Martin Sebor <[hidden email]> wrote:
>
>> Is there a way to include a reference to a specific option
>> from within a .info file rather than to the section/node
>> the option is defined in?
>
> You can add an @anchor.

Thanks.  After adding the @anchor I can use it in commands like
@ref.  It even understands the @ref command when it's nested in
the @option command, like this:

   the @option{@ref{-fno-delete-null-pointer-checks}} option

and renders it as expected in HTML:

   the <samp><a
href="Optimize-Options.html#g_t_002dfno_002ddelete_002dnull_002dpointer_002dchecks">-fno-delete-null-pointer-checks</a></samp>
option

Unfortunately, it doesn't look right in PDF where it produces

   the [-fno-delete-null-pointer-checks], page 127 option

the text between "the" and "option" is a link.

I was also hoping not to have to add @anchor (since some sort
of anchors must already exist for the Index to work), and for
a way to simply turn the name of an option (or attribute) into
a link to the the existing anchor for the option.  But I suspect
that might be too much to expect.

I could deal with the rendering issue by using references in
a way that makes sense either way, but what about avoiding
@anchor?  Is that at all possible?

Martin
Reply | Threaded
Open this post in threaded view
|

Re: references to individual options in GCC manual

Andreas Schwab
On Okt 25 2018, Martin Sebor <[hidden email]> wrote:

> I was also hoping not to have to add @anchor (since some sort
> of anchors must already exist for the Index to work), and for

The indices use line numbers.

Andreas.

--
Andreas Schwab, SUSE Labs, [hidden email]
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE  1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."