Feature request: allow using local bibliographic items

[ronaldtse]

Suggestion from @petithug :

Sometimes one has to edit a set of internet-drafts instead of a single document. The issue here is to keep the version number up to date to the local copies, not to what is already uploaded on the secretariat website.

For example draft-mph-test-01 and draft-mph-test2-04, two different I-Ds referencing each other, could be already uploaded. Now when I am working on draft-mph-test-02 and draft-mph-test2-05 (probably simultaneously) I want draft-mph-test-02 to reference draft-mph-test2-05 and vice-versa.

So the idea would be to add the possibility to overload include so it could take would take the name of the adoc file. extract the bibliography from it and include it. Something like this:

In test.adoc (which contains the text for draft-mph-test-02):

[bibliography]
== Informative References

include::draft-mph-test2[relaton]

And in test2.adoc (which contains the text for draft-mph-test2-05)

[bibliography]
== Normative References

include::draft-mph-test[relaton]

In fact I tried to implement that this afternoon, but could not figure out what relaton API to use, as the one I found returns a bibdata element, where it seems that I need a bibitem element instead.

Notice also that I never use the name of the internet-draft as filename, because the internet-draft changes name multiple times during its lifecycle (e.g. see https://datatracker.ietf.org/doc/draft-ietf-tram-stun-pmtud/ that, apart numbers, changed its name 4 times if you count the final name as an RFC). So I have a patch that instead generate the final document filename using the :name: header attribute, if present.

[ronaldtse]

I have encountered this issue myself as well — a pair of documents that are both cross-referenced with each other but not yet published.

When you write:

include::draft-mph-test2[relaton]

I assume that draft-mph-test2 the root .adoc file of the other document. Since the metadata of draft-mph-test2 is already in its root .adoc file, we don’t need to fully generate the bibliography of draft-mph-test2. We just need to pick the metadata of draft-mph-test2 and insert it.

I think it works.

On the other issue:

Notice also that I never use the name of the internet-draft as filename, because the internet-draft changes name multiple times during its lifecycle (e.g. see https://datatracker.ietf.org/doc/draft-ietf-tram-stun-pmtud/ that, apart numbers, changed its name 4 times if you count the final name as an RFC). So I have a patch that instead generate the final document filename using the :name: header attribute, if present.

This interests me… What do you usually name the file as? In the past I just rename the I-D filename to the new one, but it’s certainly not ideal… I remember xml2rfc is picky with the final document filename for its recommendations. Would you say generating the final document filename from :name: is a best practice?

(CC @opoudjis for comments)

[opoudjis]

@andrew2net, I can't find it anywhere in https://www.relaton.com/specs/relaton-cli/, but doesn't the relaton API have somewhere a switch to alternate between bibitem and bibdata?

Asciidoctor allows you to use its include macro to include a fragment of a document instead of the entire document, so you should be able to get the desired behaviour by using https://asciidoctor.org/docs/user-manual/#include-directive

[andrew2net]

@opoudjis the flavor gems have the parameter bibdata, but the relaton always save bibdata in a cache, because bibitem doesn't contain the ext element. So the relaton-cli doesn't have a switch to alternate between bibitem and bibdata. Do we need it?