unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
* documentation incorrect for function `define-package'?
@ 2021-09-24 14:16 Michelangelo Rodriguez
  2021-09-24 15:01 ` Stefan Kangas
  0 siblings, 1 reply; 5+ messages in thread
From: Michelangelo Rodriguez @ 2021-09-24 14:16 UTC (permalink / raw)
  To: emacs-devel

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.



^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: documentation incorrect for function `define-package'?
  2021-09-24 14:16 documentation incorrect for function `define-package'? Michelangelo Rodriguez
@ 2021-09-24 15:01 ` Stefan Kangas
  2021-09-25 18:13   ` Michelangelo Rodriguez
  0 siblings, 1 reply; 5+ messages in thread
From: Stefan Kangas @ 2021-09-24 15:01 UTC (permalink / raw)
  To: Michelangelo Rodriguez, emacs-devel

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



^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: documentation incorrect for function `define-package'?
  2021-09-24 15:01 ` Stefan Kangas
@ 2021-09-25 18:13   ` Michelangelo Rodriguez
  2021-09-25 18:51     ` Stefan Kangas
  0 siblings, 1 reply; 5+ messages in thread
From: Michelangelo Rodriguez @ 2021-09-25 18:13 UTC (permalink / raw)
  To: emacs-devel

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?



^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: documentation incorrect for function `define-package'?
  2021-09-25 18:13   ` Michelangelo Rodriguez
@ 2021-09-25 18:51     ` Stefan Kangas
  2021-09-25 21:48       ` Michelangelo Rodriguez
  0 siblings, 1 reply; 5+ messages in thread
From: Stefan Kangas @ 2021-09-25 18:51 UTC (permalink / raw)
  To: Michelangelo Rodriguez, emacs-devel

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.



^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: documentation incorrect for function `define-package'?
  2021-09-25 18:51     ` Stefan Kangas
@ 2021-09-25 21:48       ` Michelangelo Rodriguez
  0 siblings, 0 replies; 5+ messages in thread
From: Michelangelo Rodriguez @ 2021-09-25 21:48 UTC (permalink / raw)
  To: emacs-devel

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.



^ permalink raw reply	[flat|nested] 5+ messages in thread

end of thread, other threads:[~2021-09-25 21:48 UTC | newest]

Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2021-09-24 14:16 documentation incorrect for function `define-package'? Michelangelo Rodriguez
2021-09-24 15:01 ` Stefan Kangas
2021-09-25 18:13   ` Michelangelo Rodriguez
2021-09-25 18:51     ` Stefan Kangas
2021-09-25 21:48       ` Michelangelo Rodriguez

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).