html anchors

[kmuehlbauer]

Sorry, this might some silly issue, but I didn't find anything related. Good chance that I just didn't use the right vocabulary for search.

I'm not sure when this happened, but in November 2020 this still worked (https://docs.wradlib.org/en/1.9.0/zreferences.html#gabella2002). When I create my references the html-anchors have been something like this:

zreferences.html#gabella2002

Now, at least since June 2021 (https://docs.wradlib.org/en/1.10.0/zreferences.html#id6), this gets transformed to:

zreferences.html#id8

I think I did not change anything related in my configuration. Did I miss something in the documentation? Can this be set somewhere? Thanks for any suggestions!

[mcmtroffaes]

Yes, the anchor naming was changed a while back. The "#idxxx" anchors are directly generated by docutils and guarantee that no anchors will clash with existing anchors in the document (which had been an issue before). This has been introduced some time in December 2020. Using any of the :cite: roles will always point you to the correct anchor.

I'm curious, could you explain why you need to rely on these anchors?

[mcmtroffaes]

... for information, from the 2.1.0 changelog: "Consistent use of doctutils note_explicit_target to set ids, to ensure no clashing ids." In retrospect this is a tad more cryptic than it could be!

[kmuehlbauer]

I'm curious, could you explain why you need to rely on these anchors?

I'm referencing with the "speaking"-anchors from another resource. This is also needed if you want to have real permalinks as these ids might change from version to version. Do you see any way to work around this?

[mcmtroffaes]

There's probably a way to tell docutils to generate ids based on the bibtex key. The docutils documentation is obscure at best (somewhat ironic for a documentation utility library!), hopefully with some digging through the source code, I can figure this one out. If by any chance you, or anyone, have suggestions of how to achieve this with the docutils API, I'd be keen to hear about it!

[kmuehlbauer]

@mcmtroffaes I appreciate your efforts. Unfortunately I've no insight into docutils :-(

[kmuehlbauer]

This is from the docutils documentation: https://docutils.sourceforge.io/docs/ref/doctree.html#identifier-key

Identifier keys are used for cross references in generated documents. Therefore, they must comply with restrictions in the respective output formats (HTML4.1, HTML5, polyglot HTML, LaTeX, ODT, troff (manpage), XML).
Identifier keys cannot be specified directly in reStructuredText. Docutils generates them by applying the identifier normalization to reference names or from the auto_id_prefix, prepending the id_prefix and potentially appending numbers for disambiguation.

Not sure where the connection is between sphinxcontrib-bibtex and docutils is, but docutils uses either identifier normalization or auto_id_prefix.

[mcmtroffaes]

Thanks for having a look. The prefix is a common prefix between all ids, so not suitable for our purpose. What we need is the reference names, which correspond to the names attribute in each node, if I recall correctly. I've had some success using them on simple examples, but in general there's a problem with duplicate attributes (this is why currently it uses autogenerated "id" attributes).

The main problem is that each bibliography directive will create nodes for every bib entry (because the ids need to be known before all documents are parsed, otherwise references to these ids cannot be generated) whether or not it will be eventually included. Thus if a document has multiple bibliography directives, then it is impossible to avoid duplicate names, and docutils will complain badly. The best I can come up with is to prepend them with the id of the bibliography directive they reside in. I could add a setting to disable the prepend and enforcing just a single bibliography directive per document for those that don't want the prepend (and thus, "stable" reference names for citations). It feels a bit hackish though...

[kmuehlbauer]

@mcmtroffaes Thanks for explaining the possibilities.

The best I can come up with is to prepend them with the id of the bibliography directive they reside in.

That would be a neat way to achieve "speaking" anchors. I could get accustomed to that. Would this give something like the below?

zreferences.html#cite-1-gabella2002

I could add a setting to disable the prepend and enforcing just a single bibliography directive per document for those that don't want the prepend (and thus, "stable" reference names for citations).

This would be great, too. Even simpler for those who know what they are doing.

[mcmtroffaes]

The best I can come up with is to prepend them with the id of the bibliography directive they reside in.

That would be a neat way to achieve "speaking" anchors. I could get accustomed to that. Would this give something like the below?

zreferences.html#cite-1-gabella2002

Something like that, yes.

[mcmtroffaes]

Implemented in #265.