GNU bug report logs - #19537
Manual documents nonexistent functionality of package-upload-buffer

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 19537 in the body.
You can then email your comments to 19537 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: Kelly Dean <kelly <at> prtime.org>
To: bug-gnu-emacs <at> gnu.org
Subject: Manual documents nonexistent functionality of package-upload-buffer
Date: Thu, 08 Jan 2015 03:40:31 +0000

Manual page «(elisp) Package Archives» says:
⌜ -- Command: package-upload-buffer
     This command is similar to `package-upload-file', but instead of
     prompting for a package file, it uploads the contents of the
     current buffer.  The current buffer must be visiting a simple
     package (a `.el' file) or a multi-file package (a `.tar' file);
     otherwise, an error is raised.⌝

But in fact, it must be visiting a simple package; it can't be a multi-file package. For the latter, only package-upload-file works (and even that works only after the patch for bug #19536 is applied).

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

From: Stefan Monnier <monnier <at> IRO.UMontreal.CA>
To: Kelly Dean <kelly <at> prtime.org>
Cc: 19537 <at> debbugs.gnu.org
Subject: Re: bug#19537: Manual documents nonexistent functionality of
 package-upload-buffer
Date: Thu, 08 Jan 2015 09:31:21 -0500

> But in fact, it must be visiting a simple package; it can't be a multi-file
> package. For the latter, only package-upload-file works (and even that works
> only after the patch for bug #19536 is applied).

The package shouldn't document the "upload" functionality of package-x,
since that's a functionality that pretty much noone uses (most/all ELPA
archives use a different way to "upload" a package to it).


        Stefan

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: Kelly Dean <kelly <at> prtime.org>, 19537 <at> debbugs.gnu.org
Subject: Re: bug#19537: Manual documents nonexistent functionality of
 package-upload-buffer
Date: Sun, 14 Jul 2019 06:21:21 +0200

[Message part 1 (text/plain, inline)]

tags 19537 + patch
thanks

Kelly Dean <kelly <at> prtime.org> writes:

> Manual page «(elisp) Package Archives» says:
> ⌜ -- Command: package-upload-buffer
>      This command is similar to `package-upload-file', but instead of
>      prompting for a package file, it uploads the contents of the
>      current buffer.  The current buffer must be visiting a simple
>      package (a `.el' file) or a multi-file package (a `.tar' file);
>      otherwise, an error is raised.⌝
>
> But in fact, it must be visiting a simple package; it can't be a multi-file
> package. For the latter, only package-upload-file works (and even that works
> only after the patch for bug #19536 is applied).

Stefan Monnier <monnier <at> IRO.UMontreal.CA> writes:

> The package shouldn't document the "upload" functionality of package-x,
> since that's a functionality that pretty much noone uses (most/all ELPA
> archives use a different way to "upload" a package to it).

OK, I took a stab at removing it from the manual and added the
information it contained to the doc strings of the relevant functions
instead.  Please see attached patch -- WDYT?

Thanks,
Stefan Kangas

[0001-Remove-upload-functionality-of-package-x-from-the-el.patch (application/octet-stream, attachment)]

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: Kelly Dean <kelly <at> prtime.org>, 19537 <at> debbugs.gnu.org
Subject: Re: bug#19537: Manual documents nonexistent functionality of
 package-upload-buffer
Date: Mon, 15 Jul 2019 08:50:43 -0400

LGTM, thanks,


        Stefan


Stefan Kangas [2019-07-14 06:21:21] wrote:

> tags 19537 + patch
> thanks
>
> Kelly Dean <kelly <at> prtime.org> writes:
>
>> Manual page «(elisp) Package Archives» says:
>> ⌜ -- Command: package-upload-buffer
>>      This command is similar to `package-upload-file', but instead of
>>      prompting for a package file, it uploads the contents of the
>>      current buffer.  The current buffer must be visiting a simple
>>      package (a `.el' file) or a multi-file package (a `.tar' file);
>>      otherwise, an error is raised.⌝
>>
>> But in fact, it must be visiting a simple package; it can't be a multi-file
>> package. For the latter, only package-upload-file works (and even that works
>> only after the patch for bug #19536 is applied).
>
> Stefan Monnier <monnier <at> IRO.UMontreal.CA> writes:
>
>> The package shouldn't document the "upload" functionality of package-x,
>> since that's a functionality that pretty much noone uses (most/all ELPA
>> archives use a different way to "upload" a package to it).
>
> OK, I took a stab at removing it from the manual and added the
> information it contained to the doc strings of the relevant functions
> instead.  Please see attached patch -- WDYT?
>
> Thanks,
> Stefan Kangas
>
> From 06eff2ec14ef068f3d0bb9bc0cc2e7267ef5995d Mon Sep 17 00:00:00 2001
> From: Stefan Kangas <stefankangas <at> gmail.com>
> Date: Sun, 14 Jul 2019 05:59:46 +0200
> Subject: [PATCH] Remove upload functionality of package-x from the elisp
>  manual
>
> Suggested by Stefan Monnier.
> Ref: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=19537#8
>
> * doc/lispref/package.texi (Package Archives): Don't document
> package-x upload functions in the elisp manual, since they are not
> very commonly used.  (Bug#19537)
> * lisp/emacs-lisp/package-x.el (package-archive-upload-base)
> (package-upload-buffer, package-upload-file): Add to the doc strings
> any details removed from the elisp manual that would otherwise be
> missing.
> ---
>  doc/lispref/package.texi     | 35 -----------------------------------
>  lisp/emacs-lisp/package-x.el | 13 +++++++++++--
>  2 files changed, 11 insertions(+), 37 deletions(-)
>
> diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi
> index 7244efbd8f..a2f4f55be7 100644
> --- a/doc/lispref/package.texi
> +++ b/doc/lispref/package.texi
> @@ -321,41 +321,6 @@ Package Archives
>  by default; type @kbd{M-x load-library @key{RET} package-x @key{RET}} to
>  load it, or add @code{(require 'package-x)} to your init file.
>  @xref{Lisp Libraries,, Lisp Libraries, emacs, The GNU Emacs Manual}.
> -Once loaded, you can make use of the following:
> -
> -@defopt package-archive-upload-base
> -The value of this variable is the base location of a package archive,
> -as a directory name.  The commands in the @code{package-x} library
> -will use this base location.
> -
> -The directory name should be absolute.  You may specify a remote name,
> -such as @file{/ssh:foo@@example.com:/var/www/packages/}, if the
> -package archive is on a different machine.  @xref{Remote Files,,
> -Remote Files, emacs, The GNU Emacs Manual}.
> -@end defopt
> -
> -@deffn Command package-upload-file filename
> -This command prompts for @var{filename}, a file name, and uploads that
> -file to @code{package-archive-upload-base}.  The file must be either a
> -simple package (a @file{.el} file) or a multi-file package (a
> -@file{.tar} file); otherwise, an error is raised.  The package
> -attributes are automatically extracted, and the archive's contents
> -list is updated with this information.
> -
> -If @code{package-archive-upload-base} does not specify a valid
> -directory, the function prompts interactively for one.  If the
> -directory does not exist, it is created.  The directory need not have
> -any initial contents (i.e., you can use this command to populate an
> -initially empty archive).
> -@end deffn
> -
> -@deffn Command package-upload-buffer
> -This command is similar to @code{package-upload-file}, but instead of
> -prompting for a package file, it uploads the contents of the current
> -buffer.  The current buffer must be visiting a simple package (a
> -@file{.el} file) or a multi-file package (a @file{.tar} file);
> -otherwise, an error is raised.
> -@end deffn
>  
>  @noindent
>  After you create an archive, remember that it is not accessible in the
> diff --git a/lisp/emacs-lisp/package-x.el b/lisp/emacs-lisp/package-x.el
> index 1486aeb373..1ddcb3eeaf 100644
> --- a/lisp/emacs-lisp/package-x.el
> +++ b/lisp/emacs-lisp/package-x.el
> @@ -47,6 +47,8 @@ gnus-article-buffer
>  
>  (defcustom package-archive-upload-base "/path/to/archive"
>    "The base location of the archive to which packages are uploaded.
> +The commands in the package-x library will use this as base
> +location.
>  This should be an absolute directory name.  If the archive is on
>  another machine, you may specify a remote name in the usual way,
>  e.g. \"/ssh:foo <at> example.com:/var/www/packages/\".
> @@ -273,7 +275,9 @@ package-upload-buffer-internal
>  (defun package-upload-buffer ()
>    "Upload the current buffer as a single-file Emacs Lisp package.
>  If `package-archive-upload-base' does not specify a valid upload
> -destination, prompt for one."
> +destination, prompt for one.
> +Signal an error if the current buffer is not visiting a simple
> +package (a \".el\" file)."
>    (interactive)
>    (save-excursion
>      (save-restriction
> @@ -286,8 +290,13 @@ package-upload-file
>  Interactively, prompt for FILE.  The package is considered a
>  single-file package if FILE ends in \".el\", and a multi-file
>  package if FILE ends in \".tar\".
> +Automatically extract package attributes and update the archive's
> +contents list with this information.
>  If `package-archive-upload-base' does not specify a valid upload
> -destination, prompt for one."
> +destination, prompt for one.  If the directory does not exist, it
> +is created.  The directory need not have any initial contents
> +\(i.e., you can use this command to populate an initially empty
> +archive)."
>    (interactive "fPackage file name: ")
>    (with-temp-buffer
>      (insert-file-contents file)

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

From: Noam Postavsky <npostavs <at> gmail.com>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: Kelly Dean <kelly <at> prtime.org>, Stefan Monnier <monnier <at> iro.umontreal.ca>,
 19537 <at> debbugs.gnu.org
Subject: Re: bug#19537: Manual documents nonexistent functionality of
 package-upload-buffer
Date: Thu, 25 Jul 2019 18:37:01 -0400

tags 19537 fixed
close 19537 26.3
quit

Stefan Kangas <stefan <at> marxist.se> writes:

> OK, I took a stab at removing it from the manual and added the
> information it contained to the doc strings of the relevant functions
> instead.  Please see attached patch -- WDYT?

Pushed to emacs-26.

16a529e215 2019-07-25T18:23:55-04:00 "Remove upload functionality of package-x from the elisp manual"
https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=16a529e215331626f66160194701b74248cb9fa5

Previous Next

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