Add references from a bibtex file to an asciidoc file.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin
lib
samples
test
.gitignore
Gemfile
LICENSE.txt
README.rdoc
Rakefile
asciidoc-bib.gemspec
changes.txt

README.rdoc

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

(Note: if you are using asciidoctor, instead use github.com/asciidoctor/asciidoctor-bibtex)

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.