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

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.


Reply to: