search

metanorma / asciidoctor-rfc

AsciiRFC: an AsciiDoc/asciidoctor backend to produce RFC XML v3 (RFC 7991) and v2 (RFC 7749)
BSD 2-Clause "Simplified" License
15 stars 7 forks source link

Render RFC references #101

Closed andrew2net closed 6 years ago

andrew2net commented 6 years ago

@opoudjis I didn't find in examples reference like in asciidoctor-iso

* [[[iso123,ISO 123]]] _Standard_

do we need to add rendering such refs? If yes, suppose the place to implement the functional is ref_section(node) function in /asciidoctor-rfc/lib/asciidoctor/rfc/v3/base.rb. Do you agree?

opoudjis commented 6 years ago

Your question is, where is bibliography building handled in RFC. The answer is that they are indeed handled in ref_section(); but asciidoctor-rfc already has functionality to query the RFC bibliographic database and add references from there: common/base.rb, cache_biblio() and insert_biblio(). No functionality needs to be added to asciidoctor-rfc.

Hypothetically, we could add isobib functionality to asciidoctor-rfc; that would necessitate translating Relaton XML to RFC XML. In practice, let's not do that unless Ronald asks for it; it will make things messier, and RFC documents don't cite outside of the IETF often enough for it to add much value.

ronaldtse commented 6 years ago

We should actually extract rfcbib from asciidoctor-rfc and move it to a common framework that combines IsoBib, gbbib and rfcbib.

opoudjis commented 6 years ago

The two bibliographies of ISO and rfc are fetched completely differently, and serialised completely differently. If we keep the two separate, conflating some in the one gem is not useful. if we attempt to merge them, but somehow mapping rfc bibliographies that are already in the correct format into Relaton XML and back, it is even less useful.

ronaldtse commented 6 years ago

They are fetched differently but the fetched reference should be stored in ISODOC in the exact same format (i.e. Relaton XML). So it is useful to generalize this framework:

Fetch RFC/ISO/GB/IEC/IEV ---> Relaton model ---> Insert into ISODOC ---> Render into WhateverFormat

andrew2net commented 6 years ago

@ronaldtse I finished RfcBib gem. If we shouldn't integrate it into asciidoctor-rfc, when what is next step?

opoudjis commented 6 years ago

It is intended for integration into asciidoctor-iso and asciidoctor-gb. I will assign myself tickets to do so.

ronaldtse commented 6 years ago

The other part is to refactor asciidoctor-rfc into the same structure as asciidoctor-iso and asciidoctor-gb, but it's separate from this ticket.

ronaldtse commented 6 years ago

(https://github.com/riboseinc/asciidoctor-rfc/issues/105)