On 01/21/2013 11:11 PM, Roumen Petrov wrote:
> Hi automake developers,
>
> Current (2013-01-21) automake 1.13 manual
> http://www.gnu.org/software/automake/manual/automake.html
> list quite short distribution types in chapter 17.2 List of
> Automake options.
>
Actually, only 'dist-xz' wasn't mentioned. Which I fixed with the
attached patch.
> It seems to me up to date list is in chapter "14.5 The Types
> of Distributions"
>
Indeed (but note there is no corresponding option to 'dist-gzip',
since that is enabled by default).
> List of supported types in "14.5 The Types of Distributions"
> is alphabetical. Probably default could be listed first
> followed by other (+0 to change order).
>
Good idea (and could also explicitly identified as the default
one); see the second attached patch.
While at it, I've thrown in some other miscellaneous improvements
to the descriptions of the 'dist-*'. See third patch.
I've also make clear the 'shar' and 'tarZ' are obsolescent,
and better avoided (see discussion about automake bug#13324
for more background). See the fourth patch.
>
> Final paragraph in chapter 14.5 is "The rule dist (and its
> historical synonym dist-all) will create archives in all the
> enabled formats, Options[HREF!]. By default, only the dist-gzip
> target is hooked to dist. " What about to change HREF "#Options"
> (chapter 17 "Changing Automake's Behavior") to exact reference>
> "#List-of-Automake-options"(chapter 17.2 "List of Automake options") ?
>
Good idea as well. Done with the fifth patch.
Every point should have been addressed, so I'm closing this report.
Thanks,
Stefano
>From 7d0372aceb50e1bd0938eab2eb3a5f289e731daa Mon Sep 17 00:00:00 2001
Message-Id: <7d0372aceb50e1bd0938eab2eb3a5f289e731daa.1358856705.git.stefano.lattar...@gmail.com>
From: Stefano Lattarini <stefano.lattar...@gmail.com>
Date: Tue, 22 Jan 2013 12:03:35 +0100
Subject: [PATCH 1/5] docs: document 'dist-xz' together with the other 'dist-*'
options
See automake bug#13520.
* doc/automake.texi (List of Automake options): Here.
Signed-off-by: Stefano Lattarini <stefano.lattar...@gmail.com>
---
doc/automake.texi | 6 ++++++
1 file changed, 6 insertions(+)
diff --git a/doc/automake.texi b/doc/automake.texi
index 69e44ca..8052600 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -10067,6 +10067,12 @@ Hook @code{dist-bzip2} to @code{dist}.
Hook @code{dist-lzip} to @code{dist}.
@trindex dist-lzip
+@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-shar}
@cindex Option, @option{dist-shar}
@opindex dist-shar
--
1.8.1.rc3.438.ge9abef6
>From 6b8f20088def2f54c8d62e8a0baaa249511ed0f2 Mon Sep 17 00:00:00 2001
Message-Id: <6b8f20088def2f54c8d62e8a0baaa249511ed0f2.1358856705.git.stefano.lattar...@gmail.com>
In-Reply-To: <7d0372aceb50e1bd0938eab2eb3a5f289e731daa.1358856705.git.stefano.lattar...@gmail.com>
References: <7d0372aceb50e1bd0938eab2eb3a5f289e731daa.1358856705.git.stefano.lattar...@gmail.com>
From: Stefano Lattarini <stefano.lattar...@gmail.com>
Date: Tue, 22 Jan 2013 12:08:43 +0100
Subject: [PATCH 2/5] docs: make even clearer 'dist-gzip' is the default.
See automake bug#13520.
* doc/automake.texi (The Types of Distributions): Here.
Signed-off-by: Stefano Lattarini <stefano.lattar...@gmail.com>
---
doc/automake.texi | 9 +++++----
1 file changed, 5 insertions(+), 4 deletions(-)
diff --git a/doc/automake.texi b/doc/automake.texi
index 8052600..76761a7 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -8656,6 +8656,11 @@ 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
@@ -8665,10 +8670,6 @@ 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.
--
1.8.1.rc3.438.ge9abef6
>From e5932416dc8832616a57807ea3efd5aeeeed3ad8 Mon Sep 17 00:00:00 2001
Message-Id: <e5932416dc8832616a57807ea3efd5aeeeed3ad8.1358856705.git.stefano.lattar...@gmail.com>
In-Reply-To: <7d0372aceb50e1bd0938eab2eb3a5f289e731daa.1358856705.git.stefano.lattar...@gmail.com>
References: <7d0372aceb50e1bd0938eab2eb3a5f289e731daa.1358856705.git.stefano.lattar...@gmail.com>
From: Stefano Lattarini <stefano.lattar...@gmail.com>
Date: Tue, 22 Jan 2013 12:14:20 +0100
Subject: [PATCH 3/5] docs: improve documentation of 'dist-*' targets slightly
* doc/automake.texi (The Types of Distributions): Here.
Signed-off-by: Stefano Lattarini <stefano.lattar...@gmail.com>
---
doc/automake.texi | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/doc/automake.texi b/doc/automake.texi
index 76761a7..8d8c2c9 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -8663,8 +8663,8 @@ only format enabled by default.
@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}.
@@ -8676,7 +8676,7 @@ archives are frequently smaller than @command{bzip2}-compressed archives.
@trindex dist-lzip
@item @code{dist-shar}
-Generate a shar archive of the distribution.
+Generate a @samp{shar} archive of the distribution.
@trindex dist-shar
@vindex XZ_OPT
@@ -8691,12 +8691,12 @@ 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 program @command{compress}.
@trindex dist-tarZ
@end table
--
1.8.1.rc3.438.ge9abef6
>From a8f36147417116ab0af6977b5688e2fd94f28600 Mon Sep 17 00:00:00 2001
Message-Id: <a8f36147417116ab0af6977b5688e2fd94f28600.1358856706.git.stefano.lattar...@gmail.com>
In-Reply-To: <7d0372aceb50e1bd0938eab2eb3a5f289e731daa.1358856705.git.stefano.lattar...@gmail.com>
References: <7d0372aceb50e1bd0938eab2eb3a5f289e731daa.1358856705.git.stefano.lattar...@gmail.com>
From: Stefano Lattarini <stefano.lattar...@gmail.com>
Date: Tue, 22 Jan 2013 12:30:15 +0100
Subject: [PATCH 4/5] 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.lattar...@gmail.com>
---
doc/automake.texi | 30 ++++++++++++++++++------------
1 file changed, 18 insertions(+), 12 deletions(-)
diff --git a/doc/automake.texi b/doc/automake.texi
index 8d8c2c9..33caba4 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}
--
1.8.1.rc3.438.ge9abef6
>From 13f1d58ada3fb9709ec144954ae38254d9624f8c Mon Sep 17 00:00:00 2001
Message-Id: <13f1d58ada3fb9709ec144954ae38254d9624f8c.1358856706.git.stefano.lattar...@gmail.com>
In-Reply-To: <7d0372aceb50e1bd0938eab2eb3a5f289e731daa.1358856705.git.stefano.lattar...@gmail.com>
References: <7d0372aceb50e1bd0938eab2eb3a5f289e731daa.1358856705.git.stefano.lattar...@gmail.com>
From: Stefano Lattarini <stefano.lattar...@gmail.com>
Date: Tue, 22 Jan 2013 13:02:25 +0100
Subject: [PATCH 5/5] docs: more precise cross reference
See automake bug#13520.
* doc/automake.texi (The Types of Distributions): Here,
cross-reference "List of Automake options" rather then
the more generic node "Options". Improve wording while
at it.
Signed-off-by: Stefano Lattarini <stefano.lattar...@gmail.com>
---
doc/automake.texi | 7 ++++---
1 file changed, 4 insertions(+), 3 deletions(-)
diff --git a/doc/automake.texi b/doc/automake.texi
index 33caba4..26ff60e 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -8703,9 +8703,10 @@ is obsolescent, and use of this option is discouraged.
@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
--
1.8.1.rc3.438.ge9abef6
