bug#50467: Could :properties have index entries in the elisp manual?

bug#50467: Could :properties have index entries in the elisp manual?

[Stefan Kangas]

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.

bug#50467: Could :properties have index entries in the elisp manual?

[Lars Ingebrigtsen]

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

bug#50467: Could :properties have index entries in the elisp manual?

[Eli Zaretskii]

> 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.

bug#50467: [External] : bug#50467: Could :properties have index entries in the elisp manual?

[Drew Adams]

> ...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

bug#50467: Could :properties have index entries in the elisp manual?

[Stefan Kangas]

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.

bug#50467: Could :properties have index entries in the elisp manual?

[Stefan Kangas]

[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'.

bug#50467: Could :properties have index entries in the elisp manual?

[Eli Zaretskii]

> 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.

bug#50467: Could :properties have index entries in the elisp manual?

[Lars Ingebrigtsen]

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.