Skip to content

tschaume/asciidoc-bib

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
bin
 
 
lib
 
 
 
 
 
 
 
 
 
 
 
 

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.

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
asciidoc-bib 2.2.0

Usage: asciidoc-bib filename
    -h, --help                       help message
    -b, --bibfile FILE               location of bib file
    -n, --no-links                   do not add internal links
    -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
asciidoc-bib 2.2.0

Usage: asciidoc-bib filename
    -h, --help                       help message
    -b, --bibfile FILE               location of bib file
    -n, --no-links                   do not add internal links
    -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

  • use header to define style/biblio etc

  • 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.

About

Add references from a bibtex file to an asciidoc file.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published