From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Yuan Fu Newsgroups: gmane.emacs.devel Subject: Re: Recent changes in parsing.texi Date: Mon, 26 Dec 2022 01:44:15 -0800 Message-ID: <9313F78F-DEF4-45F0-BD2C-96870D97BE85@gmail.com> 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> <83k02f2tnk.fsf@gnu.org> Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3696.120.41.1.1\)) Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="29046"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Mon Dec 26 10:45:13 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 1p9k2j-0007N8-13 for ged-emacs-devel@m.gmane-mx.org; Mon, 26 Dec 2022 10:45:13 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1p9k1x-0008HT-DT; Mon, 26 Dec 2022 04:44:25 -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 1p9k1v-0008HL-Py for emacs-devel@gnu.org; Mon, 26 Dec 2022 04:44:23 -0500 Original-Received: from mail-pf1-x42e.google.com ([2607:f8b0:4864:20::42e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1p9k1u-0003KT-1g; Mon, 26 Dec 2022 04:44:23 -0500 Original-Received: by mail-pf1-x42e.google.com with SMTP id d82so6955972pfd.11; Mon, 26 Dec 2022 01:44:20 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=to:references:message-id:content-transfer-encoding:cc:date :in-reply-to:from:subject:mime-version:from:to:cc:subject:date :message-id:reply-to; bh=wGhVydM9IE86l0Etou80rZjOmiu7owXVocOZwBW3gck=; b=HfwTTG+gnAl8saPL+NW8LuYeC4oJrDTINAM7hBAhSlohH6kWbXrEJ6sjpVXqnL95/c ZBxfrv4/x2guJveEWMqL5qiRwZ4VM4+pFv6AwX/QwrXNwEUfti17U7j72IvUKj5tRd2C GowFY/+c8HXgJeMsMlfbs/C7cF3hqdfe0sAcejAOnxPxCkBfbugqKijvP338ixZ0eyQO DWf2gqxdT6JmNv2h0mRBmKitA3ih7S3DmGI595f800eQDRU3IjQQ6A0hScEcDSm3StVC pHr8NClEEHPv/PS8YrCURaUAdbK5cnm3QtUUJlOWtoVCyvDIADxei+YX8Ln4PfPob6ue kwsw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=to:references:message-id:content-transfer-encoding:cc:date :in-reply-to:from:subject:mime-version:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=wGhVydM9IE86l0Etou80rZjOmiu7owXVocOZwBW3gck=; b=caGF6/l8If+zeN4ajN6Ccyx3gi8lDkEnOc7FFYydNESWhLiNtyrZZvXV3fWNXa1iB1 BSBYuJi9CvdYSeHZCyS7aJ2Wneezxnp6yAj/cU5ZpJDvZ+5Xk0I8XrOU2dfPfxmbXcnL ZKc/QkZX/y2g4tfpDOeo87JYyOzn/9rE79dfl+YLBibIHLm+6KGid765DpHfZWlMJQwT z4Tfje1JRnf0G5WRjmakMCdkYnK91wcyDuSqM4SWl7eatbXgMlM3xebXq0v+zz0ZHgHw N4l4aA6GJSknPmpKZdu6gHQOnmTEGhXmFj6UuI0QzINVwfVK1+HBhLoi6+bOKkVI/EUG b9Mg== X-Gm-Message-State: AFqh2koS0joEesZto796BBpAMdqHWtE8RSTdqHSc9uyXRtvmh2DsoUSn NsOqBPjRyGaF2rPILZrdBkGCaaBlTco= X-Google-Smtp-Source: AMrXdXvbIuy+aUMrLoRszIV3p9sjR412aur8/b0Oaxrl2x+VUNFRTRVYpnATsSpe0yjhTghzukhOFw== X-Received: by 2002:a05:6a00:1da2:b0:580:f804:d704 with SMTP id z34-20020a056a001da200b00580f804d704mr6101439pfw.28.1672047859203; Mon, 26 Dec 2022 01:44:19 -0800 (PST) Original-Received: from smtpclient.apple (cpe-172-117-161-177.socal.res.rr.com. [172.117.161.177]) by smtp.gmail.com with ESMTPSA id x7-20020aa78f07000000b00580f630a05csm2837783pfr.180.2022.12.26.01.44.18 (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Mon, 26 Dec 2022 01:44:18 -0800 (PST) In-Reply-To: <83k02f2tnk.fsf@gnu.org> X-Mailer: Apple Mail (2.3696.120.41.1.1) Received-SPF: pass client-ip=2607:f8b0:4864:20::42e; envelope-from=casouri@gmail.com; helo=mail-pf1-x42e.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action 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:301927 Archived-At: > On Dec 25, 2022, at 11:02 AM, Eli Zaretskii wrote: >=20 >> From: Yuan Fu >> Date: Sun, 25 Dec 2022 10:54:17 -0800 >> Cc: emacs-devel@gnu.org >>=20 >>> 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.) >>>=20 >>> 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. >>=20 >> 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. >=20 > 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: >=20 > @vindex foobar@{, using in empty buffers} >=20 > (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{..}. >=20 >> 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? >=20 > 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. Thanks a bunch! I fully understand it now. Yuan=