From: Stefan Monnier <monnier@iro.umontreal.ca>
To: Stefan Kangas <stefan@marxist.se>
Cc: Kelly Dean <kelly@prtime.org>, 19537@debbugs.gnu.org
Subject: bug#19537: Manual documents nonexistent functionality of package-upload-buffer
Date: Mon, 15 Jul 2019 08:50:43 -0400 [thread overview]
Message-ID: <jwv36j7qx5y.fsf-monnier+emacs@gnu.org> (raw)
In-Reply-To: <CADwFkm=nb=kiy9=QNMq5ZYauE7Hw+2v3WptT2D_cu-MPS+36jA@mail.gmail.com> (Stefan Kangas's message of "Sun, 14 Jul 2019 06:21:21 +0200")
LGTM, thanks,
Stefan
Stefan Kangas [2019-07-14 06:21:21] wrote:
> tags 19537 + patch
> thanks
>
> Kelly Dean <kelly@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@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@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@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)
next prev parent reply other threads:[~2019-07-15 12:50 UTC|newest]
Thread overview: 5+ messages / expand[flat|nested] mbox.gz Atom feed top
2015-01-08 3:40 bug#19537: Manual documents nonexistent functionality of package-upload-buffer Kelly Dean
2015-01-08 14:31 ` Stefan Monnier
2019-07-14 4:21 ` Stefan Kangas
2019-07-15 12:50 ` Stefan Monnier [this message]
2019-07-25 22:37 ` Noam Postavsky
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=jwv36j7qx5y.fsf-monnier+emacs@gnu.org \
--to=monnier@iro.umontreal.ca \
--cc=19537@debbugs.gnu.org \
--cc=kelly@prtime.org \
--cc=stefan@marxist.se \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.