On 2024-12-19 21:52, Werner LEMBERG wrote:
We’d definitely need more opinions, especially from folks like
Werner who have worked on the docs/appendices a lot, as well as
from users: how do they feel about it? How much do they use which
index?
I use Appendix E only.
While people are thinking, what do you think about the idea that
contents of indices aren't supposed to overlap? (Maybe flip to the
back of a few actual books here to check?)
I very much dislike that. We use different fonts (via different
indexing commands) to provide a clear distinction between concepts and
commands, and LilyPond's clean naming schemes for properties, context,
engravers, etc., should additionally help a user to find the stuff he
or she needs.
Looking into one of the most complicated books regarding indices, the
new, third edition of the 'LaTeX companion', I see that it has only a
single index (with both concepts and commands) – this two-volume book
has in total about 1500 pages (not counting the indices), and the
index is about 150 pages.
Actually the same book came to my mind, when this email thread appeared.
The full title of the index in that book is "Index of Commands and
Concepts", which is a title that would make sense also for our App. E.
One confusing detail of the index in LaTeX Companion (at least in 2nd
edition) is that all packages are listed under "Packages", i.e. you
won't find them if you just search the general index in alphabetic
order. In a way, that sub-index under Packages plays a somewhat similar
role as our Command index but we have a much less confusing structure
where the command index is clearly visible as a separate index, and
where you find the commands even if you happen to look in the "wrong"
index. The confusion in the Lilypond documentation is rather that we
duplicate the information, but at least to me that's not a bit deal. I
mostly use App. E and since I use it on-line I typically use CTRL-F and
then it's rather a feature than a problem that both commands and other
terms are mixed together, since even if I misremember a command name, I
will typically get a relevant hit anyway when searching for (part of)
the command name. Keeping all the information in the same index also
makes sense since it's not always obvious if a specific feature is
available as a command or as a property setting, I occasionally use App.
D when I know for certain that it's a command I'm looking for, but I
wouldn't cry if App. D disappeared.
What is a bit confusing is the name "Lilypond Index" and I seem to
recall that I argued on the mailing list some 20-30 years back that it
only should be called "Index" (especially if there is only one index).
On the other hand, we still have separate indices for the different
documents (LM, NR, IR, ...) which is not always a benefit since there
might be a better description of a certain feature in the LM than in the
NR, for example. That's one of the reasons I don't like the title
"Lilypond Index", which seems to imply that you could find all LilyPond
related information there. On the other hand, using the search box at
the bottom of the left column searches the full set of documentation not
only the current document.
What certainly is confusing is that the navigation bar at the top and
bottom of
https://lilypond.org/doc/v2.25/Documentation/notation/index.html
contains a link "Index" that points to App D and not to App E. I just
discovered it when writing this email, but it seems like a "bug" that
has existed at least since version 2.14.
/Mats
