Yusef's Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== RefNotes Syntax ======

There are two major parts of the syntax: references and note blocks.


===== References =====

The basic reference syntax is similar to the footnotes:

<code>
[(This is a note.)]
</code>

As with the footnotes, the reference is replaced with a link to the note text. There are number of ways to customize the reference link (see [[#style|style]]) but by default it looks like a footnote: a sequential number with right parenthesis.

The text itself is rendered in a [[#Note blocks|separate section]] of the page (by default at the end of the page). In the notes you can use basic text formating, links, smiles, etc. But more complex syntax (e.g. paragraphs, tables, lists) is going to be ignored.


==== Multiple references ====

Quite often it is required to refer multiple times to the same note. Common examples are citing the same source multiple times or having a "feature comparison" table where cells contain only //"Yes/No"// values but there is some extra information or requirement associated with the cell. DokuWiki allows to refer to an existing footnote by copying its text. To prevent copy-pasting of the text, using RefNotes you can reference a note with ''%%[(#?)]%%'' syntax, where ''?'' is the number of the note:

<code>
This is where the note is introduced the first time[(This is a note.)].
And here is another reference[(#1)] to the same note.
</code>

Every time a note is introduced in the text it gets a sequential number as an identifier. The extra reference to the same note does not increase the note counter, so in the example above a reference ''%%[(#2)]%%'' would be ignored as there is no second note.

When multiple references to a single note are rendered, DokuWiki uses a separate identifier (sequential number) for every reference. With RefNotes you can choose whether you want multiple references to have unique identifiers or to share identifier of the note they refer to (''[[:plugin:refnotes:style#Multi-reference identifier (multi-ref-id)|multi-ref-id]]'' style).


==== Named notes ====

Referring to a note by it's number is error-prone as over the history of the page this number can change. Alternative way of the note identification is giving it a unique name. For the name you can use any string of alpha-numeric characters and underscores that starts with a letter. The name is separated from the note text with a ''">"'' sign:

<code>
[(name>This is a named note.)]
</code>

In case of multiple references, the named note can be referred to by omitting the text and using only its name. The names are case sensitive, so make sure you use the exact spelling. The note still gets the sequential numeric identifier, so you can reference it both ways:

<code>
This is where the note is introduced the first time[(name>This is a note.)].
And here is another reference[(#1)] to the same note. And yet another reference[(name)].
</code>

The most important advantage of names over numeric identifiers is that the named note is defined at the point where its name is used the first time even if there is no text attached to it. Later in the text the note body can be re-defined with the usual syntax:

<code>
This is where the note is introduced the first time[(name)].
And here is another reference[(#1)] to the same note. And yet
another reference[(name>This is a note.)].
</code>

In combination with the [[#Hidden references|hidden references]] this allows to move the note text definitions out of the main text body and group them, for example, at the end of the page. The note text can be redefined a number of times but the last definition prior to the [[#Note blocks|note rendering]] is the only one that counts. The named notes can also be defined outside of the page that refers to them. This can be done either from the [[:plugin:refnotes#configuration|configuration interface]] or in the [[:plugin:refnotes:refdb|reference database]].


==== Namespaces ====

The notes with similar purpose (e.g. citations) can be grouped into a separate namespace. Every namespace is rendered separately and can have it's own style for references and notes formatting. The RefNotes namespaces follow DokuWiki style --- the namespace and name are separated by a colon: 

<code>
[(cite:>[[wp>DokuWiki|Wikipedia]])]
[(cite:dev>[[http://www.dokuwiki.org/development|DokuWiki Development]])]
[(cite:#1)]
</code>

All the references that don't specify the namespace explicitly point to the notes in root namespace ('':''). So the following two references point to the same note:

<code>
The first reference[(note>This is a note.)] and the second[(:note)] one.
</code>

The strict rules for the note naming are slightly released for fully qualified note names. If name starts with namespace specification, apart from alpha-numeric characters you can also use some extra symbols, so you can have notes named like, for example, "Smith&Johns(2012)." Note that this applies only to note names -- namespace names are still restricted to alpha-numeric characters. The following symbols are allowed in the extended name syntax:

<code>
. & ( ) [ ] { } + -
</code>

Namespaces can be nested one into another. The nested namespace inherits all style properties from the parent namespace. This inheritance take place once during parsing of a page -- at the point of first reference to the sub-namespace. From that point the style of the parent and sub-namespaces can be changed independently. It is also possible to override this inheritance by explicitly specifying another namespace (see the ''[[:plugin:refnotes:style#Inherit style from another namespace (inherit)|inherit]]'' style description).


==== Structured references ====

Note text can be defined either as plain DokuWiki markup or as collection of named data fields. The fields are combined into the note text according to ''[[:plugin:refnotes:style#Notes rendering|note-render]]'' style. Inside the reference the text is treated as fields if it starts (or is separated from name) with double ''">"'' sign:

<code>
[(GangOfFour>>
title     : Design Patterns: Elements of Reusable Object-Oriented Software
authors   : Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides
publisher : Addison-Wesley
published : 1994
pages     : 395
)]
</code>

See [[:plugin:refnotes:structured|Structured References]] for more detailed description of this syntax.


==== Hidden references ====

Sometimes, especially in the tables, the note text breaks visual structure of the wiki markup and it's preferable to move the note definition elsewhere. The named notes allow you to reference a note that has no text yet, but eventually the text has to be defined, which normally would introduce an extra reference to the note. To prevent this behavior all references that are defined at the start of a line are excluded from rendering.

<code>
|            ^  Product 1  ^  Product 2  ^  Product 3  ^
^ Feature A  |     Yes     |   Yes[(a)]  |   Yes[(a)]  |
^ Feature B  |     Yes     |   Yes[(a)]  |     No      |
^ Feature C  |     No      |     Yes     |   Yes[(b)]  |

[(a>Some requirement.)]
[(b>Another requirement.)]
</code>

In order to be hidden the references have to be placed in a separate paragraph. So in the following example the references will be rendered even if they are at the start of a line:

<code>
The following references
[(a>This is a note.)]
[(b>Another note.)]
will be rendered.
</code>


==== Inline notes ====

All references to the inline notes use the note text as reference text. The notes themselves are not added to the notes section, so the references are the only place where the note text is displayed. As there is no entry in the notes section to point to, no link is added to the reference. But it is recommended to include some link into the note text, so that references can point somewhere. For example, a typical use case for inline notes is to have missing reference placeholders similar to Wikipedia's<sup>%%[%%//[[citation needed]]//%%]%%</sup>.

The inline notes can be created only from the [[:plugin:refnotes#configuration|configuration interface]]. There you can also control which namespace styles are applied to references.


===== Note blocks =====

By default all the notes are rendered at very bottom of a page just above the footnotes. There is no need to add any markup on the page in order to get this behavior.

Yet it's possible to specify the notes location explicitly with the following syntax:

<code>
~~REFNOTES~~
</code>

During rendering this keyword is replaced by all the notes from the root namespace. You can provide extra attributes to this command to specify the namespace to be rendered or to limit number of notes that will be rendered:

<code>
~~REFNOTES cite ~~
~~REFNOTES cite 10 ~~
~~REFNOTES cite /2 ~~
</code>

If the notes limit specification starts with a slash, the plugin will render only specified part of the notes. For example, ''/2'' will render half of the notes, ''/3'' will render a third, etc. This can be handy if you want to render the notes in [[plugin:columns|multiple columns]]:

<code>
===== Citations =====
<columns 100% 50%> ~~REFNOTES cite /2 ~~ <newcolumn> ~~REFNOTES cite ~~ </columns>
</code>


==== Style ====

Every namespace can have its own style for rendering references and notes. You can define this style either via the [[:plugin:refnotes#configuration|configuration interface]] or directly on the page using alternative notes syntax:

<code>
<refnotes>
refnote-id       : a
reference-format : []
note-id-format   : []
note-id-base     : text
</refnotes>
</code>

This syntax combines the style definition with the notes rendering. If you want to keep the styling separate from the rendering you can place such definition somewhere on the top of the page before any references --- if there are no notes in a given namespace the rendering commands are ignored.

The style definitions have to be separated either by a new line character (one definition per line) or by semicolon. Of course you can also specify the namespace and the rendering limit:

<code>
<refnotes cite /2> refnote-id: i; note-preview: none </refnotes>
</code>

All omitted styles are either derived from the parent namespace or are set to their default value. The default style resembles the footnotes formatting as close a possible.

All supported styles are listed on the [[:plugin:refnotes:style|style reference]] page.


==== Scopes ====

Every time you render the notes you introduce a new scope. The scope includes all references above the note block and the block itself. References and notes below the rendering instruction belong to the next scope. By default every scope has its own reference and note counters, so by rendering the notes you effectively reset the numbering of the references. Though, it is possible to merge all the scopes of a namespace into a single one using the ''[[:plugin:refnotes:style#Scoping behavior (scoping)|scoping]]'' style.

Every namespace has its own scoping. All styling applied to the namespace being rendered is used in the current scope and all scopes that follow.


==== Namespace merging ====

Main purpose of namespaces is to style different kinds of notes. Yet it is quite convenient, especially in the [[:plugin:refnotes:refdb|reference database]], to organize notes by topic using namespaces. For example, all programming book references could be grouped into '':ref:prog:'' namespace, while all mathematics books could go into '':ref:math:''. This approach may cause a problem when books on both topics are referenced on a single page: every namespace will have separate scope with its own note block and independent numbering of references and notes. To group all references into a single scope you can specify multiple namespace names:

<code>
~~REFNOTES ref:prog ref:math ~~
</code>

By default all notes and references from both namespaces will be rendered using style of the first one. You can override this behavior by explicitly inheriting specific style:

<code>
<refnotes ref:prog ref:math> inherit: harvard </refnotes>
</code>
Yusef's Wiki

User Tools

Site Tools

Page Tools
