On Fri, Dec 20, 2024 at 12:46 PM Werner LEMBERG <[email protected]> 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
