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 21:27:39 -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 1151382511 7149 80.91.229.2 (27 Jun 2006 04:28:31 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Tue, 27 Jun 2006 04:28:31 +0000 (UTC) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Jun 27 06:28:29 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 1Fv5B4-00006j-L8 for ged-emacs-devel@m.gmane.org; Tue, 27 Jun 2006 06:27:55 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Fv5B3-0001Iv-Qf for ged-emacs-devel@m.gmane.org; Tue, 27 Jun 2006 00:27:53 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1Fv5As-0001Hx-0n for emacs-devel@gnu.org; Tue, 27 Jun 2006 00:27:42 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1Fv5Ar-0001HD-1g for emacs-devel@gnu.org; Tue, 27 Jun 2006 00:27:41 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Fv5Aq-0001HA-Tl for emacs-devel@gnu.org; Tue, 27 Jun 2006 00:27:40 -0400 Original-Received: from [141.146.126.228] (helo=agminet01.oracle.com) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_3DES_EDE_CBC_SHA:24) (Exim 4.52) id 1Fv5Ms-0008IX-6v for emacs-devel@gnu.org; Tue, 27 Jun 2006 00:40:06 -0400 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 k5R4RdPK009160 for ; Mon, 26 Jun 2006 23:27:39 -0500 Original-Received: from dradamslap (dhcp-amer-whq-csvpn-gw3-141-144-80-242.vpn.oracle.com [141.144.80.242]) by rgmsgw300.us.oracle.com (Switch-3.1.7/Switch-3.1.7) with SMTP id k5R4RbUY021488 (version=TLSv1/SSLv3 cipher=RC4-MD5 bits=128 verify=NO) for ; Mon, 26 Jun 2006 22:27:38 -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:56214 Archived-At: > 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. I've always wondered if there should be more attempts to link from docstrings into the elisp manual. It would reduce the burden of trying to make docstrings too all-encompassing. Consider, for instance, if there were automatically added "See (elisp)FUNCTION-NAME" and/or "See (elisp)faces" links at the bottom of _every_ face function's docstring. [I seem to recall that this was discussed in some manner before?? Anybody remember?] [I don't remember such a discussion. Perhaps you are thinking of my request that we add a source-code link to the Customize section for an object (e.g. a variable) - see subject line "Getting more info on a variable in Customize buffers" from 2005/1/1.] Wrt your suggestion for *Help*: I support the idea. "See (elisp)" might not be clear to some users, and doesn't really help. The link just needs to take you to the right manual node; it need not be named after the node. It could simply say "More...", since *Help* is already providing doc on the function (or variable, or...). If the function or variable is discussed in both manuals, Emacs and Emacs Lisp, then the links could be called "Emacs Manual" and "Emacs-Lisp manual". Alternatively, we could just use "Emacs Manual" and "Emacs-Lisp manual" always (not "More.."), whichever applied. Some objects are not discussed in either manual, so they would have no manual link. Together with a) the link to the source code on the object (e.g. function) name itself, and b) the link to customize the object, users would have everything on the object in one place.