[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] emacs-26 086a56e: Clarify Gravatar docs
From: |
Basil L. Contovounesios |
Subject: |
[Emacs-diffs] emacs-26 086a56e: Clarify Gravatar docs |
Date: |
Tue, 23 Jul 2019 04:33:23 -0400 (EDT) |
branch: emacs-26
commit 086a56ed43de17015a14a4f1e799d258a789440a
Author: Basil L. Contovounesios <address@hidden>
Commit: Basil L. Contovounesios <address@hidden>
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 ee504f5..f045884 100644
--- a/doc/misc/gnus.texi
+++ b/doc/misc/gnus.texi
@@ -23441,11 +23441,11 @@ XEmacs. Here are examples:
(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
+@xref{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
@samp{libcompface} library.
@end table
@@ -23716,21 +23716,25 @@ The following variables offer control over how things
are displayed.
@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 d271a52..19cbf52 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 2b106ba..76c1ac1 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)
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] emacs-26 086a56e: Clarify Gravatar docs,
Basil L. Contovounesios <=