GNU logs - #7766, boring messages

Message sent to owner <at> debbugs.gnu.org, bug-automake@HIDDEN:

Subject: bug#7766: (lack of) config.h description in manual
Resent-From: karl@HIDDEN (Karl Berry)
Original-Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Resent-To: owner <at> debbugs.gnu.org
Resent-CC: bug-automake@HIDDEN
Resent-Date: Fri, 31 Dec 2010 23:54:02 +0000
Resent-Message-ID: <handler.7766.B.129383961215704 <at> debbugs.gnu.org>
Resent-Sender: help-debbugs@HIDDEN
To: 7766 <at> debbugs.gnu.org
Date: Sat, 1 Jan 2011 00:00:20 GMT
Message-Id: <201101010000.p0100KNA009987@HIDDEN>
From: karl@HIDDEN (Karl Berry)
Precedence: list
Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org

Hi Ralf and all,

A new GNU maintainer just asked me about how to use $(pkgdatadir) from
his C program.  I looked at the Automake manual and didn't see anywhere
especially good to point him at :(.  A couple thoughts I had as a result
of looking at this for him:

First, tiny English point in node Optional:
< As for `AC_CONFIG_FILES' (*note Requirements::), parts of the
> As with ...

The main point: although "amhello Explained" talks about
AC_CONFIG_HEADERS and gives a partial example, I don't see any "real"
description of how to determine what ends up in config.h and what the
#define names are.  If I'm not just missing something, I suggest a new
node, perhaps under "Generalities", which talks about Automake/C
linkage, including autoheader, etc.

The apparent reference definition for AC_CONFIG_HEADERS (in node
"Optional") says nothing about what it really does.

It belatedly occurs to me that perhaps this topic is gone into in more
detail in the Autoconf manual.  I don't have the energy to search
through it now, but if that is so, at least a cross-reference to that
would be nice.  (FWIW, I looked at all occurrences of config\.h and
CONFIG_HEADERS in the automake manual.)

Subsidiary points: in the general index (I continue to very strongly
encourage you to merge all indexes, BTW), I didn't find anything useful
for "preprocessor", or "#define", or "config.h", or anything else I
could think of.  Fortran preprocessing was the only thing.

Finally, the "amhello explained" node is pretty long.  It seems to break
up naturally into three pieces, for each of the files being explained.
Perhaps it would be good to make them each separate (sub)nodes.

Of course, all the above are just some ideas, please do whatever makes
sense and forget the rest.

Happy hacking in 2011,
karl

Message sent:

Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable
MIME-Version: 1.0
X-Mailer: MIME-tools 5.427 (Entity 5.427)
Content-Type: text/plain; charset=utf-8
X-Loop: help-debbugs@HIDDEN
From: help-debbugs@HIDDEN (GNU bug Tracking System)
To: karl@HIDDEN (Karl Berry)
Subject: bug#7766: Acknowledgement ((lack of) config.h description in manual)
Message-ID: <handler.7766.B.129383961215704.ack <at> debbugs.gnu.org>
References: <201101010000.p0100KNA009987@HIDDEN>
X-Gnu-PR-Message: ack 7766
X-Gnu-PR-Package: automake
Reply-To: 7766 <at> debbugs.gnu.org
Date: Fri, 31 Dec 2010 23:54:02 +0000

Thank you for filing a new bug report with GNU.

This is an automatically generated reply to let you know your message
has been received.

Your message is being forwarded to the package maintainers and other
interested parties for their attention; they will reply in due course.

Your message has been sent to the package maintainer(s):
 bug-automake@HIDDEN

If you wish to submit further information on this problem, please
send it to 7766 <at> debbugs.gnu.org.

Please do not send mail to help-debbugs@HIDDEN unless you wish
to report a problem with the Bug-tracking system.

--=20
7766: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=3D7766
GNU Bug Tracking System
Contact help-debbugs@HIDDEN with problems

Message sent to owner <at> debbugs.gnu.org, bug-automake@HIDDEN:

Subject: bug#7766: (lack of) config.h description in manual
Resent-From: Ralf Wildenhues <Ralf.Wildenhues@HIDDEN>
Original-Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Resent-To: owner <at> debbugs.gnu.org
Resent-CC: bug-automake@HIDDEN
Resent-Date: Sat, 08 Jan 2011 19:15:02 +0000
Resent-Message-ID: <handler.7766.B7766.12945140533264 <at> debbugs.gnu.org>
Resent-Sender: help-debbugs@HIDDEN
To: Karl Berry <karl@HIDDEN>, automake-patches@HIDDEN
Cc: 7766 <at> debbugs.gnu.org
Date: Sat, 8 Jan 2011 20:21:29 +0100
From: Ralf Wildenhues <Ralf.Wildenhues@HIDDEN>
Message-ID: <20110108192129.GL4786@HIDDEN>
Mail-Followup-To: Karl Berry <karl@HIDDEN>,
	automake-patches@HIDDEN, 7766 <at> debbugs.gnu.org
References: <201101010000.p0100KNA009987@HIDDEN>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <201101010000.p0100KNA009987@HIDDEN>
Organization: Institute for Numerical Simulation, University of Bonn
User-Agent: Mutt/1.5.20 (2010-08-04)
Precedence: list
Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org

Hi Karl,

* Karl Berry wrote on Sat, Jan 01, 2011 at 01:00:20AM CET:
> Finally, the "amhello explained" node is pretty long.  It seems to break
> up naturally into three pieces, for each of the files being explained.
> Perhaps it would be good to make them each separate (sub)nodes.

Hmm, I see a natural split into two, not three nodes.  Below, I replaced
the existing one rather than using another lower hierarchy level.  Does
this seem acceptable to you?

Thanks,
Ralf

    docs: split 'amhello Explained' node.
    
    * doc/automake.texi (amhello Explained): Split node ...
    (amhello/configure.ac, amhello/Makefile.am): ... 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..9e29951 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/configure.ac::        Configure setup explained
+* amhello/Makefile.am::         Makefile 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.
 
+@anchor{amhello Explained}
 @menu
 * Creating amhello::            Create @file{amhello-1.0.tar.gz} from scratch
-* amhello Explained::           @file{configure.ac} and @file{Makefile.am} explained
+* amhello/configure.ac::        Configure setup explained
+* amhello/Makefile.am::         Makefile setup explained
 @end menu
 
 @node Creating amhello
@@ -1555,8 +1558,10 @@ Creating amhello
 direct you to the right manual when seeking answers.
 
 
-@node amhello Explained
-@subsection @file{amhello-1.0} Explained
+@node amhello/configure.ac
+@subsection Configure setup explained
+
+@cindex @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}).
 
+
+@node amhello/Makefile.am
+@subsection Makefile setup explained
+
 @cindex @file{Makefile.am}, Hello World
 
 We now turn to @file{src/Makefile.am}.  This file contains

Message sent to owner <at> debbugs.gnu.org, bug-automake@HIDDEN:

Subject: bug#7766: (lack of) config.h description in manual
References: <201101010000.p0100KNA009987@HIDDEN>
Resent-From: karl@HIDDEN (Karl Berry)
Original-Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Resent-To: owner <at> debbugs.gnu.org
Resent-CC: bug-automake@HIDDEN
Resent-Date: Sun, 09 Jan 2011 00:11:01 +0000
Resent-Message-ID: <handler.7766.B7766.1294531822672 <at> debbugs.gnu.org>
Resent-Sender: help-debbugs@HIDDEN
To: Ralf.Wildenhues@HIDDEN
Cc: 7766 <at> debbugs.gnu.org, automake-patches@HIDDEN
Date: Sun, 9 Jan 2011 00:17:36 GMT
Message-Id: <201101090017.p090HaEP030387@HIDDEN>
From: karl@HIDDEN (Karl Berry)
In-Reply-To: <20110108192129.GL4786@HIDDEN>
Precedence: list
Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org

    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 /.

@node amhello/configure.ac
->
@node amhello's configure.ac Setup Explained

@subsection Configure setup explained
->
@subsection @code{amhello}'s @file{configure.ac} Setup Explained

Ditto for the other node.

And then I think the upper-level menu could just use the node names.

(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.)

Re capitalization, I seem to recall that we tried to systematically
Capitalize Node/Section Names a while back.  I don't see other downcased
names in the top-level menu just now, anyway.

    +@anchor{amhello Explained}

Very good.  Extra credit for thinking to do that :).

Thanks,
k

Message sent to owner <at> debbugs.gnu.org, bug-automake@HIDDEN:

X-Loop: help-debbugs@HIDDEN
Subject: bug#7766: (lack of) config.h description in manual
Resent-From: Ralf Wildenhues <Ralf.Wildenhues@HIDDEN>
Original-Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Resent-To: owner <at> debbugs.gnu.org
Resent-CC: bug-automake@HIDDEN
Resent-Date: Sun, 09 Jan 2011 18:59:02 +0000
Resent-Message-ID: <handler.7766.B7766.12945995336552 <at> debbugs.gnu.org>
Resent-Sender: help-debbugs@HIDDEN
X-GNU-PR-Message: followup 7766
X-GNU-PR-Package: automake
X-GNU-PR-Keywords: 
To: Karl Berry <karl@HIDDEN>
Cc: 7766 <at> debbugs.gnu.org
Received: via spool by 7766-submit <at> debbugs.gnu.org id=B7766.12945995336552
          (code B ref 7766); Sun, 09 Jan 2011 18:59:02 +0000
Received: (at 7766) by debbugs.gnu.org; 9 Jan 2011 18:58:53 +0000
Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.69)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1Pc0Tc-0001hc-DH
	for submit <at> debbugs.gnu.org; Sun, 09 Jan 2011 13:58:52 -0500
Received: from mailout-de.gmx.net ([213.165.64.22] helo=mail.gmx.net)
	by debbugs.gnu.org with smtp (Exim 4.69)
	(envelope-from <Ralf.Wildenhues@HIDDEN>) id 1Pc0TZ-0001hM-VD
	for 7766 <at> debbugs.gnu.org; Sun, 09 Jan 2011 13:58:51 -0500
Received: (qmail invoked by alias); 09 Jan 2011 19:06:11 -0000
Received: from xdsl-89-0-131-211.netcologne.de (EHLO localhost.localdomain)
	[89.0.131.211]
	by mail.gmx.net (mp054) with SMTP; 09 Jan 2011 20:06:11 +0100
X-Authenticated: #13673931
X-Provags-ID: V01U2FsdGVkX18PKzISnucPD4ukGBFT16VIqJ6E3m2fOPWPgZDOl1
	ivjIZ8LCAu8Br0
Received: from ralf by localhost.localdomain with local (Exim 4.69)
	(envelope-from <Ralf.Wildenhues@HIDDEN>)
	id 1Pc0ag-0003NQ-7l; Sun, 09 Jan 2011 20:06:10 +0100
Date: Sun, 9 Jan 2011 20:06:10 +0100
From: Ralf Wildenhues <Ralf.Wildenhues@HIDDEN>
Message-ID: <20110109190610.GR17091@HIDDEN>
References: <201101010000.p0100KNA009987@HIDDEN>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <201101010000.p0100KNA009987@HIDDEN>
Organization: Institute for Numerical Simulation, University of Bonn
User-Agent: Mutt/1.5.20 (2010-08-04)
X-Y-GMX-Trusted: 0
X-Spam-Score: -2.7 (--)
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.11
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
	<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/pipermail/debbugs-submit>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
	<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
X-Spam-Score: -2.7 (--)

retitle 7766 docs: work on index issues
thanks

* Karl Berry wrote on Sat, Jan 01, 2011 at 01:00:20AM CET:
> 
> Subsidiary points: in the general index (I continue to very strongly
> encourage you to merge all indexes, BTW), I didn't find anything useful
> for "preprocessor", or "#define", or "config.h", or anything else I
> could think of.  Fortran preprocessing was the only thing.

AFAICS the index issues are the only remaining ones from this PR,
so I'm adjusting the title accordingly.

Message received at control <at> debbugs.gnu.org:

Received: (at control) by debbugs.gnu.org; 9 Jan 2011 18:58:53 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Sun Jan 09 13:58:53 2011
Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.69)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1Pc0Tc-0001he-Mi
	for submit <at> debbugs.gnu.org; Sun, 09 Jan 2011 13:58:52 -0500
Received: from mailout-de.gmx.net ([213.165.64.22] helo=mail.gmx.net)
	by debbugs.gnu.org with smtp (Exim 4.69)
	(envelope-from <Ralf.Wildenhues@HIDDEN>) id 1Pc0TZ-0001hL-VF
	for control <at> debbugs.gnu.org; Sun, 09 Jan 2011 13:58:51 -0500
Received: (qmail invoked by alias); 09 Jan 2011 19:06:11 -0000
Received: from xdsl-89-0-131-211.netcologne.de (EHLO localhost.localdomain)
	[89.0.131.211]
	by mail.gmx.net (mp054) with SMTP; 09 Jan 2011 20:06:11 +0100
X-Authenticated: #13673931
X-Provags-ID: V01U2FsdGVkX18PKzISnucPD4ukGBFT16VIqJ6E3m2fOPWPgZDOl1
	ivjIZ8LCAu8Br0
Received: from ralf by localhost.localdomain with local (Exim 4.69)
	(envelope-from <Ralf.Wildenhues@HIDDEN>)
	id 1Pc0ag-0003NQ-7l; Sun, 09 Jan 2011 20:06:10 +0100
Date: Sun, 9 Jan 2011 20:06:10 +0100
From: Ralf Wildenhues <Ralf.Wildenhues@HIDDEN>
To: Karl Berry <karl@HIDDEN>
Subject: Re: bug#7766: (lack of) config.h description in manual
Message-ID: <20110109190610.GR17091@HIDDEN>
References: <201101010000.p0100KNA009987@HIDDEN>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <201101010000.p0100KNA009987@HIDDEN>
Organization: Institute for Numerical Simulation, University of Bonn
User-Agent: Mutt/1.5.20 (2010-08-04)
X-Y-GMX-Trusted: 0
X-Spam-Score: -2.7 (--)
X-Debbugs-Envelope-To: control
Cc: 7766 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.11
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
	<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/pipermail/debbugs-submit>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
	<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
X-Spam-Score: -2.7 (--)

retitle 7766 docs: work on index issues
thanks

* Karl Berry wrote on Sat, Jan 01, 2011 at 01:00:20AM CET:
> 
> Subsidiary points: in the general index (I continue to very strongly
> encourage you to merge all indexes, BTW), I didn't find anything useful
> for "preprocessor", or "#define", or "config.h", or anything else I
> could think of.  Fortran preprocessing was the only thing.

AFAICS the index issues are the only remaining ones from this PR,
so I'm adjusting the title accordingly.

Message received at control <at> debbugs.gnu.org:

Received: (at control) by debbugs.gnu.org; 7 Dec 2011 22:53:18 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Wed Dec 07 17:53:18 2011
Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.69)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1RYQMY-0000up-Hl
	for submit <at> debbugs.gnu.org; Wed, 07 Dec 2011 17:53:18 -0500
Received: from mail-ee0-f44.google.com ([74.125.83.44])
	by debbugs.gnu.org with esmtp (Exim 4.69)
	(envelope-from <stefano.lattarini@HIDDEN>) id 1RYQMX-0000uj-Nq
	for control <at> debbugs.gnu.org; Wed, 07 Dec 2011 17:53:18 -0500
Received: by eekd4 with SMTP id d4so879494eek.3
	for <control <at> debbugs.gnu.org>; Wed, 07 Dec 2011 14:52:31 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma;
	h=from:to:subject:date:user-agent:mime-version:content-type
	:content-transfer-encoding:message-id;
	bh=DaYSB2CghJTJRd8j8sp8BQobRc+ppUI3xYnkrfmyc9A=;
	b=DHJ34Gzpu7yTV5I3rfCnnHUHjQJzxayMR/fR9ijAp7iDh37vfWUBNyx7lqLdOgocic
	9mYuw3sFZjsXR4Y+cBkhYp9yGDs1csWaEfCDPQ8PlUqAmamnlTGXrv5cCmWsaE72YAxF
	TeFc2OR6CEAmqAYaXVMlf78GMrzbkUH0fZPCk=
Received: by 10.14.16.79 with SMTP id g55mr37772eeg.175.1323298351178;
	Wed, 07 Dec 2011 14:52:31 -0800 (PST)
Received: from bigio.localnet
	(host167-102-dynamic.2-87-r.retail.telecomitalia.it. [87.2.102.167])
	by mx.google.com with ESMTPS id 58sm11270765eet.11.2011.12.07.14.52.30
	(version=TLSv1/SSLv3 cipher=OTHER);
	Wed, 07 Dec 2011 14:52:30 -0800 (PST)
From: Stefano Lattarini <stefano.lattarini@HIDDEN>
To: control <at> debbugs.gnu.org
Subject: am
Date: Wed, 7 Dec 2011 23:52:21 +0100
User-Agent: KMail/1.13.7 (Linux/2.6.30-2-686; KDE/4.6.5; i686; ; )
MIME-Version: 1.0
Content-Type: Text/Plain;
  charset="utf-8"
Content-Transfer-Encoding: 7bit
Message-Id: <201112072352.21490.stefano.lattarini@HIDDEN>
X-Spam-Score: -4.0 (----)
X-Debbugs-Envelope-To: control
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.11
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
	<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
	<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
X-Spam-Score: -4.0 (----)

severity 7610 minor
severity 7766 minor
severity 9625 minor
severity 10248 serious
severity 7884 important
severity 9768 important
thanks

Last modified: Mon, 25 Nov 2019 12:00:02 UTC

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997 nCipher Corporation Ltd, 1994-97 Ian Jackson.