DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:refnotes:refdb

Back to RefNotes Plugin

RefNotes Reference Database

The reference database is a collection of pages in a certain namespace that define commonly used notes. A typical use case for such database is to keep together often used literature references. There are various ways to define notes: DokuWiki tables, BibTeX code sections and Data plugin entries. They all use quite straightforward key-value pair syntax, so it should be relatively easy to automate generation of such pages from any existing database.

Configuration

The namespace for the reference database is specified from the configuration interface. You should provide an absolute namespace name starting from the root. All namespaces beneath the specified one are also included into the database. Do not confuse this namespace (part of DokuWiki page name) with namespaces of notes (RefNotes formatting) defined on the page — they are completely independent. For example, on :refnotes:programming page you can define a note called :ref:Knuth68. In order to reference this note from some other page you should refer to :ref:Knuth68. The reference database namespace just tells the plugin where to look for the note definitions.

When you enable the database plugin puts a namespace template with basic formatting rules and some examples into the database namespace directory. The template text is just a reminder and can be deleted.

Page formatting

When plugin loads a database page it scans the page looking for tables that conform to a certain format. Any other text and markup on the page are ignored. Every note is defined as collection of data fields. There are number of ways to organize the note definitions:

  • Group a number of notes into single data table (sheet).
  • Use separate table for each note (card).
  • Define notes using BibTeX syntax.
  • Store one note per page as Data plugin entry.

Note sheets and cards

In note sheets every note occupies a separate table row. The first row of the table is used to specify which field the corresponding column contains.

Note name Note text
:ref:Knuth68 Knuth, Donald E. The Art of Computer Programming, Volume 1: Fundamental Algorithms, First edition, Addison-Wesley, 1968, ISBN 0-201-03801-3.
:ref:Knuth69 Knuth, Donald E. The Art of Computer Programming, Volume 2: Seminumerical Algorithms, First edition, Addison-Wesley, 1969, ISBN 0-201-03802-1.
:ref:Fowler99 Fowler, Martin; Beck, Kent; Brant, John; Opdyke, William; Roberts, Don. Refactoring: Improving the Design of Existing Code, Addison-Wesley, 1999, ISBN 0-201-48567-2.

The note card table should have two columns where the first column is used to specify the field names.

Note name :ref:HarvRef
Note text Harvard System of Referencing Guide
URL http://libweb.anglia.ac.uk/referencing/harvard.htm
Note name :ref:GangOfFour
Authors Erich Gamma, Richard Helm, Ralph Johnson, John M. Vlissides
Title Design Patterns: Elements of Reusable Object-Oriented Software
Published 1994
Publisher Addison-Wesley
Pages 416 pp.
ISBN 0-201-63361-2
URL http://www.amazon.com/dp/0201633612

The plugin does not make a distinction between normal table cells and header cells. The field name cells are identified purely based on their content. The field names are case insensitive and can also be specified using locale-specific labels, so instead of 'note-name' you can put 'Note name.' But for the rest field names should be spelled exactly as specified, in particular, avoid using any formatting in the field name cells.

BibTeX

BibTeX entries have to be wrapped into a <code> section with bibtex style. Plugin will parse all such sections, so you can either store each note in a separate section or group all of them into a single section. The key of BibTeX entry serves as name of the note.

@Book{GangOfFour,
  author     = "Erich {Gamma} and Richard {Helm} and Ralph {Johnson} and John {Vlissides}",
  author-ref = "Gamma, et al.",
  title      = "Design Patterns: Elements of Reusable Object-Oriented Software",
  publisher  = "Addison-Wesley",
  year       = 1994,
  address    = "Reading, Mass.",
  pages      = 395,
  isbn       = "0-201-63361-2",
  url        = "http://en.wikipedia.org/wiki/Design_Patterns"
}

The namespace can be either specified as part of the entry key or in a separate comment. The namespace specified in the comment is used for all following entries within the current code block that do not have namespace specified explicitly.

@Comment{refnotes,
  namespace = "ref:prog"
}
 
@Book{CodeComplete,
  author     = "Steve McConnell",
  author-ref = "McConnell",
  title      = "Code Complete: A Practical Handbook of Software Construction",
  edition    = "2<sup>nd</sup>",
  publisher  = "Microsoft Press",
  year       = 2004,
  pages      = 960,
  isbn       = "978-0735619678",
  url        = "http://www.amazon.com/dp/0735619670"
}
 
@Article{:ref:math:Knuth-LCE-1985,
  author    = "Donald Knuth",
  title     = "Deciphering a linear congruential encryption",
  journal   = "IEEE Transactions on Information Theory",
  volume    = "31(1)",
  year      = 1985,
  month     = "Jan",
  publisher = "IEEE",
  pages     = "49-52",
  issn      = "0018-9448",
  url       = "http://ieeexplore.ieee.org/xpl/articleDetails.jsp?arnumber=1056997"
}

Data plugin

With Data plugin you can store the notes in a database, which allows to make queries against the bibliography data. For example, you can see all books of a certain author. Disadvantage of using this plugin is that it allows only one dataentry section per page, so each note has to be stored on a separate page.

---- dataentry refnotes ----
note-name : :ref:prog:Hunt&Thomas(1999)
authors   : Andrew Hunt, David Thomas
title     : The Pragmatic Programmer: From Journeyman to Master
published : 1999
publisher : Addison-Wesley Professional
pages     : 352
isbn      : 0-201-61622-X
url       : http://en.wikipedia.org/wiki/The_Pragmatic_Programmer
----

The dataentry above is wrapped into <code> section to be properly presented in absence of Data plugin.

See also

plugin/refnotes/refdb.txt · Last modified: 2015-12-06 12:26 by 46.5.17.105