From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.devel Subject: RE: doc string for face-attribute-relative-p doesn't help Date: Mon, 26 Jun 2006 20:33:03 -0700 Message-ID: References: NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1151379207 31492 80.91.229.2 (27 Jun 2006 03:33:27 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Tue, 27 Jun 2006 03:33:27 +0000 (UTC) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Jun 27 05:33:24 2006 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1Fv4KI-0002Ll-N6 for ged-emacs-devel@m.gmane.org; Tue, 27 Jun 2006 05:33:23 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Fv4KI-0004hv-3f for ged-emacs-devel@m.gmane.org; Mon, 26 Jun 2006 23:33:22 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1Fv4K5-0004hq-Nt for emacs-devel@gnu.org; Mon, 26 Jun 2006 23:33:09 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1Fv4K1-0004fM-Qc for emacs-devel@gnu.org; Mon, 26 Jun 2006 23:33:08 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Fv4K1-0004fJ-O3 for emacs-devel@gnu.org; Mon, 26 Jun 2006 23:33:05 -0400 Original-Received: from [148.87.113.118] (helo=rgminet01.oracle.com) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_3DES_EDE_CBC_SHA:24) (Exim 4.52) id 1Fv4W2-0004yh-Fs for emacs-devel@gnu.org; Mon, 26 Jun 2006 23:45:30 -0400 Original-Received: from rgmsgw301.us.oracle.com (rgmsgw301.us.oracle.com [138.1.186.50]) by rgminet01.oracle.com (Switch-3.1.6/Switch-3.1.6) with ESMTP id k5R3X3uT012722 for ; Mon, 26 Jun 2006 21:33:03 -0600 Original-Received: from dradamslap (dhcp-amer-whq-csvpn-gw3-141-144-80-242.vpn.oracle.com [141.144.80.242]) by rgmsgw301.us.oracle.com (Switch-3.1.7/Switch-3.1.7) with SMTP id k5R3X2cZ019952 (version=TLSv1/SSLv3 cipher=RC4-MD5 bits=128 verify=NO) for ; Mon, 26 Jun 2006 21:33:02 -0600 Original-To: X-Priority: 3 (Normal) X-MSMail-Priority: Normal X-Mailer: Microsoft Outlook IMO, Build 9.0.6604 (9.0.2911.0) In-reply-to: X-MIMEOLE: Produced By Microsoft MimeOLE V6.00.2800.1807 Importance: Normal X-Brightmail-Tracker: AAAAAQAAAAI= X-Brightmail-Tracker: AAAAAQAAAAI= X-Whitelist: TRUE X-Whitelist: TRUE X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:56212 Archived-At: > I don't think so. It isn't clear to me, even after reading it > a couple of times. It seems to me that the real problem is a lack of knowledge about how face rendering in general works. This should be solved by having a good overview of face rendering in the manual (I don't know if there is one or not), not by trying to shove that information in every function docstring that's somehow related to faces. Yes, such an explanation in the manual is probably needed - that's what I was trying to suggest. Whether it should take the form of a new, separate section or just cleanup of existing text, I don't know. If a new section is added, the existing text should still be cleaned up so that it makes more sense (possibly cross-referencing the new section, to help). I agree, too, that each function's doc string need not try to explain everything. If the doc defines the terms it uses (e.g. "underlying", "relative") and explains them clearly, then that lessens the burden of explanation for doc strings.