bug#50825: 28.0.50; improve documentation for `define-package'

bug#50825: 28.0.50; improve documentation for `define-package'

[Michelangelo Rodriguez]

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

bug#50825: 28.0.50; improve documentation for `define-package'

[Lars Ingebrigtsen]

Michelangelo Rodriguez <michelangelo.rodriguez@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