This plugin adds new rewrite rules to use footnotes and bibliographies in your documents.

Usage:

stog --package stog_writing ...
Footnotes

Footnotes are defined with the following syntax: 

<note>...</note>

As usual, you can put any xml in the <note> node, it will be rewritten using the current environment.

For this to work, all the XML tree containing notes must be included in a node 

<prepare-notes>
  ...
</prepare-notes>

At last, all footnotes are inserted when a <notes/> node is encountered. Numbering is automatic.

Example: 

<prepare-notes>
    ...
    bla bla bla<note>Hey, this is a footnote</note>.
    ...
    pim pam poum<note>This is a second note.</note>.
    ...
    <notes/>
</prepare-notes>
Bibliography
Defining bibliographies

Bibliographies can be defined in any document header, with the following syntax: 

<bibliographies ...>
  <bibliography .../>
  <bibliography .../>
  ...
</bibliographies>

The <bibliographies> node can have the following attributes:

  • sort="...": the items in each bibliography will be sorted by default, according to the given list of comma-separated fields,
  • reverse="true": the items in each bibliography will be sorted in reverse order,
  • prefix="...": a default string to use as prefix for ids of entries read from bibtex files.

Each <bibliography> node can have the following attributes:

  • name="...": the name of the bibliography, for further reference; default name is "default"; each bibliography must have a site-wide unique name,
  • files="...": a comma-separated list of filenames, in bibtex format; filenames are relative to the document source file,
  • sort, reverse and prefix: can be used to override the same attributes of the <bibliographies> node.

Using attribute bib-files="file1.bib,file2.bib,..." in an document header is a shortcut for 

<bibliographies>
  <bibliography files="file1.bib,file2.bib,..."/>
</bibliographies>
Using bibliographies

In your pages and posts, you can use this syntax to cite an entry: 

    <cite href="entryid"/>

The format of the reference can be set by various means, in order of priority:

  • in the children of the <cite> node, for example: 
    <cite href="..."><bib-entry-author/>, <i><bib-entry-title/></i></cite>
  • using the format attribute, for example: 
    <cite format="$(author): $(title)" href="entryid"/>
  • setting cite-format in the environment, for example in the header of the page/article: 
    <cite-format><bib-entry-author/>, <i><bib-entry-title/></i></cite-format>

These examples will display the contents of the fields author and title of the entry as text for the reference link.

The default format is [<bib-entry-rank/>].

The rank is the position of the item in its bibliography.

The characters used to enclose the reference text are '[' and ']' but can be changed:

  • by using the cite-begin and cite-end attributes in the <cite> rule,
  • or by defining cite-begin and cite-end in the environement (of the document or for the whole site).

In case the href attribute contains several references, a separator is used between reference texts. By default it is "," but it can be changed by using the cite-sep attribute in the <cite> rule, or by setting cite-sep in the environment.

To include the complete list of entries of a bibliography, use the following node: 

<bibliography/>

The attribute name="..." can be used to specify the name of the bibliography to insert. Default name is "default". The attribute keywords=..." allows to filter the entries according to the keywods they are associated to, using the keywords field in the .bib files.

The <bibliography> node will reduced into the list of its entries, each entry being inserted using the bib-entry.tmpl template. A default bib-entry.tmpl file can be found in the Stog template directory.