>From 8445814d560b2ecbd7423c41b6fb492772a6a98f Mon Sep 17 00:00:00 2001 From: "Basil L. Contovounesios" Date: Mon, 22 Jul 2019 21:14:18 +0100 Subject: [PATCH 1/5] 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. --- doc/misc/gnus.texi | 26 +++++++++++++++----------- lisp/gnus/gnus-gravatar.el | 3 ++- lisp/image/gravatar.el | 35 ++++++++++++++++++++++++++++------- 3 files changed, 45 insertions(+), 19 deletions(-) diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi index f688e84e7e..07c81c49c4 100644 --- a/doc/misc/gnus.texi +++ b/doc/misc/gnus.texi @@ -23505,11 +23505,11 @@ X-Face (png . (:relief -2)))) @end lisp -@pxref{Image Descriptors, ,Image Descriptors, elisp, The Emacs Lisp -Reference Manual} for the valid properties for various image types. -Currently, @code{pbm} is used for X-Face images and @code{png} is used -for Face images in Emacs. Only the @code{:face} property is effective -on the @code{xface} image type in XEmacs if it is built with the +For the valid properties of various image types, @pxref{Image +Descriptors,,, elisp, The Emacs Lisp Reference Manual}. Currently, +@code{pbm} is used for X-Face images and @code{png} is used for Face +images in Emacs. Only the @code{:face} property is effective on the +@code{xface} image type in XEmacs if it is built with the @samp{libcompface} library. @end table @@ -23780,21 +23780,25 @@ Gravatars @item gnus-gravatar-size @vindex gnus-gravatar-size The size in pixels of gravatars. Gravatars are always square, so one -number for the size is enough. +number for the size is enough. If @code{nil}, this defaults to the +value of @code{gravatar-size}. @item gnus-gravatar-properties @vindex gnus-gravatar-properties -List of image properties applied to Gravatar images. +List of image properties applied to Gravatar images (@pxref{Image +Descriptors,,, elisp, The Emacs Lisp Reference Manual}). @item gnus-gravatar-too-ugly @vindex gnus-gravatar-too-ugly -Regexp that matches mail addresses or names of people of which avatars -should not be displayed, or @code{nil}. It default to the value of -@code{gnus-article-x-face-too-ugly} (@pxref{X-Face}). +Regexp that matches mail addresses or names of people whose avatars +should not be displayed, or @code{nil} to display all avatars. It +defaults to the value of @code{gnus-article-x-face-too-ugly} +(@pxref{X-Face}). @end table -If you want to see them in the From field, set: +If you want to see gravatars in the From field, set: + @lisp (setq gnus-treat-from-gravatar 'head) @end lisp diff --git a/lisp/gnus/gnus-gravatar.el b/lisp/gnus/gnus-gravatar.el index d271a52f90..19cbf529c6 100644 --- a/lisp/gnus/gnus-gravatar.el +++ b/lisp/gnus/gnus-gravatar.el @@ -46,7 +46,8 @@ gnus-gravatar-properties :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 91da840e3a..9a1ec3b556 100644 --- a/lisp/image/gravatar.el +++ b/lisp/image/gravatar.el @@ -40,18 +40,35 @@ gravatar-automatic-caching ;; 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) @@ -100,8 +117,10 @@ gravatar-data->image ;;;###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 @@ -120,7 +139,9 @@ gravatar-retrieve ;;;###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) -- 2.20.1