Separate index for names

[kcrisman]

Some books have a separate index of names from the general index. (Some also have many types of indices, but they probably start to get quite specialized.) This is a feature request to implement this, or perhaps just to implement multiple index types. <notation> and <index> and <solution> are in some sense all indices, so this should be possible, in principle.

[rbeezer]

Do you mean "names of people" or "defined terms" (like definitions)?

On 06/22/2015 01:42 PM, kcrisman wrote:

Some books have a separate index of names from the general index. (Some also have many types of indices, but they probably start to get quite specialized.) This is a feature request to implement this, or perhaps just to implement multiple index types. || and || and || are in some sense all indices, so this should be possible, in principle.

— Reply to this email directly or view it on GitHub https://github.com/rbeezer/mathbook/issues/115.

[kcrisman]

Both? But originally I meant names of people - one sees that from time to time, especially if it's a "historically focused" text.

[rbeezer]

I think this would be a good addition. But I'm after bigger projects during the summer right now, so not a high priority.

Maybe there should be some general index mechanism to support multiple indices of any type?

If you really need this urgently, we could discuss design and you could author in advance of actual support.

[kcrisman]

No, not urgent at all for me - I'm probably already being too ambitious. But one could imagine it being useful for other projects.

[davidfarmer]

Things like theorems and solutions could be gathered in a separate location, and this requires no changes to the source file because those things are clearly marked. (Why you would want to do that is a separate issue.)

However, multiple indices, with a separate index for names, requires planning ahead so that index entries know what type of thing they refer to. I think this is bad for several reasons. First, indexing is already pretty difficult if you do it right. For example, in LaTeX notation here are some index entries related to Euler's theorem:

\index{Euler's theorem} \index{Theorem!Euler's} \index{Euler, Leonhard}

and maybe you can think of additional entries.

I have not kept up with the MBX way to index, but it has to map down to LaTeX. The best thing I have come up with is to add an optional argument to \index, like

\index[person]{Euler, Leonhard}

And the LaTeX output of MBX needs to provide support for the new \index macro, and not break the old one.

But that takes me to my key point: I can't think of a natural use case where it is helpful to have a separate list of the names of people who appear in the index. The fact that there are books with that feature is not relevant.

Unless I am missing some way to make this feature useful, and do-able, I suggest closing this issue and then opening a related issue that lists the separate lists which could possibly be useful some day.

[kcrisman]

The fact that there are books with that feature is not relevant.

(What?! I guess Hardy & Wright isn't relevant, then.)

Anyway, I agree this isn't a high-priority feature - I don't need it yet, or probably ever - but I don't understand the rush people always have to close wish list type tickets in projects. It doesn't hurt anyone to have it there, and is a place for people to comment if they have an idea about it. As I said, in this particular case, there are enough "historically focused" texts nowadays that one can imagine it being useful. But if changing this to allowing separate index types and making it super-clear this is wish list allows it to stay around, I have no problem with that.

[davidfarmer]

Hardy and Wright does not have a real index, only an index of names! Suppose you want to know the definition of "algebraic integer"? How would you look that up? So the relevance of Hardy and Wright is that (in terms of layout) it is an example of what not to do. (As a further example, try to guess what chapter contains Theorem 104.)

As to deleting feature requests: it is not true that all features add value to a project. Since all features have a cost - of both initial development and maintenance - it is good project management to delete some feature requests. I am trying to give reasons why this is such an example.

(My H&W is the 5th edition, published in 1989. It may be that more recent editions have a real index.)

(And, yes, you can find "algebraic integer" in the TOC, but it is horribly tedious to scan the TOC hoping that the term you care about is part of a chapter title.)

On Mon, 29 Jun 2015, kcrisman wrote:

  The fact that there are books with that feature is not relevant.

(What?! I guess Hardy & Wright isn't relevant, then.)

Anyway, I agree this isn't a high-priority feature - I don't need it yet, or probably ever - but I don't understand the rush people always have to close wish list type tickets in projects. It doesn't hurt anyone to have it there, and is a place for people to comment if they have an idea about it. As I said, in this particular case, there are enough "historically focused" texts nowadays that one can imagine it being useful. But if changing this to allowing separate index types and making it super-clear this is wish list allows it to stay around, I have no problem with that.

— Reply to this email directly or view it on GitHub.[AAM6LC7-n1kZLgW6JJuApWY-WibrD6Saks5oYZOGgaJpZM4FJSVy.gif]

[rbeezer]

My two cents worth on indices:

• Very low-priority for HTML
• A "regular" index is useful for a printed book
• Indices get really complicated, really fast. Just look at any of the general tools (latex-specific or not). It'd be crazy for MBX to try to redo this.
• I find a "List of Theorems" and "List of Definitions", in chronological order, very useful in online FCLA, though perhaps that is due to my acronym decision. As David says, these are easy to build since everything is marked carefully. For HTML, these are very easy to construct and are unobtrusive at "the bottom of the book." I might implement these once I convert FCLA over to MBX.
• I do regularly see indices of names (names which do not appear in the index). Why not have proper names mixed in to the regular index?
• I think MBX index entries would easily support David's idea that they need to be marked off as to which index they belong to. And I agree that this is necessary.

• I'm going to mark this "wish list" now and move on.

  Thanks for the discussion.

[rbeezer]

Chicago Manual of Style argues against a separate index, even for names (though that would be an OK exception for them).

I have student requests for an index of Sage commands. That might be a place where two indices would be disjoint enough to not cause confusion.

[kcrisman]

Chicago Manual of Style argues against a separate index, even for names (though that would be an OK exception for them).

Style manuals can change all the time, and are just that - style manuals. (I prefer to not use "Mr." for everyone like the NYT.) I just finished reading a work with a two-part index "by name" "by something else" - Anchor Books, by a Nobel laureate. Frankly, when style and design get in the way of communication, we are in trouble. And for some works you can reasonably expect people to want separate indices by name, or by geographical location, or by year, or whatever. (Maybe not math books!)

I have student requests for an index of Sage commands. That might be a place where two indices would be disjoint enough to not cause confusion.

Yes, that would certainly be necessary, though I think that is fine as an appendix.

or perhaps just to implement multiple index types.

Really, all I think is necessary here is to optionally allow multiple indices just like there are multiple appendices. Or multiple/multipart references :) but that has already been discussed elsewhere. Certainly one could warn authors against this, but for (say) an historical text this might make a lot of sense.

Also, belatedly I realize just how bad of an example H&W was. Apparently there is a whole indexing project for that work.

[davidfarmer]

Chicago Manual of Style argues against a separate index, even for names (though that would be an OK exception for them).

Style manuals can change all the time, and are just that - style manuals. (I prefer to not use "Mr." for everyone like the NYT.)

There is much to disagree with in NYT style, because it is not an appropriate style guide for scholarly books. That is why the CMOS has been the semi-official style guide for MBX from the beginning.

I don't see how a feature request can pass the "common and reasonable" test if it goes against the CMOS. The reasoning they give for a single index is quite compelling:

It is frustrating to hunt for a name or term, only to find you are in the wrong index. Further, cross-referencing between subjects and persons is much simpler in a single index.

A separate list of sage commands (not sure I'd even call it an "index") sounds useful and does not contradict the CMOS recommendation (nor does it contradict the reasoning behind their recommendation).

Considering the large cost of having to mark up the index entries in a way that allows terms to be funneled into separate indexes, and the small gain (a loss, actually!) in having separate indexes, it seems clear that there are better places to put development efforts.

David

[rbeezer]

The notation list is much like an index, but "in order of appearance," which is a whole lot easier. And also "common and reasonable."

[rbeezer]

Thoughts on the MBX for additional indices. An attribute @subject is placed on both index entries and the index creation element. So, e.g., subject="authors". There would be an implicit default index for the main one in the absence of the @subject attribute.

I think it would be nearly trivial to filter at the start of the index creation code for HTML.

For LaTeX we use the imakeidx package now, mostly to avoid multiple runs/passes to build the index. This package appears to have been built more for multiple indices, so there may be a low-overhead way to go on the print side.

Still wishlist until more development time comes along - I need to tidy up the current index project and move on. But appears very do-able. Will also garner a new "Bully Pulpit" paragraph.

[davidfarmer]

I'd like to see some example (common and reasonable) use cases for multiple indices. In the absence of good examples, such a feature merely enables people to do the wrong thing.

[kcrisman]

It is frustrating to hunt for a name or term, only to find you are in the wrong index.

Yes, of course. Nonetheless the types of indices can be quite disparate. I'm not suggesting an index of continuous functions versus an index of discontinuous functions.

But an index of names ... I mean, it will be pretty evident that you are searching in the wrong index within about two seconds. And if there are a lot of names, but nowhere near as many as total items, and if you aren't exactly sure of the spelling (or even the name) in the first place, it sure could be useful. Better believe that's happened to me.

As for additional index types, the very first book I pulled from the shelf (at home, no math books here) has an index of ancient sources separated into 11 (!) subheadings (the last of which is "Persian sources", and believe me you want this index sub-organized or you'd never find anything, it was pages and pages long), an index of modern authors, and an index of selected topics. (Plus a multi-part bibliography again organized in three sections, the first of which is a list of abbreviations - that is very standard in this field, although its placement within the book varies.) And please don't tell me Fortress is a marginal publisher.

Now, I'm not suggesting this is necessarily a super-common use case; the next six books I picked out had just one index, or in one unfortunate case none at all. (But then the next book had two again, same style.) My point is that there could be discipline-specific reasons for having an "index of", and that (as a wishlist item, sure) MBX could support that.

In fact, as mentioned earlier, MBX already does support one such - the notation list. Here are a few ideas which actually occur - they are not always called indices, but definitely not necessarily appendices in the sense that they are certainly ordered lists.

• Notation list (math)
• Index of ancient sources (religious studies)
• Discography (music/musicology)
• List of works (any artistic field, see Werkverzeichnis)

In the latter case if one wishes to restrict to mathematics, one could e.g. imagine a book focusing on Euler which, in addition to a normal index and bibliography, had a separate index (with page numbers) directing people to Euler papers by Enestrom number. (Aware of missing umlaut but can't get this Ubuntu keyboard to do it easily, sorry.)

In any case, perhaps these are "really" appendices, but I'd say any appendix with an ordered list of "stuff" could count, particularly if it includes page numbers. Whether they are common or not probably depends upon what field you are in. Is a list of historical notes, or technology references, or of other special remarks, an index or an appendix? I really don't know. But it seems reasonable to not want some of one's list-of things to have appendix letters, though as for myself I don't care so much.

[rbeezer]

If we do this, we need to be very careful about educating authors to make it clear to the reader that there are now two places where information is located. If the headnote (#1048) is visible, then it can explain this. Cross-references between indices should be allowed and encouraged.

[davidfarmer]

I think we should be very slow to implement multiple indexes.

Are there really a lot of people who know what they are talking about and are asking for this? The names need to be a substantial fraction of the index (so much so that it annoys people who are not searching for names) before it makes any sense to think about this. Math textbooks are not on the verge of having that happen.

And then you need a way to mark up an index entry and indicate it is a name (or whatever else you might want as a separate index).

I really can't see this being anything more than a distraction.

At the moment we are struggling to get people to understand the basic principles of indexing. Part of that is making them understand why usually multiple indexes are bad.

[rbeezer]

This is #115, so I think we are being slow. Really slow. No plans, just recording things to do, so when we have a historical novel, we'll be covered. ;-)

[kcrisman]

@davidfarmer I'm baffled as to why this was closed without any further discussion over two years after the last comment. "just recording things to do" is typical open development practice. It would be very easy to put a "pipe dream" tag on it or something, and then when a not-so-mythical motivated developer implements this (or something else) with lots and lots of warnings for users, it's just waiting there for them.

[mitchkeller]

Sorry…made comment without realizing that the comment referencing another issue actually referenced this one and was merged in.