docs: 'dist-shar' and 'dist-tarZ' are obsolescent today

Both the options and the formats; and they might be deprecated
and removed in future automake versions (see discussion on
automake bug#13324).

In any case, it's better if the documentation starts advising
against their use right now.

* doc/automake.texi (The Types of Distributions): Here.
(List of Automake options): And here.

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

1 files changed, 18 insertions, 12 deletions

diff --git a/doc/automake.texi b/doc/automake.texi
index 8d8c2c91a..33caba40a 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -8675,10 +8675,6 @@ 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 @samp{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}
@@ -8696,8 +8692,15 @@ Generate a @samp{zip} archive of the distribution.
 
 @item @code{dist-tarZ}
 Generate a tar archive of the distribution, compressed with the
-historical program @command{compress}.
+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
@@ -10074,22 +10077,25 @@ Hook @code{dist-lzip} to @code{dist}.
 Hook @code{dist-xz} to @code{dist}.
 @trindex dist-xz
 
-@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-zip}
 @cindex Option, @option{dist-zip}
 @opindex dist-zip
 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}