Comments (9)
OK, I'll take it for a spin and let you know. XML in the text tag is a little brute-force, but I see that getting ascii-bibliography to do the heavy lifting would have been retrograde.
from asciidoctor-bibliography.
@paolobrasolin I agree this will be the simplest syntax. However it would be even better if we can place a "placeholder" in the middle of the text for the original reference, like cite:[Aa2017, text="Section 3 of {ref}, middle paragraph"]
?
i.e. {ref}
is the placeholder
from asciidoctor-bibliography.
@ronaldtse seems fair to me.
Just for clarity, These two lines would produce the same exact output:
cite:[Aa2017, prefix="see ", suffix=" if you will"]
cite:[Aa2017, text="see {ref} if you will"]
from asciidoctor-bibliography.
@paolobrasolin totally fine with me. Thanks @paolobrasolin !
from asciidoctor-bibliography.
OK, let me know when ready.
from asciidoctor-bibliography.
I have <<crossreference#fragment,section_number (of|comma|parens|bare): text>>
in Asciidoc, which allows #fragment
to be appended to any URL for the reference. Would that fragment
correspond to the locator argument of the macro?
from asciidoctor-bibliography.
This is how I've reconstructed what the expected asciidoc-bibliography format would be, in the README. Let me know if this is ok:
Integration with the asciidoc-bibliography gem proceeds as follows:
. Create an RFC XML references file, consisting of a `<references>` element with individual `<reference>` elements inserted,
as would be done for the informative and normative references normally. The references file will contain all possible
references to be used
in the file; the bibliography gem will select which references have actually been cited in the document.
.. Rather than hand crafting RFC XML references for RFC documents, you should download them from an authoritative
source; e.g. http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml
.. Unlike the case for RFC XML documents created manually, the references file does not recognise XML entities
and will not attempt to download them during processing.
Any references to http://xml.resource.org/public/rfc/bibxml/ will need to be downloaded and inserted into the references file.
.. The RFC XML in the references file will need to be appropriate to the version of RFC XML used in the main document, as
usual. Note that RFC XML v2 references are forward compatible with v3; v3 contains a couple of additional elements.
. Add the following header attributes to the main document:
+
--
`:bibliography-database:` :: The name of the references file; this is expected to be in the same directory as
the main document.
`:bibliography-passthrough:` ::
`:bibliography-prepend-empty:` ::
`:bibliography-hyperlinks:` ::
`:bibliography-style:` :: The style of reference used in the references file; the recognised styles are `rfc-v2` and
`rfc-v3`, for RFC XML v2 and RFC XML v3 respectively.
--
. References to a normative reference are inserted with the macro `cite:norm[id]` instead of `<<id>>`, where `id` is
the anchor of the reference.
. References to an infomrative reference are inserted with the macro `cite:info[id]` instead of `<<id>>`, where `id` is
the anchor of the reference.
.. Arbitrary text associated with a crossreference is inserted with a `text` attribute, and fragment references are
inserted with a `locator` attribute. Using `cite:norm`:
*** NOTE: To be implemented next week
*** `<<id,words>>` = `cite:norm[id, text="words"]`
*** `<<id,format=counter: words>>` (processed as a formatted crossreference) = `cite:norm[id, text="format=counter: words"]`
*** `<<id,2.4 comma: words>>` (processed as relref) = `cite:norm[id, text="2.4 comma: words"]`
*** `<<id#section2_4,2.4 comma: words>>` (processed as relref with a cross-document internal reference) = `cite:norm[id, text="2.4 comma: words" location="section2_4"]`
. Normative and Informative References are inserted in the document through a macro, which occurs where the RFC XML
references would be inserted
+
[source,asciidoc]
--
[bibliography]
== Normative References
++++
bibliography::norm[]
++++
[bibliography]
== Informative References
++++
bibliography::info[]
++++
--
. In order to preprocess the macros, the asciidoctor-bibliography gem is passed as an `-r` argument to the
asciidoctor-rfc invocation:
** `bin/asciidoctor-rfc2 -r asciidoctor-bibliography spec/examples/refs-v2.adoc`
** `bin/asciidoctor-rfc3 -r asciidoctor-bibliography spec/examples/refs-v3.adoc`
from asciidoctor-bibliography.
The arbitrary-text feature is implemented in #63.
The "bug" outlined in #61 is partially fixed in #62.
The required asciidoctor-bibliography
options are
:bibliography-database: refs-v2-database.xml
:bibliography-passthrough: citations
:bibliography-prepend-empty: false
:bibliography-hyperlinks: false
:bibliography-style: rfc-v2
Citing with ´cite:norm[RFC0000]´ (resp. info
) will get you the correct xref
tag for both V3 and V3.
To produce bibliographies, you can
[bibliography]
== Normative References
++++
bibliography::norm[]
++++
[bibliography]
== Informative References
++++
bibliography::info[]
++++
To get advanced features for V3, you can just feed in the rendered tag.
cite:norm[RFC0000, text="<relref ...> ... </relref>"]
(Note: I'll update the demo in bibliography
branch as soon as we merge #62 and #63)
I thought about parsing some extra options, parsing them and rendering through CSL, but:
asciidoctor-bibliography
should be agnostic, so it shouldn't be tied to a document format; this means that maybe we should do it, but as a small extension included inasciidoctor-rfc
instead;- given we're using
<<..>>
interpolation, implementing new options forcite:[]
(options that the user wouldn't even see) seems to me like unnecessary work.
The rfc-v2
and rfc-v3
styles cover bibliographies, citations for V2 and base citations for V3. The text
option should allow you to get any XML you need in there without interference. In essence, we're using asciidoctor-bibliography
through asciidoctor-rfc
mostly for its bookkeeping and the simple styles. Am I forgetting anything @opoudjis?
from asciidoctor-bibliography.
Welp, it's working.
I'm not in love with making people redundantly give the anchors twice in the macro (the {cite} interpolation does not work), or in fact with making people put raw XML in the macro at all; but I understand that we don't have that much wiggle room here.
I've incorporated the citation macros into the asciidoctor-rfc readme and rspec:
cite:info[RFC2119, text="<xref format='counter' target='RFC2119'>RFC 2119</xref>"]
cite:info[RFC2119, text="<relref displayFormat='comma' section='2.4' target='RFC2119'/>"]
cite:info[RFC2119, text="<relref relative='section2_4' displayFormat='comma' section='2.4' target='RFC2119'/>"]
And <<id,words>>
ends up as cite:norm[id, text="<xref target='id'>words</xref>"]
. Which is... well, it's not succinct.
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
- Feature request: Styling per bibliography
- 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.