initial hints about replacing emacsen-startup

These probably need wordsmithing

1 files changed, 57 insertions, 0 deletions

diff --git a/dh_elpa.in b/dh_elpa.in
index 96e2881..8353b3f 100755
--- a/dh_elpa.in
+++ b/dh_elpa.in
@@ -419,3 +419,60 @@ environment variable in debian/rules:
 
 You can also specify the name on a per binary package basis with
 C<ELPA_NAME_binary-package-name>=tpp-mode.
+
+=head2 Debian specific customizations
+
+Pre-B<dh_elpa> packages using C<emacsen-common> typically had an Emacs
+Lisp file C<debian/emacsen-startup> which is installed into
+C</etc/emacs/site-start.d>. One of the most important functions these
+files was the correct setting of C<load-path> to make the package
+available to users; this is no longer required as it is handled by the
+Emacs Package system when generating I<elpa-package>-autoloads.el.
+This means that many packages do not need any debian specific
+configuration.
+
+Other kinds of configuration can be handled by adding the special
+I<autoload cookie> in front of a form to be run at package
+initialization time. These forms are added to
+I<elpa-package>-autoloads.el, which is B<not> in C</etc/>. This
+simplifies package maintenance.
+
+These cookies can either annotate upstream source, or be added (along
+with the relevant forms) to a file in C<debian/>, by convention
+C<debian/debian-autoloads.el>. Currently you will have manually
+include that file in debian/I<package>.elpa.
+
+=over 4
+
+=item Autoload a function
+
+In general definitions of which functions to autoload belong in the
+upstream source beside the function definition.
+
+    ;;;###autoload
+    (defun hello ()
+    "wave in a friendly manner"
+    (interactive)
+    ...)
+
+One option is to patch in the autoload cookie (if needed) and send
+those patches upstream. If that is not possible, you can manually
+create the autoload form and add it to C<debian-autoloads.el>.
+
+    ;;;###autoload
+    (autoload 'hello "goodbye.el" "wave in a friendly manner" t)
+
+=item Other customizations
+
+Other customizations (e.g. key bindings or setting variables) can be
+handled similarly to autoloading functions.
+
+    ;;;###autoload
+    (setq the-package-setting 42)
+
+The Emacs package system will copy an arbitrary (non-defun) form to
+the package autoloads file.  Changing the behaviour of the package (as
+opposed to making it work) should in most cases happen in upstreamed
+patches.
+
+=back