[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: bug#7766: (lack of) config.h description in manual
From: |
Ralf Wildenhues |
Subject: |
Re: bug#7766: (lack of) config.h description in manual |
Date: |
Sun, 9 Jan 2011 07:34:13 +0100 |
User-agent: |
Mutt/1.5.20 (2010-08-04) |
[ 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