From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Recent changes in parsing.texi Date: Sun, 25 Dec 2022 21:02:55 +0200 Message-ID: <83k02f2tnk.fsf@gnu.org> References: <838riw3pph.fsf@gnu.org> <2ACC7406-A345-4693-9BC2-83A33653373B@gmail.com> <329336DF-73AD-48F0-B34A-27F3C0C267A7@gmail.com> <83zgbb3jvi.fsf@gnu.org> <8307E55B-4576-4921-BD48-C1D8A5BD69AA@gmail.com> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="11261"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: Yuan Fu Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sun Dec 25 20:03:24 2022 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1p9WHM-0002j6-0h for ged-emacs-devel@m.gmane-mx.org; Sun, 25 Dec 2022 20:03:24 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1p9WGt-0003w1-WB; Sun, 25 Dec 2022 14:02:56 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1p9WGs-0003vc-Bw for emacs-devel@gnu.org; Sun, 25 Dec 2022 14:02:54 -0500 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1p9WGs-0000Lc-3v; Sun, 25 Dec 2022 14:02:54 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=F+7oY+QgaNNnlfllelMCJgXXkg24+ZI5cEKFvxqeBZQ=; b=S2SXaPgg/p1I WNeR90QlrcTozTtgQY5/Njj7c3jlQgx+vmZ1lWisjOPicne86onn3uOkpMlok4mjysEo6eSB4xtKj 6wvLKyXo+6qbAqIi+K5KYMawu5KHwZr9WZMQK+qBR4E0Qa2iwp0p++/PIAwGRLRRTXD8qEj1IlyJ+ OLAj2zY4HPaJ9RZT4CoSoByAlNGc/Wlts3wdPnAD1rZPEHPemF6zFuD4p+ptSJ7ey5SSIqVRMpcbr lfItRbdXiKp049b/GLM48neiMiHW3/NI4dIBUcPyMVZmKLGpDRRDw6gMOkH0TjaV9ha4TAgJVFdp9 3QUlxYfp0npU2/hcGupUVA==; Original-Received: from [87.69.77.57] (helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1p9WGr-000797-K1; Sun, 25 Dec 2022 14:02:53 -0500 In-Reply-To: <8307E55B-4576-4921-BD48-C1D8A5BD69AA@gmail.com> (message from Yuan Fu on Sun, 25 Dec 2022 10:54:17 -0800) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.devel:301915 Archived-At: > From: Yuan Fu > Date: Sun, 25 Dec 2022 10:54:17 -0800 > Cc: emacs-devel@gnu.org > > > If a symbol appears in some @defXX directive, there's no need for a > > separate @cindex entry, since @defXX does that automatically. (Also, > > I mistakenly used @cindex where I should have used @vindex; fixed.) > > > > I added these index entries because these variables didn't seem to > > appear in any @defXX directive, nor had any existing index entries. > > If I missed something, please tell. > > Thanks, I was actually just asking for confirmation of my understanding. Because my impression of vindex was that they mark the paragraph introducing and defining the variable. Basically you need to add it if you use a plain paragraph instead of defar to introduce that variable. And your change seem to imply we need to index every occurrence of a variable. The @vindex marks the place where the variable is documented to its fullest. There should be just one such place, and all the other places where the variable is mentioned should have cross-references to that full description. With one exception: if you document some very special and particular aspect of the variable in a different place, that place should have its own @vindex qualified by the aspect. For example: @vindex foobar@{, using in empty buffers} (You need the @r{..} thingy in @vindex and @findex because otherwise the entire text of these index entries is typeset as if it were in @code; @cindex doesn't need @r{..}. > Just to clarify, do I need to add @vindex bbb in the following case? (Ie, do I need to index every occurrence of a variable, or do I only need to index where it is defined? Only index the full description of the variable, of which there should be just one in the entire manual. If there's no description, then index the best approximation to it, i.e. the one place where you say the most about it.