Literature Reference Management with DokuWiki

They must often change, who would be constant in happiness or wisdom.

I switched from handling my literature with Circus Ponies Notebook (CPN) to Dokuwiki. I really like CPN, but it became too slow as the file became larger, even with all the images and PDFs not embedded in the file-directory itself but linked to it. DokuWiki might not be that much faster in showing the page, but it’s displayed in a Browser and I’m used to a slight latency. Also, my literature is split into hundreds of text files and not one large file that must be loaded. Consequently, there should not be any decrease in speed over time when the collection gets larger (up to 300k files I think).

A few things make DokuWiki especially suitable for handling files:

Page Creation with Ferret

I use my Ferret Frame and have modified it to allow the quick creation of entries in the literature-directory of DokuWiki (it’s a top-level directory). Clicking the literature radio-button (checked by default) and entering a name for the literature (e.g., “Goodwin 2009”) creates the page in the literature directory (e.g., “literature\goodwin_2009.txt”). This makes entering literature very quick.

Using author_year for files

I have seen different ways to refer to literature. Some people assign numbers (#1, #2, #3, …) to texts, others use the name of the author(s) and the year. I think that the later is way superior. First, you will refer to your literature by author and name only (e.g., in an article). Expert researchers can cite the author and year of a study from memory, and referring to your literature the same way will help you to achieve this feat more quickly (or do you want to say: “In my literature list No. 7302, the authors did something similar”? ;-)).

It is also short enough as a file name (remember that DokuWiki uses the name of the page as a text file name). Like with the APA citation rules, you should probably use “et al.” when a text was written by more than 6 authors. You will also quickly spot double entries (when you try to enter a text with an author_year that already exists, Ferret Frame will open this page in edit mode). If it is really a different text, you can simply add an “b”, or “c” behind the year (e.g., resulting in Goodwin_2009b.txt).

Using tags and pagelist (see below) to get a list of the entries also allows you to enter the citation later. I find it more useful to quickly create the page (and author and year is something that is easy to find in almost all cases). So the page is created as author_year. The header of the page (first headline with ====== author_year ====== is then replaced by the citation as far as I know it. If some information is missing, so be it. I can always add it later. But author and year must be known and exact, otherwise you cannot spot duplicates — and yes, you might really forget that you have already entered a text into your literature list.

Templates with Ferret

Given that most entries look the same in the beginning (e.g., Title, Citation, link to PDF file, notes-section), I created templates to accommodate the most common literature types. After creating the page with the Ferret Frame, I simply click on the link to the respective template and the standard content is copies into the open text field (text area) of the wiki. For example, I updated the template.php of Ferret to include a template for an article in the function transfertitel(pagetype,titelnameheader):

if(pagetype == “article”) {
tagline = “[[:literature|{{:back.gif }}]]====== ” + titelnameheader + ” ======\n\n  * **Citation:** xxxx\n  * **Source:** PDF\n  * **Key-Points**\n    * xxxx\n  * **Strengths**\n    * xxxx\n  * **Weaknesses**\n    * xxxx\n\n—- \n\n===== Abstract =====\n\n===== Theory =====\n\n===== Research Question(s) =====\n\n===== Method =====\n\n==== Design ====\n\n==== Participants ====\n\n==== Instruments ====\n\n==== Procedure ====\n\n===== Results =====\n\n===== Discussion =====\n\n===== Conclusion =====\n\n\n{{tag>literature article}}\n====== eof ======”;

which can be selected with the link <a href=”javascript:transfertitel(‘article’,document.Jswdata.Seitentitel.value)”>Article</a>

Taglist with Ferret

Important for handling literature are tags. I’ve long given up the use of static categories. For example, I’m interested in mobile media, museums, and electronic guidebooks in museum. Suppose I have a text regarding electronic guidebooks, where do I put it? In the electronic guidebook category? But it also belongs in the mobile media and the museum category. Tags solve this problem quickly: tagging the text with mobile media and museum assigns the text to all three categories — mobile media, museum and electronic guidebooks in museums (= mobile media + museum). Given that tags are hard to remember (was it “museum” or “museums“?) they are listed in the Ferret Frame and can be assigned by a simple click on the respective tag.

Pagelist with predefined tag search terms

I have created some pages that consist of predefined search terms. For example, one link from my main Literature page leads to a page with the following content:

[[:literature|{{:back.gif }}]]====== Literature – Museums ======

{{topic>literature +museum}}

====== eof ======

This page displays every page that is tagged with literature and museum. Why the literature tag? It’s assigned per default to all my literature entries (it is in the template) because I have other pages (e.g., in community – people) where the tag museum is used. Using tags for the main categories of my wiki allows me to quickly narrow down the search to — here — literature.

Similarly, other search terms can be used, e.g., for Electronic Guidebooks in Museums I would use: {{topic>literature +museum +mobile_media}} and for mobile media outside a museum I would use {{topic>literature -museum +mobile_media}} … and so on.

Note: I have changed the pagelist plugin settings in Admin – Configuration Settings – Pagelist Plugin Settings to no heading line, hide date column, hide user column (it’s a single user wiki), hide description column, hide comments column, hide linkbacks column, hide tags column, but enabled show the first headline instead of the page name. The last setting shows me the whole citation (which I use for the page header), e.g, for the goodwin_2009.txt the text “Goodwin, C. J. (2009). Research in Psychology. Methods and Design. Wiley.” is shown (yes, it’s an incomplete citation).

Note 2: I will probably write a PHP script that allows for a similar function like in many online databases — you can select multiple tags and get the results quickly. But this will take a while.

Author List with PHP

A PHP Script (rename it to .php) creates a page in DokuWiki that has an alphabetical Listing of all entries in the literature-directory. While a complete literature list can be build on demand via the pagelist-plugin and the tags used (here: all that included literature), using PHP to create/update such a file once is much quicker. The entries are actually saved in the text file and do not need time to create on loading the page.

Acrobat OCR

Given that most of the literature are PDFs (or can be converted into PDFs), I have used the Acrobat OCR feature to recognize the text in the file and make it selectable if this is not the case. This allows me to quickly copy and paste content from the file to my notes. Note: There is a plugin for Firefox for Mac that allows you to open the PDFs in Firefox itself. I’m not sure yet whether I prefer this or whether it is better to use the icon that appears in the lower part of the PDF to open it in Acrobat itself. Currently I’m using the later and make notes first in a normal text editor (Text Wrangler) and copy my notes into the Wiki later.

Quickly Linking to a Literature Page (or any other page) in the Wiki

Note: For notes, I have switched back to Circus Ponies Notebook. I still think that the Wiki is perfect for long term storage of literature, but it’s much easier to go through the literature (e.g., with a list of relevant literature based on tag search or portals) and then copy the relevant notes into a CPN outline to use it for the specific project (article, proposal, book, etc.).

Given that I use pages in the notes-directory to make … well … notes about topics that are not specific to an individual text (e.g., information about Mobile Eye Tracking that combines information from multiple texts) I need a way to refer to the original literature. That’s one aspect where I miss CPN (using the keyword feature to assign a source-keyword to each cell and then simply copy the cells into a new document made this very easy and non-distracting).

However, I’ve modified Ferret to include four links that grab the location and name of the page that is currently displayed and modify it so that links can be made quickly. If I want to refer to a text in my notes, I open my wiki in another Firefox Tab. Then I go to the literature I want to cite. Next I press the “as superscript” Link, which gets me the wiki-link to this page in the text area (for example, the literature\goodwin_2009.txt page would lead to the link: <sup>[[Literature:Goodwin 2009]]</sup>. Copying this link and pasting it at the respective place in the other tab quickly creates a link to this literature text. I’ve tried out a few other ways to link, e.g., the direct link ( [[Literature:Goodwin 2009]] ), the link as footnote ( (([[Literature:Goodwin 2009]])) ), and also the link with a given title (here: link, <sup>[[Literature:Goodwin 2009|Link]]</sup> ). However, I think using it as superscript is the best way (using it as a footnote and then holding the mouse over the link and clicking on the link that appears does not seem to function, somehow the tilde (~) is not preserved).

Grabbing the Link from an existing page by clicking on Get Link

Grabbing the link to an existing page by clicking on the links in the ferret frame

allows you to quickly copy and paste the link from the text field below to the page where you want to make the reference:

How the different links look like in the text

which allows for these four possibilities to link it:

How the different links look like on a page

This feature also allows me to quickly create a portal page or jot down below an article page which literature I have used. I simply open the respective literature page in another frame, get the link, and paste it on the page it should go. No need to use the link wizard and I can predefine how the link should look like.

It’s probably too soon to say whether this kind of literature management works — but I think so. My notes are preserved for a long time in an open standard (text files!!!! yeah, baby :-)) with all benefits of tags and auto-lists and so on. The work with the source is facilitated by getting links and letting pagelist/php-script integrate the pages into the wiki structure. In short, it should work … whether it will be usable for me for the future … I’ll see, in a year or so.


You can use the Ferret Frame described here and here or have a look at the modified template.htm source code (you need to change the LINKS for it to work, and probably also the top.wikiframe.document.forms[0] number — 0 works for the monobook template, the original dokuwiki template used 4 I think). If you want to modify your template file, add the following functions before the </script> near the end of the template.php (sorry, I know, it’s ugly code but I works):

function get_address() {
prestep = top.wikiframe.location.href.replace(/http:\/\/localhost\/~ipsych\/sci\/doku.php\?id=/ig, “”);
sp = prestep.split(‘&’);
step = sp[0];
step = step.replace(/_/gi, ” “);
step = capitAll(step);
document.Jswdata.Verzeichnisinfo.value = “[[” + step + “]]”;

function get_address_footnote() {
prestep = top.wikiframe.location.href.replace(/http:\/\/localhost\/~ipsych\/sci\/doku.php\?id=/ig, “”);
sp = prestep.split(‘&’);
step = sp[0];
step = step.replace(/_/gi, ” “);
step = capitAll(step);
document.Jswdata.Verzeichnisinfo.value = “(([[” + step + “]]))”;

function get_address_upper_link() {
prestep = top.wikiframe.location.href.replace(/http:\/\/localhost\/~ipsych\/sci\/doku.php\?id=/ig, “”);
sp = prestep.split(‘&’);
step = sp[0];
step = step.replace(/_/gi, ” “);
step = capitAll(step);
document.Jswdata.Verzeichnisinfo.value = “<sup>[[” + step + “]]<\/sup>”;

function get_address_upper_link_link() {
prestep = top.wikiframe.location.href.replace(/http:\/\/localhost\/~ipsych\/sci\/doku.php\?id=/ig, “”);
sp = prestep.split(‘&’);
step = sp[0];
step = step.replace(/_/gi, ” “);
step = capitAll(step);
document.Jswdata.Verzeichnisinfo.value = “<sup>[[” + step + “|Link]]<\/sup>”;

capitAll = function(str) {
// uses example from
str = str.toLowerCase().replace(/([-\.’]) */g,’$1 ‘);
var rx= /\b([a-z’-\.]+)\b/ig;
str = str.replace(rx,function(w){
return w.charAt(0).toUpperCase()+w.substring(1);
return str.replace(/^ *|(\-|’) *| *$/g,’$1′);

and add the following lines below the Create New line (<a href=”javascript:create_new()”>Create New!</a>):

<p><a href=”javascript:get_address()”>Get Link</a> | <a href=”javascript:get_address_footnote()”>as Footnote</a> | <a href=”javascript:get_address_upper_link()”>as superscript</a> <a href=”javascript:get_address_upper_link_link()”>-link</a></p>

Your Modifications

As usual, you a free to modify the code as long as you cite the source and make it available for free (if you make it available). Given that I’m by no means an expert in JavaScript and PHP, you probably should modify the code (I want to work with the tool, not on it.)