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

Download
Stog-writing is available in Opam. With opam installed, just type the following command to install stog-writing:
opam install stog-writing

Stog-writing is hosted on Framagit.

Releases
  • 0.19.0 [2021/05/18]:
    • Upgrade to ocaml 4.12.0 and Stog 0.19.0
  • 0.17.0 [2016/11/30]:
    • when generating ids, use attribute values if could not get a non-empty id from cdata
    • in configuration file, it is now possible to specify for each tag whether to add anchor link and whether to embed the link and the block in another tag.
  • 0.16.0 [2015/11/25]:
    • Upgrade to Stog 0.16.0 and Xtmpl 0.13.0
  • 0.13.0 [2014/10/09]:
    • more powerful format specification in <cite>: <cite begin="..." end="..." sep="..." format="..."/> and also look for <cite-begin>, <cite-end> and <cite-sep> in environment,
    • <bibliography keywords="kwd1,.."> to include bibliography items having the required keywords associated in keywords fields
  • 0.12.0 [2014/05/16]:
    • Upgrade to Stog 0.12.0.
  • 0.11.0 [2014/03/20]:
    • <note> handles an id attribute used instead of the one forged from the note number,
    • follow changes in Stog 0.11.0 (hids->paths, documents instead of elements),
    • use <doc> tag to generate links to bibliography references.
  • 0.10.0 [2014/01/21]:
    • Upgrade to new Stog 0.10.0 architecture,
    • Add class for footnote links,
    • Handle multiple references in <cite>,
    • Apply base rules when bulding bib entries,
    • Use template bib-entry.tmpl instead of bib_entry.tmpl,
    • Fix: generate paragraph link code even for paragraphs with predefined ids,
    • Simplify auto id generation.
  • 0.8.0 [2013/03/19]: Upgrade to Stog 0.8.0.
  • 0.7.0 [2013/02/13]: Minor fixes.
  • 0.6: First numbered release.
Installation and usage

To install:

git clone git@github.com:zoggy/stog-writing.git
cd stog-writing
make all install

(you must have Menhir installed). This will install the stog-writing package with ocamlfind.

To use:

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. You can use the bib-entry.tmpl file included as an example. You will have to place it in your stog template directory.