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

From: Eli Zaretskii <[email-masked]>
Date: Fri, 10 Sep 2021 10:14:00 +0300

> From: Stefan Kangas <[email-masked]>
> Date: Fri, 10 Sep 2021 09:00:00 +0200
> Cc: [email-masked]
> 
> [Sorry, I missed replying to these below points so I'll do that here.]
> 
> Eli Zaretskii <[email-masked]> 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.