Hi David, Thank you for replying quickly, and sorry for the tardiness of mine. Holiday season, you know? ;-) David Bremner <david@tethera.net> writes: > Nicholas D Steeves <sten@debian.org> writes: > [snip] >> >> 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. > Thanks! >> +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. I've been wondering that too :-) I hope some ideas for the name of that subheading will emerge in the course of this discussion. > - it might be useful to define "legacy-style" Would referring to /usr/share/doc/emacsen-common/debian-emacs-policy.gz do the trick? More broadly, Policy §11.10 maintains that this Emacs Policy is still the standard, while lintian complains that packages should migrate to dh-elpa. I suspect this is a source of confusion, but at the same time we don't want to throw Rob (and his excellent documentation) under the bus. > - I tripped over "neglegible to zero", perhaps replace with something > simpler like "minimal". > Fair point! Likewise, it appears that the onus is on us to make a case for dh-elpa vis à vis debian-emacs-policy. What would you suggest would communicate "less than minimal"? The impression I've gotten from other maintainers of legacy/maintscript/debian-emacs-policy packages is that their packages work fine with minimal maintenance burden, so I think we need to say something that communicates that dh-elpa saves time/future headaches vs the existing status quo. It might also be worth referencing dh_elpa_test, and expanding those docs to expand on the value of the autopkgtests that using it enables. >> +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. > Good point, and yes, I'm not sure. The phrase used in the doc referenced above is "maintainer scripts". >> +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. > Yeah, I suppose that phrase is a bit marketing-speak ;-) To be honest I'm not sure what precise point to make here, because I'm not sure that most users will mix dh-elpa packages with user-specific ELPA/MELPA ones, and because the expectation in a Debian-context is that users don't have to worry about dependency resolution...so additional package.el dependency checks might not add a tonne of practical value for users. I feel like, here, there's a fine line between a tangential and an orthogonal explanation. For example, it would be cool if package.el could prompt the user to resolve ELPA-level dependencies with elpa-foo.deb via one of the interfaces to apt, and fall back to ELPA/MELPA repos if the user can't get root. The use case for this would be when installing a leaf package from ELPA/MELPA, but to fulfill its deps with apt. What would you suggest? >>>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. > > 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. > Oh yeah, the wiki docs! Agreed. Done, and pushed to: https://salsa.debian.org/sten/dh-elpa.git No rush to reply :-) Merry Christmas! Nicholas
Attachment:
signature.asc
Description: PGP signature