Clarify meaning of 'Link' section in module description

Clarify meaning of 'Link' section in module description

[Bruno Haible]

Currently, the meaning of the 'Link' section in the module description
is not clear: If absent, does it mean that the user of the module needs
no libraries on the link command line? Or does it mean that the user
needs to collect the 'Link' section of all dependencies?

We need to consider two kinds of modules:
* Most gnulib modules depend on other modules in order to invoke their
  code. Thus, the link options of a module needs to combine the link
  options of all its dependencies.
* Some gnulib modules (such as those of the math functions, but also
  c-stack, file-has-acl, getaddrinfo, gethostname, gethrxtime, nanosleep,
  poll, pthread_sigmask, select, thread, timer-time) have a .m4 file that
  computes the needed link options for the module, based on some variables
  determined by other modules. In this case, the link options of all the
  dependencies ought to be ignored by the user of the module.

To clarify the meaning, while accommodating the needs of both kinds of
modules, I'm changing the module description specification:


2019-01-04  Bruno Haible  <bruno@clisp.org>

	Clarify meaning of 'Link' section in module description.
	* doc/gnulib.texi (Module description): Clarify the meaning of the
	'Link' section versus the one of the dependencies.
	* NEWS: Mention the change.

diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index ece6f5c..a79c7c9 100644
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -476,6 +476,8 @@ Example:
 $(POW_LIBM)
 $(LTLIBICONV) when linking with libtool, $(LIBICONV) otherwise
 @end smallexample
+When this field is omitted, it defaults to the union of the @code{Link}
+field of the dependencies.
 
 @item License
 This field specifies the license that governs the source code parts of
diff --git a/NEWS b/NEWS
index c28bbc7..22a4e1e 100644
--- a/NEWS
+++ b/NEWS
@@ -3,6 +3,10 @@ Important general notes
 
 Date        Modules         Changes
 
+2019-01-04  (all)           The meaning of the 'Link' section in the module
+                            descriptions has been clarified: It overrides the
+                            combined 'Link' sections from the dependencies.
+
 2018-10-22  (all)           Automake >= 1.11 and Autoconf >= 2.63 are required.
 
 2016-09-05  progname        There is now an alternate module 'getprogname'. It