Bug#1001131: [RFC PATCH] Enhance docs with answers for common questions
Nicholas D Steeves <sten@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 <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.
d
Reply to: