Nicholas D Steeves <s...@debian.org> writes: > 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.
Overall this seems like a good idea. I have a few suggestions. > +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. > + - I did wonder if all of "legacy-style" discussion should be together, perhaps under a subheading. - it might be useful to define "legacy-style" - I tripped over "neglegible to zero", perhaps replace with something simpler like "minimal". > +Why convert a legacy-style Debian Emacs package to a new-style ELPA > +one? Using B<dh_elpa> centralises maintscripts, allowing one to drop - "maintscripts" seems a bit jargony, and the real point is that the packager does not need to maintain emacsen-common install/remove scripts. However, maybe it is better to be concise than precise here. > +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 - The phrase "consistent with a better user experience" sounds quite a bit overcomplicated and overqualified. > +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 <nstee...@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. I guess for an audience of debian contributors foo is OK, but I guess if possible it would be nice to have something a bit less in-jokey. I don't know if it's a strict improvement, but "hello" would be consistent with other docs. d