DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:refnotes:structured

Back to RefNotes Plugin

RefNotes Structured References

Structured references is an extended syntax for bibliographical references that allows to define the note in terms of individual data fields. Having semantics attached to the fields allows to use them in various ways. For example, the same note can be rendered differently based on the namespace style. Also parts of the note definition can be used to render references. For example, author names and publication date can be used in references as specified by common referencing systems (e.g. Harvard, APA, etc.).

Syntax

The basic syntax for structured reference is similar to named note definition:

[(name>>field-name:Field value; another-field-name:Another field value)]

There are two ways to format the fields. One is similar to namespace style syntax: fields are separated by semicolon or new line character, field name is separated from its value by colon. If there are semicolons in the value they should be escaped with backslash.

[( :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 second syntax is similar to Wikipedia citations: fields are separated by vertical bar, name is separated from value by equals sign. The values may span multiple lines. This syntax is used when note data starts with a vertical bar character.

[( :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
)]

Each field has to be specified only once. If specified multiple times, the last value overrides the previous ones.

Fields

The plugin supports the following fields:

Name Label Description Defined in Used in
Basic Harvard
address Address Address of the publisher. r, d n
author Author List of the authors. r, d r, n
authors Authors
booktitle Book title The title of the book, if only part of it is being cited. r, d n
chapter Chapter Name of a book chapter. r, d n
direct Harvard referencing system allows two types of formatting for references: when author name is directly mentioned in the text and when it isn't. Using direct field you can control this formatting for each individual reference. r r
edition Edition Book edition. r, d n
isbn ISBN Book number. r, d n
issn ISSN
journal Journal Name of a journal or magazine. r, d n
month Month Month of publication. r, d n
note-name Note name Fully qualified note name including the namespace. d1 r2
note-page Note page Number of pages in a book or page range for an article. r, d n
note-pages Note pages
note-text Note text Text of the note. r, d n n3
page Page Number of pages in a book or page range for an article. When used in a reference, this field defines page that is referred by this particular reference. To define page range for the note from a reference use note-pages field. r, d r, n
pages Pages
published Published Date of publication. Alternatively it can be specifies with month and year fields. r, d r, n
publisher Publisher Address and name of the publisher. r, d n
ref-author Reference author RefNotes plugin doesn't do any processing on the list of authors. If there are too many of them to include in the reference, you can use ref-authors to provide an alternative list just for the references. r, d r
ref-authors Reference authors
title Title Title of a book or an article. r, d n4 n
url URL5 Wraps the note-text or title into a link. r, d n n
volume Volume Volume or issue number of a journal. r, d n
year Year Year of publication. r, d r, n

Legend:

d — defined in reference database.
r — defined/used in references.
n — used in notes.

Notes:

1) In BibTeX entries the entry key serves as note-name.
2) If refnote-id style is set to name.
3) If title is not defined.
4) If note-text is not defined.
5) Links should not contain have wiki-markup so internal links can be used by giving the namespace:page_name

Rendering

There are two structured data renderers supported by the plugin: Basic text renderer and Harvard referencing system renderer. They can be selected independently for references and notes using reference-render and note-render namespace styles.

Basic rendering

The basic rendering is similar to rendering of regular (non-structured) notes. Only note-text and url fields are used in the note text. The note-text may use any text formatting (e.g. bold or italic), but if url is provided, it will wrap the text into [[url|note-text]] syntax, and all formatting will be ignored.

[(HarvRefSys>>
note-text : Harvard System of Referencing Guide
url       : http://libweb.anglia.ac.uk/referencing/harvard.htm
)]

The above note will be rendered as:

If note-text field is not defined, title field is used instead:

[(KnuthAoP2>>
author     : Donald Knuth
title      : Arts of Programming, Volume 2: Seminumerical Algorithms
edition    : Third Edition
published  : 1997
publisher  : Addison-Wesley
note-pages : xiv + 762 pp.
isbn       : 0-201-89684-2
url        : http://en.wikipedia.org/wiki/The_Art_of_Computer_Programming
)]

The above note will be rendered as:

References are rendered the usual way without using any data fields.

Harvard rendering

Notes

Harvard System of Referencing describes various ways to format bibliographical references. RefNotes plugin supports only the most common ones: a book, a chapter in a book and a journal article. There are number of optional data fields that add some variety to the rendered notes, but it all boils down to one of the basic schemes.

The minimal requirement for a book reference is presence of title field. If this field is not defined the plugin will fall back to basic rendering.

[(KnuthAoP2>>
author     : Donald Knuth
title      : Arts of Programming, Volume 2: Seminumerical Algorithms
edition    : Third Edition
published  : 1997
publisher  : Addison-Wesley
note-pages : xiv + 762 pp.
isbn       : 0-201-89684-2
url        : http://en.wikipedia.org/wiki/The_Art_of_Computer_Programming
)]

The above note will be rendered as:

Donald Knuth, 1997. Arts of Programming, Volume 2: Seminumerical Algorithms. Third Edition. Addison-Wesley, xiv + 762 pp., ISBN 0-201-89684-2.

When chapter field is present it is rendered in front of the book title:

[(KnuthAoP2Ch3>>
author     : Donald Knuth
title      : Arts of Programming, Volume 2: Seminumerical Algorithms
chapter    : Random numbers
edition    : Third Edition
published  : 1997
publisher  : Addison-Wesley
note-pages : Ch. 3
isbn       : 0-201-89684-2
url        : http://en.wikipedia.org/wiki/The_Art_of_Computer_Programming
)]

The above note will be rendered as:

Donald Knuth, 1997. Random numbers. In Arts of Programming, Volume 2: Seminumerical Algorithms. Third Edition. Addison-Wesley, Ch. 3, ISBN 0-201-89684-2.

Presence of journal field triggers article rendering:

[(KnuthLCE1985>>
author     : Donald Knuth
title      : Deciphering a linear congruential encryption
journal    : IEEE Transactions on Information Theory
volume     : 31(1)
published  : Jan 1985
publisher  : IEEE
note-pages : 49-52
issn       : 0018-9448
url        : http://ieeexplore.ieee.org/search/freesrchabstract.jsp?tp=&arnumber=1056997
)]

The above note will be rendered as:

Donald Knuth, Jan 1985. Deciphering a linear congruential encryption. IEEE Transactions on Information Theory, 31(1), IEEE, pp.49-52, ISSN 0018-9448.

References

To render the references according to Harvard system style the note data should meet minimum requirements: there should be an author and either referenced page or publication date. Minimal syntax is just to specify the not name:

The subject of random number generation and has been extensively studied in computer science [(KnuthAoP2)].

Using style of predefined :harvard: namespace, the above reference will be rendered as:

The subject of random number generation and has been extensively studied in computer science (Donald Knuth, 1997).

In order to refer to a certain page of a book you can use page (or pages) field:

The simplest and most common type of numerical distribution is a random integer [(KnuthAoP2>>page:119)].

The above reference will be rendered as:

The simplest and most common type of numerical distribution is a random integer (Donald Knuth, 1997, p.119).

Note that when page or pages fields are used within a reference they remain private to this particular reference. To define range of pages (or number of pages) for the note use note-pages field. In the reference database, though, pages and note-pages fields cam be used interchangeably.

When the author name is directly mentioned in the text, Harvard system specifies alternative formatting of the reference that can be achieved with direct field:

[(KnuthAoP2>> direct:yes; pages:10-15)] provides an extensive analysis of linear congruential generator in //Seminumerical Algorithms//.

The above reference will be rendered as:

Donald Knuth (1997, pp.10-15) provides an extensive analysis of linear congruential generator in Seminumerical Algorithms.

If you want to have different formatting of author name for notes and references (e.g. to shorten long list of authors) you can define ref-author field. Note that this field will affect all references to the specified note on the page:

It has been shown that the seed value of a LCG can be deduced from generated random numbers [(KnuthLCE1985>> ref-author:Knuth)].

The above reference will be rendered as:

It has been shown that the seed value of a LCG can be deduced from generated random numbers (Knuth, Jan 1985).

The publication date also can be rendered differently in notes and references. If it is specified using month and year fields, the references will use only year of publication:

[(:KnuthLCE-Jan-1985>>
author     : Donald Knuth
ref-author : Knuth
title      : Deciphering a linear congruential encryption
journal    : IEEE Transactions on Information Theory
volume     : 31(1)
month      : Jan
year       : 1985
publisher  : IEEE
note-pages : 49-52
issn       : 0018-9448
url        : http://ieeexplore.ieee.org/search/freesrchabstract.jsp?tp=&arnumber=1056997
)]

It has been shown that the seed value of a LCG can be deduced from generated random numbers [(:KnuthLCE-Jan-1985)].

The above reference will be rendered as:

It has been shown that the seed value of a LCG can be deduced from generated random numbers (Knuth, 1985).

The note text for KnuthLCE-Jan-1985 will be rendered identical to the note KnuthLCE1985 above.

See also

plugin/refnotes/structured.txt · Last modified: 2017-02-28 08:07 by pan One