[PATCH] {maint} Docs: better documentation for silent make rules.

[Stefano Lattarini]

Hi Eric, and thanks for the review.

On Saturday 04 December 2010, Eric Blake wrote:
 On 12/04/2010 01:48 PM, Stefano Lattarini wrote:
  Hello automakers.
  
  I've worked some more on this, and I think I've now managed to find
  the proper layout for the new chapter, and a decently complete list
  of topics to be touched.  There are still some TODOs and rough edges,
  but I think the patch is approaching to a state acceptable for
  application.
  
  Attached are the new version of the patch, plus the diffs from the
  older version.
  
  Any feedback before I attempt the final respin would be really
  appreciated.
 
  +...@cindex default verbosity for silent-rules
  +Note that silent rules are @emph{enabled} by default; the user have to
 
 disabled by default
 
Oops *blush*!  Thank for catching this; it's fixed now.

  +enable them explicitly at either make at either @command{configure} run
  +time or at @command{make} run time.
  +
 
 One thing that might also be worth mentioning is that a user can set
 their own preferences via a config.site file

Good idea.  IMO, this also requires a new testcase, which I've added to
the respinned patch.

 (for example, I have enable_silent_rules=yes as one of the lines in my
 /usr/local/share/config.site).
 
I'd prefer something like `enable_silent_rules=${enable_silent_rules-yes}'
which allows disabling of silent rules from the configure command line.

-*-*-

I've also made many fixings, rewordings, improvements and extensions
w.r.t. the previous version of the patch.  Attached is what I've
squashed in the previous version, plus the amended patch.  If there
are no objections, I'd like to consider this the final version of the
patch, and apply it to maint.  Further improvements can still be done
later.

OK to apply?

Regards,
Stefano
From 3ce71c7f997b101fe94229cd9e273d96c5ad9032 Mon Sep 17 00:00:00 2001
From: Stefano Lattarini stefano.lattar...@gmail.com
Date: Fri, 12 Nov 2010 20:26:59 +0100
Subject: [PATCH] Docs: better documentation for silent make rules.

Docs: better documentation for silent make rules.
* doc/automake.texi (Options): Detailed description of the
automake option `silent-rules' moved from here ...
(Silent Make): ... into this new chapter, expanded, improved,
and subdivided into ...
(Make verbosity, Tricks For Silencing Make,
Automake silent-rules Option): ... these new sections.
(@menu, @detailmenu): Update.
* tests/silent-configsite.test: New test, checking that the
user can control default mode of silent-rules from config.site,
as is documented in the manual.
* tests/Makefile.am (TESTS): Updated.
---
 ChangeLog|   16 ++
 doc/automake.texi|  372 +-
 tests/Makefile.am|1 +
 tests/Makefile.in|1 +
 tests/silent-configsite.test |   87 ++
 5 files changed, 398 insertions(+), 79 deletions(-)
 create mode 100755 tests/silent-configsite.test

diff --git a/ChangeLog b/ChangeLog
index e8864f1..3007a76 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,19 @@
+2010-12-05  Stefano Lattarini  stefano.lattar...@gmail.com
+
+	Docs: better documentation for silent make rules.
+	* doc/automake.texi (Options): Detailed description of the
+	automake option `silent-rules' moved from here ...
+	(Silent Make): ... to this new chapter, expanded, improved,
+	and complemented with ...
+	(Make verbosity, Tricks For Silencing Make,
+	Automake silent-rules Option): ... these two new introductory
+	sections.
+	(@menu, @detailmenu): Update.
+	* tests/silent-configsite.test: New test, checking that the
+	user can control default mode of silent-rules from config.site,
+	as is documented in the manual.
+	* tests/Makefile.am (TESTS): Updated.
+
 2010-11-25  Stefano Lattarini  stefano.lattar...@gmail.com
 
 	Fix spurious failures in `silent*.test' for $CC != gcc
diff --git a/doc/automake.texi b/doc/automake.texi
index 5a805b3..d558909 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -117,6 +117,7 @@ section entitled ``GNU Free Documentation License.''
 * Miscellaneous::   Miscellaneous rules
 * Include:: Including extra files in an Automake template
 * Conditionals::Conditionals
+* Silencing Make::  Obtain less verbose output from @command{make}
 * Gnits::   The effect of @option{--gnu} and @option{--gnits}
 * Cygnus::  The effect of @option{--cygnus}
 * Not Enough::  When Automake is not Enough
@@ -330,6 +331,12 @@ Conditionals
 * Usage of Conditionals::   Declaring conditional content
 * Limits of Conditionals::  Enclosing complete statements
 
+Silencing Make
+
+* Make verbosity::   Make is verbose by default
+* Tricks For Silencing Make::Standard and generic ways to silence make
+* Automake silent-rules Option:: How Automake can help in silencing make
+
 When Automake Isn't Enough
 
 * Extending::   Adding 

Re: [PATCH] Modernize, improve and/or tweak some test scripts.

[Stefano Lattarini]

Now that Savannah is up again, I'm pinging this patch again,
according to this:
 http://lists.gnu.org/archive/html/automake-patches/2010-11/msg3.html

I'll wait the customary 72 hours (until wednesday evening) before pushing.

Regards,
  Stefano

Re: [PATCH] Extend checks on remake rules.

[Ralf Wildenhues]

* Stefano Lattarini wrote on Sun, Dec 05, 2010 at 06:06:00PM CET:
 I'll wait the customary 72 hours (until wednesday evening) before pushing.

This patch should have proper testing on several systems, and seems ok
when tested and with nitse below addressed.  If you still don't have
access, please ping the person involved again, and me so that I can test
the patch eventually.

A couple of issues in this patch I'm seeing just from glancing at it
is that it touches this sed limitation (quoting autoconf.info):

 If a sed script is specified on the command line and ends in an
 `a', `c', or `i' command, the last line of inserted text should be
 followed by a newline.  Otherwise some `sed' implementations
 (e.g., OpenBSD 3.9) do not append a newline to the inserted text.

In remake1a, your sanity check requires that 'make -n' works to really
not remake anything.  If that were the main purpose of the test, that
would be fine, but as a sanity check I'd rather not use -n here.

What is remake11.test for?

Some of the tests look like they are testing the same things really
as other new or existing tests.  Can you explain them (ideally, the
comment at the start of the test should be unique for each test so
we can infer from that that each of the tests is actually required)?
But maybe I'm just overlooking something?

I wish you'd get yourself convinced to get rid of some of the 'for
debugging' type comments, these things seem a bit obvious to need a
comment.  OTOH, I can see that some of them really help getting over
the wait, isn't that a typo sort of feeling.  Hmm, maybe leave them
in, skipping over them isn't that hard.

 The updated rebased patch is attached.  In it I have:
  - removed the overly hackish and complex tests remake2{a,b,c}.test,
introduced by the previous version of my patch; I'll hopefully
be able to find a saner way to improve coverage in that area (it
can always be done in a follow-up patch without problems);
  - removed a uselessly-added make distcheck from `remake4.test';
  - removed all usages of in-line shell commments in make rules (since
it turned out they're unportable to at least Tru64/OSF 5.1 make);
this affected only test `remake12.test';
  - removed usages of `##' special automake comments which weren't on
lines of their own (this usage is not part of the automake API)
  - added or extended comments for trickier tests;
  - thrown in some micellanous minor improvements and simplifications.

Good!

Thanks,
Ralf