Bug#1001131: [RFC PATCH] Enhance docs with answers for common questions
Package: dh-elpa
Version: 2.0.9
Severity: normal
Control: tag -1 patch
Hello,
I've noticed that these questions are still coming up on
#debian-emacs, so I thought I'd work on a documentation enhancement
proposal. I've attached a patch series, and--if preferred--a git remote is available at: https://salsa.debian.org/sten/dh-elpa.git
The commit messages further information, and short changelog messages
have also been provided.
Thanks,
Nicholas
>From e9d5277aaf7bdc2acf5f282dd17f276781505a35 Mon Sep 17 00:00:00 2001
From: Nicholas D Steeves <nsteeves@gmail.com>
Date: Sat, 4 Dec 2021 19:31:54 -0500
Subject: [PATCH 1/3] =?UTF-8?q?Eliminate=20potential=20ambiguity=20by=20ch?=
=?UTF-8?q?anging=20the=20case=20of=20"elpa"=20to=E2=80=A6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
"ELPA" everywhere it makes sense to do so. Previously a mix of the
two existed.
---
debian/changelog | 5 +++++
dh_elpa | 18 +++++++++---------
2 files changed, 14 insertions(+), 9 deletions(-)
diff --git a/debian/changelog b/debian/changelog
index b94a950..f99ee4c 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,7 +1,12 @@
dh-elpa (2.0.10) UNRELEASED; urgency=medium
+ [ David Bremner ]
* Update dh_elpa_test documentation
+ [ Nicholas D Steeves ]
+ * Eliminate potential ambiguity by changing the case of "elpa" to "ELPA"
+ everywhere it makes sense to do so. Previously a mix of the two existed.
+
-- David Bremner <bremner@debian.org> Fri, 24 Sep 2021 10:14:54 -0300
dh-elpa (2.0.9) unstable; urgency=medium
diff --git a/dh_elpa b/dh_elpa
index f51a592..0370f50 100755
--- a/dh_elpa
+++ b/dh_elpa
@@ -21,7 +21,7 @@ B<dh_elpa> [S<I<debhelper options>>] [S<I<pkg-file>>]
=head1 DESCRIPTION
B<dh_elpa> is a debhelper program that is responsible for installing
-elpa style emacs lisp packages into package build directories.
+ELPA style emacs lisp packages into package build directories.
B<dh_elpa> will attempt to run ERT and Buttercup test suites using
dh_elpa_test(1) if the debhelper compat level is 10 or higher. This
@@ -38,19 +38,19 @@ dh_elpa_test(1).
=item debian/elpa
List of files to be installed into I<package> (respectively into the
-first binary package) as an elpa package. The format is a set of
+first binary package) as an ELPA package. The format is a set of
lines, where each line is either (i) a single filename or glob, or
(ii) a space-separated list of one or more filenames or globs,
followed by the name of a destination subdirectory (which should not
begin with a slash).
For lines with a single file or glob, B<dh_elpa> will install matching
-file(s) into the top level elpa package directory.
+file(s) into the top level ELPA package directory.
For lines which include a destination subdirectory, B<dh_elpa> will
install matching file(s) into the named subdirectory.
-Only elisp files in the top level elpa package directory will be
+Only elisp files in the top level ELPA package directory will be
automatically byte-compiled.
=item I<elpa-package>-pkg.el
@@ -185,7 +185,7 @@ sub maybe_install_helper{
error "elpa package name not found";
my $elpaversion = $desc->{'ELPA-Version'};
- error "elpa version not found" if (!defined($elpaversion));
+ error "ELPA version not found" if (!defined($elpaversion));
sed_file (sub {s/#ELPAPACKAGE#/$elpapackage/;
s/#ELPAVERSION#/$elpaversion/;
@@ -219,12 +219,12 @@ foreach my $package (getpackages()) {
my $varname="ELPA_NAME_${package}";
my $elpapkg = $ENV{$varname} || $ENV{ELPA_NAME};
if (!defined($elpapkg)) {
- verbose_print("Guessing elpa package name from package name $package");
+ verbose_print("Guessing ELPA package name from package name $package");
$elpapkg = $package;
$elpapkg =~ s/^elpa-//;
}
- verbose_print("Using elpa package name $elpapkg");
+ verbose_print("Using ELPA package name $elpapkg");
my @lines;
my @actions;
@@ -235,7 +235,7 @@ foreach my $package (getpackages()) {
# as a side effect.
isnative($package);
if ($file) {
- # Read in the contents of the elpa control file into an array of
+ # Read in the contents of the ELPA control file into an array of
# arrays. Don't glob yet, we need to count the words first.
@lines=filedoublearray($file);
@@ -250,7 +250,7 @@ foreach my $package (getpackages()) {
# Glob expand every word in the current line
$action->{src} = [ map { glob_expand(["."], \&glob_expand_error_handler_warn_and_discard, $_) } @$line ];
- # Check for an multi-file elpa package control file
+ # Check for an multi-file ELPA package control file
$has_package_file ||= (grep m/\b${elpapkg}-pkg.el$/, @{$action->{src}});
push @actions, $action;
--
2.30.2
>From e06d515b6d0a863cd367c3c1afc769b9e56e7504 Mon Sep 17 00:00:00 2001
From: Nicholas D Steeves <nsteeves@gmail.com>
Date: Sat, 4 Dec 2021 19:32:58 -0500
Subject: [PATCH 2/3] Enhance the Description (in dh_elpa.1) to better answer
the question
"What is dh_elpa?"
---
debian/changelog | 2 ++
dh_elpa | 19 +++++++++++++++++++
2 files changed, 21 insertions(+)
diff --git a/debian/changelog b/debian/changelog
index f99ee4c..0c407c6 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -6,6 +6,8 @@ dh-elpa (2.0.10) UNRELEASED; urgency=medium
[ Nicholas D Steeves ]
* Eliminate potential ambiguity by changing the case of "elpa" to "ELPA"
everywhere it makes sense to do so. Previously a mix of the two existed.
+ * Enhance the Description (in dh_elpa.1) to better answer the question
+ "What is dh_elpa?"
-- David Bremner <bremner@debian.org> Fri, 24 Sep 2021 10:14:54 -0300
diff --git a/dh_elpa b/dh_elpa
index 0370f50..509cfed 100755
--- a/dh_elpa
+++ b/dh_elpa
@@ -23,6 +23,25 @@ B<dh_elpa> [S<I<debhelper options>>] [S<I<pkg-file>>]
B<dh_elpa> is a debhelper program that is responsible for installing
ELPA style emacs lisp packages into package build directories.
+An "Emacs Lisp Package Archive" style package is a library that
+includes the metadata that is necessary to integrate with GNU Emacs
+via B<package.el.> This metadata is provided using headers and/or an
+B<elpa-foo-pkg.el> file. B<dh_elpa> will attempt to autogenerate
+this file from headers, and will warn when this is not possible. When
+converting a legacy-style Debian Emacs package to a new-style ELPA
+package, maintainers will typically choose to hand-craft this file;
+When upstream releases no longer occur, the B<Version> variable of
+this file will not need to be updated, thus for such packages, a
+B<elpa-foo-pkg.el> involves neglegible to zero maintenance burden.
+
+Why convert a legacy-style Debian Emacs package to a new-style ELPA
+one? Using B<dh_elpa> centralises maintscripts, allowing one to drop
+them from the package; this eliminates a source of bugs, and allows
+all B<dh_elpa>-using packages to inherit cross-archive updates to
+emacsen packages. Integration with the GNU Emacs package manager is
+consistent with a better user experience, and the primary reason to
+not adopt B<dh_elpa> is when compatibility with XEmacs is required.
+
B<dh_elpa> will attempt to run ERT and Buttercup test suites using
dh_elpa_test(1) if the debhelper compat level is 10 or higher. This
will override dh_auto_test(1). To disable this behaviour, or tweak it
--
2.30.2
>From 6b1105955c1eb56ace4413d37f06973409417629 Mon Sep 17 00:00:00 2001
From: Nicholas D Steeves <nsteeves@gmail.com>
Date: Sat, 4 Dec 2021 19:34:17 -0500
Subject: [PATCH 3/3] =?UTF-8?q?Replace=20occurrences=20of=20<package>=20wi?=
=?UTF-8?q?th=20<foo>=20for=20disambiguation=E2=80=A6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
and readability. The new Description in dh_elpa.1 mentions
"package.el". Here, "package" is a static atom; however, in
"elpa-package-pkg.el" the same atom is a foo-style variable. The term
also appears too often in the man page, and this reduces readability.
Please feel free to change to something more appropriate should foo
not be desired.
---
debian/changelog | 2 ++
dh_elpa | 10 +++++-----
2 files changed, 7 insertions(+), 5 deletions(-)
diff --git a/debian/changelog b/debian/changelog
index 0c407c6..d0f972b 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -8,6 +8,8 @@ dh-elpa (2.0.10) UNRELEASED; urgency=medium
everywhere it makes sense to do so. Previously a mix of the two existed.
* Enhance the Description (in dh_elpa.1) to better answer the question
"What is dh_elpa?"
+ * Replace occurrences of <package> with <foo> for disambiguation and
+ readability.
-- David Bremner <bremner@debian.org> Fri, 24 Sep 2021 10:14:54 -0300
diff --git a/dh_elpa b/dh_elpa
index 509cfed..811305f 100755
--- a/dh_elpa
+++ b/dh_elpa
@@ -52,11 +52,11 @@ dh_elpa_test(1).
=over 4
-=item debian/I<package>.elpa
+=item debian/I<foo>.elpa
=item debian/elpa
-List of files to be installed into I<package> (respectively into the
+List of files to be installed into I<foo> (respectively into the
first binary package) as an ELPA package. The format is a set of
lines, where each line is either (i) a single filename or glob, or
(ii) a space-separated list of one or more filenames or globs,
@@ -72,7 +72,7 @@ install matching file(s) into the named subdirectory.
Only elisp files in the top level ELPA package directory will be
automatically byte-compiled.
-=item I<elpa-package>-pkg.el
+=item I<elpa-foo>-pkg.el
This file contains packaging metadata for a multi-file package -- see
the Emacs manual on the subject of "Packaging" for full details.
@@ -81,9 +81,9 @@ This file is often part of the upstream source, but when it is not,
dh_elpa will try to create it at package build time. If it cannot,
and you need to create one manually, you can add it to the upstream
source, or create the file in C<debian/> and list it in
-debian/I<package>.elpa.
+debian/I<foo>.elpa.
-=item I<elpa-package>-autoloads.el
+=item I<elpa-foo>-autoloads.el
This file is used by the Emacs packaging system to collect autoloads
from the Emacs Lisp sources. It is usually generated at package build
--
2.30.2
Reply to: