From 086a56ed43de17015a14a4f1e799d258a789440a Mon Sep 17 00:00:00 2001 From: "Basil L. Contovounesios" Date: Mon, 22 Jul 2019 21:14:18 +0100 Subject: Clarify Gravatar docs For discussion, see the following thread: https://lists.gnu.org/archive/html/emacs-devel/2019-07/msg00528.html * doc/misc/gnus.texi (X-Face): Fix cross-reference. (Gravatars): * lisp/gnus/gnus-gravatar.el (gnus-gravatar-too-ugly): * lisp/image/gravatar.el (gravatar-cache-ttl, gravatar-rating) (gravatar-size): Clarify user option descriptions. (gravatar-retrieve, gravatar-retrieve-synchronously): Document return value. --- lisp/gnus/gnus-gravatar.el | 3 ++- lisp/image/gravatar.el | 35 ++++++++++++++++++++++++++++------- 2 files changed, 30 insertions(+), 8 deletions(-) (limited to 'lisp') diff --git a/lisp/gnus/gnus-gravatar.el b/lisp/gnus/gnus-gravatar.el index d271a52f908..19cbf529c65 100644 --- a/lisp/gnus/gnus-gravatar.el +++ b/lisp/gnus/gnus-gravatar.el @@ -46,7 +46,8 @@ If nil, default to `gravatar-size'." :group 'gnus-gravatar) (defcustom gnus-gravatar-too-ugly gnus-article-x-face-too-ugly - "Regexp matching posters whose avatar shouldn't be shown automatically." + "Regexp matching posters whose avatar shouldn't be shown automatically. +If nil, show all avatars." :type '(choice regexp (const nil)) :version "24.1" :group 'gnus-gravatar) diff --git a/lisp/image/gravatar.el b/lisp/image/gravatar.el index 2b106ba0675..76c1ac1644d 100644 --- a/lisp/image/gravatar.el +++ b/lisp/image/gravatar.el @@ -40,18 +40,35 @@ ;; FIXME a time value is not the nicest format for a custom variable. (defcustom gravatar-cache-ttl (days-to-time 30) - "Time to live for gravatar cache entries." + "Time to live for gravatar cache entries. +If a requested gravatar has been cached for longer than this, it +is retrieved anew." :type '(repeat integer) :group 'gravatar) -;; FIXME Doc is tautological. What are the options? (defcustom gravatar-rating "g" - "Default rating for gravatar." + "Most explicit Gravatar rating level to allow. +Some gravatars are rated according to how suitable they are for +different audiences. The supported rating levels are, in order +of increasing explicitness, the following: + +\"g\" - Suitable for any audience. +\"pg\" - May contain rude gestures, provocatively dressed + individuals, mild profanity, or mild violence. +\"r\" - May contain harsh profanity, intense violence, nudity, + or hard drug use. +\"x\" - May contain hardcore sexual imagery or extremely + disturbing violence. + +Each level covers itself as well as all less explicit levels. +For example, setting this variable to \"pg\" will allow gravatars +rated either \"g\" or \"pg\"." :type 'string :group 'gravatar) (defcustom gravatar-size 32 - "Default size in pixels for gravatars." + "Gravatar size in pixels to request. +Valid sizes range from 1 to 2048 inclusive." :type 'integer :group 'gravatar) @@ -104,8 +121,10 @@ If no image available, return 'error." ;;;###autoload (defun gravatar-retrieve (mail-address cb &optional cbargs) - "Retrieve MAIL-ADDRESS gravatar and call CB on retrieval. -You can provide a list of argument to pass to CB in CBARGS." + "Asynchronously retrieve a gravatar for MAIL-ADDRESS. +When finished, call CB as (apply CB GRAVATAR CBARGS), +where GRAVATAR is either an image descriptor, or the symbol +`error' if the retrieval failed." (let ((url (gravatar-build-url mail-address))) (if (gravatar-cache-expired url) (let ((args (list url @@ -126,7 +145,9 @@ You can provide a list of argument to pass to CB in CBARGS." ;;;###autoload (defun gravatar-retrieve-synchronously (mail-address) - "Retrieve MAIL-ADDRESS gravatar and returns it." + "Synchronously retrieve a gravatar for MAIL-ADDRESS. +Value is either an image descriptor, or the symbol `error' if the +retrieval failed." (let ((url (gravatar-build-url mail-address))) (if (gravatar-cache-expired url) (with-current-buffer (url-retrieve-synchronously url) -- cgit v1.2.3 From 16a529e215331626f66160194701b74248cb9fa5 Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Sun, 14 Jul 2019 05:59:46 +0200 Subject: 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(-) (limited to 'lisp') diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi index 39bdc01a75c..8729f02bc82 100644 --- a/doc/lispref/package.texi +++ b/doc/lispref/package.texi @@ -307,41 +307,6 @@ How to accomplish this is beyond the scope of this manual. 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 a207ece885f..9e63dce6d7b 100644 --- a/lisp/emacs-lisp/package-x.el +++ b/lisp/emacs-lisp/package-x.el @@ -47,6 +47,8 @@ (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 @@ if it exists." (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 @@ destination, prompt for one." 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) -- cgit v1.2.3 From 7f42277b96130861967de3936defb0ef5bf07fbb Mon Sep 17 00:00:00 2001 From: Noam Postavsky Date: Wed, 24 Jul 2019 22:02:59 -0400 Subject: Mention term.el's \032 dir tracking in commentary (Bug#19524) * lisp/term.el: Mention both forms of directory tracking in commentary. Remove obsolete ChangeLog comments. Move more relevant summary comments to the top. --- lisp/term.el | 143 ++++++++++++++++++++++------------------------------------- 1 file changed, 52 insertions(+), 91 deletions(-) (limited to 'lisp') diff --git a/lisp/term.el b/lisp/term.el index 9785ce30249..fb624e4b7a8 100644 --- a/lisp/term.el +++ b/lisp/term.el @@ -33,6 +33,21 @@ ;;; Commentary: +;; This file defines a general command-interpreter-in-a-buffer package +;; (term mode). The idea is that you can build specific process-in-a-buffer +;; modes on top of term mode -- e.g., lisp, shell, scheme, T, soar, .... +;; This way, all these specific packages share a common base functionality, +;; and a common set of bindings, which makes them easier to use (and +;; saves code, implementation time, etc., etc.). + +;; If, instead of `term', you call `ansi-term', you get multiple term +;; buffers, after every new call ansi-term opens a new +;; "*ansi-term*" window, where is, as usual, a number... + +;; For hints on converting existing process modes (e.g., tex-mode, +;; background, dbx, gdb, kermit, prolog, telnet) to use term-mode +;; instead of shell-mode, see the notes at the end of this file. + ;; Speed considerations and a few caveats ;; -------------------------------------- ;; @@ -85,13 +100,6 @@ ;; # By default nobody can't do anything ;; deny root * ;; -;; -;; ---------------------------------------- -;; -;; If, instead of 'term', you call 'ansi-term', you get multiple term -;; buffers, after every new call ansi-term opens a new *ansi-term* window, -;; where is, as usual, a number... -;; ;; ---------------------------------------- ;; ;; With the term-buffer-maximum-size you can finally decide how many @@ -100,7 +108,6 @@ ;; ;; ---------------------------------------- ;; -;; ;; ANSI colorization should work well, I've decided to limit the interpreter ;; to five outstanding commands (like ESC [ 01;04;32;41;07m. ;; You shouldn't need more, if you do, tell me and I'll increase it. It's @@ -115,38 +122,6 @@ ;; - Add hooks to allow raw-mode keys to be configurable ;; - Which keys are better ? \eOA or \e[A ? ;; -;; -;; Changes: -;; -;; V4.0 January 1997 -;; -;; - Huge reworking of the faces code: now we only have roughly 20-30 -;; faces for everything so we're even faster than the old md-term.el ! -;; - Finished removing all the J-Shell code. -;; -;; V3.0 January 1997 -;; -;; - Now all the supportable ANSI commands work well. -;; - Reworked a little the code: much less jsh-inspired stuff -;; -;; V2.3 November -;; -;; - Now all the faces are accessed through an array: much cleaner code. -;; -;; V2.2 November 4 1996 -;; -;; - Implemented ANSI output colorization ( a bit rough but enough for -;; color_ls ) -;; -;; - Implemented a maximum limit for the scroll buffer (stolen from -;; comint.el) -;; -;; v2.1 October 28 1996, first public release -;; -;; - Some new keybindings for term-char mode ( notably home/end/...) -;; - Directory, hostname and username tracking via ange-ftp -;; - Multi-term capability via the ansi-term call -;; ;; ---------------------------------------------------------------- ;; You should/could have something like this in your .emacs to take ;; full advantage of this package @@ -160,7 +135,6 @@ ;; (auto-fill-mode -1) ;; (setq tab-width 8 )))) ;; -;; ;; ---------------------------------------- ;; ;; If you want to use color ls the best setup is to have a different file @@ -171,7 +145,6 @@ ;; ;; ---------------------------------------- ;; -;; ;; # Configuration file for the color ls utility ;; # This file goes in the /etc directory, and must be world readable. ;; # You can copy this file to .dir_colors in your $HOME directory to @@ -228,17 +201,23 @@ ;; .xbm 01;35 ;; .xpm 01;35 ;; -;; ;; ---------------------------------------- ;; -;; Notice: for directory/host/user tracking you need to have something -;; like this in your shell startup script (this is for a POSIXish shell -;; like Bash but should be quite easy to port to other shells). +;; There are actually two methods for directory tracking, one +;; implemented in `term-command-hook' which sets the directory +;; according to an escape sequence of the form "\032\n". +;; Some shells like bash will already send this escape sequence when +;; they detect they are running in Emacs. This can be configured or +;; disabled on the Emacs side by setting `term-command-hook' to +;; a different function. ;; -;; For troubleshooting in Bash, you can check the definition of the -;; custom functions with the "type" command. e.g. "type cd". If you -;; do not see the expected definition from the config below, then the -;; directory tracking will not work. +;; The second method is in `term-handle-ansi-terminal-messages' which +;; sets user, host, and directory according to escape sequences of the +;; form "\033AnSiTc \n" (replace the "c" with "u" and "h" +;; for user and host, respectively). If the user and host don't +;; match, it will set directory to a remote one, so it is important to +;; set user and host correctly first. See the example bash +;; configuration below. ;; ;; ---------------------------------------- ;; @@ -262,42 +241,24 @@ ;; ;; # The \033 stands for ESC. ;; # There is a space between "AnSiT?" and $whatever. +;; printf '\033AnSiTh %s\n' "$HOSTNAME" +;; printf '\033AnSiTu %s\n' "$USER" +;; printf '\033AnSiTc %s\n' "$PWD" ;; ;; cd() { command cd "$@"; printf '\033AnSiTc %s\n' "$PWD"; } ;; pushd() { command pushd "$@"; printf '\033AnSiTc %s\n' "$PWD"; } ;; popd() { command popd "$@"; printf '\033AnSiTc %s\n' "$PWD"; } ;; -;; printf '\033AnSiTc %s\n' "$PWD" -;; printf '\033AnSiTh %s\n' "$HOSTNAME" -;; printf '\033AnSiTu %s\n' "$USER" -;; ;; # Use custom dircolors in term buffers. ;; # eval $(dircolors $HOME/.emacs_dircolors) ;; esac ;; ;; # ... ;; -;; - -;;; Original Commentary: -;; --------------------- - -;; The changelog is at the end of this file. - -;; Please send me bug reports, bug fixes, and extensions, so that I can -;; merge them into the master source. -;; - Per Bothner (bothner@cygnus.com) - -;; This file defines a general command-interpreter-in-a-buffer package -;; (term mode). The idea is that you can build specific process-in-a-buffer -;; modes on top of term mode -- e.g., lisp, shell, scheme, T, soar, .... -;; This way, all these specific packages share a common base functionality, -;; and a common set of bindings, which makes them easier to use (and -;; saves code, implementation time, etc., etc.). - -;; For hints on converting existing process modes (e.g., tex-mode, -;; background, dbx, gdb, kermit, prolog, telnet) to use term-mode -;; instead of shell-mode, see the notes at the end of this file. +;; For troubleshooting in Bash, you can check the definition of the +;; custom functions with the "type" command. e.g. "type cd". If you +;; do not see the expected definition from the config below, then the +;; directory tracking will not work. ;; Brief Command Documentation: @@ -305,21 +266,21 @@ ;; Term Mode Commands: (common to all derived modes, like cmushell & cmulisp ;; mode) ;; -;; m-p term-previous-input Cycle backwards in input history -;; m-n term-next-input Cycle forwards -;; m-r term-previous-matching-input Previous input matching a regexp -;; m-s comint-next-matching-input Next input that matches +;; M-p term-previous-input Cycle backwards in input history +;; M-n term-next-input Cycle forwards +;; M-r term-previous-matching-input Previous input matching a regexp +;; M-s comint-next-matching-input Next input that matches ;; return term-send-input -;; c-c c-a term-bol Beginning of line; skip prompt. -;; c-d term-delchar-or-maybe-eof Delete char unless at end of buff. -;; c-c c-u term-kill-input ^u -;; c-c c-w backward-kill-word ^w -;; c-c c-c term-interrupt-subjob ^c -;; c-c c-z term-stop-subjob ^z -;; c-c c-\ term-quit-subjob ^\ -;; c-c c-o term-kill-output Delete last batch of process output -;; c-c c-r term-show-output Show last batch of process output -;; c-c c-h term-dynamic-list-input-ring List input history +;; C-c C-a term-bol Beginning of line; skip prompt. +;; C-d term-delchar-or-maybe-eof Delete char unless at end of buff. +;; C-c C-u term-kill-input ^u +;; C-c C-w backward-kill-word ^w +;; C-c C-c term-interrupt-subjob ^c +;; C-c C-z term-stop-subjob ^z +;; C-c C-\ term-quit-subjob ^\ +;; C-c C-o term-kill-output Delete last batch of process output +;; C-c C-r term-show-output Show last batch of process output +;; C-c C-h term-dynamic-list-input-ring List input history ;; ;; Not bound by default in term-mode ;; term-send-invisible Read a line w/o echo, and send to proc @@ -329,8 +290,8 @@ ;; term-replace-by-expanded-filename Expand and complete filename at point; ;; replace with expanded/completed name. ;; term-kill-subjob No mercy. -;; term-show-maximum-output Show as much output as possible. -;; term-continue-subjob Send CONT signal to buffer's process +;; term-show-maximum-output Show as much output as possible. +;; term-continue-subjob Send CONT signal to buffer's process ;; group. Useful if you accidentally ;; suspend your process (with C-c C-z). -- cgit v1.2.3 From d6ca1fc531ce6e6abbbe273187420ee5cc8c8b26 Mon Sep 17 00:00:00 2001 From: Noam Postavsky Date: Thu, 25 Jul 2019 22:51:28 -0400 Subject: ; * lisp/term.el: Add missing / to esc seq commentary. --- lisp/term.el | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'lisp') diff --git a/lisp/term.el b/lisp/term.el index fb624e4b7a8..5ace5e341d0 100644 --- a/lisp/term.el +++ b/lisp/term.el @@ -205,7 +205,7 @@ ;; ;; There are actually two methods for directory tracking, one ;; implemented in `term-command-hook' which sets the directory -;; according to an escape sequence of the form "\032\n". +;; according to an escape sequence of the form "\032/\n". ;; Some shells like bash will already send this escape sequence when ;; they detect they are running in Emacs. This can be configured or ;; disabled on the Emacs side by setting `term-command-hook' to -- cgit v1.2.3 From d4c49875eaae3078ea3b51cc7b72ae3403cb2c04 Mon Sep 17 00:00:00 2001 From: Tino Calancha Date: Fri, 26 Jul 2019 17:18:19 +0200 Subject: Update view-mode docstring Not all the kill commands save the text in the kill ring by default (e.g. `kill-rectangle'). It is more precise to just say that the kill commands save the text and do not change the buffer (Bug#36741). * lisp/view.el (view-mode): Update docstring. --- lisp/view.el | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'lisp') diff --git a/lisp/view.el b/lisp/view.el index 3d423f17480..5e6f3e2caa9 100644 --- a/lisp/view.el +++ b/lisp/view.el @@ -386,8 +386,8 @@ and disable it otherwise. If called from Lisp, enable View mode if ARG is omitted or nil. When View mode is enabled, commands that do not change the buffer -contents are available as usual. Kill commands insert text in -kill buffers but do not delete. Most other commands beep and +contents are available as usual. Kill commands save text but +do not delete it from the buffer. Most other commands beep and tell the user that the buffer is read-only. \\ -- cgit v1.2.3 From 304e96f50d49e142edd8ec1b1c7d9fb1ce9a7385 Mon Sep 17 00:00:00 2001 From: Martin Rudalics Date: Tue, 30 Jul 2019 09:23:22 +0200 Subject: Fix doc-string of 'fit-window-to-buffer' (Bug#36848) * lisp/window.el (fit-window-to-buffer): Fix doc-string. Suggested by Drew Adams --- lisp/window.el | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'lisp') diff --git a/lisp/window.el b/lisp/window.el index de110111b5a..a86c2f96bdc 100644 --- a/lisp/window.el +++ b/lisp/window.el @@ -8285,7 +8285,7 @@ and defaults to `window-min-width'. Both MAX-WIDTH and MIN-WIDTH are specified in columns and include fringes, margins, a scrollbar and a vertical divider, if any. -If the optional argument `preserve-size' is non-nil, preserve the +Optional argument PRESERVE-SIZE non-nil means to preserve the size of WINDOW (see `window-preserve-size'). Fit pixelwise if the option `window-resize-pixelwise' is non-nil. -- cgit v1.2.3