build-ids and endnotes

[vr8hub]

We had a spirited discussion back in the day when this command was created on whether it should mess with endnote IDs. I said it shouldn't, you said it should; at the end you said you would take a PR to exclude endnotes.

I finally got around to looking at that, but in my initial testing, I found that the current build-ids actually renders endnotes invalid if the endnotes are numbered incorrectly.

The invalidity is caused by it only correcting the actual ID of the endnote in the endnotes file and the corresponding reference. It does not correct the backlink noteref in the endnotes file, nor does it correct the noteref id or the actual text in the noteref in the reference. So any endnote it affects is now messed up—in the endnote file, the note-id doesn't agree with the noteref-id, and in the source reference, the noteref-id and text don't agree with the reference.

That's a worse situation than before, because now renumber-endnotes won't correct them. Lint does still report the noteref being off, but in order to get renumber-endnotes to work, they have to put everything back like it was before build-ids messed with it.

I'm thus going to resurrect my argument that build-ids should not be touching endnotes at all; that should be left entirely to renumber-endnotes. Having now looked at it, it's an easy change, a couple of lines in build-ids and a couple more in find_unexpected_ids.

EDIT: If you got this via email, I corrected the penultimate paragraph.

[acabal]

Can you link me to the discussion? I doubt my reasoning has changed at all. If the script causes errors then its logic should be fixed, rather than simply removing that logic wholesale.

[vr8hub]

Yes, we're alike in that way. :) The discussion is here.

If the logic is "fixed," then 1) it's no longer just "build-ids", and 2) it's, again, completely replicating renumber-endnotes for no purpose.

You also mention in the discussion that not doing so (processing endnotes) could leave the repo in a "broken state," but it's processing endnotes that leaves it in a broken state.

Regardless, I'll submit the PR in a minute to add the --no-endnotes option.

[vr8hub]

Another note for whenever you fix build-ids, it also doesn't handle endnote references that are in the incorrect order in the text. E.g., note-1, note-2, note-5, note-3, note-4 (in chronological order in the text) aren't rearranged to note-1, note-2, note-3, note-4, note-5. They are not touched at all. renumber-endnotes does correct them.

I suppose technically the ids are in the correct order in endnotes, but the noteref-ids aren't in the correct order in the text. Either way, the endnotes are incorrect, build-ids doesn't correct them, renumber-endnotes does.

[acabal]

Yes, we're alike in that way. :) The discussion is here.

My opinion has not changed. You can add the flag if you want.

[vr8hub]

Here are what I've seen that needs fixing in build-ids for it to not mess up endnotes. Some of this was mentioned above, I'm just putting everything here so you'll have it in one place.

• It only changes the note-ids in the endnotes (and the references to those ids), it doesn't change the noteref-ids (and their references).
• It also doesn't change the superscripted numbers.
• In some cases because of the above, build-ids can make changes that it's then impossible for renumber-endnotes to correct. Sometimes renumber-endnotes still works; I haven't identified the difference, and don't plan to.
• Because it's changing the note-ids and not the noterefs, it is assuming that the order in the endnotes file is the correct order, but it's not. The correct order is chronologically through the book text in spine order.
• Because of that, it doesn't update note-ids/refs that "match" and are in order in endnotes, but that are the wrong id based on the order within the book. This again results in a book that is wrong, but our tools don't identify as wrong; lint won't complain either, since it's using the same function as build-ids to identify bad ids.