asciidoc-bib/README.rdoc

= asciidoc-bib 

== Description

Adds references from a bibtex file to an asciidoc[http://asciidoc.org] 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]
- transforms source text to include references and full reference list

(Note: for asciidoctor[https://asciidoctor.org], prefer 
asciidoctor-bibtex[https://github.com/asciidoctor/asciidoctor-bibtex/].)


== Use 

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

Styles must be one of those supported by CSL[https://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-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'.


== Notes 

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.