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 17:01:03 +0300 Message-ID: References: <4637B285.9050200@gmail.com> <463B381F.40207@gmail.com> Reply-To: Eli Zaretskii NNTP-Posting-Host: lo.gmane.org X-Trace: sea.gmane.org 1178287279 31382 80.91.229.12 (4 May 2007 14:01:19 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Fri, 4 May 2007 14:01:19 +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 16:01:17 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 1HjyLS-0003wC-D7 for ged-emacs-devel@m.gmane.org; Fri, 04 May 2007 16:01:14 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1HjyS5-0001JH-OK for ged-emacs-devel@m.gmane.org; Fri, 04 May 2007 10:08:05 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1HjyS2-0001He-Et for emacs-devel@gnu.org; Fri, 04 May 2007 10:08:02 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1HjyS0-0001CK-R5 for emacs-devel@gnu.org; Fri, 04 May 2007 10:08:01 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1HjyS0-0001C8-Js for emacs-devel@gnu.org; Fri, 04 May 2007 10:08:00 -0400 Original-Received: from romy.inter.net.il ([213.8.233.24]) by monty-python.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1HjyLM-0003DV-9v for emacs-devel@gnu.org; Fri, 04 May 2007 10:01:08 -0400 Original-Received: from HOME-C4E4A596F7 (IGLD-83-130-244-37.inter.net.il [83.130.244.37]) by romy.inter.net.il (MOS 3.7.3-GA) with ESMTP id HTR89395 (AUTH halo1); Fri, 4 May 2007 17:01:05 +0300 (IDT) In-reply-to: <463B381F.40207@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:70545 Archived-At: > Date: Fri, 04 May 2007 15:41:51 +0200 > From: "Lennart Borgman (gmail)" > CC: emacs-devel@gnu.org > > Eli Zaretskii wrote: > > (@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 would not look for how to write links under something labeled with > "other conventions". Are you talking about the situation where someone looks specifically for the information about how to write links? If so, the index entry I just added should solve that: just type "i hyperlink RET", and you are there. If, by contrast, you are talking about someone who studies the doc string facility for the first time, then that person will bump into the cross-reference to "Documentation Tips", and I expect them to go there, since the text is quite inviting. > The way you write links is a way to use a functionality, not a > convention. It is a convention because you don't _have_ to use links, it's just a nicety that makes documentation better. The Tips section describes a lot of other similar functionalities, such as \\[foo], \\, the fact that arguments should be written in UPPER case, the fact that opening parens should be escaped, etc. It doesn't make sense to move only the links stuff to the other section; either we move most of the rest, or we don't move anything at all.