GNU bug report logs - #60168
28.2; Doc string of `face-spec-recalc'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 60168 in the body.
You can then email your comments to 60168 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: "bug-gnu-emacs <at> gnu.org" <bug-gnu-emacs <at> gnu.org>
Subject: 28.2; Doc string of `face-spec-recalc'
Date: Sat, 17 Dec 2022 20:57:48 +0000

I don't understand this doc string.

What is the meaning of the indented occurrences of `|'?

How is one supposed to read this?  Are there 3 sources?  5 sources? 6
sources?

Is `|' supposed to separate the sources (so there are only 3)?  If so,
how to understand the one that starts with `(theme...)' and ends with
`(X resources...)'?

Why are some things - which clearly are NOT code - in parens?  Of what
use are the parens here?  Why `(defface default spec)' (parens) but
`defface override spec' (no parens)?

And lest someone claim that this is just a "helper" function or
"internal": this is the meat of what `face-spec-set' does.  If this
isn't described here then it should be described for `face-spec-set'.
(And in any case, the doc string here needs to be fixed or removed.)

In GNU Emacs 28.2 (build 2, x86_64-w64-mingw32)
 of 2022-09-13 built on AVALON
Windowing system distributor 'Microsoft Corp.', version 10.0.19044
System Description: Microsoft Windows 10 Pro (v10.0.2009.19044.2251)

Configured using:
 'configure --with-modules --without-dbus --with-native-compilation
 --without-compress-install CFLAGS=-O2'

Configured features:
ACL GIF GMP GNUTLS HARFBUZZ JPEG JSON LCMS2 LIBXML2 MODULES NATIVE_COMP
NOTIFY W32NOTIFY PDUMPER PNG RSVG SOUND THREADS TIFF TOOLKIT_SCROLL_BARS
XPM ZLIB

(NATIVE_COMP present but libgccjit not available)

Message #8 received at 60168 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 60168 <at> debbugs.gnu.org
Subject: Re: bug#60168: 28.2; Doc string of `face-spec-recalc'
Date: Sun, 18 Dec 2022 11:01:12 +0200

tags 60168 notabug wontfix
close 60168
thanks

> From: Drew Adams <drew.adams <at> oracle.com>
> Date: Sat, 17 Dec 2022 20:57:48 +0000
> 
> I don't understand this doc string.

You aren't supposed to, unless you are hacking on the face-related
code (in which case the doc string is crystal clear).

> And lest someone claim that this is just a "helper" function or
> "internal": this is the meat of what `face-spec-set' does.  If this
> isn't described here then it should be described for `face-spec-set'.

face-spec-set has its own doc string that explains what it does.  Its
doc string doesn't reference face-spec-recalc.  The "meat" you mention
is basically internal implementation details of how face spec is
calculated and applied, something that doesn't belong to doc strings.

If you have specific questions needed to understand how to define and
use faces in Lisp programs, please ask those specific questions
(probably in another thread).  Or if you have specific questions
regarding the face implementation and face spec (re-)calculation,
please ask specific questions on emacs-devel.

> (And in any case, the doc string here needs to be fixed or removed.)

I disagree.

There's no bug here that I can see.

Closing.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.