Patchwork PATCH: PR other/59055: gcc.texinfo warnings

login
register
mail settings
Submitter H.J. Lu
Date Nov. 8, 2013, 10:28 p.m.
Message ID <20131108222816.GA25314@intel.com>
Download mbox | patch
Permalink /patch/289931/
State New
Headers show

Comments

H.J. Lu - Nov. 8, 2013, 10:28 p.m.
bugreport.texi has

@menu
* Criteria:  Bug Criteria.   Have you really found a bug?
* Reporting: Bug Reporting.  How to report a bug effectively.
* Known: Trouble.            Known problems.
* Help: Service.             Where to ask for help.
@end menu

That means include order should be bugreport.texi, trouble.texi,
service.texi.  And we need to specify next, previous and up nodes to
Service and Trouble nodes.  OK to install?

H.J.
---
2013-11-08  H.J. Lu  <hongjiu.lu@intel.com>

	PR other/59055
	* doc/gcc.texi: Move Trouble after Bugs in menu.  Include
	trouble.texi after bugreport.texi.
	* doc/service.texi: Add next, previous and up nodes to Service
	nodes.
	* doc/trouble.texi: Add next, previous and up nodes to Trouble
	nodes.
Gerald Pfeifer - Dec. 2, 2013, 1:10 p.m.
On Fri, 8 Nov 2013, H.J. Lu wrote:
> bugreport.texi has
> 
> @menu
> * Criteria:  Bug Criteria.   Have you really found a bug?
> * Reporting: Bug Reporting.  How to report a bug effectively.
> * Known: Trouble.            Known problems.
> * Help: Service.             Where to ask for help.
> @end menu
> 
> That means include order should be bugreport.texi, trouble.texi,
> service.texi.  And we need to specify next, previous and up nodes to
> Service and Trouble nodes.  OK to install?

Thanks for looking into this, H.J.!  Looking at the logic we have
been using elsewhere, I am wondering whether it shouldn't be the
order in bugreport.texi that should be adjusted -- switching the
"Known: Trouble" and "Reporting: Bug Reporting" nodes?

That way you could omit

> 2013-11-08  H.J. Lu  <hongjiu.lu@intel.com>
> 
> 	PR other/59055
> 	* doc/gcc.texi: Move Trouble after Bugs in menu.  Include
> 	trouble.texi after bugreport.texi.

those two changes, and only update bugreport.texi?  If this sounds
acceptable, please go ahead and make this change.

> 	* doc/service.texi: Add next, previous and up nodes to Service
> 	nodes.
> 	* doc/trouble.texi: Add next, previous and up nodes to Trouble
> 	nodes.

Why are these necessary?  The texinfo documentation say the following
about @node:

    The subsequent arguments are optional—they are the names of the 
    ‘Next’, ‘Previous’, and ‘Up’ pointers, in that order. We strongly 
    recommend omitting them if your Texinfo document is hierarchically 
    organized, as virtually all are

Gerald
H.J. Lu - Dec. 2, 2013, 5:01 p.m.
On Mon, Dec 2, 2013 at 5:10 AM, Gerald Pfeifer <gerald@pfeifer.com> wrote:
> On Fri, 8 Nov 2013, H.J. Lu wrote:
>> bugreport.texi has
>>
>> @menu
>> * Criteria:  Bug Criteria.   Have you really found a bug?
>> * Reporting: Bug Reporting.  How to report a bug effectively.
>> * Known: Trouble.            Known problems.
>> * Help: Service.             Where to ask for help.
>> @end menu
>>
>> That means include order should be bugreport.texi, trouble.texi,
>> service.texi.  And we need to specify next, previous and up nodes to
>> Service and Trouble nodes.  OK to install?
>
> Thanks for looking into this, H.J.!  Looking at the logic we have
> been using elsewhere, I am wondering whether it shouldn't be the
> order in bugreport.texi that should be adjusted -- switching the
> "Known: Trouble" and "Reporting: Bug Reporting" nodes?

It doesn't work:

/export/gnu/import/git/gcc/gcc/doc/trouble.texi:5: warning: node next
`Trouble' in menu `Service' and in sectioning `Bugs' differ
/export/gnu/import/git/gcc/gcc/doc/trouble.texi:5: warning: node prev
`Trouble' in menu `Bug Reporting' and in sectioning `Gcov' differ
/export/gnu/import/git/gcc/gcc/doc/trouble.texi:5: warning: node up
`Trouble' in menu `Bugs' and in sectioning `Top' differ
/export/gnu/import/git/gcc/gcc/doc/service.texi:5: warning: node prev
`Service' in menu `Trouble' and in sectioning `Bugs' differ
/export/gnu/import/git/gcc/gcc/doc/service.texi:5: warning: node up
`Service' in menu `Bugs' and in sectioning `Top' differ

> That way you could omit
>
>> 2013-11-08  H.J. Lu  <hongjiu.lu@intel.com>
>>
>>       PR other/59055
>>       * doc/gcc.texi: Move Trouble after Bugs in menu.  Include
>>       trouble.texi after bugreport.texi.
>
> those two changes, and only update bugreport.texi?  If this sounds
> acceptable, please go ahead and make this change.
>
>>       * doc/service.texi: Add next, previous and up nodes to Service
>>       nodes.
>>       * doc/trouble.texi: Add next, previous and up nodes to Trouble
>>       nodes.
>
> Why are these necessary?  The texinfo documentation say the following
> about @node:
>
>     The subsequent arguments are optional—they are the names of the
>     ‘Next’, ‘Previous’, and ‘Up’ pointers, in that order. We strongly
>     recommend omitting them if your Texinfo document is hierarchically
>     organized, as virtually all are
>

gcc.texi has

@include gcov.texi
@include trouble.texi
@include bugreport.texi
@include service.texi

and there is a menu in bugreport.texi as well as

@node Bug Criteria,Bug Reporting,,Bugs
@node Bug Reporting,,Bug Criteria,Bugs

They aren't really hierarchically organized.


H.J.

Patch

diff --git a/gcc/doc/gcc.texi b/gcc/doc/gcc.texi
index 55307cd..ef8d98a 100644
--- a/gcc/doc/gcc.texi
+++ b/gcc/doc/gcc.texi
@@ -138,8 +138,8 @@  Introduction, gccint, GNU Compiler Collection (GCC) Internals}.
 * Objective-C::     GNU Objective-C runtime features.
 * Compatibility::   Binary Compatibility
 * Gcov::            @command{gcov}---a test coverage program.
-* Trouble::         If you have trouble using GCC.
 * Bugs::            How, why and where to report bugs.
+* Trouble::         If you have trouble using GCC.
 * Service::         How to find suppliers of support for GCC.
 * Contributing::    How to contribute to testing and developing GCC.
 
@@ -164,8 +164,8 @@  Introduction, gccint, GNU Compiler Collection (GCC) Internals}.
 @include objc.texi
 @include compat.texi
 @include gcov.texi
-@include trouble.texi
 @include bugreport.texi
+@include trouble.texi
 @include service.texi
 @include contribute.texi
 
diff --git a/gcc/doc/service.texi b/gcc/doc/service.texi
index 2a6d431..f57e0a5 100644
--- a/gcc/doc/service.texi
+++ b/gcc/doc/service.texi
@@ -2,7 +2,7 @@ 
 @c This is part of the GCC manual.
 @c For copying conditions, see the file gcc.texi.
 
-@node Service
+@node Service,Contributing,Trouble,Bugs
 @chapter How To Get Help with GCC
 
 If you need help installing, using or changing GCC, there are two
diff --git a/gcc/doc/trouble.texi b/gcc/doc/trouble.texi
index d5b056a..6d8f0ee 100644
--- a/gcc/doc/trouble.texi
+++ b/gcc/doc/trouble.texi
@@ -2,7 +2,7 @@ 
 @c This is part of the GCC manual.
 @c For copying conditions, see the file gcc.texi.
 
-@node Trouble
+@node Trouble,Service,Bug Reporting,Bugs
 @chapter Known Causes of Trouble with GCC
 @cindex bugs, known
 @cindex installation trouble