GNU bug report logs - #50825
28.0.50; improve documentation for `define-package'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 50825 in the body.
You can then email your comments to 50825 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Michelangelo Rodriguez <michelangelo.rodriguez <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 28.0.50; improve documentation for `define-package'
Date: Sun, 26 Sep 2021 19:36:21 +0200

In the elisp manual, and precisely in "(elisp) multi-file packages" we
read:

"   Prior to installation, a multi-file package is stored in a package
archive as a tar file.  The tar file must be named ‘NAME-VERSION.tar’,
where NAME is the package name and VERSION is the version number.  Its
contents, once extracted, must all appear in a directory named
‘NAME-VERSION’, the “content directory” (*note Packaging Basics::).
Files may also extract into subdirectories of the content directory.

   One of the files in the content directory must be named
‘NAME-pkg.el’.".
It should be clarified that, actually, the <name>-pkg.el is generated by
the archive, and is not "responsibility" of the programmer that is
actually writing the code.
The responsibility of a programmer is just to write library headers
correctly.
Infact, if as a coder i write manually package-pkg.el using just the
parameters specified for the `define-package' function, and afterwards i
generate `package.tar", and install it using `package-install-file' when
i use `describe-package' to see it's documentation, the headers i had
specified in the package are not reported.



In GNU Emacs 28.0.50 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.24.24, cairo version 1.16.0)
 of 2021-09-25 built on mugno
Repository revision: 2767c89db729a6106146d0aeff76678c64d4fc53
Repository branch: master
System Description: Debian GNU/Linux 11 (bullseye)

Configured using:
 'configure --with-native-compilation'

Configured features:
ACL CAIRO DBUS FREETYPE GIF GLIB GMP GNUTLS GPM GSETTINGS HARFBUZZ JPEG
JSON LIBOTF LIBSELINUX LIBSYSTEMD LIBXML2 M17N_FLT MODULES NATIVE_COMP
NOTIFY INOTIFY PDUMPER PNG RSVG SECCOMP SOUND THREADS TIFF
TOOLKIT_SCROLL_BARS X11 XDBE XIM XPM GTK3 ZLIB

Important settings:
  value of $LANG: it_IT.UTF-8
  locale-coding-system: utf-8-unix

Major mode: Info

Minor modes in effect:
  semantic-minor-modes-format: ((:eval (if (or semantic-highlight-edits-mode semantic-show-unmatched-syntax-mode)  S)))
  shell-dirtrack-mode: t
  greader-mode: t
  gpm-mouse-mode: t
  global-voice-lock-mode: t
  voice-lock-mode: t
  global-company-mode: t
  company-mode: t
  midnight-mode: t
  tooltip-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: linux
  auto-encryption-mode: t
  auto-compression-mode: t
  buffer-read-only: t
  indent-tabs-mode: t

Load-path shadows:
/home/michelangelo/.emacs.d/elpa/transient-20210919.1006/transient hides /usr/local/share/emacs/28.0.50/lisp/transient
/home/michelangelo/emacspeak/lisp/tetris hides /usr/local/share/emacs/28.0.50/lisp/play/tetris

Features:
(shadow emacsbug emacspeak-wizards url-cache format-spec
emacspeak-outline noutline outline emacspeak-eww emacspeak-google gweb
emacspeak-we emacspeak-xslt dom-addons eww xdg url-queue mm-url
emacspeak-eterm two-column term ehelp ucs-normalize url-http url-auth
url-gw emacspeak-twittering twittering-mode apropos finder-inf package-x
mule-util greader-speechd ereader xml+ emacspeak-view view s picture
dash emacspeak-bookmark bookmark mm-archive gnutls network-stream nsm
mailalias smtpmail sendmail bbdb-com crm emacspeak-bbdb bbdb bbdb-site
timezone emacspeak-custom cus-edit sort gnus-cite mail-extr gnus-async
gnus-bcklg gnus-ml disp-table cursor-sensor qp nndraft nnmh nnfolder
nnml gnus-agent gnus-srvr gnus-score score-mode nnvirtual gnus-msg nntp
gnus-cache greader greader-espeak easy-mmode emacspeak-compile compile
autoload lisp-mnt emacspeak-tar tar-mode emacspeak-arc arc-mode
archive-mode emacspeak-comint shell pcomplete comint ansi-color
dired-aux misearch multi-isearch help-fns radix-tree cl-print debug
backtrace cus-start thingatpt emacspeak-xref emacspeak-widget
emacspeak-tab-bar emacspeak-rmail emacspeak-project emacspeak-package
emacspeak-calendar appt diary-lib diary-loaddefs g-utils solar cal-dst
cal-menu calendar cal-loaddefs emacspeak-message emacspeak-kmacro
emacspeak-info emacspeak-gnus gm-nnir nnir gnus-art mm-uu mml2015
mm-view mml-smime smime dig gnus-sum shr kinsoku svg dom gnus-group
gnus-undo gnus-start gnus-dbus dbus emacspeak-advice emacspeak-cedet xml
gnus-cloud nnimap nnmail mail-source utf7 netrc nnoo parse-time iso8601
gnus-spec gnus-int gnus-range message rmc puny emacspeak-dired locate
dired dired-loaddefs rfc822 mml mml-sec emacspeak-epa epa derived epg
rfc6068 epg-config mm-decode mm-bodies mm-encode mail-parse rfc2231
mailabbrev gmm-utils mailheader gnus-win emacspeak-hide
emacspeak-company emacspeak-buff-menu t-mouse term/linux jka-compr
emacspeak-setup emacspeak emacspeak-preamble emacspeak-sounds
emacspeak-speak sox-gen emacspeak-keymap emacspeak-pronounce voice-defs
voice-setup espeak-voices dtk-speak advice comp comp-cstr warnings rx
cl-extra help-mode company-oddmuse company-keywords company-etags etags
fileloop generator xref project ring company-gtags company-dabbrev-code
company-dabbrev company-files company-clang company-capf company-cmake
company-semantic company-template company-bbdb company pcase server
semantic/util-modes semantic/util semantic pp semantic/tag semantic/lex
semantic/fw mode-local find-func cedet midnight gnus nnheader gnus-util
rmail rmail-loaddefs rfc2047 rfc2045 ietf-drums text-property-search
time-date mail-utils mm-util mail-prsvr wid-edit cus-load debian-el
edmacro kmacro info package browse-url url url-proxy url-privacy
url-expand url-methods url-history url-cookie url-domsuf url-util
mailcap url-handlers url-parse auth-source cl-seq eieio eieio-core
cl-macs eieio-loaddefs password-cache json subr-x map url-vars seq
byte-opt gv bytecomp byte-compile cconv cl-loaddefs cl-lib iso-transl
tooltip eldoc electric uniquify ediff-hook vc-hooks lisp-float-type
elisp-mode mwheel term/x-win x-win term/common-win x-dnd tool-bar dnd
fontset image regexp-opt fringe tabulated-list replace newcomment
text-mode lisp-mode prog-mode register page tab-bar menu-bar rfn-eshadow
isearch easymenu timer select scroll-bar mouse jit-lock font-lock syntax
font-core term/tty-colors frame minibuffer cl-generic cham georgian
utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao korean
japanese eucjp-ms cp51932 hebrew greek romanian slovak czech european
ethiopic indian cyrillic chinese composite emoji-zwj charscript charprop
case-table epa-hook jka-cmpr-hook help simple abbrev obarray
cl-preloaded nadvice button loaddefs faces cus-face macroexp files
window text-properties overlay sha1 md5 base64 format env code-pages
mule custom widget hashtable-print-readable backquote threads dbusbind
inotify dynamic-setting system-font-setting font-render-setting cairo
move-toolbar gtk x-toolkit x multi-tty make-network-process
native-compile emacs)

Memory information:
((conses 16 2884205 280184)
 (symbols 48 48845 21)
 (strings 32 370227 19381)
 (string-bytes 1 13462965)
 (vectors 16 110573)
 (vector-slots 8 2388979 36361)
 (floats 8 667 509)
 (intervals 56 277979 15032)
 (buffers 992 38))

Message #8 received at 50825 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Michelangelo Rodriguez <michelangelo.rodriguez <at> gmail.com>
Cc: 50825 <at> debbugs.gnu.org
Subject: Re: bug#50825: 28.0.50; improve documentation for `define-package'
Date: Mon, 27 Sep 2021 06:13:17 +0200

Michelangelo Rodriguez <michelangelo.rodriguez <at> gmail.com> writes:

>    One of the files in the content directory must be named
> ‘NAME-pkg.el’.".
> It should be clarified that, actually, the <name>-pkg.el is generated by
> the archive, and is not "responsibility" of the programmer that is
> actually writing the code.

These sections of the manual are directed at people managing an ELPA
repository, not towards people who are writing code that will end up
there.  So all the stuff about tar file names and -pkg files are things
ELPA repository maintainers need to know, but people that write the code
doesn't have to care about at all.

I've now added a paragraph to the Packaging node that explicitly says
this.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #13 received at 50825 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>, 50825 <at> debbugs.gnu.org
Subject: Re: master 44dbc11: Note that the Packaging sub-nodes are mostly for
 maintainers
Date: Mon, 27 Sep 2021 05:47:49 -0700

larsi <at> gnus.org (Lars Ingebrigtsen) writes:

> branch: master
> commit 44dbc11ff7bdccc8af2cdd311e6ebacfef2c43a7
> Author: Lars Ingebrigtsen <larsi <at> gnus.org>
> Commit: Lars Ingebrigtsen <larsi <at> gnus.org>
>
>     Note that the Packaging sub-nodes are mostly for maintainers
>
>     * doc/lispref/package.texi (Packaging): Note that the information
>     is mostly for ELPA maintainers (bug#50825).
> ---
>  doc/lispref/package.texi | 5 +++++
>  1 file changed, 5 insertions(+)
>
> diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi
> index 9c033fe..aeb455b 100644
> --- a/doc/lispref/package.texi
> +++ b/doc/lispref/package.texi
> @@ -17,6 +17,11 @@ put it in a @dfn{package archive} for others to download.
>  @xref{Packages,,, emacs, The GNU Emacs Manual}, for a description of
>  user-level features of the packaging system.
>
> +  These sections are mostly directed towards package archive
> +maintainers---much of this information is not relevant for package
> +authors (i.e., people who write code that will be distributed via
> +these archives).
> +
>  @menu
>  * Packaging Basics::        The basic concepts of Emacs Lisp packages.
>  * Simple Packages::         How to package a single .el file.

If this entire section is only relevant for package archive maintainers,
I think it should be wrapped in "@ifnottex" so it's excluded from the
printed manual.

But it seems to me that, while of the information indeed almost only
relevant for package maintainers, at least some part of it is useful for
package developers.  Do you agree?  See for example this paragraph in
(info "(elisp) Packaging Basics").

       Installing a package, either via the command ‘package-install-file’,
    or via the Package Menu, creates a subdirectory of ‘package-user-dir’
    named ‘NAME-VERSION’, where NAME is the package’s name and VERSION its
    version (e.g., ‘~/.emacs.d/elpa/auctex-11.86/’).

And then it repeats some stuff about `package-activate-all' that is
presumably already said in the user manual.

See also (info "(elisp) Simple Packages").

Perhaps we should think about it a bit more and make it more clear who
this documentation is intended for?  Once we know that, it should be
easier to make any necessary changes.

For example, if this is indeed all mixed up, could we split this up into
two subchapters or something?  In the more user-oriented section, we
could skip many of the more low-level details and just focus on: here's
what you need to do to produce a valid package.  Or perhaps that should
be documented by the package archives themselves?  Or is that in the
user manual?  Etc.

Message #16 received at 50825 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: 50825 <at> debbugs.gnu.org
Subject: Re: master 44dbc11: Note that the Packaging sub-nodes are mostly
 for maintainers
Date: Tue, 28 Sep 2021 07:22:38 +0200

Stefan Kangas <stefankangas <at> gmail.com> writes:

> For example, if this is indeed all mixed up, could we split this up into
> two subchapters or something?  In the more user-oriented section, we
> could skip many of the more low-level details and just focus on: here's
> what you need to do to produce a valid package.  Or perhaps that should
> be documented by the package archives themselves?  Or is that in the
> user manual?  Etc.

Yes, I think splitting up this part of the manual would be a good idea.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.