Comments (22)
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/˜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/˜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.
Related Issues (20)
- Bug with custom attributes when translating to DocBook HOT 3
- Question: own styles HOT 1
- :bibliography-database: not set via asciidoctor-epub3 for included documents HOT 6
- Bib entry with identical author and year HOT 18
- Minor APA format issue HOT 4
- Converting directly with Ruby HOT 2
- Variable interpolation breaks include
- anomalies when using Asciidoctor's ifeval::[] and asciidoctor-bibliography HOT 3
- Errors with asciidoctor-pdf HOT 2
- Numbered bibliography
- Comparison with asciidoc-bib and asciidoctor-bibtex
- A problem building Nokogiri, when installing on Windows HOT 7
- Migrate to GitHub Actions from Travis
- Change default branch to main HOT 1
- Asciidoc-bibliography messes with section levels after include
- The generated bibliography is incomplete HOT 6
- Citations get parsed within inline source code environment HOT 2
- Multi-Citation of more than two keys not working HOT 5
- [enhancement] nocite macro for bibliography entry without expicit citation HOT 1
- Incompatibility with asciidoctor version >= 2.0 HOT 3
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. ๐๐๐
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google โค๏ธ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from asciidoctor-bibliography.