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: What is normal these days (display.texi)? Date: Sat, 08 Jul 2006 17:34:36 +0300 Message-ID: References: <85zmflu62p.fsf@lola.goethe.zz> <85lkr5qusn.fsf@lola.goethe.zz> <85psgg4hvv.fsf@lola.goethe.zz> Reply-To: Eli Zaretskii NNTP-Posting-Host: main.gmane.org X-Trace: sea.gmane.org 1152369359 14257 80.91.229.2 (8 Jul 2006 14:35:59 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sat, 8 Jul 2006 14:35:59 +0000 (UTC) Cc: karl@freefriends.org, emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Jul 08 16:35:57 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 1FzDuT-0007Ab-R4 for ged-emacs-devel@m.gmane.org; Sat, 08 Jul 2006 16:35:54 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1FzDuS-0002xU-1z for ged-emacs-devel@m.gmane.org; Sat, 08 Jul 2006 10:35:52 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1FzDtS-0001y5-05 for emacs-devel@gnu.org; Sat, 08 Jul 2006 10:34:50 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1FzDtQ-0001wX-3p for emacs-devel@gnu.org; Sat, 08 Jul 2006 10:34:49 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1FzDtP-0001wJ-V6 for emacs-devel@gnu.org; Sat, 08 Jul 2006 10:34:48 -0400 Original-Received: from [192.114.186.66] (helo=romy.inter.net.il) by monty-python.gnu.org with esmtp (Exim 4.52) id 1FzDu3-0000gJ-Lm; Sat, 08 Jul 2006 10:35:28 -0400 Original-Received: from HOME-C4E4A596F7 (IGLD-80-230-70-118.inter.net.il [80.230.70.118]) by romy.inter.net.il (MOS 3.7.3-GA) with ESMTP id FDO36829 (AUTH halo1); Sat, 8 Jul 2006 17:34:34 +0300 (IDT) Original-To: bob@rattlesnake.com In-reply-to: (bob@rattlesnake.com) 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:56788 Archived-At: > Date: Sat, 8 Jul 2006 13:10:41 +0000 (UTC) > From: "Robert J. Chassell" > Cc: > > > ! precisely at the right margin, not at a word boundary. > > ! @xref{Filling}, @ref{Longlines,, Long Lines Mode, emacs, > > ! The GNU Emacs Manual}. > > > > That doesn't seem like proper Texinfo usage; is it? > > What's wrong with it? > > @ref is for the end of a sentence. No, it isn't. It's for _any_ kind of situation where the leading `see' in the printed manual might be inappropriate. It's true that such situations frequently happen at the end of a sentence, but saying that @ref is _only_ for the end of a sentence (and that there should be a mandatory `see' before it) is limiting its use for no good reason. > The documentation says: > > (texinfo)ref > > `@ref' is nearly the same as `@xref' except that it does not > generate a `See' in the printed output, just the reference itself. > This makes it useful as the last part of a sentence. This text was somewhat misleading. That's why I suggested (and I think Karl accepted) to change it as follows: Sometimes, `See' or `see' before a reference is not what you want, because there's some other similar word that fits the text better. That's when you need @code{@@ref}. @code{@@ref} is nearly the same as @code{@@xref} except that it does not generate a `See' in the printed output, just the reference itself. It also produces a lower-case @samp{*note} instead of @samp{*Note}. These two features make @code{@@ref} useful as the last part of a sentence or in the middle of a sentence, if you want to replace `see' with something else, or remove it altogether. Note that the rest of the section already refrains from another misleading recommendation--to add a `see' before each @ref: In general, it is best to use @code{@@ref} only when you need some word other than ``see'' to precede the reference. When ``see'' (or ``See'') is ok, @code{@@xref} and @code{@@pxref} are preferable.