= Citations and Bibliography the "asciidoctor-way" asciidoctor-bibliography lets you handle citations and bibliography the "http://asciidoctor.org/[asciidoctor]-way"! image:https://img.shields.io/gem/v/asciidoctor-bibliography.svg["Gem Version", link="https://rubygems.org/gems/asciidoctor-bibliography"] image:https://img.shields.io/travis/riboseinc/asciidoctor-bibliography/master.svg["Build Status", link="https://travis-ci.org/riboseinc/asciidoctor-bibliography"] image:https://codeclimate.com/github/riboseinc/asciidoctor-bibliography/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/riboseinc/asciidoctor-bibliography"] == Introduction This gem allows you to add citations to AsciiDoc imported from BibTex files. Citation styling leverages the popular http://citationstyles.org/[CSL] language so you have direct access to thousands of crowdsourced styles including IEEE, APA, Chicago, DIN and ISO 690. The `bibliography::[]` command generates a full reference list that adheres to your configured citation style. On top of that you also have a formatter derived from the `Bib(La)TeX` world, so all the macros you are familiar with are recognized. Its syntax is designed to be "`native-asciidoctor`": * single cite `cite:[key]`; * contextual cite `cite[key, page=3]`; * multiple cites `cite:[key1]+[key2]`; * full cite `fullcite:[key]`; and * TeX-compatible macros including `citep:[key]`, `citet:[key]` and friends. == Installation Add this line to your Gemfile: [source,ruby] ---- gem "asciidoctor-bibliography" ---- And then execute: [source,console] ---- $ bundle install ---- Or install it yourself as: [source,console] ---- $ gem install asciidoctor-bibliography ---- == Quick start In your document header, choose the filename of a `BibTeX` database and a style (e.g. `apa`, `ieee`, `nature` and http://editor.citationstyles.org/searchByName/[others]). [source,asciidoc] ---- = My first document using asciidoctor-bibliography :bibliography-database: my_database.bib :bibliography-style: apa ---- In your document body, cite your resources using their keys: [source,asciidoc] ---- This will end with a citation cite:[Aa2017]. ---- Then list out the resources you cited: [source,asciidoc] ---- bibliography::[] ---- When compiling, include `asciidoctor-bibliography` in your chain: [source,console] ---- $ asciidoctor -r asciidoctor-bibliography my_first_document.adoc ---- That's it! == Usage `asciidoctor-bibliography` allows for more customizations and macros. Let's examine all its features in full detail. === Citations To cite a resource you provide its unique database key to an inline macro: [source,asciidoc] ---- Here comes a citation cite:[Aa2017] and it's gone. ---- Referring to a specific location inside a resource can be done providing an extra named attribute: [source,asciidoc] ---- cite:[Aa2017, page=42] ---- Allowed locators are `book`, `chapter`, `column`, `figure`, `folio`, `issue`, `line`, `note`, `opus`, `page`, `paragraph`, `part`, `section`, `sub-verbo`, `verse` and `volume`. Their support depends upon which ones your style implements. An extra `locator` attribute with no custom rendering exists. It appears where the ordinary locators would, but you can fully customize it: [source,asciidoc] ---- cite:[Aa2017, locator=" halfway through"] ---- Note that all locators except the first one will be ignored. To `prefix` and `suffix` citations with arbitrary strings you can use the relative attributes: [source,asciidoc] ---- cite:[Aa2017, prefix="see ", suffix=" if you will"] ---- To cite multiple resources you concatenate them as follows: [source,asciidoc] ---- cite:[Aa2017]+[Bb2017]+[Cc2017] ---- You can apply a different locator to each one. === Bibliographies To render the bibliography you simply use the following block macro: [source,asciidoc] ---- bibliography::[] ---- You can handle multiple bibliographies by providing a target parameter to citation macros: [source,asciidoc] ---- cite:foo[Aa2017]+bar[Bb2017] ---- You can then render all citations targeting a specific bibliography by using the target parameter again: [source,asciidoc] ---- ## Index of Foos bibliography::foo[] ## Index of Bars bibliography::bar[] ---- Giving no target is equivalent to using `default` as a target. === Databases Specifying a database file is mandatory and it can be done in the header with its filename: [source,asciidoc] ---- :bibliography-database: my_database.bib ---- Currently only the `BibTeX` format is supported; more will come soon. === Styling The default style for citations and bibliographies is `apa`. You can change that in the header: [source,asciidoc] ---- :bibliography-style: apa ---- Valid style names can be found directly in the https://github.com/citation-style-language/styles[official repository] or searching through the friendly http://editor.citationstyles.org/[style editor]. You can also simply use the filename of a CSL file on your machine if you need more customization. === Localization Citation styles can be localized using the following option: [source,asciidoc] ---- :bibliography-locale: en-US ---- The default is `en-US`. Here is an exhaustive list of recognized locales: `af-ZA`, `ar`, `bg-BG`, `ca-AD`, `cs-CZ`, `cy-GB`, `da-DK`, `de-AT`, `de-CH`, `de-DE`, `el-GR`, `en-GB`, `en-US`, `es-CL`, `es-ES`, `es-MX`, `et-EE`, `eu`, `fa-IR`, `fi-FI`, `fr-CA`, `fr-FR`, `he-IL`, `hr-HR`, `hu-HU`, `id-ID`, `is-IS`, `it-IT`, `ja-JP`, `km-KH`, `ko-KR`, `lt-LT`, `lv-LV`, `mn-MN`, `nb-NO`, `nl-NL`, `nn-NO`, `pl-PL`, `pt-BR`, `pt-PT`, `ro-RO`, `ru-RU`, `sk-SK`, `sl-SI`, `sr-RS`, `sv-SE`, `th-TH`, `tr-TR`, `uk-UA`, `vi-VN`, `zh-CN` and `zh-TW`. === Hyperlinks By default, citations include hyperlinks to their entry in the bibliography. You can disable them in the header: [source,asciidoc] ---- :bibliography-hyperlinks: false ---- === Sorting You can override the sorting specified by the CSL style you have chosen, if you desire to do so. The relevant option is `bibliography-sort` and it accepts a YAML string specifying a list of keys to sort the entries with. Let's explore some of the possibilities. ==== No Sort The simplest option is *no sorting*; an empty list will cause the entries to be in appearance order. [source,asciidoc] ---- :bibliography-sort: [] ---- ==== Sort By Single Key To sort in a single key - say, the rendered author name - it's as simple as [source,asciidoc] ---- :bibliography-sort: macro: author ---- ==== Reverse Sort However you might want to reverse the order: [source,asciidoc] ---- :bibliography-sort: { macro: author, sort: descending } ---- ==== Sort By Multiple Keys It is possible to use any number of sorting keys putting them in an array. E.g. to sort by issuing date: [source,asciidoc] ---- :bibliography-sort: [{ macro: author, sort: descending }, { variable: issued }] ---- You might be asking: what is the difference between `variable` s and `macro` s? The former are metadata fields fixed by the http://docs.citationstyles.org/en/stable/specification.html#appendix-iv-variables[CSL specification]. The latter are combinations of variables defined by your chosen style. To use them effectively you'll need to know its implementation. This task is not daunting at all, as the http://editor.citationstyles.org/[style editor] allows you to quickly list them and understand their role. As for the `sort` option, the valid values are `ascending` (default) and `descending` as you'd expect. === TeX-mode While the `cite` macro is reserved for CSL styling, all traditional Bib(La)TeX macros are accessible through the same syntax with their usual names: * `citet` * `citet*` * `citealt` * `citealt*` * `citep` * `citep*` * `citealp` * `citealp*` * `citeauthor` * `citeauthor*` * `citeyear` * `citeyearpar` NOTE: no macros are missing since `\cite` is equivalent to `\citet`! To cite multiple items you can concatenate them just like with `cite`. All macros accept standard locators, `locator`, `suffix` and `prefix`. The behaviour of these parameters is designed to reproduce the one expected from the traditional `TeX` citation macros `\cite...[prefix][suffix]{key}`. You can set their style in the header: [source,asciidoc] ---- :bibliography-tex-style: authoryear ---- Accepted values are `authoryear` (default) and `numeric`. Furthermore, `fullcite` is also available and accepts no parameters except a single reference key. == Development We follow Sandi Metz's Rules for this gem, you can read the http://robots.thoughtbot.com/post/50655960596/sandi-metz-rules-for-developers[description of the rules here]. All new code should follow these rules. If you make changes in a file that already violates these rules, you should fix the violations as part of your contribution. === Setup Clone the repository. [source,sh] ---- git clone https://github.com/riboseinc/asciidoctor-bibliography ---- Setup your environment. [source,sh] ---- bin/setup ---- Run the test suite [source,sh] ---- bin/rspec ---- == Contributing First, thank you for contributing! We love pull requests from everyone. By participating in this project, you hereby grant https://www.ribose.com[Ribose Inc.] the right to grant or transfer an unlimited number of non exclusive licenses or sub-licenses to third parties, under the copyright covering the contribution to use the contribution by all means. Here are a few technical guidelines to follow: 1. Open an https://github.com/riboseinc/asciidoctor-bibliography/issues[issues] to discuss a new feature. 2. Write tests to support your new feature. 3. Make sure the entire test suite passes locally and on CI. 4. Open a Pull Request. 5. https://github.com/thoughtbot/guides/tree/master/protocol/git=write-a-feature[Squash your commits] after receiving feedback. 6. Party! == Credits This gem is developed, maintained and funded by https://www.ribose.com[Ribose Inc.] == License The gem is available as open source under the terms of the http://opensource.org/licenses/MIT[MIT License].