Commit 086a56ed authored by Basil L. Contovounesios's avatar Basil L. Contovounesios

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.
parent 05924677
Pipeline #2531 passed with stage
in 26 minutes and 38 seconds
......@@ -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
......@@ -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)
......
......@@ -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)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment