Table of Contents
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
Refer to a structured reference
In order to include a reference into your wiki page, you basically create a note that contains the name of the reference:
[(:ref:prog:Hunt&Thomas(1999))]
Define a structured reference
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 | ||||
accessed | Accessed | Last access date for an online publication URL. | r, d | n | |
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 | |
format | Format | Format of an electronic publication (e.g. Online, Kindle, PDF, EPUB, etc.). | 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 will automatically reduce a long list of authors when rendering references. The list containing more than 3 names will be replaced by the first name followed by et al. If this behavior is not suitable, 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.