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

[Michelangelo Rodriguez <michelangelo.rodriguez@gmail.com>]

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