[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Bug#1001131: [RFC PATCH] Enhance docs with answers for common questions

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:
>> 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.

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

> - 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:

No rush to reply :-)
Merry Christmas!


Attachment: signature.asc
Description: PGP signature

Reply to: