<- [[:plugin:refnotes | 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, [[wp>BibTeX]] code sections and [[doku>plugin:data|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 [[:plugin:refnotes#configuration|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_templates|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 [[wp>BibTeX]] syntax.
  * Store one note per page as [[doku>plugin:data|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. //[[http://books.google.com/books?id=1MsETFPD3I0C&printsec=frontcover|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 [[:plugin:refnotes:structured#fields|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.

<code bibtex>
@Book{GangOfFour,
  author     = "Erich {Gamma} and Richard {Helm} and Ralph {Johnson} and John {Vlissides}",
  ref-author = "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"
}
</code>

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.

<code bibtex>
@Comment{refnotes,
  namespace = "ref:prog"
}

@Book{CodeComplete,
  author     = "Steve McConnell",
  ref-author = "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"
}
</code>
 

==== Data plugin ====

With [[doku>plugin:data|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.

<code>
---- 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
----
</code>

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


===== See also =====

  * [[:plugin:refnotes|RefNotes Plugin]]
  * [[:plugin:refnotes:syntax|Syntax]]
  * [[:plugin:refnotes:structured|Structured References]]
  * [[:plugin:refnotes:style|Style Reference]]
  * [[:plugin:refnotes:discussion|Discussion Archive]]