riboseinc / asciidoctor-bibliography Goto Github PK

asciidoctor-bibliography don't seem to handle a citation inside a footnote, which is a rather common scenario

I'm using alphabetical now but the bibliography comes out like this:

[18] T. P. A. AICPA, “Trust Services Principles, Criteria and Illustrations,” American Institute of Certified Public Accountants, Inc., New York, USA, AICPA, 2014.

[16] BSI, “Specification of common management system requirements as a framework for integration,” British Standards Institution, London, United Kingdom, PAS 99:2012, 2012.

[4] BSI, “Occupational health and safety management systems—Specifications,” British Standards Institution, London, United Kingdom, BS OHSAS 18001:2007(E), 2007.

However, the citation numbers themselves should also be according to this order.

[1] T. P. A. AICPA, “Trust Services Principles, Criteria and Illustrations,” American Institute of Certified Public Accountants, Inc., New York, USA, AICPA, 2014.

[2] BSI, “Specification of common management system requirements as a framework for integration,” British Standards Institution, London, United Kingdom, PAS 99:2012, 2012.

[3] BSI, “Occupational health and safety management systems—Specifications,” British Standards Institution, London, United Kingdom, BS OHSAS 18001:2007(E), 2007.

The gem allows all CSL styles that can be found in csl/styles, such as:

:bibliography-reference-style: din-1505-2-alphanumeric

We should update the README to show this.

I have BibLatex (not bibtex) file and this extension throws:
Failed to load AsciiDoc document - Option :bibliography-database: is mandatory. A bibliographic database is required.
I am sure that this attribute is set, I tested both in the header and command line, so I guess this is a problem in misunderstanding the bibfile as it is biblatex.

In asciidoctor-rfc, I have special processing of particular replacement text in cross references:

<<RFC5322,2.1.1 comma>>

is expected to convert into

<relref section="2.1.1" displayFormat="comma" target="RFC5322"/> (v3)
<xref target="RFC5322">[RFC5322], Section 2.1.1</xref> (v2)

Whatever is going on in cite:[xxxx] with asciidoctor-bibliography, I want those cross-references to work like that still. Right now they don't, because the target RFC5322 is being replaced by asciidoctor-bibliography with bibliography-RFC5322.

Even if that didn't happen, I would expect that cite macros would permit me my own alternate text, just as <<crossref,alttext>> does in Asciidoctor, and <xref target="crossref">alttext</xref> does in RFC XML. The fact that asciidoctor-bibliography supplies its own crossreference text depending on style is irrelevant to the requirements of RFC XML.

So in fact, I would expect cite:[xxxx] and cite:[xxxx,yyyy] to behave identically to <<xxxx>> and <<xxxx,yyyy>> in Asciidoctor, and to be processed by inline_anchor_xref() in asciidoctor-rfc.

I know these tickets are likely a radical change in spec to asciidoctor-bibliography. But without them, this gem does not contribute to authoring usable RFC XML.

I have some bib files that provide the shorthand attribute. E.g.,

%ISO 31000:2009(E)
@techreport{iso:31000,
  author = {ISO},
  institution = {International Organization for Standardization},
  address = {Geneva, Switzerland},
  title = {Risk management---Principles and guidelines},
  number = {31000:2009},
  shorthand = {ISO 31000:2009},
  type = {ISO},
  year = {2009}
}

% ISO Guide 73:2009
@techreport{iso:guide73,
  author = {ISO},
  institution = {International Organization for Standardization},
  address = {Geneva, Switzerland},
  title = {Risk management---Vocabulary},
  number = {73:2009(E/F)},
  shorthand = {ISO Guide 73:2009},
  type = {ISO Guide},
  year = {2013}
}

I'd like to have a mode that provides a citation using the shorthand, e.g., "[ISO:31000:2009]", instead of "[16]". With this mode obviously not all bib infos have the "shorthand" which could fall back to "authoryear" or just pure numbers ("[16]").

One first improvement would be to allow for a bibpunct option in header that allows the full range of styling one is used to.

A second step is to allow a complete analogy to TeX syntax.
On one hand, it'd be nice to have automatically defined locators (making them localizable is not trivial), on the other hand a user coming from the TeX world is more or less accustomed to inputting an arbitrary string, like in \cite[prefix][postfix]{key}.
I feel that in the short term getting the prefix/postifix working would have the highest payoff. And maybe then the parser could treat pure lists of numbers as page ranges as an (optional) shortcut (as some LaTeX packages do).

Also, there's the possibility to simply implement the TeX citation styles as CSL styles themselves and not write any custom code.

Just some food for thought. Do you think custom locators should have higher riority than prefix/suffix? @ronaldtse

This should be pretty cheap and would assure all styles are rendered correctly and directly in the correct format (instead of regexping our way around html a posteriori).

Now we support authoryear and numbers but the gem doesn't provide functionality to do simple citations like "[16]". Could we have another option such as purenum to enable this?

Or better year, make number show "[16]" and authornum show "AuthorLastName [16]" ?

In a chain multiple citation cite:[key1]+[key2]+[key3] just a white space breaks the chain, so cite:[key1]+[key2]+ [key3] ignores the third item. I do not know how Asciidoctor tokenizes the text-block and if it is possible to ignore white spaces. I also do not know if there could be cases where ignoring white space might cause globing too much. Otherwise it might be easier for the writer to care less about possible white-spaces in between the chain. This might happen, especially, when the chain is spread over two lines.

Alternatively, a suggestion might be to support cite:[key1;key2;key3].

My document is actually not compiling using 0.4.x but is perfect with 0.2.x / 0.3.x.

It seems that in 0.4.x the includes:: directive is not working at all. Maybe there is some place that the gem is parsing and taking away the directive from the original asciidoctor engine?

Originally from metanorma/asciidoctor-rfc#76

I think the new way of using a large XML file with all references could be broken down to individual files -- in this repo (https://github.com/riboseinc/rfc-in-asciidoc-template) I included the "IncludeGlobProcessor" to allow the "*" file filter syntax for including all files in a directory.

We can allow a new option called bibliography-database to take a directory to include all BibTeX and BibXML files within and parse them into our gem's "database" (so as to speak).

What do you think?

cc: @opoudjis

EDIT: Please delete this issue. Everything works as expected. Sorry !!!!

Unfortunately, I don't know where to place my question, so I'll place it here once.

There is the possibility to define your own styles. Suppose I have generated a style "test.csl" and it is located in the same directory as my adoc-file.

The following code does not work:

= My first document using asciidoctor-bibliography
:bibliography-database: test.bib
:bibliography-style: test.csl

Compiling leads to:

asciidoctor: FAILED: C:/test/test.adoc: Failed to load AsciiDoc document - no CSL node: nil

How do I integrate these own styles?

Since @opoudjis pinged me on this, I think the next thing is to adopt the new bibliography data model in https://github.com/riboseinc/isodoc-models .

@paolobrasolin thoughts?

The current default style is APA. But the style we want for inline citations is the reference abbreviation in brackets; so the inline citation of RFC5322 should be in fact [RFC5322], not (Resnick, 2008). Is there such a reference style in CSL? If not, can we make one? I'm nervous about APA-style citations making it into RFC XML.

When these are not set the gem crashes:

:bibliography-database: biblio.bib
:bibliography-citation-style: authoryear

Trace:

...gems/asciidoctor-bibliography-0.0.1.dev/lib/asciidoctor-bibliography/database.rb:12:in `extname': asciidoctor:
FAILED: main.adoc: Failed to load AsciiDoc document - no implicit conversion of nil into String (TypeError)

Should:

• allow processing even when there is no set database
• set a default :bibliography-citation-style: e.g., authoryear

This error happens on 0.4.1...

NoMethodError: asciidoctor: FAILED: /Users/me/src/ribose-crimson/crimson/main.adoc: Failed to load AsciiDoc document - undefined method `lines' for nil:NilClass
  /Users/me/.rbenv/versions/2.3.3/lib/ruby/gems/2.3.0/gems/asciidoctor-bibliography-0.4.1/lib/asciidoctor-bibliography/asciidoctor/bibliographer_preprocessor.rb:40:in `fetch_citations'

Better error handling?

More content needed in README though.

The execution of asciidoctor currently assumes that the bibliography-database is in the current directory where the executable is run. Consistent with how asciidoctor works, the bibliography-database should be assumed to be in the same directory as the asciidoc file.

So:

./bin/asciidoctor-rfc2 --trace -r asciidoctor-bibliography spec/examples/rfc6350.adoc

Is expecting to find rfc6350.bib in ./ . It should in fact expect to find it in spec/examples/ .

Are in https://xml2rfc.tools.ietf.org and zipped. If that helps?

In particular, sample bibliography needs more examples of RFCs!

https://tm.uka.de/~bless/rfc.bib has all RFCs in Bibtex; that'd be useful to cite in README too.

Thanks for this great extension. Very easy to use and useful.
When using a reference to an edited book and apa style, the reference shows up incorrectly. Not sure if asciidoctor-bibliography is responsible for this or if there’s a bug in apa style (unlikely) or in zotero export to bibtex (unlikely) or if I’m doing something incorrect (likely).

cite.bib

@book{myref,
	title = {The title},
	editor = {The Editor},
	year = {2010}
}

cite.adoc

= Test
:bibliography-database: cite.bib
:bibliography-style: apa

A test citep:[myref].

bibliography::[]

$ asciidoctor -r asciidoctor-bibliography cite.adoc
produces:

Test
A test (2010).
Editor, T. (Ed.). (2010). The title.

but I expected:

Test
A test (Editor, 2010).
Editor, T. (Ed.). (2010). The title.

I have two bibliography entries in my .bib file with the same author and year of publication (see below). I typically append a and b on the key to distinguish the entries (e.g., Cheung_2009a and Cheung_2009b). When I convert the AsciiDoc to html using asciidoctor -r asciidoctor-bibliography text.adoc both entries are referred to as Cheung, 2009 on the html document. Is there a way form me to have Cheung, 2009a and Cheung, 2009b on the html document instead of having Cheung, 2009 for both entries? I am using :bibiliography-style: apa. Thanks very much for this very useful extension.

@Article{Cheung_2009a,
author = {Mike W.-L. Cheung},
title = {Comparison of Methods for Constructing Confidence Intervals of Standardized Indirect Effects},
number = {2},
pages = {425--438},
volume = {41},
date = {2009},
doi = {10.3758/brm.41.2.425},
journaltitle = {Behavior Research Methods},
publisher = {Springer Nature},
}

@Article{Cheung_2009b,
author = {Mike W.-L. Cheung},
title = {Constructing Approximate Confidence Intervals for Parameters With Structural Equation Models},
number = {2},
pages = {267--294},
volume = {16},
date = {2009},
doi = {10.1080/10705510902751291},
journaltitle = {Structural Equation Modeling: A Multidisciplinary Journal},
publisher = {Informa {UK} Limited},
}

When using the asciidoctor-epub3 gem, if I define :bibliography-database: in the spine document, asciidoctor-bibliography fails to keep that value when parsing included documents. This leads to a crash as documented in issue #9.

asciidoctor-bibliography creates the bibliography as expected when generating HTML or PDF with asciidoctor. It also works as expected if I define :bibliography-database: in every included document, but that partially defeats the purpose of the include macro.

Here some sample script output, with the full path elided:

$ bundle exec asciidoctor-epub3 -r asciidoctor-bibliography sample.adoc
asciidoctor: FAILED: .../bibliography-sample/sample.adoc: Failed to load AsciiDoc document - asciidoctor: FAILED: .../bibliography-sample/sample-2.adoc: Failed to load AsciiDoc document - Option :bibliography-database: is mandatory.
A bibliographic database is required.
  Use --trace for backtrace

While I don't get any error or warning when compiling, the generated bibliography misses multiple items.

The bibliography section of my thesis:

[bibliography]
== Bibliography

bibliography::[]

A paragraph from my thesis:

The Advanced Research Projects Agency Network (ARPANET),
an early network connecting many major universities and
research institutions in the USA,
was first demonstrated publicly in October 1972
cite:[roberts_arpanet_1986, page=3].
It was initially funded by the United States
Department of Defense during the cold war as a part of
"the command and control assignment" of the ARPA program
cite:[lukasik_why_2011, page=10].
The ((ARPANET)) was designed to be "as distributed as possible,"
because its routing algorithm was adapted from an article by Paul Baran,
written at the time he was at the RAND Corporation researching
on highly survivable communication networks "in the thermonuclear era"
cite:[baran_distributed_1964, page=18].
With the support of the US National Science Foundation, ARPANET gradually
"evolved into a commercial, worldwide open network" -- the Internet
cite:[dommering_internet:_2015, page=13].

While all the citations are generated as expected, the lukasik_why_2011 is missing in the bibliography section. Its citation is linked to #bibliography-default-lukasik_why_2011, but the target is missing.

I event tried to generate it by putting bibliography::lukasik_why_2011[] in the text, but the result was empty.

Here is the article entry in my database:

@article{lukasik_why_2011,
	title = {Why the {Arpanet} {Was} {Built}},
	volume = {33},
	issn = {1058-6180},
	url = {http://ieeexplore.ieee.org/document/5432117/},
	doi = {10.1109/MAHC.2010.11},
	language = {en},
	number = {3},
	urldate = {2019-02-20},
	journal = {IEEE Annals of the History of Computing},
	author = {Lukasik, Stephen},
	month = mar,
	year = {2011},
	pages = {4--21},
	file = {Lukasik - 2011 - Why the Arpanet Was Built.pdf:/Users/reza/Zotero/storage/I4F9Y8VI/Lukasik - 2011 - Why the Arpanet Was Built.pdf:application/pdf}
}

Is there any way to get more logs from the tool when compiling?

Thanks for all your fixes. I've noticed a strange bug when using asciiidoctor-bibliography to convert to DocBook. The following works fine:

:bibliography-database: refs.bib
:bibliography-style: ieee
...
Look for further information in the GNU Make manual cite:[GMAKE].
Some text.
#Some highlighted text.#

But if I replace the last line with:

[.sb]#Some text in semibold#.

Asciidoctor-bibliography gets confused, the DocBook output is:

<simpara>Look for further information in the GNU Make manual <link 
linkend="bibliography-default-GMAKE"><phrase role="1&rsqb;</link>.
Some text.
[.sb">Some text in semibold.</phrase></simpara>"""

Currently we only support "numbers" and "authoryear" citation styles:

:bibliography-citation-style: numbers

We should support more "citation key" styles. The CSL library already provides multiple styles we could use:

• "[HiNJ16]" from DIN 1505-2 (alphanumeric, German)
• "[3]" the numeric style
• "AuthorLastName (YEAR)" authoryear, etc.

I strongly recommend that the differentiation between normative and informative bibliography items occur through attributes of the bibtex item: e.g. possibly

@misc{RFC3536,
bibliography="informative",
}

or

@misc{RFC3536,
bibliography="normative",
}

Once that is done, instead of having a single macro instance bibliography::[], we would have two instances, one for each type of bibliography:

[bibliography]
== References

[bibliography]
=== Normative References
bibliography::[normative]

=== Informative References
bibliography::[informative]

If there is an empty citation cite:[], even in a commented block, it stops and alarms: "Failed to load AsciiDoc document - No entry with id '' was found in the bibliographic database". There are two things to consider:
1- A comment block is comment and should not be converted
2-It is common to put an empty citation cite:[] to fill in later. In latex those empty citations \cite{} are translated to ?? so the user would see them later in the text.

DockBook has citation tag <citation> but Asciidoctor does not support that (yet). Regarding that asciidoctor-bibliography already parse citations it can also add this support.
I do not know if Asciidoc -> DocBook is still common for most of users or not, but Asciidoc -> DocBook -> (Xe)Latex is still the most reliable way of creating Latex document from asciidoc and get the Tex family typesetting quality features.

If more than two citations are used in a multi-citation, only the first and the last elements are used:

foo.adoc:

= Test
:bibliography-database: bibliography.bib

== Chapter

cite:[keyA]+[keyB]+[keyC]+[keyD]

== Bibliography

bibliography::[]

bibliography.bib:

@book{keyA,
  title = {Title A},
  author = {Author A},
  year = {2015},
}

@book{keyB,
  title = {Title B},
  author = {Author B},
  year = {2016},
}

@book{keyC,
  title = {Title C},
  author = {Author C},
  year = {2017},
}

@book{keyD,
  title = {Title D},
  author = {Author D},
  year = {2018},
}

command:

asciidoctor -r asciidoctor-bibliography foo.adoc

output:

Tested with the HEAD of this repo, asciidoctor 1.5.8 and 2.0.10dev (from the repo)

@paolobrasolin we should have some tests that guard against the issue we had with #46 .

Basically to ensure original asciidoctor functionality doesn't get broken with our gem. Thanks!

Similar to the bibtex \nocite{*} command, I propose a nocite:[..] macro to include entries in the bibliography without explicitly citing them.

I openend a pull request #90 that implements that although I do not claim this would be the best way to do this.

For example in the IEEE style, this:

cite:[iso:27001, clause="6.1.2 c 2"]

Will show:

[2]

It should show something like:

[2] (Clause 6.1.2 c 2)
# or
Clause 6.1.2 c 2 of [2]

In RFC XML v3, citations may be of not only reference elements, but also of referencegroup elements, which group multiple reference elements together. So the following citation should be possible:

cite:info[RFC3552_5226]

citing:

<referencegroup anchor="RFC3552_5226">
  <reference anchor="RFC3552" target="https://www.rfc-editor.org/info/rfc3552">
<front>
<title>
Guidelines for Writing RFC Text on Security Considerations
</title>
<author initials="E." surname="Rescorla" fullname="E. Rescorla">
<organization/>
</author>
<author initials="B." surname="Korver" fullname="B. Korver">
<organization/>
</author>
<date year="2003" month="July"/>
<abstract>
<t>
All RFCs are required to have a Security Considerations section. Historically, such sections have been relatively weak. This document provides guidelines to RFC authors on how to write a good Security Considerations section. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.
</t>
</abstract>
</front>
<seriesInfo name="BCP" value="72"/>
<seriesInfo name="RFC" value="3552"/>
<seriesInfo name="DOI" value="10.17487/RFC3552"/>
</reference>
<reference anchor="RFC5226" target="https://www.rfc-editor.org/info/rfc5226">
<front>
<title>
Guidelines for Writing an IANA Considerations Section in RFCs
</title>
<author initials="T." surname="Narten" fullname="T. Narten">
<organization/>
</author>
<author initials="H." surname="Alvestrand" fullname="H. Alvestrand">
<organization/>
</author>
<date year="2008" month="May"/>
<abstract>
<t>
Many protocols make use of identifiers consisting of constants and other well-known values. Even after a protocol has been defined and deployment has begun, new values may need to be assigned (e.g., for a new option type in DHCP, or a new encryption or authentication transform for IPsec). To ensure that such quantities have consistent values and interpretations across all implementations, their assignment must be administered by a central authority. For IETF protocols, that role is provided by the Internet Assigned Numbers Authority (IANA).
</t>
<t>
In order for IANA to manage a given namespace prudently, it needs guidelines describing the conditions under which new values can be assigned or when modifications to existing values can be made. If IANA is expected to play a role in the management of a namespace, IANA must be given clear and concise instructions describing that role. This document discusses issues that should be considered in formulating a policy for assigning values to a namespace and provides guidelines for authors on the specific text that must be included in documents that place demands on IANA.
</t>
<t>
This document obsoletes RFC 2434. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.
</t>
</abstract>
</front>
<seriesInfo name="RFC" value="5226"/>
<seriesInfo name="DOI" value="10.17487/RFC5226"/>
</reference>
</referencegroup>

Currently it crashes, complaining that the reference RFC3552_5226 could not be found. (I've put this example into the asciidoctor-rfc rspec.)

In v3, cite:info[RFC2119] is supposed to render as <xref target="RFC2119"/>; it is ending up rendering incorrectly as <relref target="RFC2119"/>.

As far as I can tell, that's occurring inside the gem: it happens when I run it just as asciidoctor -r asciidoctor-bibliography refs-v3.adoc

The problem is that in v3, there is differential output depending on the format of what is contained in the added text: a relref is indeed expected if the Asciidoc crossreference is of format <<id,\S+ (of|comma|parens|bare)(: )?(.*)$/, with attributes extracted by inline_anchor_xref()

Does the asciidoctor-bibliography gem have to replicate the work of inline_anchor_xref(), or can it output an Asciidoc <<x,y>> reference, which can then be processed by inline_anchor_xref()?

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.

This style gives me a sorted bibliography, which is correct:

:bibliography-reference-style: din-1505-2-alphanumeric
:bibliography-citation-style: numbers
:bibliography-order: alphabetical

Output:

[aicpa:tsp100] AICPA, Technical Practice Aids: Trust Services Principles, Criteria and Illustrations (AICPA). New York, USA : American Institute of Certified Public Accountants, Inc., 2014

[cdsa:cps] CDSA: Content Protection & Security Standard and Guidance (CDSA). New York, USA : Content Delivery & Security Alliance, 2014

However, this gives me an unsorted one:

:bibliography-reference-style: ieee
:bibliography-citation-style: numbers
:bibliography-order: alphabetical

Output:

[1]CDSA, “Content Protection & Security Standard and Guidance,” Content Delivery & Security Alliance, New York, USA, CDSA, Mar. 2014.

[2]ISO, “Quality management systems—Requirements,” International Organization for Standardization, Geneva, Switzerland, ISO 9001:2015(E), 2015.

[3]ISO, “Environmental management systems—Requirements with guidance for use,” International Organization for Standardization, Geneva, Switzerland, ISO 14001:2015(E), 2015.

Given the file test.adoc (which includes the bibliography macro but does not use any citations):

:bibliography-database: /tmp/ref.bib
:bibliography-style: ieee

# This is a test file

And some example text.

bibliography::[]

When I run asciidoctor -r asciidoctor-bibliography --trace test.adoc, I get the following:

asciidoctor -r asciidoctor-bibliography --trace test.adoc Traceback (most recent call last):
        22: from /usr/local/bin/asciidoctor:23:in `<main>'
        21: from /usr/local/bin/asciidoctor:23:in `load'
        20: from /var/lib/gems/2.5.0/gems/asciidoctor-1.5.7.1/bin/asciidoctor:14:in `<top (required)>'
        19: from /var/lib/gems/2.5.0/gems/asciidoctor-1.5.7.1/lib/asciidoctor/cli/invoker.rb:112:in `invoke!'
        18: from /var/lib/gems/2.5.0/gems/asciidoctor-1.5.7.1/lib/asciidoctor/cli/invoker.rb:112:in `each'
        17: from /var/lib/gems/2.5.0/gems/asciidoctor-1.5.7.1/lib/asciidoctor/cli/invoker.rb:129:in `block in invoke!'
        16: from /var/lib/gems/2.5.0/gems/asciidoctor-1.5.7.1/lib/asciidoctor.rb:1589:in `convert_file'
        15: from /var/lib/gems/2.5.0/gems/asciidoctor-1.5.7.1/lib/asciidoctor.rb:1589:in `open'
        14: from /var/lib/gems/2.5.0/gems/asciidoctor-1.5.7.1/lib/asciidoctor.rb:1589:in `block in convert_file'
        13: from /var/lib/gems/2.5.0/gems/asciidoctor-1.5.7.1/lib/asciidoctor.rb:1473:in `convert'
        12: from /var/lib/gems/2.5.0/gems/asciidoctor-1.5.7.1/lib/asciidoctor.rb:1361:in `load'
        11: from /var/lib/gems/2.5.0/gems/asciidoctor-1.5.7.1/lib/asciidoctor/document.rb:559:in `parse'
        10: from /var/lib/gems/2.5.0/gems/asciidoctor-1.5.7.1/lib/asciidoctor/document.rb:559:in `each'
         9: from /var/lib/gems/2.5.0/gems/asciidoctor-1.5.7.1/lib/asciidoctor/document.rb:560:in `block in parse'
         8: from /var/lib/gems/2.5.0/gems/asciidoctor-1.5.7.1/lib/asciidoctor/document.rb:560:in `[]'
         7: from /var/lib/gems/2.5.0/gems/asciidoctor-bibliography-0.8.0/lib/asciidoctor-bibliography/asciidoctor/bibliographer_preprocessor.rb:18:in `process'
         6: from /var/lib/gems/2.5.0/gems/asciidoctor-bibliography-0.8.0/lib/asciidoctor-bibliography/asciidoctor/bibliographer_preprocessor.rb:31:in `process_lines'
         5: from /var/lib/gems/2.5.0/gems/asciidoctor-bibliography-0.8.0/lib/asciidoctor-bibliography/asciidoctor/bibliographer_preprocessor.rb:53:in `render_indices'
         4: from /var/lib/gems/2.5.0/gems/asciidoctor-bibliography-0.8.0/lib/asciidoctor-bibliography/asciidoctor/bibliographer_preprocessor.rb:53:in `map'
         3: from /var/lib/gems/2.5.0/gems/asciidoctor-bibliography-0.8.0/lib/asciidoctor-bibliography/asciidoctor/bibliographer_preprocessor.rb:56:in `block in render_indices'
         2: from /var/lib/gems/2.5.0/gems/asciidoctor-bibliography-0.8.0/lib/asciidoctor-bibliography/index.rb:17:in `render'
         1: from /var/lib/gems/2.5.0/gems/asciidoctor-bibliography-0.8.0/lib/asciidoctor-bibliography/index.rb:44:in `setup_formatter'
/var/lib/gems/2.5.0/gems/asciidoctor-bibliography-0.8.0/lib/asciidoctor-bibliography/index.rb:53:in `prepare_filtered_db': asciidoctor: FAILED: /tmp/test.adoc: Failed to load AsciiDoc document - undefined method `map' for nil:NilClass (NoMethodError)

This fails because it assumes the bibliographer's occuring_keys map is empty, since no citations are present in test.adoc.

Folks, yesterday I updated from 0.7.2 to 0.8.0. It broke it: gave me an error that the first thng I cited was not in the database file (which it was). I uninstalled 0.8.0 (which put me back to 0.7.2), and everything worked.

I know I'm using a slightly older version of Ruby:
ruby 2.4.2p198 (2017-09-14 revision 59899) [x64-mingw32]
Could that be the issue?
Thanks.

P.S. The citation about which it complained was in a comment block.

When I cite an item that isn't in the database file, the gem throws a "nil cannot be converted to string" error.

What happens is actually the "find" method is unable to find the item, then the immediate subsequent code assumes the return is a string instead of nil.

I think we should offer proper StandardError classes for expected errors, such as BibItemNotFoundInDatabase, to directly tell the user what is missing and how to fix it.

There are many places in our code where "success" is assumed. We need to implement better resilience.

There is a bug in the adoc formatter CiteProc::Ruby::Formats::Adoc due to a typo.

I'd assumed that this gem would take bibtex input, and output native RFC XML bibliography; e.g.

Input:

@misc{RFC3536,
  author="P. Hoffman",
  title="{Terminology Used in Internationalization in the IETF}",
  howpublished="RFC 3536 (Informational)",
  series="Internet Request for Comments",
  type="RFC",
  number="3536",
  pages="1--30",
  year=2003,
  month=may,
  issn="2070-1721",
  publisher="RFC Editor",
  institution="RFC Editor",
  organization="RFC Editor",
  address="Fremont, CA, USA",
    note="Obsoleted by RFC 6365",
url="https://www.rfc-editor.org/rfc/rfc3536.txt",
  key="RFC 3536",
  abstract={This document provides a glossary of terms used in the IETF when discussing internationalization.  The purpose is to help frame discussions of internationalization in the various areas of the IETF and to help introduce the main concepts to IETF participants.  This memo provides information for the Internet community.},
  keywords="internet engineering task force",
  doi="10.17487/RFC3536",
  }

Output (RFC XML v2):

<references>
<reference anchor="RFC3536" target="https://www.rfc-editor.org/rfc/rfc3536.txt">
<title>Terminology Used in Internationalization in the IETF</title>
<author surname="Hoffman" initials="P."/>
<date month="May" year="2003"/>
<seriesInfo name="RFC" value="3536"/>
</reference>
</references>

Instead, as far as I can tell, the output is:

Hoffman, P. (2003, May). Terminology Used in Internationalization in the IETF. RFC, Fremont, CA, USA: RFC Editor. 

I hate to say this, but this is useless for asciidoctor-rfc. If bibliography::[] is not generating XML with that markup, it is not generating anything that can be used in asciidoctor-rfc.

What I assume this means is, creating a new CSL definition which understands RFC XML's notions of authors, dates, and series.

... @paolobrasolin, I assume we'll need to work on this together? The notion of seriesInfo is presumably idiosyncratic to RFC.

Citations within the asciidoctor inline source code environment (backticks) get parsed. This may not be desired as source code environments are often used to actually explain source code behaviour.

So `cite:[some_key]` gets parsed to (Autor, Year) or whatever style you're using, instead of just staying cite:[some_key].

Emerged from #70