====== bibtex4dw Plugin ======

---- plugin ----
description: Handling references stored in BibTeX (text) databases in DokuWiki
author     : Till Biskup
email      : code [at] till [minus] biskup [dot] de
type       : syntax
lastupdate : 2024-02-24
compatible : Elenor of Tsort, Frusterick Manners, Greebo, Hogfather, Igor, Jack Jackrum
depends    : 
conflicts  : 
similar    : bibtex, publist, publistx, publistf, refnotes, zotero
tags       : bibtex, literature, references

downloadurl: http://github.com/tillbiskup/dokuwiki-bibtex/zipball/master
bugtracker : http://github.com/tillbiskup/dokuwiki-bibtex/issues
sourcerepo : http://github.com/tillbiskup/dokuwiki-bibtex/

screenshot_img : 
----

:!: The plugin has been renamed from "bibtex" to "bibtex4dw" in May 2023 (due to name clashes as old as the plugin, development started in 2010) to finally surface at [[:dokuwiki|dokuwiki.org]], parallel to some major code changes. Code and documentation still need some attention, but the plugin should work (and is regularly used by its author).


===== What and why? =====

Handling references stored in BibTeX (text) databases in DokuWiki.

**DokuWiki is an excellent tool for knowledge management** and has been successfully used in academic context for long time. However, **academics tend to use references to the literature** when managing their knowledge, and DokuWiki is missing appropriate tools here. Being familiar with using BibTeX both, as a bibliographic (text) database format and as an engine to format references in documents written using LaTeX, a plugin for DokuWiki understanding the BibTeX format and allowing to reference literature from within wiki pages seems an obvious choice.


==== Intended use cases ====

  * Literature references in an academic context
  * Reuse existing BibTeX databases


==== Core criteria ====

  * Works with larg(er) bibliographic databases (several thousand entries)
  * Allows to use string replacements (concrete example: abbreviated and full journal names)
  * Access to PDF files of the reference, as long as available locally and accessible by the currently logged-in user (obeying ACLs)


==== Philosophy ====

  * Resilience: plain text files, no external dependencies, no database as permanent storage (only temporary, the "truth" is in the text files)
  * Unix philosophy (sort of):
    * Write programs that do one thing and do it well.
    * Write programs to work together.
    * Write programs that handle text streams, because that is a universal interface.


===== Installation =====

Search and install the plugin using the [[plugin:plugin|Plugin Manager]] and the download URL above, which points to latest version of the plugin. Refer to [[:Plugins]] on how to install plugins manually.

**Optional dependencies:** This plugin can optionally make use of a SQLite database to (temporarily) store the references. To use this feature, you need to install the [[sqlite|sqlite plugin]].


===== Examples/Usage =====

See the plugin in action [[https://www.till-biskup.de:/de/software/dokuwiki/bibtex|here]] (in German). The sample page shows all the basic capabilities of the plugin.

Generally, the plugin provides **two distinct pieces of syntax**: one for the **references** (mostly in the text), the other for the **bibliographies** (lists of references, mostly at the end of the page or a longer text section).

Everybody who has ever worked with a reference management software, be it BibTeX in combination with LaTeX or EndNote with Word or else, will be familiar with this distinction. For referencing a piece of literature, a (unique) key is used (reference in the text), and the reference management software takes care of checking all the keys referenced throughout the text and produces the corresponding full references in the bibliography.

References in the text using keys are as simple as:

  {[dijk-cacm-15-859]}
  
where "''dijk-cacm-15-859''" is the (unique) key of your BibTeX record. Depending on the style you've selected for your references in the text (numeric, authoryear, alpha, apa), the above code will be rendered slightly differently, //e.g.//: [Dijkstra, 1972] or simply [1].

While the rendered reference keys themselves already provide the full reference as tooltip on hovering with the mouse pointer, you will often want to have a dedicated bibliography section appearing somewhere on your page. In its simplest form, you would write:

  <bibtex bibliography>
  </bibtex>

Again, depending on the citation style you selected (and configured in the admin configuration panel), the rendered reference section may look slightly different. An example of the above reference could look like this:

Dijkstra, Edsger W. (1972): The humble programmer, //Communications of the ACM// **15**:859--865

If you now wonder where the information for rendering the full reference comes from: Obviously, at some place in your wiki you need to provide the BibTeX-formatted information, and you need to tell your wiki (//e.g.// via the configuration of the plugin) where to look for this information. Just to provide you with the BibTeX code of the reference used above:

  @Article{dijk-cacm-15-859,
    author =  {Edsger W. Dijkstra},
    title =   {The humble programmer},
    journal = CACM,
    year =    {1972},
    volume =  {15},
    pages =   {859--865},
    doi =     {10.1145/355604.361591}
  }

Those either familiar with BibTeX or carefully looking at the record will notice that the journal is provided here as BibTeX string that gets replaced upon rendering the reference. Hence, at some other place (preferrably another bibliography file), you will have a list of these strings that are replaced upon rendering your references. For the above example:

  @STRING{CACM = {Communications of the ACM}}

Why all the fuss? This is a simple way of adjusting the reference style to either full or abbreviated journal names, depending on the style required by your publication medium (or personal preference), and without affecting your actual records at all.((Admittedly, "modern" bibliography management software manages this as well, but perhaps you see the beauty and resilience of plain text files as in the case of BibTeX. And if not, never mind... ;-)))


===== Syntax =====

As mentioned in the "Examples" section above, the plugin provides two distinct pieces of syntax: one for the **references** (mostly in the text), the other for the **bibliographies** (lists of references, mostly at the end of the page or a longer text section). A third kind, although rather a subtype of the latter, is the **(textual) database** containing the BibTeX records. 

Basically, the handling of references and the distinction between the different pieces of syntax should be familiar for everybody who has worked with a reference management software, be it BibTeX/LaTeX or EndNote/Word or else: You need some kind of database where the information for each individual reference is stored in a structured way, together with a (unique) key for each reference. From within the text, you refer to a reference using its key, and at some point in your document (usually towards the end) you tell the software to render and output the references you referred to throughout the text.


==== References ====

Adding a reference to a record in the text by using the (unique) key defined in the literature database is as simple as:

  {[dijk-cacm-15-859]}
  
where "''dijk-cacm-15-859''" is the (unique) key of your BibTeX record. Depending on the style you've selected for your references in the text (numeric, authoryear, alpha, apa), the above code will be rendered slightly differently, //e.g.//: [Dijkstra, 1972] or simply [1].

In a DokuWiki instance with the plugin actually installed, the references will provide additional features:

  * Each reference key will be a link to the bibliography (see below).
  * Each reference key will provide the full rendered reference as tooltip on hovering with the mouse pointer.

Given the latter feature, you can even go away with not inserting a dedicated bibliography on your page, as long as you have configured the source of the BibTeX database appropriately.

As familiar from LaTeX/BibTeX, you can have several keys in one reference, separating the keys with comma:

  {[dijk-cacm-11-147,dijk-cacm-15-859]}

A note to users of the plugin familiar with BibTeX/LaTeX: Currently, there is no support for all the advanced features the LaTeX "''\cite{}''" command offers, such as optionally adding page numbers. The intent of the plugin was not to mimic advanced LaTeX features, but to feel as natural to DokuWiki markup as possible.((If you are in urgent need of adding optional page numbers to references, feel free to open an issue at the GitHub page of the plugin, or even better: fork the repository, implement a solution, and file a pull request.))

**Hint:** If you use a key in your text that cannot be found in the database(s) currently considered/configured, the plugin will issue a warning using the DokuWiki message capabilities. This hopefully helps with debugging, be it a typo or the record actually not in the database.


==== Bibliographies ====

While the rendered reference keys themselves already provide the full reference as tooltip on hovering with the mouse pointer, you will often want to have a dedicated bibliography section appearing somewhere on your page. In its simplest form, you would write:

  <bibtex bibliography>
  </bibtex>

Again, depending on the citation style you selected (and configured in the admin configuration panel), the rendered reference section may look slightly different. An example of the above reference could look like this:

Dijkstra, Edsger W. (1972): The humble programmer, //Communications of the ACM// **15**:859--865

But **why adding a dedicated bibliography section** if the references as such get rendered as tooltips already in the text? Because bibliographies allow for additional settings, such as changing the style the references are displayed, and, more importantly, they allow for adding references not present in the text (the equivalent of the LaTeX "''\nocite{}''" command).


=== Adding additional references ===

Assume we had referenced both articles by Dijkstra in the text somewhere, using, //e.g.//

  {[dijk-cacm-11-147,dijk-cacm-15-859]}

and now, in the bibliography, we would like to have the seminal paper by Böhm and Jacopini to appear as well:

  <bibtex bibliography>
  nocite=boeh-cacm-9-366
  </bibtex>

This would render your bibliography similar to the following, again depending on your formatting settings:

Dijkstra, Edsger W. (1968): Go to statement considered harmful, //Communications of the ACM// **11**:147-148

Dijkstra, Edsger W. (1972): The humble programmer, //Communications of the ACM// **15**:859-865

Böhm, Corrado; Jacopini, Giuseppe (1966): Flow diagrams, Turing machines and languages with only two formation rules, //Communications of the ACM// **9**:366-371

**Hint:** The key "''nocite''" seems unintuitive at first, but it is the direct analogon to the LaTeX "''\nocite{}''" command, as mentioned above.


=== Locally changing the way things look ===

There is other things you can change by adding further key--value pairs to your "''<bibtex bibliography>...</bibtex>''" block, such as the sorting. Additionally, in the "furtherreading" blocks (see below), the citation style can be changed as well.

^ Key  ^ Explanation ^
| sort | Switch deciding whether references are sorted alphabetically\\ Options are: true/false\\ Hint: Has no effect if the citation style is set to "numeric" |


=== Further Reading sections ===

Sometimes it comes in quite handy to have one or several "further reading" bibliography sections on a page. These sections are **completely independent of one another** and of the references given in the text so far.

Therefore, to have some references appear in this special bibliography section, you need to specify them using the "''nocite''" key shown above:

  <bibtex furtherreading>
  nocite=floy-cacm-22-455
  </bibtex>

The result would render something like this (again depending on your settings):

Floyd, Robert W. (1979): The paradigms of programming, //Communications of the ACM// **22**:455--460

Depending on the style of your references as set in the (global) configuration, you may want to have the further-reading sections styled differently, //e.g.// with author-year style rather than numeric, and perhaps (alphabetically) sorted. This can be done with additional key--value pairs in the "''<bibtex furtherreading>...</bibtex>''" block.


^ Key      ^ Explanation ^
| citetype | citation stype for references in the text\\ Options are: alpha, apa, authordate, numeric |
| sort     | Switch deciding whether references are sorted alphabetically\\ Options are: true/false\\ Hint: Has no effect if the citation style is set to "numeric" |

==== BibTeX database ====

If you now wonder where the information for rendering the full reference comes from: Obviously, at some place in your wiki you need to provide the BibTeX-formatted information, and you need to tell your wiki (//e.g.// via the configuration of the plugin) where to look for this information. Just to provide you with the BibTeX code of the reference used above:

  @Article{dijk-cacm-15-859,
    author =  {Edsger W. Dijkstra},
    title =   {The humble programmer},
    journal = CACM,
    year =    {1972},
    volume =  {15},
    pages =   {859--865},
    doi =     {10.1145/355604.361591}
  }

Those either familiar with BibTeX or carefully looking at the record will notice that the journal is provided here as BibTeX string that gets replaced upon rendering the reference. Hence, at some other place (preferrably another bibliography file), you will have a list of these strings that are replaced upon rendering your references. For the above example:

  @STRING{CACM = {Communications of the ACM}}

Why all the fuss? This is a simple way of adjusting the reference style to either full or abbreviated journal names, depending on the style required by your publication medium (or personal preference), and without affecting your actual records at all.

**Hint:** To have the BibTeX records appear somewhat nicely formatted on the wiki page, surround them with a "''<bibtex database>...</bibtex>''" structure. This renders them as preformatted text, thus preserving the records. Otherwise, due to indentation, the BibTeX database may be a bit hard to read.


===== Configuration and Settings =====

The plugin can be configured extensively using the admin configuration interface of DokuWiki.

//Details of the configuration settings will follow in due course. For now, see the admin panel, where the individual config settings are documented in some detail.//

:!: Starting with the version 2024-02-24, there is a larger reorganisation of the configuration settings, thanks to the contributions from [[https://github.com/SECtim|SECtim]]. These will be documented soon.


===== Development =====

Development takes place via git and GitHub. Plugin development has long been dormant, though the plugin has actively been used by its author in mulitple DokuWiki instances. In May 2023, some major code modifications took place, and eventually the plugin got renamed from "bibtex" to "bibtex4dw" to escape name clashes as old as the development of this plugin.

Feel free to fork the repository, change it and submit pull requests.


=== Change Log ===

{{rss>https://github.com/tillbiskup/dokuwiki-bibtex/commits/master.atom date}}


=== Known Bugs and Issues ===

Please report bugs or feature requests at the [[https://github.com/tillbiskup/dokuwiki-bibtex/issues|bug tracker]].


=== ToDo/Wish List ===

For the developers roadmap, see the ''TODO.md'' file in the GitHub repository of the plugin:

  * [[https://github.com/tillbiskup/dokuwiki-bibtex/blob/master/TODO.md]]


===== FAQ =====

//[discussions should ideally be deleted and turned into FAQ entries along the way]//


===== Discussion =====

//Could be placed on an external page (e.g. plugin:pluginname:discussion) to have a distinction between user comments and author docs//