BibTex 4 DokuWiki Plugin

https://www.bibtex.com/g/bibtex-format/

—- plugin

description: Handling references stored in BibTeX (text) databases in DokuWiki author : Till Biskup email : till [at] till [minus] biskup [dot] de type : syntax lastupdate : 2023-05-28 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.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).

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.

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

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

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

Search and install the plugin using the 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 plugin.

See the plugin in action 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.¹⁾

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.

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.²⁾

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.

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

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.

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.

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.

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.

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.

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.

• Merge pull request #8 from SECtim/sqlite_performance (Saturday, February 24, 2024 11:30 AM)
• Update changelog (Saturday, February 24, 2024 11:28 AM)
• Update plugin info (Saturday, February 24, 2024 10:57 AM)
• Merge branch 'SECtim-improved_bibliography_formatting' (Saturday, February 24, 2024 10:56 AM)
• Execute SQL insert/update statements in a single transaction (Monday, November 20, 2023 03:22 AM)
• Deduplicate code for storing entries (Monday, November 20, 2023 02:35 AM)
• Merge branch 'master' into improved_bibliography_formatting (Monday, November 20, 2023 01:09 AM)
• Add format string syntax change to CHANGELOG.md (Monday, November 20, 2023 12:37 AM)

Please report bugs or feature requests at the bug tracker.

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

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

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