Normalize HTML anchor names for citations

[goerz]

The HTML anchor name is now derived from the citation key via a normalization to ASCII alphanumeric characters and _ and -.

Closes #86

[goerz]

@kellertuer Any comments? Otherwise, I'll merge this and release as 1.4.0 in the near future

[kellertuer]

This already looks very good! Thanks for working on this!

The only thing I am not so sure, is, what happens if two keys normalise to the same normalised key, is this “caught” and avoided? Sure, this is a rare edge case, but what if we have

ABC:2 and ABC:2å or so that they both normalise to ABC2. Are these still distinguishable?
If not, I am not so sure how to avoid that, and maybe Bijections already does this?
The simplest would maybe be:
If the normalised jet already exist, try to add an integer k=1,2,3,4,... until the key does not exist, so maybe at the point of adding this, it is also just a few lines to add.

Again, thanks for working on this!

[goerz]

what happens if two keys normalise to the same normalised key, is this “caught” and avoided?

Yes, that gets caught and results in an error:

DocumenterCitations.jl/test/test_anchor_keys.jl

Line 29 in bb4cfb2

msg = "Cannot generate HTML anchor for citation key \"AbsilMahonySepulchre.2008\": normalizes to ambiguous \"AbsilMahonySepulchre2008\" conflicting with citation key \"AbsilMahonySepulchre:2008\""

If the normalised jet already exist, try to add an integer k=1,2,3,4,... until the key does not exist

Actually, good point! I can turn that error into a warning and add suffixes. No good reason to confront people with recoverable errors! Thanks for the suggestion!

ABC:2 and ABC:2å or so that they both normalise to ABC2

Actually, these normalize to ABC2 and ABC2a, respectively: stripping of diacritics (NFKD normalization) is part of the conversion. But the point still stands.

I'm having second thoughts about stripping . too (I use it myself, mostly for arXiv preprints). Yes, it creates an issue with CSS selectors (it would have to be escaped), but how many people are going to be writing a CSS selector for a particular bibliography item in the documentation? It's probably better not to change anchors too much, which could be unnecessarily disruptive for existing users. Unfortunately, : in particular is incompatible with Documenter.DOM at the moment. (Edit: . is also fundamentally incompatible with Documenter.DOM.)

I'm also considering whether I should replace disallowed punctuation (like :) with _, instead of just dropping it. That might result in more readable anchors. Not that the anchors are extremely user-facing, but still.

[goerz]

I'm holding off on putting out a release until the potential reorganization of Bijections.jl is done, see JuliaCollections/Bijections.jl#19