Re: bug#7766: (lack of) config.h description in manual

[Ralf Wildenhues]

[ dropping bug-automake ]

* Karl Berry wrote on Sun, Jan 09, 2011 at 01:17:36AM CET:
>     Hmm, I see a natural split into two, not three nodes.  
> 
> Ok, fine.
> 
>     Below, I replaced the existing one rather than using another lower
>     hierarchy level.  Does this seem acceptable to you?
> 
> Sure, but I suggest making the @node names closer to the @section names,
> and not using that unusual-looking /.
[...]
> And then I think the upper-level menu could just use the node names.

You mean without a description added afterwards in the @menu, right?
Fine with me, the only small bummer is that emacs ^C ^U ^V then
generates trailing white space in the menus; oh well.

> (In general, despite longstanding precedent in various GNU manuals, my
> belief is that it is not helpful to readers to have @node names that
> unnecessarily differ from their section names.  The result is confusion
> when an xref is made.)

Agreed.

I'm pushing this to maint now; thanks for the quick review!

Cheers,
Ralf

    docs: split 'amhello Explained' node.
    
    * doc/automake.texi (amhello Explained): Split node ...
    (amhello's configure.ac Setup Explained)
    (amhello's Makefile.am Setup Explained) : ... into these two.
    (Top, Hello World): Adjust, and add @anchor for stable URL links.
    Suggestion by Karl Berry in automake bug#7766.

diff --git a/doc/automake.texi b/doc/automake.texi
index c63dbf3..775c95f 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -157,7 +157,8 @@ Top
 A Small Hello World
 
 * Creating amhello::            Create @file{amhello-1.0.tar.gz} from scratch
-* amhello Explained::           @file{configure.ac} and @file{Makefile.am} 
explained
+* amhello's configure.ac Setup Explained::  
+* amhello's Makefile.am Setup Explained::  
 
 General ideas
 
@@ -1392,9 +1393,11 @@ Hello World
 meaning of the @file{configure.ac} and @file{Makefile.am} files read
 by the Autotools.
 
address@hidden Explained}
 @menu
 * Creating amhello::            Create @file{amhello-1.0.tar.gz} from scratch
-* amhello Explained::           @file{configure.ac} and @file{Makefile.am} 
explained
+* amhello's configure.ac Setup Explained::  
+* amhello's Makefile.am Setup Explained::  
 @end menu
 
 @node Creating amhello
@@ -1555,8 +1558,10 @@ Creating amhello
 direct you to the right manual when seeking answers.
 
 
address@hidden amhello Explained
address@hidden @file{amhello-1.0} Explained
address@hidden amhello's configure.ac Setup Explained
address@hidden @code{amhello}'s @file{configure.ac} Setup Explained
+
address@hidden @file{configure.ac}, Hello World
 
 Let us begin with the contents of @file{configure.ac}.
 
@@ -1664,6 +1669,10 @@ amhello Explained
 @command{autoscan} to Create @file{configure.ac}, autoconf, The
 Autoconf Manual}).
 
+
address@hidden amhello's Makefile.am Setup Explained
address@hidden @code{amhello}'s @file{Makefile.am} Setup Explained
+
 @cindex @file{Makefile.am}, Hello World
 
 We now turn to @file{src/Makefile.am}.  This file contains