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: how to retrieve doc string for a face... Date: Sat, 19 Nov 2005 23:53:14 -0800 Message-ID: NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1132473721 3696 80.91.229.2 (20 Nov 2005 08:02:01 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sun, 20 Nov 2005 08:02:01 +0000 (UTC) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Nov 20 09:01:55 2005 Return-path: Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1Edk8G-0006uv-H6 for ged-emacs-devel@m.gmane.org; Sun, 20 Nov 2005 09:01:04 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Edk8F-0006EB-Ev for ged-emacs-devel@m.gmane.org; Sun, 20 Nov 2005 03:01:03 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1Edk10-0002vi-ON for emacs-devel@gnu.org; Sun, 20 Nov 2005 02:53:35 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1Edk0r-0002sO-7Z for emacs-devel@gnu.org; Sun, 20 Nov 2005 02:53:32 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Edk0m-0002qx-5O for emacs-devel@gnu.org; Sun, 20 Nov 2005 02:53:21 -0500 Original-Received: from [141.146.126.228] (helo=agminet01.oracle.com) by monty-python.gnu.org with esmtp (TLS-1.0:DHE_RSA_3DES_EDE_CBC_SHA:24) (Exim 4.34) id 1Edk0m-0001pR-Ae for emacs-devel@gnu.org; Sun, 20 Nov 2005 02:53:20 -0500 Original-Received: from rgmsgw300.us.oracle.com (rgmsgw300.us.oracle.com [138.1.186.49]) by agminet01.oracle.com (Switch-3.1.7/Switch-3.1.7) with ESMTP id jAK86bCE027662 for ; Sun, 20 Nov 2005 02:06:37 -0600 Original-Received: from rgmsgw300.us.oracle.com (localhost [127.0.0.1]) by rgmsgw300.us.oracle.com (Switch-3.1.7/Switch-3.1.7) with ESMTP id jAK7rIMf019868 for ; Sun, 20 Nov 2005 00:53:18 -0700 Original-Received: from dradamslap (dhcp-amer-csvpn-gw2-141-144-73-49.vpn.oracle.com [141.144.73.49]) by rgmsgw300.us.oracle.com (Switch-3.1.7/Switch-3.1.7) with SMTP id jAK7rHl8019861 (version=TLSv1/SSLv3 cipher=RC4-MD5 bits=128 verify=NO) for ; Sun, 20 Nov 2005 00:53:17 -0700 Original-To: "Emacs-Devel" X-Priority: 3 (Normal) X-MSMail-Priority: Normal X-Mailer: Microsoft Outlook IMO, Build 9.0.6604 (9.0.2911.0) Importance: Normal X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2800.1506 X-Brightmail-Tracker: AAAAAQAAAAI= 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:46326 Archived-At: Info node (elisp) Accessing Documentation says this: "In Emacs Lisp, a documentation string is accessible through the function or variable that it describes:" And then it speaks of using functions `documentation' and `documentation-property'. It says nothing about retrieving the doc string supplied with `defface' or `defgroup' or `defmacro' or .... 1. How are those doc strings retrieved? (e.g. `face-documentation') 2. Shouldn't that retrieval be documented too? 3. Info mentions the `function-documentation' property, in parallel with the `variable-documentation' property. Is there no equivalent shortcut to `documentation-property' for retrieving the doc string of a keyboard macro, so that you must use `get'? Similarly, for properties `face-documentation', `group-documentation', etc. (which are not even mentioned). This business of retrieving doc strings doesn't seem very homogeneous - it seems ad hoc. Shouldn't there be a simple, single way to get the doc string(s) of an object? If the same symbol has multiple doc strings, then that simple function would need to let you specify which one(s) you want - by taking, for instance, a TYPE argument, which could be a symbol such as `face' or a list of such symbols. In the latter case, it would return the list (same order) of doc strings. nil would be used to indicate that there is no doc string of the given type. I may not understand the design well, so that the above suggestion is not appropriate, but I think that the manual, at least, should be more complete on this matter. Even if completeness is not priority #1, node "Accessing Documentation" should say more than it does.