# Contents of /libjabref-plugin-oo-java/branches/upstream/current/OOPlugin.html

Revision 2085 - (show annotations)
Thu Feb 25 16:20:37 2010 UTC (10 years, 9 months ago) by gregoa
File MIME type: text/html
File size: 18031 byte(s)
[svn-upgrade] Integrating new upstream version, libjabref-plugin-oo-java (0.7.2+ds)

 1

OpenOffice plugin for JabRef

2 3

Introduction

4 5

JabRef is an open source BibTeX bibliography 6 manager. 7

This plugin offers an interface for inserting citations and formatting a Bibliography in an 8 OpenOffice writer document from JabRef.

9 10 11

How to use the plugin

12 13

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 plugins below the directory where the JabRef 16 jar file is installed (typically under C:\Program files\Jabref 2.x 17 if you are running under Windows). The plugin should be loaded next time you 18 start JabRef, and an item named OpenOffice.org panel should appear in 19 JabRef's Plugins menu. 20

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 openoffice.org-java-common or something similar).

24 25

26 2009-08-26: Version 0.7: BibTeX fields are now preprocessed to handle LaTeX \textit and \textbf commands and 27 character sequences. NOTE: it is no longer necessary to run FormatChars on fields.
28 2009-08-23: Version 0.6: Improved handling of undefined BibTeX keys. Added option to not sync automatically when adding citation.
29 2009-08-05: Version 0.5: Fixed connection problem on Mac. Fixed bug in merge function.
30 2009-06-03: Version 0.4: Added support for superscript/subscript tags in reference list, subscripted citations 31 and different brackets for numbering in the reference list.
32 2009-05-17: Version 0.3: Added MinimumGroupingCount property. Some GUI changes.
33 2009-04-02: Version 0.2.1: Fixed bug in sorting of reference list.
34 2009-03-01: Version 0.2: Better sorting of citations in captions, tables and footnotes.
35 2009-02-25: Version 0.1.9: Added support for bold/italic citation markers, and for citations in table cells and footnotes.
36 2008-12-21: Version 0.1.2: Added invisible citations. Merged citations are now sorted.
37 2008-11-19: Version 0.1.1: Improved handling of OpenOffice shutdown and reconnect.
38 2008-10-25: Version 0.1: User interface improvements. Can now select which Writer document to work with.
39 2008-10-19: Version 0.0.9: Enabled connection to OpenOffice.org 3. Streamlined connection process.
40 2008-09-03: Version 0.0.8: No major changes, but packaged with JabRef 2.4.
41 2008-02-20: Version 0.0.7: New interface for style selection. Styles can now specify paragraph format.
42 2008-02-13: Version 0.0.6: Sorting and grouping of number citation markers.
43 2008-02-06: Version 0.0.5: Modified style file format. Fixed bug in handling names with elements like "van der".
44 2008-01-09: Version 0.0.4: Style file is now automatically reloaded if modified.
45 2007-12-17: Version 0.0.3: From this version, we bypass OO's built-in bibliographic system.
46 2007-12-04: Version 0.0.2
47 2007-12-01: Version 0.0.1
48 49

50

The plugin.

51

Plugin source code. The source code tree includes four 52 OpenOffice.org jars and JabRef 2.5. The plugin is built using 53 an included Ant build file.

54

Example style file

55 56

The plugin is distributed under the terms of the GNU 57 General Public License, 58 version 2 or later.

59 60

Using the OpenOffice interface

61 62

To communicate with OpenOffice, the OO plugin must first connect to a running OpenOffice 63 instance. You need to start OpenOffice and enter your document before connecting from 64 JabRef. The plugin needs to know the location of your OpenOffice executable (soffice.exe on 65 Windows, and soffice on other platforms), and the directory where several OpenOffice 66 jar files reside. If you connect by clicking the Connect button, the plugin will try to 67 automatically determine these locations. If this does not work, you need to connect using the 68 Manual connect button, which will open a window asking you for the needed locations.

69 70

After the connection has been established, you can insert citations by selecting one or more 71 entries in JabRef and using the Push to OpenOffice button in the dropdown menu of JabRef's 72 toolbar, or by using the appropriate button in the OpenOffice plugin panel in the side pane. This 73 will insert citations for the selected entries at the current cursor position in the OpenOffice 74 document, and update the bibliography to contain the full reference.

75 76

Note: JabRef does not use OpenOffice's built-in bibliography system, because of the 77 limitations of that system. A document containing citations inserted from JabRef will 78 not generally be compatible with other reference managers such as Bibus and Zotero.

79 80

Two different types of citations 81 can be inserted - either a citation in parenthesis, "(Author 2007)", or an in-text citation, 82 "Author (2007)". This distinction is only meaningful if author-year citations are used instead of 83 numbered citations, but the distinction will be preserved if you switch between the two styles.

84 85

If you modify entries in JabRef after inserting their citations into OpenOffice, you will 86 need to synchronize the bibliography. The Sync OO bibliography button will update all 87 entries of the bibliography, provided their BibTeX keys have not been altered (JabRef encodes the 88 BibTeX key into the reference name for each citation to keep track of which BibTeX key 89 the original JabRef entry has).

90 91

The style file

92 93 You need to select a style file before connecting to OpenOffice - an external file which is selected 94 using a standard file dialog. The style file defines the 95 format of citations and the format of the bibliography. You can use standard JabRef export 96 formatters to process entry fields before they are sent to OpenOffice. 97 Through the style file, the intention is to give as much flexibility in citation styles as possible. 98 99

Here is an example style file:

100
101  NAME
102  Example style file for JabRef-oo plugin.
103
104  JOURNALS
105  Journal name 1
106  Journal name 2
107
108  PROPERTIES
109  Title=References
110  IsSortByPosition=false
111  IsNumberEntries=false
112  ReferenceParagraphFormat=Default
114
115  CITATION
116  AuthorField=author/editor
117  YearField=year
118  MaxAuthors=3
119  MaxAuthorsFirst=6
120  AuthorSeparator=,
121  AuthorLastSeparator= &
122  EtAlString= et al.
123  YearSeparator=
124  InTextYearSeparator=
125  BracketBefore=[
126  BracketAfter=]
127  BracketBeforeInList=[
128  BracketAfterInList=]
129  CitationSeparator=;
130  UniquefierSeparator=,
132  MinimumGroupingCount=3
133  FormatCitations=false
134  ItalicCitations=false
135  BoldCitations=false
136  SuperscriptCitations=false
137  SubscriptCitations=false
138
139
140  LAYOUT
141  article=\format[AuthorLastFirst,AuthorAbbreviator,AuthorAndsReplacer]{\author} (<b>\year\uniq). <i>\title, \journal \volume\begin{pages} : \format[FormatPagesForHTML]{\pages}\end{pages}.
142
143  book=\format[AuthorLastFirst,AuthorAbbreviator,AuthorAndsReplacer]{\author}\begin{editor}\format[AuthorLastFirst,AuthorAbbreviator,AuthorAndsReplacer]{\editor} (Ed.)\end{editor}, <b>\year\uniq. <i>\title. \publisher, \address.
144
145  incollection=\format[AuthorLastFirst,AuthorAbbreviator,AuthorAndsReplacer]{\author} (<b>\year\uniq). <i>\title. In: \format[AuthorLastFirst,AuthorAbbreviator,AuthorAndsReplacer]{\editor} (Ed.), <i>\booktitle, \publisher.
146
147  inbook=\format[AuthorLastFirst,AuthorAbbreviator,AuthorAndsReplacer]{\author} (<b>\year\uniq). <i>\chapter. In: \format[AuthorLastFirst,AuthorAbbreviator,AuthorAndsReplacer]{\editor} (Ed.), <i>\title, \publisher.
148
149  phdthesis=\format[AuthorLastFirst,AuthorAbbreviator,AuthorAndsReplacer]{\author} (<b>\year\uniq). <i>\title, \school.
150
151  default=\format[AuthorLastFirst,AuthorAbbreviator,AuthorAndsReplacer]{\author} (<b>\year\uniq). <i>\title, \journal \volume\begin{pages} : \format[FormatPagesForHTML]{\pages}\end{pages}.
152
153
154 155

(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.)

156
157 158

The PROPERTIES section describes global properties for the bibliography: 159

• Title: determines the header text for the bibliography.
160
• IsSortByPosition: determines how the bibliography is sorted. If true, the entries 161 will be sorted according to the order in which they are cited. If false, the entries will be 162 sorted alphabetically by authors.
163
• IsNumberEntries: determines the type of citations to use. If true, number 164 citations will be used. The citation numbers will be included in the bibliography as well. 165 If false, author-year citations will be used.
166

167 168

The CITATION section describes the format of the citation markers inserted into the text. 169 If numbered entries are used, only the BracketBefore and BracketAfter properties 170 are relevant - they define which characters the citation number is wrapped in. The citation is composed 171 as follows:
172 [BracketBefore][Number][BracketAfter]
173 where [Number] is the number of the citation, determined according to the ordering of the bibliography and/or 174 the position of the citation in the text. If a citation refers to several entries, these will be separated 175 by the string given in the property CitationSeparator (for instance, if CitationSeparator=;, 176 the citation could look like [2;4;6]). If two or more of the entries have a series of consecutive 177 numbers, the numbers can be grouped (for instance [2-4] for 2, 3 and 4 or [2;5-7] for 178 2, 5, 6 and 7). The property GroupedNumbersSeparator (default -) determines which string separates the first and last 179 of the grouped numbers. The integer property MinimumGroupingCount (default 3) determines what number of 180 consecutive numbers are required before entries are grouped. If MinimumGroupingCount=3, the numbers 181 2 and 3 will not be grouped, while 2, 3, 4 will be. If MinimumGroupingCount=0, no grouping will be 182 done regardless of the number of consecutive numbers. 183

184

If numbered entries are not used, author-year citations will be created based on the citation properties. 185 A parenthesis citation is composed as follows:
186 [BracketBefore][Author][YearSeparator][Year][BracketAfter]
187 where [Author] is the result of looking up the field or fields given in the AuthorField property, 188 and formatting a list of authors. The list can contain up to MaxAuthors names - if more are present, 189 the list will be composed as the first author plus the text specified in the property EtAlString. 190 If several, slash-separated, fields are given in the AuthorField property, they will be looked up 191 successively if the first field is empty for the given BibTeX entry. In the example above, the "author" field will 192 be used, but if empty, the "editor" field will be used as a backup. 193

The names in the author list will be separated by the text given by the AuthorSeparator 194 property, except for the last two names, which will be separated by the text given by AuthorLastSeparator. 195

196

[Year] is the result of looking up the field or fields given in the [YearField] property.

197 An in-text citation is composed as follows:
198 [Author][InTextYearSeparator][BracketBefore][Year][BracketAfter]
199 where [Author] and [Year] are resolved in exactly the same way as for the parenthesis citations. 200

201

If two different cited sources have the same authors and publication year, and author-year citations are used, 202 their markers will need modification in order to be distinguishable. This is done automatically by appending a 203 letter after the year for 204 each of the publications; 'a' for the first cited reference, 'b' for the next, and so on. 205 For instance, if the author "Olsen" has two cited papers from 2005, the citation markers will be modified to 206 (Olsen, 2005a) and (Olsen, 2005b). In the bibliography 207 layout, the placement of the "uniquefier" letter is indicated explicitly by inserting the virtual field 208 uniq.

209

If several entries that have been "uniquefied" are cited together, they will be grouped in the citation 210 marker. For instance, of the two entries in the example above are cited together, the citation marker will 211 be (Olsen, 2005a, b) rather than Olsen, 2005a; Olsen, 2005b). The grouped uniquefier 212 letters (a and b in our example) will be separated by the string specified by the UniquefierSeparator 213 property. 214

215

The property FormatCitations determines whether the citation markers should be formatted with 216 regards to italics, boldness, superscript and subscript. If FormatCitations is false, no such formatting 217 will be done. If true, the citations will be italicized or not depending on the ItalicCitations property, set to bold 218 or not depending on the BoldCitations property, and similar for the SuperscriptCitations and 219 SubscriptCitations properties.

220

The LAYOUT section describes how the bibliography entry for each entry type in JabRef 221 should appear. Each line should start with either the name of a BibTeX entry type, or the word 222 default, followed by a '='. The default layout will be used for all 223 entry types for which an explicit layout hasn't been given.

224

The remainder of each line defines the layout, with normal text and spaces appearing literally 225 in the bibliography entry. Information from the BibTeX entry is inserted by adding \field markers 226 with the appropriate field name (e.g. \author for inserting the author names). Formatting 227 information for the field can be included here, following JabRef's standard export layout syntax. 228 Refer to JabRef's documentation on custom export filters 229 for more information about which formatters are available.

230

If author-year citations are used, you have to explicitly specify the position of the "uniquefier" letter 231 that is added to distinguish similar-looking citations. This is done by including a marker for the virtual field 232 uniq, typically right after the year (as shown in the example style file). The uniq 233 field is automatically set correctly for each entry before its reference text is laid out. 234

235

To indicate formatting in the bibliography, you can use the HTML-like tag pairs <b> </b>, 236 <i> </i>, <sup> </sup> and <sub> </sub> to specify bold text, 237 italic text, superscript and subscript, respectively.

238

If you are using numbered citations, the number for each entry will be automatically inserted at the start 239 of each entry in the reference list. By default, the numbers will be enclosed in the same brackets defined for 240 citations. The optional citation properties BracketBeforeInList and 241 BracketAfterInList override BracketBefore and BracketAfter if set. These 242 can be used if you want different types of brackets (or no brackets) in the reference list. Note that these need 243 not be brackets as such - they can be any combination of characters.

244 245

Known issues

246 247
248
• Make sure to save your Writer document in OpenDocument format 249 (odt). Saving to Word format will lose your reference marks.
• 250
• There is currently no support for footnote based citations.
• 251
• The cursor may be poorly positioned after inserting a citation.
• 252