* bug#11178: 24.0.94; Elisp manual: add index entries for :link LINK-DATA alternatives @ 2012-04-04 22:24 Drew Adams 2012-04-11 6:18 ` Chong Yidong 0 siblings, 1 reply; 7+ messages in thread From: Drew Adams @ 2012-04-04 22:24 UTC (permalink / raw) To: 11178 (elisp) Common Keywords should be indexed for each of the LINK-DATA alternatives: `custom-manual', `info-link', `url-link', `emacs-commentary-link', `emacs-library-link', `file-link', `function-link', `variable-link', and `custom-group-link'. In GNU Emacs 24.0.94.1 (i386-mingw-nt5.1.2600) of 2012-03-19 on MARVIN Windowing system distributor `Microsoft Corp.', version 5.1.2600 Configured using: `configure --with-gcc (4.6) --no-opt --enable-checking --cflags -ID:/devel/emacs/libs/libXpm-3.5.8/include -ID:/devel/emacs/libs/libXpm-3.5.8/src -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include -ID:/devel/emacs/libs/giflib-4.1.4-1/include -ID:/devel/emacs/libs/jpeg-6b-4/include -ID:/devel/emacs/libs/tiff-3.8.2-1/include -ID:/devel/emacs/libs/gnutls-3.0.9/include' ^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#11178: 24.0.94; Elisp manual: add index entries for :link LINK-DATA alternatives 2012-04-04 22:24 bug#11178: 24.0.94; Elisp manual: add index entries for :link LINK-DATA alternatives Drew Adams @ 2012-04-11 6:18 ` Chong Yidong 2012-04-11 6:27 ` Drew Adams 0 siblings, 1 reply; 7+ messages in thread From: Chong Yidong @ 2012-04-11 6:18 UTC (permalink / raw) To: Drew Adams; +Cc: 11178 "Drew Adams" <drew.adams@oracle.com> writes: > (elisp) Common Keywords should be indexed for each of the LINK-DATA > alternatives: `custom-manual', `info-link', `url-link', > `emacs-commentary-link', `emacs-library-link', `file-link', > `function-link', `variable-link', and `custom-group-link'. No. That makes no sense---there's already an index entry for adding links to custom docs. I don't want to pollute the index with entries listing every possible value for what's just a keyword. (Though I eagerly await the coming long-form article arguing against this.) ^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#11178: 24.0.94; Elisp manual: add index entries for :link LINK-DATA alternatives 2012-04-11 6:18 ` Chong Yidong @ 2012-04-11 6:27 ` Drew Adams 2012-04-11 8:13 ` Eli Zaretskii 0 siblings, 1 reply; 7+ messages in thread From: Drew Adams @ 2012-04-11 6:27 UTC (permalink / raw) To: 'Chong Yidong'; +Cc: 11178 > > (elisp) Common Keywords should be indexed for each of the LINK-DATA > > alternatives: `custom-manual', `info-link', `url-link', > > `emacs-commentary-link', `emacs-library-link', `file-link', > > `function-link', `variable-link', and `custom-group-link'. > > No. That makes no sense---there's already an index entry for adding > links to custom docs. I don't want to pollute the index with entries > listing every possible value for what's just a keyword. (Though I > eagerly await the coming long-form article arguing against this.) These are reference entries. No different from indexing individual function names or individual button properties. We don't use the argument that just because there is an index entry for the general topic of Apropos in the Emacs manual there should not also be entries for the individual apropos commands. Etc. ^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#11178: 24.0.94; Elisp manual: add index entries for :link LINK-DATA alternatives 2012-04-11 6:27 ` Drew Adams @ 2012-04-11 8:13 ` Eli Zaretskii 2012-04-11 17:37 ` Drew Adams 0 siblings, 1 reply; 7+ messages in thread From: Eli Zaretskii @ 2012-04-11 8:13 UTC (permalink / raw) To: Drew Adams; +Cc: 11178, cyd > From: "Drew Adams" <drew.adams@oracle.com> > Date: Tue, 10 Apr 2012 23:27:43 -0700 > Cc: 11178@debbugs.gnu.org > > > > (elisp) Common Keywords should be indexed for each of the LINK-DATA > > > alternatives: `custom-manual', `info-link', `url-link', > > > `emacs-commentary-link', `emacs-library-link', `file-link', > > > `function-link', `variable-link', and `custom-group-link'. > > > > No. That makes no sense---there's already an index entry for adding > > links to custom docs. I don't want to pollute the index with entries > > listing every possible value for what's just a keyword. (Though I > > eagerly await the coming long-form article arguing against this.) > > These are reference entries. No different from indexing individual function > names or individual button properties. Perhaps adding two more index entries, something like @cindex links to documentation for customization items @cindex customization items, links to documentation would do the job. Currently, I see only one index entry there: @kindex link@r{, customization keyword} which IMO is not enough for when the reader wants to find information about adding links to the docs. The existing index entry only covers efficiently the case when the reader is specifically looking for the 'link' keyword and already knows what that's used for. ^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#11178: 24.0.94; Elisp manual: add index entries for :link LINK-DATA alternatives 2012-04-11 8:13 ` Eli Zaretskii @ 2012-04-11 17:37 ` Drew Adams 2012-04-11 19:35 ` Eli Zaretskii 0 siblings, 1 reply; 7+ messages in thread From: Drew Adams @ 2012-04-11 17:37 UTC (permalink / raw) To: 'Eli Zaretskii'; +Cc: 11178, cyd > > These are reference entries. No different from indexing > > individual function names or individual button properties. > > Perhaps adding two more index entries, something like > > @cindex links to documentation for customization items > @cindex customization items, links to documentation > > would do the job. Currently, I see only one index entry there: > > @kindex link@r{, customization keyword} > > which IMO is not enough for when the reader wants to find information > about adding links to the docs. The existing index entry only covers > efficiently the case when the reader is specifically looking for the > 'link' keyword and already knows what that's used for. What Eli says is also pertinent. But independent. Again, you are talking about indexing _topics_. I am talking about _reference_ index entries. If a user wants to look up the particular button property `follow-link', she does `i follow-link' and Bob's an uncle. This is about looking up a particular :link alternative, such as `emacs-commentary-link'. It is not about looking up the topic of "links to documentation for customization items". ^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#11178: 24.0.94; Elisp manual: add index entries for :link LINK-DATA alternatives 2012-04-11 17:37 ` Drew Adams @ 2012-04-11 19:35 ` Eli Zaretskii 2012-04-11 20:34 ` Drew Adams 0 siblings, 1 reply; 7+ messages in thread From: Eli Zaretskii @ 2012-04-11 19:35 UTC (permalink / raw) To: Drew Adams; +Cc: 11178, cyd > From: "Drew Adams" <drew.adams@oracle.com> > Cc: <cyd@gnu.org>, <11178@debbugs.gnu.org> > Date: Wed, 11 Apr 2012 10:37:39 -0700 > > > > These are reference entries. No different from indexing > > > individual function names or individual button properties. > > > > Perhaps adding two more index entries, something like > > > > @cindex links to documentation for customization items > > @cindex customization items, links to documentation > > > > would do the job. Currently, I see only one index entry there: > > > > @kindex link@r{, customization keyword} > > > > which IMO is not enough for when the reader wants to find information > > about adding links to the docs. The existing index entry only covers > > efficiently the case when the reader is specifically looking for the > > 'link' keyword and already knows what that's used for. > > What Eli says is also pertinent. But independent. > > Again, you are talking about indexing _topics_. I am talking about _reference_ > index entries. We've been through this before, Drew, and we already established that your views about indexing are not shared. Bringing that up again won't change that. > If a user wants to look up the particular button property `follow-link', she > does `i follow-link' and Bob's an uncle. She can also do 'i link TAB', see "link, customization keyword" and Bob's her uncle. IOW, if she already knows she's after follow-link, she'll have no trouble finding it. ^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#11178: 24.0.94; Elisp manual: add index entries for :link LINK-DATA alternatives 2012-04-11 19:35 ` Eli Zaretskii @ 2012-04-11 20:34 ` Drew Adams 0 siblings, 0 replies; 7+ messages in thread From: Drew Adams @ 2012-04-11 20:34 UTC (permalink / raw) To: 'Eli Zaretskii'; +Cc: 11178, cyd > > Again, you are talking about indexing _topics_. I am > > talking about _reference_ index entries. > > We've been through this before, Drew, and we already established that > your views about indexing are not shared. Bringing that up again > won't change that. There you go again, Eli, generalizing and ad hominem ad nauseum. Apparently "my views" related to this bug report _are_ shared when it comes to button properties, functions, etc. - those are all indexed individually by name. You just do not agree that link alternatives should be handled the same way. It would be fair enough to say that (we can disagree), but you do not. Instead, you cast this as being about some purported general "view" of mine. No, it's about the question posed by the bug report: indexing the individual link alternatives, which are specific Emacs-Lisp symbols/sexps. As for "bringing it up again won't change that": Again, you are generalizing, caricaturing, and ignoring the particular request. I have never before brought up this request. And I understood as soon as Yidong said "That makes no sense" that the request would likely not be fulfilled. His reason, that there was already a topic entry for adding links to custom docs, does not at all address the need expressed - this bug report. Your independent request for adding more topic entries does not address it either. So I explained the difference, using a particular button property (_not_ the topic of button properties) as an example of how we do typically DTRT. Functions that are mentioned in the manual are indexed under their names, in addition to being indirectly indexed via topics where they are mentioned. Likewise button properties and other entities. Not so link alternatives. That is this bug. It has nothing to do with wanting more topic entries about links or linking. > > If a user wants to look up the particular button property > > `follow-link', she does `i follow-link' and Bob's an uncle. > > > > This is about looking up a particular :link alternative, > > such as `emacs-commentary-link'. It is not about looking > > up the topic of "links to documentation for customization items". > > She can also do 'i link TAB', see "link, customization keyword" and > Bob's her uncle. IOW, if she already knows she's after follow-link, > she'll have no trouble finding it. Still missing the point, Eli. `follow-link' is the example of a case where we do DTRT: the `follow-link' button property is indexed as such, not only indirectly via topics (such as "button properties") where it is mentioned. It's about indexing the particular, literal reference term: `follow-link' in the case of the button property (done), and `emacs-commentary-link' in the case of the link alternative (not done). ^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2012-04-11 20:34 UTC | newest] Thread overview: 7+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2012-04-04 22:24 bug#11178: 24.0.94; Elisp manual: add index entries for :link LINK-DATA alternatives Drew Adams 2012-04-11 6:18 ` Chong Yidong 2012-04-11 6:27 ` Drew Adams 2012-04-11 8:13 ` Eli Zaretskii 2012-04-11 17:37 ` Drew Adams 2012-04-11 19:35 ` Eli Zaretskii 2012-04-11 20:34 ` Drew Adams
Code repositories for project(s) associated with this external index https://git.savannah.gnu.org/cgit/emacs.git https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.