No RFC XML output! about asciidoctor-bibliography HOT 22 CLOSED

I did some extensive tests. I'm afraid the CSL data structures (and Citeproc, and BibTeX for that matter) are unable to represent all needed structured data for RFC citations. Also, CSL renderers have kind of a bad time rendering structured XML.

As @opoudjis states to handle RFC citations you pretty much need RFC XML. Transformations like BibTeX -> RFC or BiBTeX -> Citeproc -> RFC will be inherently lacking data from the source.

I think the best course of action is to

• implement a db reader for RFC XML citation databases
• held the data as Citeproc + one extra field holding the original XML
• write an RFC CSL style that renders inline citations (simple) and just dumps the extra XML when rendering bibliographies.

This could be also done in parallel to the main asciidoctor-bibliography mechanism (we're using it mostly as a passthrough) but doing it this way offers two advantages:

• we can integrate into the RFC style a best approximation rendering of RFC XML items even for items coming from non-RFC sources (is this desirable?)
• we can parse the RFC db data to populate the CSL tree and render the items with arbitrary styles (in non-RFC documents, of course)
  Neither of the two side benefits are priorities, but they might add some value to the framework.

So, in essence I feel the best approach here is to:

• use RFC XML as a source of RFC structured bibliographical data
• use asciidoctor-bibliography as a (more or less) passthrough
• parse RFC XML citations to offer typesetting to other styles in non-RFC documents (optional)
• offer a best-guess rendering (since BibTeX nor Citeproc itself can really represent all needed structured data) of items coming from other sources for RFC documents (optional)

from asciidoctor-bibliography.

@paolobrasolin here's a real-life example of a v2 that uses pretty much all the syntax options.

<references>
<reference anchor='BC-EVAL' target='http://web.cs.ucdavis.edu/&tilde;Rogaway/papers/modes.pdf'>
  <front>
    <title>Evaluation of Some Blockcipher Modes of Operation</title>
    <author initials="P." surname="Rogaway" fullname="Phillip Rogaway">
      <organization>University of California, Davis</organization>
      <address>
        <postal>
          <street>Dept. of Computer Science</street>
          <street>Kemper Hall of Engineering, #3009</street>
          <street>One Shields Avenue</street>
          <city>Davis</city>
          <region>California</region>
          <code>95616-8562</code>
          <country>United States of America</country>
        </postal>
        <phone>+1 530 752 7583</phone>
        <email>[email protected]</email>
        <uri>http://www.cs.ucdavis.edu/&tilde;rogaway</uri>
      </address>
    </author>
    <date day='10' month='February' year='2011'/>
  </front>
</reference>
</references>

See RFC 7749 for v2 syntax.

In particular:

• <references>
• <reference>
• <front>: supports <title|author|area|workgroup|keyword|abstract|note>

from asciidoctor-bibliography.

@paolobrasolin sounds like a good plan -- could you help implement this? This seems like the only remaining issue before asciidoctor-rfc can be used full on! 👍

from asciidoctor-bibliography.

@paolobrasolin 0.51 and 0.6 both released now 👍

from asciidoctor-bibliography.

@opoudjis you are again correct, we will need an output style that generates RFC XML, and the best way to do so is to create a CSL bibliography style (https://github.com/citation-style-language/styles).

@paolobrasolin would you be able to do so? Thanks!

from asciidoctor-bibliography.

As @ronaldtse states, fixing the issues amounts to writing a CSL style.
I don't think I need your assistance with this @opoudjis. However, could you please paste a link to a reference for bibliographic data structures for v2 and v3, so I'll be sure to refer to the correct ones?

from asciidoctor-bibliography.

Per #51, all RFCs in Bibtex are here: https://tm.uka.de/~bless/rfc.bib , and a bunch of official RFC XML are available from IETF; e.g.

<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC2629 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2629.xml">
<!ENTITY RFC3552 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3552.xml">
<!ENTITY RFC5226 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5226.xml">

from asciidoctor-bibliography.

Actually you can find all official RFC XML documents in the "Citation Libraries" section of this page:
https://xml2rfc.tools.ietf.org

There's also a tool called doilit from https://github.com/cabo/kramdown-rfc2629/ that helps you retrieve a DOI document from the IETF library (even though the results aren't always useable).

from asciidoctor-bibliography.

v3 RFC XML references are v2 RFC XML references, plus some extra stuff: annotations, and "refcontent", which is free text interpolated before the end of the reference (e.g. "self-published pamphlet".) For our purposes, I believe we can ignore those differences.

from asciidoctor-bibliography.

The main challenge I think you'll find, @paolobrasolin, is that the RFC XML references are heavily biased towards standards documents as a specialised kind of journal: populating the seriesInfo element will be critical, where possible. seriesInfo is in theory a journal equivalent, but no page numbers, and idiosyncratic notions of status and stream.

I'd recommend that if you can get native RFC XML references, you do use them in preference to bibtex.

from asciidoctor-bibliography.

For non-IETF standards (such as ISO), which also need seriesInfo, see the examples in https://raw.githubusercontent.com/riboseinc/rfc-openpgp-oscca-adoc/master/sections/98-references.adoc (raw xml).

from asciidoctor-bibliography.

FWIW, the XML-based workflow in samples I've seen seems to have been XML entities for RFC standards (imported externally), and inline XML for non-RFC standards. Which aligns to import RFC XML vs author bibtex in what you'd be doing. So treating RFC entries separately will be familiar to people.

from asciidoctor-bibliography.

Ok, I set up the rendering as a custom style that renders XML wrapped in a passthrough. It seems to me it's the bet way to ensure the code gets safely to the final rendered file.

I whipped up a quick integration test on this branch https://github.com/riboseinc/asciidoctor-rfc/tree/cite-test-deleteme

A few details are missing (i.e. automatically setting up options when using rfc doctype).
However I need your advice @opoudjis; it seems the bibliography::[] output gets lost , but only when used in the back matter (renders correctly elsewhere). You probably already know what's the matter so I'm asking you to suggest what you feel is the best way to integration.

from asciidoctor-bibliography.

@paolobrasolin I think there is some issue with asciidoctor-rfc as nokogiri wasn't fully implemented. Would you be able to fully migrate it to nokogiri? Thanks!

from asciidoctor-bibliography.

@ronaldtse I'm getting up to speed with the code and taking care of that.

from asciidoctor-bibliography.

@ronaldtse found the bug. taking care of that.

from asciidoctor-bibliography.

Thank you @paolobrasolin ! Really looking forward to ensuring that Nokogiri is used for all XML...

from asciidoctor-bibliography.

@ronaldtse Ok, the use of nokogiri was not directly responsible for the malfunctioning, so I'll leave that to the other existing issue.

asciidoctor-rfc now has a branch with a fix and a working demo for V2. It relies on feature-54 in this repo. I'm writing a demo for V3 now. Then I'll merge and we can release 0.7 of asciidoctor-bibliography with the new styles/features.

from asciidoctor-bibliography.

Thank you @paolobrasolin, you have no idea how much I’m hoping this gets done 😉

from asciidoctor-bibliography.

@ronaldtse #60 all green, ready to merge and be released as v0.6.0.

This RFC branch uses the feature branch of #60 and contains both a V2 and a V3 example with references named as refs-v*.

Finetuning on the rfc side might be needed, but the mechanism seems to be working.

I implemented (and documented) two new options: bibliography-prepend-empty and bibliography-passthrough that are needed to let our trick work (and offer some nice possibilites).

Long story short, an rfc targeted adoc document like this would compile:

= Whatever title
Mark Foo <[email protected]>
:bibliography-database: refs-v2-database.xml
:bibliography-passthrough: citations
:bibliography-prepend-empty: false
:bibliography-hyperlinks: false
:bibliography-style: rfc-v2
:doctype: rfc

First I cite something cite:info[RFC2119] and then something else cite:norm[RFC2629].

[bibliography]
== Normative References

++++
bibliography::norm[]
++++

[bibliography]
== Informative References

++++
bibliography::info[]
++++

I'll explain more details in the asciidoctor-rfc repo later today.

(While I was at it, I also fixed another bug that escaped me; v0.5.1 tag is already on master.)

from asciidoctor-bibliography.

Sorry I was incommunicado last week, @paolobrasolin ; Day job blew up, lots of overtime.

OK, ticket me in asciidoctor-rfc, but my intention is to get a little toy example into rspec, and then more and more.

from asciidoctor-bibliography.

The bibliography::norm[] etc macro is working fine, and you will have worked out Paolo what was happening—that I was expecting XML pass for references in ++++, which your macros now respect.

from asciidoctor-bibliography.