asciidoc-bib ¶ ↑

Add references from a bibtex file to an asciidoc file.

Features:

simple syntax for adding a citation within text and placing bibliography
formatting of references and reference list according to range of styles supported by citeproc-ruby
supports some styling of citation text (page numbers, bracket placement, and pretext)
multiple references within a single citation
groups consecutive numeric references, e.g. [1,2,3] -> [1-3]
use either:
- by transforming source text to include references and full reference list
- with asciidoctor extension for single-pass compilation of document with references

Install¶ ↑

> gem install asciidoc-bib

Installs two executable programs:

‘asciidoc-bib’ for transforming source text into asciidoc
‘asciidoctor-bib’ uses asciidoctor extension for single-pass output

asciidoc-bib depends on bibtex-ruby, citeproc-ruby and csl-styles. (Ensure ‘ruby-dev’ and ‘libxslt1-dev’ are installed, so the dependencies will compile.)

asciidoctor must also be installed for ‘asciidoctor-bib’ to work; version 2.3.1 requires asciidoctor version 1.5.2 or higher.

Use ¶ ↑

There are two ways of using asciidoc-bib.

The first is required if using asciidoc. ‘asciidoc-bib’ works by transforming an asciidoc document containing syntax to include citations and a bibliography. The transformed document will contain a complete reference and bibliography list where indicated, and can then be processed further by asciidoc’s toolchain to produce a completed document.

The second is for asciidoctor only, and uses its extension mechanism to provide a single pass compilation of your documentation, including references. ‘asciidoctor-bib’ works as a replacement for asciidoctor. (Currently, asciidoctor command-line options are not supported.)

Styles must be one of those supported by CSL: github.com/citation-style-language/styles

Include a citation¶ ↑

Syntax for inserting a citation is [cite|citenp:(pretext:)ref(,pages)] where ‘pretext’ and ‘pages’ are optional. The ref and optional pages may be repeated multiple times, separated by ‘;’. A citation must be complete on a single line of text.

Examples of chicago-author-date style:

[cite:Lane12]: becomes “(Lane 2012)”
[citenp:Lane12]: becomes “Lane (2012)”
[cite:Lane12,59]: becomes “(Lane 2012, 59)”
[cite:See:Lane12,59]: becomes “(See Lane 2012, 59)”
[cite:See:Lane12,59;Lane11]: becomes “(See Lane 2012, 59; Lane 2011)”

For apa (Harvard-like) style:

[cite:Lane12]: becomes “(Lane, 2012)”
[citenp:Lane12]: becomes “Lane (2012)”
[cite:Lane12,59]: becomes “(Lane, 2012, p.59)”

For ieee, a numeric style:

[cite:Lane12;Lane11]: becomes “[1, 2]”
[cite:See:Lane12,59;Lane11]: becomes “See [1 p.59, 2]”

Place bibliography in text¶ ↑

[bibliography]: on a line by itself.

Processing text: Asciidoc¶ ↑

> asciidoc-bib filename.txt

Looks for a bib file in current folder and in ~/Documents.

Outputs a new file: filename-ref.txt which includes your references.

Check the new file, and process in the usual way with asciidoc.

Command-line options:

> asciidoc-bib -h
Usage: asciidoc-bib filename
    -h, --help                       help message
    -b, --bibfile FILE               location of bib file
    -n, --no-links                   do not add internal links
        --numeric-alphabetic-order
                                     sort numeric styles in alphabetical order (DEFAULT)
        --numeric-appearance-order
                                     sort numeric styles in order of appearance
    -s, --style STYLE                reference style
    -v, --version                    show version

All styles available through CSL are supported.
The default style is 'apa'.

Processing Text: Asciidoctor¶ ↑

> asciidoctor-bib filename

Looks for a bib file in current folder and in ~/Documents.

Outputs an html file, including all citations and references.

Command-line options:

> asciidoctor-bib -h
asciidoctor-bib 2.3.1

Usage: asciidoctor-bib filename
    -h, --help                       help message
    -b, --bibfile FILE               location of bib file
    -n, --no-links                   do not add internal links
        --numeric-alphabetic-order
                                     sort numeric styles in alphabetical order (DEFAULT)
        --numeric-appearance-order
                                     sort numeric styles in order of appearance
    -s, --style STYLE                reference style
    -v, --version                    show version

All styles available through CSL are supported.
The default style is 'apa'.

Limitations/TODO¶ ↑

no automatic use of et al
no asciidoctor options in asciidoctor-bib
bracketed citations should not be placed in footnotes

License¶ ↑

The files within this project may be distributed under the terms of the Open Works License: owl.apotheon.org

Notes on Using¶ ↑

There is a sample document and bibliography in the folder ‘samples’; build “sample-1.txt”, which includes “sample-2.txt”.

If you make a Bibliography/Reference heading, a2x interprets this specially, and will fail to make a pdf. To prevent a2x treating a heading specially, place a section template name, [sect1], before it.

Contributors¶ ↑

Michel Krämer provided the code linking to citeproc.

Patrick Huck presentation order for numeric styles.

Dan Allen for updating asciidoctor processing to use new API.

andreabedini / asciidoctor-bibtex