[svn-upgrade] Integrating new upstream version, jabref-plugin-oo (0.7.4+ds)
[debian/jabref-plugin-oo.git] / OOPlugin.html
1 <h1>OpenOffice plugin for JabRef</h1>
2
3 <h2>Introduction</h2>
4
5         <p><a href="http://jabref.sf.net">JabRef</a> is an open source BibTeX bibliography
6           manager.
7         <p>This plugin offers an interface for inserting citations and formatting a Bibliography in an
8         OpenOffice writer document from JabRef.</p>
9
10
11         <h2>How to use the plugin</h2>
12
13         <p>The plugin can be used with JabRef 2.4 or newer. If your JabRef version doesn't
14         have a plugin manager (versions 2.4.x), you need to put the plugin jar file
15         in a directory named <code>plugins</code> below the directory where the JabRef
16         jar file is installed (typically under <code>C:\Program files\Jabref 2.x</code>
17         if you are running under Windows). The plugin should be loaded next time you
18         start JabRef, and an item named <b>OpenOffice.org panel</b> should appear in
19         JabRef's <b>Plugins</b> menu.
20         <p>The plugin should work with OpenOffice versions 2.4.x and 3.x, provided it
21         is installed with Java support (this is usually the case on Windows, while in
22         some Linux distributions you need to install a separate package named
23         <code>openoffice.org-java-common</code> or something similar).</p>
24
25         <p><b>Updates:</b></p>
26         2010-05-11: Version 0.7.4: Added option to sort alphabetically for citations with multiple entries.<br>
27         2010-03-04: Version 0.7.3: Added support for &lt;smallcaps&gt; tag to indicate small caps in reference list. Several bug fixes.<br>
28         2010-02-02: Version 0.7.2: Added MaxAuthorsFirst property to override MaxAuthors the first time each citation appears.<br>
29         2009-10-07: Version 0.7.1: Several important bug fixes.<br>
30             2009-08-26: Version 0.7: BibTeX fields are now preprocessed to handle LaTeX \textit and \textbf commands and
31           character sequences. <b>NOTE: it is no longer necessary to run FormatChars on fields.</b><br>
32         2009-08-23: Version 0.6: Improved handling of undefined BibTeX keys. Added option to not sync automatically when adding citation.<br>
33         2009-08-05: Version 0.5: Fixed connection problem on Mac. Fixed bug in merge function.<br>
34         2009-06-03: Version 0.4: Added support for superscript/subscript tags in reference list, subscripted citations
35            and different brackets for numbering in the reference list.<br>
36             2009-05-17: Version 0.3: Added MinimumGroupingCount property. Some GUI changes.<br>
37         2009-04-02: Version 0.2.1: Fixed bug in sorting of reference list.<br>
38         2009-03-01: Version 0.2: Better sorting of citations in captions, tables and footnotes.<br> 
39         2009-02-25: Version 0.1.9: Added support for bold/italic citation markers, and for citations in table cells and footnotes.<br>
40         2008-12-21: Version 0.1.2: Added invisible citations. Merged citations are now sorted.<br>
41             2008-11-19: Version 0.1.1: Improved handling of OpenOffice shutdown and reconnect.<br>
42             2008-10-25: Version 0.1: User interface improvements. Can now select which Writer document to work with.<br>
43         2008-10-19: Version 0.0.9: Enabled connection to OpenOffice.org 3. Streamlined connection process.<br>
44         2008-09-03: Version 0.0.8: No major changes, but packaged with JabRef 2.4.<br>
45         2008-02-20: Version 0.0.7: New interface for style selection. Styles can now specify paragraph format.<br>
46         2008-02-13: Version 0.0.6: Sorting and grouping of number citation markers.<br>
47         2008-02-06: Version 0.0.5: Modified style file format. Fixed bug in handling names with elements like "van der".<br>
48         2008-01-09: Version 0.0.4: Style file is now automatically reloaded if modified.<br>
49         2007-12-17: Version 0.0.3: From this version, we bypass OO's built-in bibliographic system.<br>
50         2007-12-04: Version 0.0.2<br>
51         2007-12-01: Version 0.0.1<br>
52
53         <p><b>Downloads:</b></p>
54         <p><a href="net.sf.jabref.oo.ooplugin-0..jar">The plugin.</a></p>
55         <p><a href="JabRef-oo-0.6-src.zip">Plugin source code.</a> The source code tree includes four
56         OpenOffice.org jars and JabRef 2.5. The plugin is built using
57         an included Ant build file.</p>
58         <p><a href="example_style_file.jstyle">Example style file</a></p>
59
60         <p>The plugin is distributed under the terms of the GNU
61         <a href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html">General Public License</a>,
62         version 2 or later.</p>
63
64         <h2>Using the OpenOffice interface</h2>
65
66         <p>To communicate with OpenOffice, the OO plugin must first connect to a running OpenOffice
67         instance. You need to start OpenOffice and enter your document before connecting from
68         JabRef. The plugin needs to know the location of your OpenOffice executable (<b>soffice.exe</b> on
69         Windows, and <b>soffice</b> on other platforms), and the directory where several OpenOffice
70         jar files reside. If you connect by clicking the <b>Connect</b> button, the plugin will try to
71         automatically determine these locations. If this does not work, you need to connect using the
72         <b>Manual connect</b> button, which will open a window asking you for the needed locations.</p>
73
74         <p>After the connection has been established, you can insert citations by selecting one or more
75         entries in JabRef and using the <b>Push to OpenOffice</b> button in the dropdown menu of JabRef's
76         toolbar, or by using the appropriate button in the OpenOffice plugin panel in the side pane. This
77         will insert citations for the selected entries at the current cursor position in the OpenOffice
78         document, and update the bibliography to contain the full reference.</p>
79
80         <p><b>Note:</b> JabRef does not use OpenOffice's built-in bibliography system, because of the
81         limitations of that system. A document containing citations inserted from JabRef will
82         not generally be compatible with other reference managers such as Bibus and Zotero.</p>
83
84         <p>Two different types of citations
85         can be inserted - either a citation in parenthesis, "(Author 2007)", or an in-text citation,
86         "Author (2007)". This distinction is only meaningful if author-year citations are used instead of
87         numbered citations, but the distinction will be preserved if you switch between the two styles.</p>
88
89         <p>If you modify entries in JabRef after inserting their citations into OpenOffice, you will
90         need to synchronize the bibliography. The <b>Sync OO bibliography</b> button will update all
91         entries of the bibliography, provided their BibTeX keys have not been altered (JabRef encodes the
92         BibTeX key into the reference name for each citation to keep track of which BibTeX key
93         the original JabRef entry has).</p>
94
95         <h3>The style file</h3>
96
97         You need to select a style file before connecting to OpenOffice - an external file which is selected
98         using a standard file dialog. The style file defines the
99         format of citations and the format of the bibliography. You can use standard JabRef export
100         formatters to process entry fields before they are sent to OpenOffice.
101         Through the style file, the intention is to give as much flexibility in citation styles as possible.
102         
103         <p>Here is an example style file:</p>
104         <code><pre>
105 NAME
106 Example style file for JabRef-oo plugin.
107
108 JOURNALS
109 Journal name 1
110 Journal name 2
111
112 PROPERTIES
113 Title=References
114 IsSortByPosition=false
115 IsNumberEntries=false
116 ReferenceParagraphFormat=Default
117 ReferenceHeaderParagraphFormat=Heading 1
118
119 CITATION
120 AuthorField=author/editor
121 YearField=year
122 MaxAuthors=3
123 MaxAuthorsFirst=6
124 AuthorSeparator=,
125 AuthorLastSeparator= &
126 EtAlString= et al.
127 YearSeparator=
128 InTextYearSeparator=
129 BracketBefore=[
130 BracketAfter=]
131 BracketBeforeInList=[
132 BracketAfterInList=]
133 CitationSeparator=;
134 UniquefierSeparator=,
135 GroupedNumbersSeparator=-
136 MinimumGroupingCount=3
137 FormatCitations=false
138 ItalicCitations=false
139 BoldCitations=false
140 SuperscriptCitations=false
141 SubscriptCitations=false
142
143
144 LAYOUT
145 article=\format[AuthorLastFirst,AuthorAbbreviator,AuthorAndsReplacer]{\author} (&lt;b&gt;\year\uniq</b>). &lt;i&gt;\title</i>, \journal \volume\begin{pages} : \format[FormatPagesForHTML]{\pages}\end{pages}.
146
147 book=\format[AuthorLastFirst,AuthorAbbreviator,AuthorAndsReplacer]{\author}\begin{editor}\format[AuthorLastFirst,AuthorAbbreviator,AuthorAndsReplacer]{\editor} (Ed.)\end{editor}, &lt;b&gt;\year\uniq</b>. &lt;i&gt;\title</i>. \publisher, \address.
148
149 incollection=\format[AuthorLastFirst,AuthorAbbreviator,AuthorAndsReplacer]{\author} (&lt;b&gt;\year\uniq</b>). &lt;i&gt;\title</i>. In: \format[AuthorLastFirst,AuthorAbbreviator,AuthorAndsReplacer]{\editor} (Ed.), &lt;i&gt;\booktitle</i>, \publisher.
150
151 inbook=\format[AuthorLastFirst,AuthorAbbreviator,AuthorAndsReplacer]{\author} (&lt;b&gt;\year\uniq</b>). &lt;i&gt;\chapter</i>. In: \format[AuthorLastFirst,AuthorAbbreviator,AuthorAndsReplacer]{\editor} (Ed.), &lt;i&gt;\title</i>, \publisher.
152
153 phdthesis=\format[AuthorLastFirst,AuthorAbbreviator,AuthorAndsReplacer]{\author} (&lt;b&gt;\year\uniq</b>). &lt;i&gt;\title</i>, \school.
154
155 default=\format[AuthorLastFirst,AuthorAbbreviator,AuthorAndsReplacer]{\author} (&lt;b&gt;\year\uniq</b>). &lt;i&gt;\title</i>, \journal \volume\begin{pages} : \format[FormatPagesForHTML]{\pages}\end{pages}.
156
157 </pre>
158
159 <p>(Note that the layout for each entry type must be constrained to a single line in the style file - above, the lines are broken up to improve readability.)</p>
160         </code>
161
162         <p>The <b>PROPERTIES</b> section describes global properties for the bibliography:
163             <ul><li><code>Title</code>: determines the header text for the bibliography.</li></ul>
164             <ul><li><code>IsSortByPosition</code>: determines how the bibliography is sorted. If true, the entries
165                 will be sorted according to the order in which they are cited. If false, the entries will be
166                 sorted alphabetically by authors.</li></ul>
167             <ul><li><code>IsNumberEntries</code>: determines the type of citations to use. If true, number
168                 citations will be used. The citation numbers will be included in the bibliography as well.
169                 If false, author-year citations will be used.</li></ul>
170         </p>
171
172         <p>The <b>CITATION</b> section describes the format of the citation markers inserted into the text.
173         If numbered entries are used, only the <code>BracketBefore</code> and <code>BracketAfter</code> properties
174         are relevant - they define which characters the citation number is wrapped in. The citation is composed
175         as follows:<br>
176             [BracketBefore][Number][BracketAfter]<br>
177         where [Number] is the number of the citation, determined according to the ordering of the bibliography and/or
178         the position of the citation in the text. If a citation refers to several entries, these will be separated
179         by the string given in the property <code>CitationSeparator</code> (for instance, if <code>CitationSeparator</code>=;,
180         the citation could look like <code>[2;4;6]</code>). If two or more of the entries have a series of consecutive
181         numbers, the numbers can be grouped (for instance <code>[2-4]</code> for 2, 3 and 4 or <code>[2;5-7]</code> for
182         2, 5, 6 and 7). The property <code>GroupedNumbersSeparator</code> (default <code>-</code>) determines which string separates the first and last
183         of the grouped numbers. The integer property <code>MinimumGroupingCount</code> (default 3) determines what number of
184         consecutive numbers are required before entries are grouped. If <code>MinimumGroupingCount</code>=3, the numbers
185         2 and 3 will not be grouped, while 2, 3, 4 will be. If <code>MinimumGroupingCount</code>=0, no grouping will be
186         done regardless of the number of consecutive numbers.
187         </p>
188         <p>If numbered entries are not used, author-year citations will be created based on the citation properties.
189         A parenthesis citation is composed as follows:<br>
190             [BracketBefore][Author][YearSeparator][Year][BracketAfter]<br>
191         where [Author] is the result of looking up the field or fields given in the <code>AuthorField</code> property,
192         and formatting a list of authors. The list can contain up to <code>MaxAuthors</code> names - if more are present,
193         the list will be composed as the first author plus the text specified in the property <code>EtAlString</code>.
194         If several, slash-separated, fields are given in the <code>AuthorField</code> property, they will be looked up
195         successively if the first field is empty for the given BibTeX entry. In the example above, the "author" field will
196         be used, but if empty, the "editor" field will be used as a backup.
197         <p>The names in the author list will be separated by the text given by the <code>AuthorSeparator</code>
198         property, except for the last two names, which will be separated by the text given by <code>AuthorLastSeparator</code>.
199         If the property <code>AuthorLastSeparatorInText</code> is given, it overrides the former for citations of the in-text
200         type. This makes it possible to get citations like <code>(Olsen & Jensen, 2008)</code> and <code>Olsen and Jensen (2008)</code>
201         for the same style.
202         </p>
203         <p>[Year] is the result of looking up the field or fields given in the [YearField] property.</p>
204         An in-text citation is composed as follows:<br>
205             [Author][InTextYearSeparator][BracketBefore][Year][BracketAfter]<br>
206         where [Author] and [Year] are resolved in exactly the same way as for the parenthesis citations.
207         </p>
208         <p>If two different cited sources have the same authors and publication year, and author-year citations are used,
209         their markers will need modification in order to be distinguishable. This is done automatically by appending a
210         letter after the year for
211         each of the publications; 'a' for the first cited reference, 'b' for the next, and so on.
212         For instance, if the author "Olsen" has two cited papers from 2005, the citation markers will be modified to
213         <code>(Olsen, 2005a)</code> and <code>(Olsen, 2005b)</code>. In the bibliography
214         layout, the placement of the "uniquefier" letter is indicated explicitly by inserting the virtual field
215         <code>uniq</code>.</p>
216         <p>If several entries that have been "uniquefied" are cited together, they will be grouped in the citation
217         marker. For instance, of the two entries in the example above are cited together, the citation marker will
218         be <code>(Olsen, 2005a, b)</code> rather than <code>Olsen, 2005a; Olsen, 2005b)</code>. The grouped uniquefier
219         letters (a and b in our example) will be separated by the string specified by the <code>UniquefierSeparator</code>
220         property.
221         </p>
222         <p>The property <code>FormatCitations</code> determines whether the citation markers should be formatted with
223         regards to italics, boldness, superscript and subscript. If <code>FormatCitations</code> is false, no such formatting
224         will be done. If true, the citations will be italicized or not depending on the <code>ItalicCitations</code> property, set to bold
225         or not depending on the <code>BoldCitations</code> property, and similar for the <code>SuperscriptCitations</code> and
226         <code>SubscriptCitations</code> properties.</p>
227         <p>The <b>LAYOUT</b> section describes how the bibliography entry for each entry type in JabRef
228         should appear. Each line should start with either the name of a BibTeX entry type, or the word
229         <code>default</code>, followed by a '='. The <code>default</code> layout will be used for all
230         entry types for which an explicit layout hasn't been given.</p>
231         <p>The remainder of each line defines the layout, with normal text and spaces appearing literally
232         in the bibliography entry. Information from the BibTeX entry is inserted by adding <code>\field</code> markers
233         with the appropriate field name (e.g. <code>\author</code> for inserting the author names). Formatting
234         information for the field can be included here, following JabRef's standard export layout syntax.
235         Refer to <a href="http://jabref.sourceforge.net/help/CustomExports.php">JabRef's documentation on custom export filters</a>
236         for more information about which formatters are available.</p>
237         <p>If author-year citations are used, you have to explicitly specify the position of the "uniquefier" letter
238         that is added to distinguish similar-looking citations. This is done by including a marker for the virtual field
239         <code>uniq</code>, typically right after the year (as shown in the example style file). The <code>uniq</code>
240         field is automatically set correctly for each entry before its reference text is laid out.
241         </p>
242         <p>To indicate formatting in the bibliography, you can use the HTML-like tag pairs &lt;b&gt; &lt;/b&gt;,
243          &lt;i&gt; &lt;/i&gt;,  &lt;sup&gt; &lt;/sup&gt; and  &lt;sub&gt; &lt;/sub&gt; to specify bold text,
244          italic text, superscript and subscript, respectively.</p>
245         <p>If you are using numbered citations, the number for each entry will be automatically inserted at the start
246         of each entry in the reference list. By default, the numbers will be enclosed in the same brackets defined for
247         citations. The optional citation properties <code>BracketBeforeInList</code> and
248         <code>BracketAfterInList</code> override <code>BracketBefore</code> and <code>BracketAfter</code> if set. These
249         can be used if you want different types of brackets (or no brackets) in the reference list. Note that these need
250         not be brackets as such - they can be any combination of characters.</p>
251
252 <h2>Known issues</h2>
253
254 <ul>
255   <li>Make sure to save your Writer document in OpenDocument format
256   (odt). Saving to Word format will lose your reference marks.</li>
257   <li>There is currently no support for footnote based citations.</li>
258   <li>The cursor may be poorly positioned after inserting a citation.</li>
259   <li>Copy-pasting the example style file directly from this page can give an unparseable
260     file. To avoid this, instead download the example file from the link in the download section.</li>
261 </ul>
262
263 <h2>Contact</h2>
264
265 If you have tested this plugin, and want to give your feedback, or if you
266 want to contribute to the development of the plugin, please contact me at the
267 e-mail address mortenalver at users.sourceforge.net.
268
269