RefNotes plugin

The RefNotes plugin is an extension for build-in DokuWiki footnotes syntax. In addition to the basic footnotes functionality it provides a number of extra features, most notably:

• Multiple independent note classes on the same page (e.g. citations, footnotes, etc).
• Customizable look of the references and notes.
• Render the notes at any place on the page, not only at the very bottom.
• Often used notes (e.g. book references) can be shared between different pages.

Download and install the plugin using the Plugin Manager using the following URL. Refer to Plugins on how to install plugins manually.

• refnotes-2010-04-05

There are two major parts of the syntax: references and note blocks. The references are used in a text body to define a note and during rendering are replaced with a short link. The basic reference syntax is similar to the footnotes:

Here goes the reference[(This is a note.)].

Apart from the basic functionality provided by footnotes, the references have a number of extra features:

• Better support for multiple references to the same note.
• You can name a note and later refer to it by name from another reference. The named notes can be shared between different pages via the reference database.
• The notes can be grouped into namespaces. For example, you can keep footnotes apart from bibliographical references.
• References can be hidden from rendering and used only to define the note text. This can be convenient if you want to keep the notes apart from the main text body.

The note blocks indicate a page location where text of the notes will be rendered. They are optional and if there are no explicit note blocks on the page, all notes will be rendered at the end of the page. The minimal syntax for the note block is:

~~REFNOTES~~

Apart of specifying the notes location the note blocks can be used to:

• Render notes from a certain namespace.
• Render only part of the notes. For example, this can be used to render the notes in multiple columns.
• Change formatting of the references and the note blocks.

For more details on the extended syntax see the complete syntax description.

The RefNotes plugin has its own configuration interface that is available from the administration page. This interface allows to control some general settings, predefine commonly used namespace styles and notes (it's the only place to define inline notes). The predefined namespaces and notes are available on any wiki page without explicit declaration.

The configuration page heavily uses JavaScript, so it must be enabled or the page will be completely useless.

• Added support for structured note definition in the reference database.
• Added note text alignment style.
• Improved detection of hidden notes.
• Fixed handling of references inside of list items.
• A number of fixes in handling of database references.

• Fixed ignoring of the settings from General section.
• Fixed a couple of minor issues.

• Added reference database.
• Fixed disabled configuration UI on DokuWiki installations that use URL rewriting.
• Fixed a number of minor issues.

• First public release

Please report bugs or feature requests at the bug tracker.

See older topics on the discussion archive page.

Is there a way to achieve consecutive numbering of the notes? Independent of where the notes come from. If I mix notes from the reference database and footnotes, I get multiple references with the same number.

— Tammo 2010/04/05

Every namespace has independent numbering. It doesn't matter if the notes are defined on the page or in the database. As long as you keep them in the same namespace the numbering will be consecutive. — Mykola Ostrovskyy 2010/04/07 20:30

I guess I don't understand something then. Here is a minimal example:

  * Test 1: [(This is a test reference)]
  * Test 2: [(:refnotes:lit:king65)] 

yields

King65 is a book. I would like to have one database with all my books such that I can easily reference them on different pages, etc.

Thank you for your fast responses.

— Tammo 2010/04/08

The namespaces are introduced for different formatting of the references and notes rather than for organizing your references collection. If you really want to keep King65 in :refnotes:lit: then all the notes, which you want to be in the same notes block (and have consecutive numbering), also have to be in that namespace:

  * Test 1: [(:refnotes:lit: > This is a test reference)]
  * Test 2: [(:refnotes:lit:king65)]

But I would rather suggest to use something along the lines:

  * Test 1: [(:ref: > This is a test reference)]
  * Test 2: [(:ref:lit_king65)]

— Mykola Ostrovskyy 2010/04/09 20:13

Ok. The named note is a good idea. I will keep a single page will all my literature references. Now I get consecutive numbering. Thank you very much.

— Tammo 2010/04/09

Is there a way to add a per citation page number to the reference? Something like [(:ref:knuth97>205)] leading to the following output: Knuth, Donald E., 1997. Random numbers. In Arts of Programming, Volume 2: Seminumerical Algorithms. Third Edition. Reading, Massachusetts: Addison-Wesley. p.205

— Anonymous 2010/04/18

No. But I'm thinking about adding such thing in some future release (if there will be a future release). However, it will require significant changes to the syntax, so there is no timeline for this feature. — Mykola Ostrovskyy 2010/04/18 17:04

Hi,

Thanks for the excellent work done with this plugin. My only issue is that if I try to add a References section per your example, I get a double underline between the header of the section and the references per se: one is coming from the section formatting, the other from the REFNOTES formatting. Any trick to solve this? The solution previously suggested (in previous Discussions) is not working.

— Sylvain Foisy 2010/05/03

Did you try notes block separator style? For example:

===== References =====

<refnotes ref> notes-separator: none </refnotes>

Of course, you can also set this style in the configuration if you want to disable the separator permanently for a given namespace. — Mykola Ostrovskyy 2010/05/07 14:50

Hi,

Thanks for the input I try the block separator routine but no success. — Sylvain Foisy 2010/05/09

Nevermind… I goofed with the namespace Everything looks great now. Keep up the good work! — Sylvain Foisy 2010/05/10

The Configuration RefNotes gives error corrupted data from the server and I can not configure it. Installation without problems with the Manager plugins. This happens in Release 2009-12-25c “Lemming” of DokuWiki.

Any ideas? — Anonymous 05/11/2010

The only obvious thing that comes to my mind is to reinstall and try again. If that doesn't resolve the problem, please report it on the bug tracker. — Mykola Ostrovskyy 2010/05/24 19:14

I have the exact same problem in release 2011-11-10 No way to change the setup. The installation worked fine. I reinstalled, and obtained the same result. I wonder what to do. Michel 2012-01-01

There was an unreleased fix for webhosts that add extra stuff to served pages. If you don't run your own HTTP server, you could try to update action.php and admin.js to their latest versions. — Mykola OstrovskyyMykola Ostrovskyy
pan One

2012/01/12 08:06

I prefer that the namespaces in the reference database sheets and cards be hidden. I was able to make it work by hacking refnotes/namespace.php, inserting the following around line 28:

function refnotes_parseName($name) {
+   $name = trim($name,'[]');	// hack to allow links as note names.  This will strip [[]] surrounding names
    $pos = strrpos($name, ':');

It allows you to use internal links, such as [[:ref:Knuth68]], for note names–refnotes will ignore the surrounding brackets with this hack. It works because DokuWiki hides internal link namespaces.

With this change your reference database may look like¹⁾:

— Rik BlokRik Blok
rikblok

2011/02/14 05:08

I have a bad feeling about this hack.

From looking around the source it seems to me, that this function is also used for lookups in the ref-database - so this might/should break namespaces in some way.

Maybe a more appropriate place to hack this is in refnotes/syntax/references.php line 715, 721 (or rather 188? dunno…). Looks more like the place, where the entries are rendered to the page.

— bjoernXbjoernX

2011/04/22 08:24

I am very excited by this plugin, it does exactly what I was looking for - with a bit of tweaking. I keep my bibliography in Bibtex (through BibDesk), and wanted to write a script that automatically created a bunch of pages in DokuWiki, one for each publication. I would then write notes about the publication on that page, and cite it in other pages, with a link back to that page.

So I set the :ref: namespace as my reference database namespace, create a few pages (manually for now) for each publication (use the bibtex cite key as the name of the page), and insert a table in each page with the citation info.

Then I made a tiny change to the syntax/references.php around line 860 (in the refnotes_harvard_note_renderer class), and changed this:

    private function renderTitle($field) {
        $text = $field['title'] . '.';
 
        if (array_key_exists('url', $field)) {
            $text = '[[' . $field['url'] . '|' . $text . ']]';
        }
 
        return $text;
    }

to this”:

    private function renderTitle($field) {
        $text = $field['title'] . '.';
 
            $text = '[[' . $field['note-name'] . '|' . $text . ']]';
 
        return $text;
    }

That means that the title of the citation is always a link back to the page (I use the page name as the note-name).

Now the only thing that would really make my day, would be some way of making the 1) more like an APA citation (like Johnson & Morell (1990))… I would love to contribute to the code, but I need some guidance. feature request

— houshuanghoushuang

2011/04/30 03:18

Actually, all of this is in a TODO list:

• Basic BibTeX support in the reference database
• Custom note/reference renderers based on semantic fields (structured notes)
• Structured references (a.k.a. APA citations)

I think the first two items are too advanced to be used widely. The work on the last one has been started, but currently I don't have time for it — Mykola OstrovskyyMykola Ostrovskyy
pan One

2011/05/04 11:07

Hi there,

I am currently working on some of these features for my brother, as he needs them urgently for his work.

Currently, I nearly finished implementing:

• A Bibtex parser based on bibtexParse from the Bibliophile project
• A Bibtex entry formatter based on OSBiB (same project as bibtexParse), which is also used in the MediaWiki Plugin for bib files
  • this could also be used for other kinds of sources, it easily provides styles, like the requested APA one (the code of OSBiB is quite old and sometimes a pain in the ass, but it works, if you spend some time on it ;) )
• some detail improvements of the code

Mykola, I would like to contact you in the next few weeks, when I finished with programming, testing and documentation - perhaps you can have a look on it and we put up an update for this plugin together? —Oliver Schmidt

I would add that this code requires using the structured mode. huithuit