Allow citation with arbitrary text

paolobrasolin commented 7 years ago

An option to allow an (hyperlinked) citation to be rendered using arbitrary text is desirable. This was indirectly suggested in #56.

The current syntax for affixes and custom locators to be embedded in CSL rendered styles is

cite:[Aa2017, locator=" halfway through"]
cite:[Aa2017, prefix="see ", suffix=" if you will"]

I suggest using an option superceding the three above, like

cite:[Aa2017, text="This would be the rendered stuff"]

We could also use a macro with another name, or an unnamed parameter (i.e. the second one by convention); I'm pretty biased against these possibilites, though, as I think we should prefer clarity over a marginally terser syntax.

ronaldtse commented 7 years ago

@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

paolobrasolin commented 6 years ago

@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"]

ronaldtse commented 6 years ago

@paolobrasolin totally fine with me. Thanks @paolobrasolin !

opoudjis commented 6 years ago

OK, let me know when ready.

opoudjis commented 6 years ago

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?

opoudjis commented 6 years ago

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`

paolobrasolin commented 6 years ago

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 in asciidoctor-rfc instead;
given we're using <<..>> interpolation, implementing new options for cite:[] (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?

opoudjis commented 6 years ago

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.

opoudjis commented 6 years ago

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.

riboseinc / asciidoctor-bibliography

Allow citation with arbitrary text #59