diff mbox

[doc] Rename "Language Independent Options" @node in invoke.texi

Message ID 20150721125201.GR21787@redhat.com
State New
Headers show

Commit Message

Jonathan Wakely July 21, 2015, 12:52 p.m. UTC 
This texinfo @node seems misnamed:
https://gcc.gnu.org/onlinedocs/gcc/Language-Independent-Options.html#Language-Independent-Options

It should be something like "Diagnostic Message Formatting Options"
not "Language Independent Options".

The misnomer makes the TOC and navbar confusing and seems to suggest
that warning and debuging options are not language independent, since
they're not part of that node. See
https://gcc.gnu.org/onlinedocs/gcc/Invoking-GCC.html#Invoking-GCC
which has:

* Language Independent Options: Controlling how diagnostics should be formatted.
* Warning Options: How picky should the compiler be?
* Debugging Options: Symbol tables, measurements, and debugging dumps.
* Optimize Options: How much optimization? 

The title of the first entry is completely unrelated to its
description.

An alternative fix would be to keep a "Language Independent Options"
node but nest "Diagnostic Message Formatting Options", "Warning
Options", "Debugging Options" and "Optimize Options" as sub-sections
of it. The downside of that is that it would be harder to find those
sub-sections from the
https://gcc.gnu.org/onlinedocs/gcc/Invoking-GCC.html#Invoking-GCC
node, as you'd have to click through to another page to see the
sub-sections.

OK for trunk?

Comments

Sandra Loosemore July 21, 2015, 3:07 p.m. UTC | #1 
On 07/21/2015 06:52 AM, Jonathan Wakely wrote:
> This texinfo @node seems misnamed:
> https://gcc.gnu.org/onlinedocs/gcc/Language-Independent-Options.html#Language-Independent-Options
>
>
> It should be something like "Diagnostic Message Formatting Options"
> not "Language Independent Options".
>
> The misnomer makes the TOC and navbar confusing and seems to suggest
> that warning and debuging options are not language independent, since
> they're not part of that node. See
> https://gcc.gnu.org/onlinedocs/gcc/Invoking-GCC.html#Invoking-GCC
> which has:
>
> * Language Independent Options: Controlling how diagnostics should be
> formatted.
> * Warning Options: How picky should the compiler be?
> * Debugging Options: Symbol tables, measurements, and debugging dumps.
> * Optimize Options: How much optimization?
> The title of the first entry is completely unrelated to its
> description.
>
> An alternative fix would be to keep a "Language Independent Options"
> node but nest "Diagnostic Message Formatting Options", "Warning
> Options", "Debugging Options" and "Optimize Options" as sub-sections
> of it. The downside of that is that it would be harder to find those
> sub-sections from the
> https://gcc.gnu.org/onlinedocs/gcc/Invoking-GCC.html#Invoking-GCC
> node, as you'd have to click through to another page to see the
> sub-sections.
>
> OK for trunk?

I agree with the proposed renaming of the node, but you need to fix all 
the references to the old name and not just the @node, so no, the patch 
is not OK as-is.

-Sandra
diff mbox

Patch

commit e3b0376e0440e8af4768b1e1502a57f9ca36be53
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Tue Jul 21 13:37:16 2015 +0100

    	* doc/invoke.texi (Language Independent Options): Rename node to
    	Diagnostic Message Formatting Options.

diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 55c2659..9fb2f37 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -3153,7 +3153,7 @@  value, if any.
 
 @end table
 
-@node Language Independent Options
+@node Diagnostic Message Formatting Options
 @section Options to Control Diagnostic Messages Formatting
 @cindex options to control diagnostics formatting
 @cindex diagnostic messages