Re: NR appendices D and E are confusing

[Trevor Bača]

On Fri, Dec 20, 2024 at 12:46 PM Werner LEMBERG <wl@gnu.org> wrote:

> > Two more examples.
> >
> > An orchestration textbook:
> >
> > Appendix A: List of Foreign Names for Instruments and Orchestral Terms
> > Appendix B: Ranges of Instruments
> > Bibliography
> > Index
> >
> > A harmony textbook:
> >
> > Appendix A: Instrumental Ranges and Transpositions
> > Appendix B: Lead-Sheet Symbols
> > Appendix C: Set Class List
> > Appendix D: Answers to Self-Tests
> > Index of Music Examples
> > Subject Index
>
> It's not clear to me what these examples should demonstrate.  Please
> elaborate.


1. If a book has more than one index, the contents of the indices don't
overlap. The LaTeX companion (that you and Mats both mentioned) and the
orchestration textbook (above) all fit this criterion, by virtue of having
only one index. The harmony textbook (above) and the book that Kieren
mentioned also fit this criterion, because we can assume that "Index of
Music Examples" contains different information than "Subject Index," for
example. All the books we've looked at here follow this principle, which is
my point. My contention is that this is an unspoken rule about the
structure of books, and it costs us nothing to follow that convention,
clarifying the structure of our most important docs. (With a reminder that
users sometimes write to the list and say that they're confused about our
Appendix D / Appendix E split. My point through all of this is that there's
a perfectly good reason why users are confused. We're violating a [minor]
convention of the who books work. Please, nobody take offense here. There's
nothing bad or wrong here, and it would be crazy to assume that anyone's at
fault. It's just that we've missed a rather subtle aspect of how books are
structured, and it will cost us almost nothing to fix it.)

2. That when a book has an index, it is not listed as an appendix.

3. When a book has only a single index, the clearest way of labeling it is
as "Index" (Mats's observation).

I totally get how it can feel like an affront to show up and say "hey,
we're kinda modeling the concept of a book a touch wrong." I get it, I do.
But it costs us almost nothing (in terms of writing actual code) to just
drop Appendix D and rename Appendix E as "Index." And, as Mats pointed out,
at that point the hyperlinks at the bottom of every page that say "Index"
can simply point to the index.

-- 
Trevor Bača
www.trevorbaca.com
soundcloud.com/trevorbaca