From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Info about how to write links in doc string Date: Fri, 04 May 2007 16:26:02 +0300 Message-ID: References: <4637B285.9050200@gmail.com> Reply-To: Eli Zaretskii NNTP-Posting-Host: lo.gmane.org X-Trace: sea.gmane.org 1178285183 23349 80.91.229.12 (4 May 2007 13:26:23 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Fri, 4 May 2007 13:26:23 +0000 (UTC) Cc: emacs-devel@gnu.org To: "Lennart Borgman (gmail)" Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri May 04 15:26:21 2007 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1Hjxnb-0004Cc-FN for ged-emacs-devel@m.gmane.org; Fri, 04 May 2007 15:26:15 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1HjxuE-00041U-Mt for ged-emacs-devel@m.gmane.org; Fri, 04 May 2007 09:33:06 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1HjxuB-0003qx-N4 for emacs-devel@gnu.org; Fri, 04 May 2007 09:33:03 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1HjxuB-0003oW-5E for emacs-devel@gnu.org; Fri, 04 May 2007 09:33:03 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1HjxuB-0003nv-0q for emacs-devel@gnu.org; Fri, 04 May 2007 09:33:03 -0400 Original-Received: from heller.inter.net.il ([213.8.233.23]) by monty-python.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1HjxnW-0006k3-Te for emacs-devel@gnu.org; Fri, 04 May 2007 09:26:11 -0400 Original-Received: from HOME-C4E4A596F7 (IGLD-83-130-244-37.inter.net.il [83.130.244.37]) by heller.inter.net.il (MOS 3.7.3a-GA) with ESMTP id CMW90977 (AUTH halo1); Fri, 4 May 2007 16:26:02 +0300 (IDT) In-reply-to: <4637B285.9050200@gmail.com> (lennart.borgman@gmail.com) X-detected-kernel: FreeBSD 4.7-5.2 (or MacOS X 10.2-10.4) (2) 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:70542 Archived-At: > Date: Tue, 01 May 2007 23:35:01 +0200 > From: "Lennart Borgman (gmail)" > > Information about how to write links in doc strings is kind of hidden. > It is not found under > > (info "(elisp) Documentation") > > which is where I think most programmers would look for it. Instead it is > found under > > (info "(elisp) Documentation Tips") > > I think at least mentioning this after the link from 1 above to 2 above > would be good. Thanks for the suggestion, but I decided not to change the manual. This is because there's a direct cross-reference from "Documentation" to "Documentation Tips" right near the beginning of the former: A documentation string is written using the Lisp syntax for strings, with double-quote characters surrounding the text of the string. This is because it really is a Lisp string object. The string serves as documentation when it is written in the proper place in the definition of a function or variable. In a function definition, the documentation string follows the argument list. In a variable definition, the documentation string follows the initial value of the variable. When you write a documentation string, make the first line a complete sentence (or two complete sentences) since some commands, such as @code{apropos}, show only the first line of a multi-line documentation string. Also, you should not indent the second line of a documentation string, if it has one, because that looks odd when you use @kbd{C-h f} (@code{describe-function}) or @kbd{C-h v} (@code{describe-variable}) to view the documentation string. There are many other conventions for doc strings; see @ref{Documentation Tips}. IMO, this can hardly be regarded as ``hidden information''. I did reorder the items in the "Documentation Tips" section to put the more important ones first. That included the item that described the hyperlinks: it doesn't make sense to me to make that the last tip. I also added an index entry for the hyperlinks in doc strings, so now this material can be easily found no matter where it is. Thanks again for pointing this out.