README.rst 3.22 KB
Newer Older
1 2 3
=================================================
 zot4rst: Zotero for reStructuredText (docutils)
=================================================
Erik Hetzner's avatar
Erik Hetzner committed
4 5

Background
6
~~~~~~~~~~
Erik Hetzner's avatar
Erik Hetzner committed
7

Erik Hetzner's avatar
Erik Hetzner committed
8
Zotero_ is a useful tool for managing citations.
Erik Hetzner's avatar
Erik Hetzner committed
9

10
zot4rst is an extension to the Python docutils_ package for including
Erik Hetzner's avatar
Erik Hetzner committed
11 12
citations in reStructuredText_ documents. zot4rst uses a simple
citation format, identical to that of pandoc.
13 14 15

zot4rst is developed under Linux, has been tested on Windows, and
should run under Mac OS.
16

Erik Hetzner's avatar
Erik Hetzner committed
17
Installation
18
~~~~~~~~~~~~
Erik Hetzner's avatar
Erik Hetzner committed
19 20

1. Install Zotero_.
21

22 23 24 25
2. Download and install zotxt:

   https://bitbucket.org/egh/zotxt/downloads/zotxt.xpi

26
3. Install zot4rst::
27

28
     pip install zot4rst
29

30 31 32
   or you can install from source::

     sudo python setup.py install
33

34 35
Quickstart
~~~~~~~~~~
Erik Hetzner's avatar
Erik Hetzner committed
36

37
See ``example/example.rst``, and the generated ``example/example.pdf``
Erik Hetzner's avatar
Erik Hetzner committed
38
and ``example/example.html``. Citation syntax is identical to pandoc.
Erik Hetzner's avatar
Erik Hetzner committed
39

40 41 42
zot4rst automatically maps citation keys (e.g., @DoeTitle2010) to
entries in the zotero database. The key should be of the form
@AuthorTitleDate. So, for the item:
Erik Hetzner's avatar
Erik Hetzner committed
43

44
  John Doe, “Article,” Journal of Generic Studies, 2006.
Erik Hetzner's avatar
Erik Hetzner committed
45

46
You could use: @DoeArticle2006. This should be easy to use, but the
Erik Hetzner's avatar
Erik Hetzner committed
47 48
reference needs to be unambiguous, which might be a problem if there
are multiple items with the same author, title, and year. I am looking
49
into ways to handle this better.
Erik Hetzner's avatar
Erik Hetzner committed
50

51 52 53 54 55 56 57 58 59
To include Zotero_ citations in a reStructuredText_ document, you must
use the bundled ``zrst2*`` scripts, which have been modified to
include support for ``zotero`` directives. These executables are
installed using ``setup.py`` above. Currently, they are:

- ``zrst2html``
- ``zrst2odt``
- ``zrst2pdf``
- ``zrst2pseudoxml``
Erik Hetzner's avatar
Erik Hetzner committed
60 61
- ``zrst2rst``

62 63 64 65 66 67 68 69
Sphinx
~~~~~~

To use in sphinx, simply add the ``zot4rst.sphinx`` extension to your
``conf.py`` file::

  extensions = ['zot4rst.sphinx']

70 71 72 73 74 75 76 77
Pelican
~~~~~~~

To use in pelican_ (version 3.1 or later), add the following to your
``pelicanconf.py`` file:

  PLUGINS = ['zot4rst.pelican_plugin',]

78 79
Details
~~~~~~~
Erik Hetzner's avatar
Erik Hetzner committed
80

81
Some details, in no particular order.
Erik Hetzner's avatar
Erik Hetzner committed
82

83 84 85 86 87 88 89
Note that ``zrst2rst`` will transform your citations into plain
reStructuredText files without the Zotero extension. For example::

  A citation group :xcite:`[see @item1 p. 34-35; also @item3 chap. 3]`.

will become::

Erik Hetzner's avatar
Erik Hetzner committed
90 91
  A citation group (see Doe 2005, p. 34–35; also Doe and Roe 2007,
  chap. 3).
92 93

and the bibliography will be fully expanded. This can be used to
Erik Hetzner's avatar
Erik Hetzner committed
94
create RST files that will work without zot4rst.
95

Erik Hetzner's avatar
Erik Hetzner committed
96 97
If you use a footnote citation format, zot4rst will insert footnotes
for you.
Erik Hetzner's avatar
Erik Hetzner committed
98

99 100 101 102
However, if you also use regular autonumbered footnotes in the same
section or paragraph, the ordering will be wrong. So if you want to do
this, you will need to put your citations in a footnote
explicitly. For example::
Erik Hetzner's avatar
Erik Hetzner committed
103

104 105
  Water is wet. [#]_ But there are those who dispute it. [#]_

Erik Hetzner's avatar
Erik Hetzner committed
106
  .. [#] :xcite:`[See @item3]`.
107 108

  .. [#] These people are wrong.
Erik Hetzner's avatar
Erik Hetzner committed
109 110 111 112

.. _Zotero: http://www.zotero.org/
.. _`org-mode`: http://orgmode.org/
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
Erik Hetzner's avatar
Erik Hetzner committed
113
.. _docutils: http://docutils.sourceforge.net/
114
.. _`docutils snapshot`: http://docutils.sourceforge.net/docutils-snapshot.tgz
115 116
.. _`sphinx bibtex`: http://sphinxcontrib-bibtex.readthedocs.org/
.. _pelican: https://github.com/getpelican/pelican/