documentation incorrect for function `define-package'?

documentation incorrect for function `define-package'?

[Michelangelo Rodriguez]

The documentation for `define-package' function says:
EXTRA-PROPERTIES is currently unused.
But, indeed, it's not true.
In order for a multi-package to correctly work, and in particular to
`describe-package' to report correctly information on a multi-package,
it is necessary to specify keywords as :author, :keywords, and so on...
Neither function documentation nor info manual mention that.
Infact, if i specify only library headers containing that information,
describe-package don't report keywords, nor other tags.

Re: documentation incorrect for function `define-package'?

[Stefan Kangas]

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

> The documentation for `define-package' function says:
> EXTRA-PROPERTIES is currently unused.
> But, indeed, it's not true.
> In order for a multi-package to correctly work, and in particular to
> `describe-package' to report correctly information on a multi-package,
> it is necessary to specify keywords as :author, :keywords, and so on...
> Neither function documentation nor info manual mention that.
> Infact, if i specify only library headers containing that information,
> describe-package don't report keywords, nor other tags.

This is its current definition:

    (defun define-package ( _name-string _version-string
                            &optional _docstring _requirements
                            &rest _extra-properties)
      "Define a new package.
    NAME-STRING is the name of the package, as a string.
    VERSION-STRING is the version of the package, as a string.
    DOCSTRING is a short description of the package, a string.
    REQUIREMENTS is a list of dependencies on other packages.
     Each requirement is of the form (OTHER-PACKAGE OTHER-VERSION),
     where OTHER-VERSION is a string.

    EXTRA-PROPERTIES is currently unused."
      ;; FIXME: Placeholder!  Should we keep it?
      (error "Don't call me!"))

On the one hand, this function is clearly not intended for use.

On the other hand, where else do we document the `define-package' list
that goes in "foo-pkg.el"?

Those definitions look like this, but again this is just data (the
"package.el" Commentary section incorrectly says "'PACKAGE-pkg.el' which
consists of a *call* to define-package", my emphasis):

(define-package "which-key" "20210824.11" "Display available
keybindings in popup" '((emacs "24.4")) :commit
"4790a14683a2f3e4f72ade197c78e4c0af1cdd4b" :authors '(("Justin
Burkett" . "justin@burkett.cc")) :maintainer '("Justin Burkett" .
"justin@burkett.cc") :url
"https://github.com/justbur/emacs-which-key")

Re: documentation incorrect for function `define-package'?

[Michelangelo Rodriguez]

Stefan Kangas <stefankangas@gmail.com> writes:


> This is its current definition:
>
>     (defun define-package ( _name-string _version-string
>                             &optional _docstring _requirements
>                             &rest _extra-properties)
>       "Define a new package.
>     NAME-STRING is the name of the package, as a string.
>     VERSION-STRING is the version of the package, as a string.
>     DOCSTRING is a short description of the package, a string.
>     REQUIREMENTS is a list of dependencies on other packages.
>      Each requirement is of the form (OTHER-PACKAGE OTHER-VERSION),
>      where OTHER-VERSION is a string.
>
>     EXTRA-PROPERTIES is currently unused."
>       ;; FIXME: Placeholder!  Should we keep it?
>       (error "Don't call me!"))
>
> On the one hand, this function is clearly not intended for use.
>
> On the other hand, where else do we document the `define-package' list
> that goes in "foo-pkg.el"?
>
> Those definitions look like this, but again this is just data (the
> "package.el" Commentary section incorrectly says "'PACKAGE-pkg.el' which
> consists of a *call* to define-package", my emphasis):
>
> (define-package "which-key" "20210824.11" "Display available
> keybindings in popup" '((emacs "24.4")) :commit
> "4790a14683a2f3e4f72ade197c78e4c0af1cdd4b" :authors '(("Justin
> Burkett" . "justin@burkett.cc")) :maintainer '("Justin Burkett" .
> "justin@burkett.cc") :url
> "https://github.com/justbur/emacs-which-key")
So, in my actual understanding of how the package system works, actually
<package>-pkg.el is generated by an authomation when that package is
installed from elpa or another archive?
I think that because i try to install a local package in which i'm
working and if i try to install it by using `package-install-file' and i
don't specify various keywords to `define-package' then
`describe-package' does'nt report correctly some information.
so, which is the "correct way " to test the package?

Re: documentation incorrect for function `define-package'?

[Stefan Kangas]

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

> So, in my actual understanding of how the package system works, actually
> <package>-pkg.el is generated by an authomation when that package is
> installed from elpa or another archive?

It is generated by whatever software creates the package archive.

GNU ELPA and MELPA are two notable examples.

> I think that because i try to install a local package in which i'm
> working and if i try to install it by using `package-install-file' and i
> don't specify various keywords to `define-package' then
> `describe-package' does'nt report correctly some information.
> so, which is the "correct way " to test the package?

In general, you shouldn't need to create this file yourself.  It will be
created for you by e.g. GNU ELPA.  What you do need to do is ensure that
your package headers are correct.

The usual work-flow here, I think, is to add your package to a package
archive, see what kind of metadata it comes up with and address any
problems you see.

Re: documentation incorrect for function `define-package'?

[Michelangelo Rodriguez]

Thank you Stefan for your help.

Stefan Kangas <stefankangas@gmail.com> writes:

> Michelangelo Rodriguez <michelangelo.rodriguez@gmail.com> writes:
>
>> So, in my actual understanding of how the package system works, actually
>> <package>-pkg.el is generated by an authomation when that package is
>> installed from elpa or another archive?
>
> It is generated by whatever software creates the package archive.
>
> GNU ELPA and MELPA are two notable examples.
>
>> I think that because i try to install a local package in which i'm
>> working and if i try to install it by using `package-install-file' and i
>> don't specify various keywords to `define-package' then
>> `describe-package' does'nt report correctly some information.
>> so, which is the "correct way " to test the package?
>
> In general, you shouldn't need to create this file yourself.  It will be
> created for you by e.g. GNU ELPA.  What you do need to do is ensure that
> your package headers are correct.
>
> The usual work-flow here, I think, is to add your package to a package
> archive, see what kind of metadata it comes up with and address any
> problems you see.