bug#24879: [PATCH] Point out the default value of FRAME in the `set-face-*' functions.

bug#24879: [PATCH] Point out the default value of FRAME in the `set-face-*' functions.

[Hong Xu]

---

Feel free to make changes.

 doc/lispref/ChangeLog.1  | 5 +++++
 doc/lispref/display.texi | 4 ++--
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/doc/lispref/ChangeLog.1 b/doc/lispref/ChangeLog.1
index 610e7541e7de..e492a607368d 100644
--- a/doc/lispref/ChangeLog.1
+++ b/doc/lispref/ChangeLog.1
@@ -1,3 +1,8 @@
+2016-11-04  Hong Xu  <hong@topbug.net>
+
+	* display.texi (Attribute Functions): Point out the default value
+	of FRAME in the various `set-face-*` functions.
+
 2015-03-29  Glenn Morris  <rgm@gnu.org>
 
 	* objects.texi (Equality Predicates): Fix typo in example.
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 2e316f8a532c..b19bfa9ef5c2 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2644,8 +2644,8 @@ Attribute Functions
 
   The following commands and functions mostly provide compatibility
 with old versions of Emacs.  They work by calling
-@code{set-face-attribute}.  Values of @code{t} and @code{nil} for
-their @var{frame} argument are handled just like
+@code{set-face-attribute}.  Values of @code{t} and @code{nil}
+(default) for their @var{frame} argument are handled just like
 @code{set-face-attribute} and @code{face-attribute}.  The commands
 read their arguments using the minibuffer, if called interactively.
 

bug#24879: [PATCH] Point out the default value of FRAME in the `set-face-*' functions.

[Eli Zaretskii]

> From: Hong Xu <hong@topbug.net>
> Date: Fri,  4 Nov 2016 13:29:10 -0700
> 
>    The following commands and functions mostly provide compatibility
>  with old versions of Emacs.  They work by calling
> -@code{set-face-attribute}.  Values of @code{t} and @code{nil} for
> -their @var{frame} argument are handled just like
> +@code{set-face-attribute}.  Values of @code{t} and @code{nil}
> +(default) for their @var{frame} argument are handled just like
>  @code{set-face-attribute} and @code{face-attribute}.  The commands
>  read their arguments using the minibuffer, if called interactively.

Do we really need to tell people that an omitted argument defaults to
nil?  And if we do, why in this section?

Thanks.

bug#24879: [PATCH] Point out the default value of FRAME in the `set-face-*' functions.

[Hong Xu]

[-- Attachment #1: Type: text/plain, Size: 575 bytes --]


On 2016-11-04 Fri 14:31 GMT-0700, Eli Zaretskii <eliz@gnu.org> wrote:

> Do we really need to tell people that an omitted argument defaults to
> nil?  And if we do, why in this section?

Hmm, I didn't notice that we don't say optional args are default to nil
in the doc. Never mind, we should close this bug.

Despite that, I sort of see some confusion in the doc when mentioning
optional args: Sometimes we say "omitted or nil" (e.g.,
face-all-attributes FRAME arg), sometimes we just say "nil" (e.g.,
face-attribute FRAME arg). Perhaps more consistency is less confusing.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 818 bytes --]

bug#24879: [PATCH] Point out the default value of FRAME in the `set-face-*' functions.

[Eli Zaretskii]

> From: Hong Xu <hong@topbug.net>
> Cc: 24879@debbugs.gnu.org
> Date: Sat, 05 Nov 2016 01:17:38 -0700
> 
> Despite that, I sort of see some confusion in the doc when mentioning
> optional args: Sometimes we say "omitted or nil" (e.g.,
> face-all-attributes FRAME arg), sometimes we just say "nil" (e.g.,
> face-attribute FRAME arg). Perhaps more consistency is less confusing.

Thanks, I made sure we mention this consistently in that node.