* bug#50467: Could :properties have index entries in the elisp manual? @ 2021-09-08 1:52 Stefan Kangas 2021-09-08 5:51 ` Lars Ingebrigtsen 2021-09-08 6:31 ` Eli Zaretskii 0 siblings, 2 replies; 8+ messages in thread From: Stefan Kangas @ 2021-09-08 1:52 UTC (permalink / raw) To: 50467 Severity: wishlist Please consider adding properties to the index of the elisp manual for easy access. Rationale: I find myself often looking for properties such as :align-to in the elisp manual, but they are not indexed. This means that I have to look instead for them manually instead, which takes more time. Perhaps there is some conflict of interest between having a usable index inside Emacs and the length of the printed manual. One way to side-step that would be to put them in the index only in the info version of the manual, while excluding them from the print version. I don't know if texinfo supports this. If we decide to go ahead with this wishlist request, we would only need to add a few properties as examples. We could then close this bug add the rest in over time. Perhaps some properties are more important to add than others, and perhaps others still would not even make sense adding. ^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#50467: Could :properties have index entries in the elisp manual? 2021-09-08 1:52 bug#50467: Could :properties have index entries in the elisp manual? Stefan Kangas @ 2021-09-08 5:51 ` Lars Ingebrigtsen 2021-09-08 6:31 ` Eli Zaretskii 1 sibling, 0 replies; 8+ messages in thread From: Lars Ingebrigtsen @ 2021-09-08 5:51 UTC (permalink / raw) To: Stefan Kangas; +Cc: 50467 Stefan Kangas <stefan@marxist.se> writes: > Please consider adding properties to the index of the elisp manual for > easy access. > > Rationale: I find myself often looking for properties such as > :align-to in the elisp manual, but they are not indexed. This means > that I have to look instead for them manually instead, which takes > more time. Sure, I think that's a good idea. That'd basically be @cindex @code{:align-to}, @code{display} text property That's a mouthful... I mean, these aren't text properties per se, but properties when displaying a space-filling `display' property. -- (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no ^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#50467: Could :properties have index entries in the elisp manual? 2021-09-08 1:52 bug#50467: Could :properties have index entries in the elisp manual? Stefan Kangas 2021-09-08 5:51 ` Lars Ingebrigtsen @ 2021-09-08 6:31 ` Eli Zaretskii 2021-09-08 15:55 ` bug#50467: [External] : " Drew Adams ` (2 more replies) 1 sibling, 3 replies; 8+ messages in thread From: Eli Zaretskii @ 2021-09-08 6:31 UTC (permalink / raw) To: Stefan Kangas; +Cc: 50467 > From: Stefan Kangas <stefan@marxist.se> > Date: Wed, 8 Sep 2021 03:52:34 +0200 > > Please consider adding properties to the index of the elisp manual for > easy access. Which ones? all of them? There are a lot of them, and we sometimes have the same keyword used in different contexts to mean different things, so we'd need a lot of disambiguation text to make unique entries. (And you mean keywords that start with a colon, not properties. Right?) One problem here is that use of the colon character in index entries should be avoided, as some Info readers could get confused by that (the colon is a special character in Info file format). Also, most of the keywords are, or should be, found by using their "family name". For example, for faces we have "face attributes" in the index. That said, feel free to suggest additions to the indexing for the important keywords, we can always discuss them one by one. Thanks. ^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#50467: [External] : bug#50467: Could :properties have index entries in the elisp manual? 2021-09-08 6:31 ` Eli Zaretskii @ 2021-09-08 15:55 ` Drew Adams 2021-09-10 6:54 ` Stefan Kangas 2021-09-10 7:00 ` Stefan Kangas 2 siblings, 0 replies; 8+ messages in thread From: Drew Adams @ 2021-09-08 15:55 UTC (permalink / raw) To: Eli Zaretskii, Stefan Kangas; +Cc: 50467@debbugs.gnu.org > ...keywords that start with a colon... > > One problem here is that use of the colon character in index entries > should be avoided, as some Info readers could get confused by that > (the colon is a special character in Info file format). Indeed. See bugs #18957 and #30478. https://debbugs.gnu.org/cgi/bugreport.cgi?bug=18957 https://debbugs.gnu.org/cgi/bugreport.cgi?bug=30478 ^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#50467: Could :properties have index entries in the elisp manual? 2021-09-08 6:31 ` Eli Zaretskii 2021-09-08 15:55 ` bug#50467: [External] : " Drew Adams @ 2021-09-10 6:54 ` Stefan Kangas 2021-09-10 7:00 ` Stefan Kangas 2 siblings, 0 replies; 8+ messages in thread From: Stefan Kangas @ 2021-09-10 6:54 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 50467 Eli Zaretskii <eliz@gnu.org> writes: > > Please consider adding properties to the index of the elisp manual for > > easy access. > > Which ones? all of them? There are a lot of them, and we sometimes > have the same keyword used in different contexts to mean different > things, so we'd need a lot of disambiguation text to make unique > entries. As a first approximation, only some of them. (That's what I meant when I wrote: "Perhaps some properties are more important to add than others, and perhaps others still would not even make sense adding.") > (And you mean keywords that start with a colon, not properties. > Right?) Yes, that was a thinko, sorry. > That said, feel free to suggest additions to the indexing for the > important keywords, we can always discuss them one by one. That seems like a good approach here. ^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#50467: Could :properties have index entries in the elisp manual? 2021-09-08 6:31 ` Eli Zaretskii 2021-09-08 15:55 ` bug#50467: [External] : " Drew Adams 2021-09-10 6:54 ` Stefan Kangas @ 2021-09-10 7:00 ` Stefan Kangas 2021-09-10 7:14 ` Eli Zaretskii 2 siblings, 1 reply; 8+ messages in thread From: Stefan Kangas @ 2021-09-10 7:00 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 50467 [Sorry, I missed replying to these below points so I'll do that here.] Eli Zaretskii <eliz@gnu.org> writes: > One problem here is that use of the colon character in index entries > should be avoided, as some Info readers could get confused by that > (the colon is a special character in Info file format). How important is this consideration? In other words, how serious of a breakage are we risking? For example, if it is just that the index entries won't work in other info readers, that seems acceptable to me. > Also, most of the keywords are, or should be, found by using their > "family name". For example, for faces we have "face attributes" in > the index. This is the workflow that I wanted to avoid. For example, I might not know which section ":align-to" belongs to, which means that the fastest way for me to find out is to search the entire manual. This is less convenient than typing 'i :a TAB'. ^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#50467: Could :properties have index entries in the elisp manual? 2021-09-10 7:00 ` Stefan Kangas @ 2021-09-10 7:14 ` Eli Zaretskii 2022-08-25 14:26 ` Lars Ingebrigtsen 0 siblings, 1 reply; 8+ messages in thread From: Eli Zaretskii @ 2021-09-10 7:14 UTC (permalink / raw) To: Stefan Kangas; +Cc: 50467 > From: Stefan Kangas <stefan@marxist.se> > Date: Fri, 10 Sep 2021 09:00:00 +0200 > Cc: 50467@debbugs.gnu.org > > [Sorry, I missed replying to these below points so I'll do that here.] > > Eli Zaretskii <eliz@gnu.org> writes: > > > One problem here is that use of the colon character in index entries > > should be avoided, as some Info readers could get confused by that > > (the colon is a special character in Info file format). > > How important is this consideration? In other words, how serious of a > breakage are we risking? For example, if it is just that the index > entries won't work in other info readers, that seems acceptable to me. It is serious enough that the Texinfo manual advises against it. Which in practice means we should use it sparingly, only for very important attributes that aren't readily accessible otherwise. > > Also, most of the keywords are, or should be, found by using their > > "family name". For example, for faces we have "face attributes" in > > the index. > > This is the workflow that I wanted to avoid. For example, I might not > know which section ":align-to" belongs to, which means that the > fastest way for me to find out is to search the entire manual. Where the "family name" is not obvious, and the attribute is important or popular, it is indeed justified to have a separate index entry. I agree that :align-to is one such example, so it's okay to add it. One other consideration is that Info-index uses substring matches, so having an index entry :foo runs the risk of its turning up in searches for "foo", which could be undesirable if "foo" is a general enough word, like "weight" or similar. ^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#50467: Could :properties have index entries in the elisp manual? 2021-09-10 7:14 ` Eli Zaretskii @ 2022-08-25 14:26 ` Lars Ingebrigtsen 0 siblings, 0 replies; 8+ messages in thread From: Lars Ingebrigtsen @ 2022-08-25 14:26 UTC (permalink / raw) To: Eli Zaretskii; +Cc: Stefan Kangas, 50467 Eli Zaretskii <eliz@gnu.org> writes: >> How important is this consideration? In other words, how serious of a >> breakage are we risking? For example, if it is just that the index >> entries won't work in other info readers, that seems acceptable to me. > > It is serious enough that the Texinfo manual advises against it. > Which in practice means we should use it sparingly, only for very > important attributes that aren't readily accessible otherwise. It seems like the info readers now support quoted node names (see bug#57277), but info.el doesn't. ^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2022-08-25 14:26 UTC | newest] Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2021-09-08 1:52 bug#50467: Could :properties have index entries in the elisp manual? Stefan Kangas 2021-09-08 5:51 ` Lars Ingebrigtsen 2021-09-08 6:31 ` Eli Zaretskii 2021-09-08 15:55 ` bug#50467: [External] : " Drew Adams 2021-09-10 6:54 ` Stefan Kangas 2021-09-10 7:00 ` Stefan Kangas 2021-09-10 7:14 ` Eli Zaretskii 2022-08-25 14:26 ` Lars Ingebrigtsen
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).