Merge branch 'branch-1.13.2' into maint

* branch-1.13.2:
  docs: '.txi' and '.texinfo' extensions are deprecated
  NEWS: document recent documentation improvements
  docs: more precise cross reference
  docs: 'dist-shar' and 'dist-tarZ' are obsolescent today
  docs: improve documentation of 'dist-*' targets slightly
  docs: make even clearer 'dist-gzip' is the default.
  docs: document 'dist-xz' together with the other 'dist-*' options
  docs: 'no-define' option and AM_INIT_AUTOMAKE three-args usage: fixlets
  warn: correct broken hyperlink in warning message

Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>

1 files changed, 41 insertions, 27 deletions

diff --git a/doc/automake.texi b/doc/automake.texi
index a32d8bdc7..feae3ac80 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -3951,9 +3951,9 @@ explicitly).
 @opindex no-define
 By default this macro @code{AC_DEFINE}'s @code{PACKAGE} and
 @code{VERSION}.  This can be avoided by passing the @option{no-define}
-option:
+option (@pxref{List of Automake options}):
 @example
-AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2])
+AM_INIT_AUTOMAKE([no-define ...])
 @end example
 
 @item AM_PATH_LISPDIR
@@ -7828,9 +7828,9 @@ Currently Automake provides support for Texinfo and man pages.
 If the current directory contains Texinfo source, you must declare it
 with the @code{TEXINFOS} primary.  Generally Texinfo files are converted
 into info, and thus the @code{info_TEXINFOS} variable is most commonly used
-here.  Any Texinfo source file must end in the @file{.texi},
-@file{.txi}, or @file{.texinfo} extension.  We recommend @file{.texi}
-for new manuals.
+here.  Any Texinfo source file should have the @file{.texi} extension.
+Automake also accepts @file{.txi} or @file{.texinfo} extensions, but their
+use is discouraged now, and will elicit runtime warnings.
 
 Automake generates rules to build @file{.info}, @file{.dvi},
 @file{.ps}, @file{.pdf} and @file{.html} files from your Texinfo
@@ -8668,28 +8668,25 @@ Automake generates rules to provide archives of the project for
 distributions in various formats.  Their targets are:
 
 @table @asis
+@item @code{dist-gzip}
+Generate a @samp{gzip} tar archive of the distribution.  This is the
+only format enabled by default.
+@trindex dist-gzip
+
 @vindex BZIP2
 @item @code{dist-bzip2}
-Generate a bzip2 tar archive of the distribution.  bzip2 archives are
-frequently smaller than gzipped archives.
+Generate a @samp{bzip2} tar archive of the distribution.  bzip2 archives
+are frequently smaller than gzipped archives.
 By default, this rule makes @samp{bzip2} use a compression option of @option{-9}.
 To make it use a different one, set the @env{BZIP2} environment variable.
 For example, @samp{make dist-bzip2 BZIP2=-7}.
 @trindex dist-bzip2
 
-@item @code{dist-gzip}
-Generate a gzip tar archive of the distribution.
-@trindex dist-gzip
-
 @item @code{dist-lzip}
 Generate an @samp{lzip} tar archive of the distribution.  @command{lzip}
 archives are frequently smaller than @command{bzip2}-compressed archives.
 @trindex dist-lzip
 
-@item @code{dist-shar}
-Generate a shar archive of the distribution.
-@trindex dist-shar
-
 @vindex XZ_OPT
 @item @code{dist-xz}
 Generate an @samp{xz} tar archive of the distribution.  @command{xz}
@@ -8702,18 +8699,26 @@ default compression ratio, but with a progress indicator:
 @trindex dist-xz
 
 @item @code{dist-zip}
-Generate a zip archive of the distribution.
+Generate a @samp{zip} archive of the distribution.
 @trindex dist-zip
 
 @item @code{dist-tarZ}
-Generate a compressed tar archive of
-the distribution.
+Generate a tar archive of the distribution, compressed with the
+historical (obsolescent) program @command{compress}.  Use of this
+option is discouraged.
 @trindex dist-tarZ
+
+@item @code{dist-shar}
+Generate a @samp{shar} archive of the distribution.  This format archive
+is obsolescent, and use of this option is discouraged.
+@trindex dist-shar
+
 @end table
 
-The rule @code{dist} (and its historical synonym @code{dist-all}) will
-create archives in all the enabled formats, @ref{Options}.  By
-default, only the @code{dist-gzip} target is hooked to @code{dist}.
+The rule @code{dist} (and its historical synonym @code{dist-all})
+will create archives in all the enabled formats (@pxref{List of
+Automake options} for how to change this list).  By default, only
+the @code{dist-gzip} target is hooked to @code{dist}.
 
 
 @node Tests
@@ -10079,11 +10084,11 @@ Hook @code{dist-bzip2} to @code{dist}.
 Hook @code{dist-lzip} to @code{dist}.
 @trindex dist-lzip
 
-@item @option{dist-shar}
-@cindex Option, @option{dist-shar}
-@opindex dist-shar
-Hook @code{dist-shar} to @code{dist}.
-@trindex dist-shar
+@item @option{dist-xz}
+@cindex Option, @option{dist-xz}
+@opindex dist-xz
+Hook @code{dist-xz} to @code{dist}.
+@trindex dist-xz
 
 @item @option{dist-zip}
 @cindex Option, @option{dist-zip}
@@ -10091,10 +10096,19 @@ Hook @code{dist-shar} to @code{dist}.
 Hook @code{dist-zip} to @code{dist}.
 @trindex dist-zip
 
+@item @option{dist-shar}
+@cindex Option, @option{dist-shar}
+@opindex dist-shar
+Hook @code{dist-shar} to @code{dist}.  Use of this option
+is discouraged, as the @samp{shar} format is obsolescent and
+problematic.
+@trindex dist-shar
+
 @item @option{dist-tarZ}
 @cindex Option, @option{dist-tarZ}
 @opindex dist-tarZ
-Hook @code{dist-tarZ} to @code{dist}.
+Hook @code{dist-tarZ} to @code{dist}.  Use of this option
+is discouraged, as the @samp{compress} program is obsolete.
 @trindex dist-tarZ
 
 @item @option{filename-length-max=99}