Imported Upstream version 2.9.1+ds
[debian/jabref.git] / src / help / OpenOfficeIntegration.html
1 <html xmlns="http://www.w3.org/1999/xhtml">\r
2 <head>\r
3     <link rel="stylesheet" type="text/css" href="jabref_help.css"/>\r
4 </head>\r
5 \r
6 <body>\r
7 <h1>OpenOffice/LibreOffice integration</h1>\r
8 \r
9 <h2>Introduction</h2>\r
10 \r
11 <p>This feature offers an interface for inserting citations and formatting a Bibliography in an OpenOffice\r
12     or LibreOffice Writer document from JabRef.</p>\r
13 \r
14 <p>Throughout this help document, whenever the name <i>OpenOffice</i>\r
15     is used, it can be interchanged with <i>LibreOffice</i>.</p>\r
16 \r
17 <h2>Using the OpenOffice/LibreOffice interface</h2>\r
18 \r
19 <p>To communicate with OpenOffice, JabRef must first connect to a running OpenOffice instance. You need to start\r
20     OpenOffice and enter your document before connecting from JabRef. JabRef needs to know the location of your\r
21     OpenOffice executable (<b>soffice.exe</b> on Windows, and <b>soffice</b> on other platforms), and the directory\r
22     where several OpenOffice jar files reside. If you connect by clicking the <b>Connect</b> button, JabRef will try\r
23     to automatically determine these locations. If this does not work, you need to connect using the <b>Manual\r
24     connect</b> button, which will open a window asking you for the needed locations.</p>\r
25 \r
26 <p>After the connection has been established, you can insert citations by selecting one or more entries in JabRef and\r
27     using the <b>Push to OpenOffice</b> button in the dropdown menu of JabRef's toolbar, or by using the appropriate\r
28     button in the OpenOffice panel in the side pane. This will insert citations for the selected entries at the\r
29     current cursor position in the OpenOffice document, and update the bibliography to contain the full reference.</p>\r
30 \r
31 <p><b>Note:</b> JabRef does not use OpenOffice's built-in bibliography system, because of the limitations of that\r
32     system. A document containing citations inserted from JabRef will not generally be compatible with other reference\r
33     managers such as Bibus and Zotero.</p>\r
34 \r
35 <p>Two different types of citations can be inserted - either a citation in parenthesis, "(Author 2007)", or an in-text\r
36     citation, "Author (2007)". This distinction is only meaningful if author-year citations are used instead of numbered\r
37     citations, but the distinction will be preserved if you switch between the two styles.</p>\r
38 \r
39 <p>If you modify entries in JabRef after inserting their citations into OpenOffice, you will need to synchronize the\r
40     bibliography. The <b>Sync OO bibliography</b> button will update all entries of the bibliography, provided their\r
41     BibTeX keys have not been altered (JabRef encodes the BibTeX key into the reference name for each citation to keep\r
42     track of which BibTeX key the original JabRef entry has).</p>\r
43 \r
44 <h2>The style file</h2>\r
45 \r
46 <p>To customize the citation style you need to select a style file, or use one of the default styles.\r
47    The style defines the format of citations and the format of the bibliography. You can use standard\r
48    JabRef export formatters to process entry fields before they are sent to OpenOffice. Through the style file, the\r
49    intention is to give as much flexibility in citation styles as possible. You can switch style files at any time,\r
50    and use the <b>Update</b> button to refresh your bibliography to follow the new style.</p>\r
51 <p>By clicking the <b>Select style</b> button you can bring up a window that allows selection of either the default\r
52    style or an external style file. If you want to create a new style based on the default, you can click the\r
53    <b>View</b> button to bring up the default style contents, which can be copied into a text editor and modified.</p>\r
54 <p>To choose an external style file, you have two options. Either you can choose a style file directly, or you can\r
55    set a style file directory. If you do the latter, you will see a list of styles from that directory (and\r
56    subdirectories), and can choose one from that list.</p>\r
57 \r
58 <p>Here is an example style file:</p>\r
59 <pre>\r
60 NAME\r
61 Example style file for JabRef-OpenOffice integration.\r
62 \r
63 JOURNALS\r
64 Journal name 1\r
65 Journal name 2\r
66 \r
67 PROPERTIES\r
68 Title="References"\r
69 IsSortByPosition="false"\r
70 IsNumberEntries="false"\r
71 ReferenceParagraphFormat="Default"\r
72 ReferenceHeaderParagraphFormat="Heading 1"\r
73 \r
74 CITATION\r
75 AuthorField="author/editor"\r
76 YearField="year"\r
77 MaxAuthors="3"\r
78 MaxAuthorsFirst="3"\r
79 AuthorSeparator=", "\r
80 AuthorLastSeparator=" &amp; "\r
81 EtAlString=" et al."\r
82 ItalicEtAl="true"\r
83 YearSeparator=" "\r
84 InTextYearSeparator=" "\r
85 BracketBefore="["\r
86 BracketAfter="]"\r
87 BracketBeforeInList="["\r
88 BracketAfterInList="]"\r
89 CitationSeparator="; "\r
90 UniquefierSeparator=","\r
91 GroupedNumbersSeparator="-"\r
92 MinimumGroupingCount="3"\r
93 FormatCitations="false"\r
94 CitationCharacterFormat="Default"\r
95 MultiCiteChronological="false"\r
96 PageInfoSeparator="; "\r
97 \r
98 LAYOUT\r
99 article=\format[AuthorLastFirst,AuthorAbbreviator,AuthorAndsReplacer]{\author}\r
100 (&lt;b&gt;\year\uniq&lt;/b&gt;). &lt;i&gt;\title&lt;/i&gt;, \journal \volume\begin{pages} :\r
101 \format[FormatPagesForHTML]{\pages}\end{pages}.\r
102 \r
103 book=\format[AuthorLastFirst,AuthorAbbreviator,AuthorAndsReplacer]{\author}\begin{editor}\r
104 \format[AuthorLastFirst,AuthorAbbreviator,AuthorAndsReplacer]{\editor} (Ed.)\end{editor},\r
105 &lt;b&gt;\year\uniq&lt;/b&gt;. &lt;i&gt;\title&lt;/i&gt;. \publisher, \address.\r
106 \r
107 incollection=\format[AuthorLastFirst,AuthorAbbreviator,AuthorAndsReplacer]{\author}\r
108 (&lt;b&gt;\year\uniq&lt;/b&gt;). &lt;i&gt;\title&lt;/i&gt;. In: \format[AuthorLastFirst,\r
109 AuthorAbbreviator,AuthorAndsReplacer]{\editor} (Ed.), &lt;i&gt;\booktitle&lt;/i&gt;, \publisher.\r
110 \r
111 inbook=\format[AuthorLastFirst,AuthorAbbreviator,AuthorAndsReplacer]{\author}\r
112 (&lt;b&gt;\year\uniq&lt;/b&gt;). &lt;i&gt;\chapter&lt;/i&gt;. In: \format[AuthorLastFirst,\r
113 AuthorAbbreviator,AuthorAndsReplacer]{\editor} (Ed.), &lt;i&gt;\title&lt;/i&gt;, \publisher.\r
114 \r
115 phdthesis=\format[AuthorLastFirst,AuthorAbbreviator,AuthorAndsReplacer]{\author}\r
116 (&lt;b&gt;\year\uniq&lt;/b&gt;). &lt;i&gt;\title&lt;/i&gt;, \school.\r
117 \r
118 default=\format[AuthorLastFirst,AuthorAbbreviator,AuthorAndsReplacer]{\author}\r
119 (&lt;b&gt;\year\uniq&lt;/b&gt;). &lt;i&gt;\title&lt;/i&gt;, \journal \volume\begin{pages} :\r
120 \format[FormatPagesForHTML]{\pages}\end{pages}.\r
121 \r
122 </pre>\r
123 \r
124 <p>(Note that the layout for each entry type must be constrained to a single line in the style file - above, the lines\r
125     are broken up to improve readability.)</p>\r
126 \r
127 <h3>Global properties</h3>\r
128 \r
129 <p>The <b>PROPERTIES</b> section describes global properties for the bibliography.\r
130     The following table describes the available properties:</p>\r
131 \r
132 <table border="1" rules="none" summary="Available Properties">\r
133     <tr>\r
134         <td><b>Property</b></td>\r
135         <td><b>Type</b></td>\r
136         <td><b>Default value</b></td>\r
137         <td><b>Description</b></td>\r
138     </tr>\r
139     <tr>\r
140         <td>IsNumberEntries</td>\r
141         <td>boolean</td>\r
142         <td><code>false</code></td>\r
143         <td>Determines the type of citations to use. If <code>true</code>, number citations will be\r
144             used. If <code>false</code>, author-year citations will be used.\r
145         </td>\r
146     </tr>\r
147     <tr>\r
148         <td>IsSortByPosition</td>\r
149         <td>boolean</td>\r
150         <td><code>false</code></td>\r
151         <td>Determines how the bibliography is sorted. If true, the entries\r
152             will be sorted according to the order in which they are cited. If false, the entries will be\r
153             sorted alphabetically by authors.\r
154         </td>\r
155     </tr>\r
156     <tr>\r
157         <td>ReferenceParagraphFormat</td>\r
158         <td>string</td>\r
159         <td><code>Default</code></td>\r
160         <td>Gives the name of the paragraph format to be used for the reference list. This format\r
161             must be defined in your OpenOffice document.\r
162         </td>\r
163     </tr>\r
164     <tr>\r
165         <td>ReferenceHeaderParagraphFormat</td>\r
166         <td>string</td>\r
167         <td><code>Heading 1</code></td>\r
168         <td>Gives the name of the paragraph format to be used for the headline of the reference list.\r
169             This format must be defined in your OpenOffice document.\r
170         </td>\r
171     </tr>\r
172     <tr>\r
173         <td>Title</td>\r
174         <td>string</td>\r
175         <td><code>Bibliography</code></td>\r
176         <td>The text to enter as the headline of the reference list.</td>\r
177     </tr>\r
178 </table>\r
179 \r
180 <h3>Citation properties</h3>\r
181 \r
182 <p>The <b>CITATION</b> section describes the format of the citation markers inserted into the text.</p>\r
183 \r
184 <p>The following table gives a brief description of all the available citation properties. Properties that are not\r
185     given in the style file will keep their default value.</p>\r
186 \r
187 <table border="1" rules="none" summary="Brief Description">\r
188     <tr>\r
189         <td><b>Property</b></td>\r
190         <td><b>Type</b></td>\r
191         <td><b>Default value</b></td>\r
192         <td><b>Description</b></td>\r
193     </tr>\r
194     <tr>\r
195         <td>AuthorField</td>\r
196         <td>string</td>\r
197         <td><code>author/editor</code></td>\r
198         <td>BibTeX field containing author names. Can specify fallback field, e.g. <code>author/editor</code></td>\r
199     </tr>\r
200     <tr>\r
201         <td>AuthorLastSeparator</td>\r
202         <td>string</td>\r
203         <td><code> &amp; </code></td>\r
204         <td>Text inserted between the two last author names.</td>\r
205     </tr>\r
206     <tr>\r
207         <td>AuthorLastSeparatorInText</td>\r
208         <td>string</td>\r
209         <td>&nbsp;</td>\r
210         <td>If specified, this propery overrides <code>AuthorLastSeparator</code> for in-text citations such as\r
211             <code>Smith &amp; Jones (2001)</code>.\r
212         </td>\r
213     </tr>\r
214     <tr>\r
215         <td>AuthorSeparator</td>\r
216         <td>string</td>\r
217         <td><code>, </code></td>\r
218         <td>Text inserted between author names except the last two.</td>\r
219     </tr>\r
220     <tr>\r
221         <td>BracketAfter</td>\r
222         <td>string</td>\r
223         <td><code>]</code></td>\r
224         <td>The closing bracket of citations.</td>\r
225     </tr>\r
226     <tr>\r
227         <td>BracketAfterInList</td>\r
228         <td>string</td>\r
229         <td>]</td>\r
230         <td>The closing bracket for citation numbering in the reference list.</td>\r
231     </tr>\r
232     <tr>\r
233         <td>BracketBefore</td>\r
234         <td>string</td>\r
235         <td><code>[</code></td>\r
236         <td>The opening bracket of citations.</td>\r
237     </tr>\r
238     <tr>\r
239         <td>BracketBeforeInList</td>\r
240         <td>string</td>\r
241         <td>[</td>\r
242         <td>The opening bracket for citation numbering in the reference list.</td>\r
243     </tr>\r
244     <tr>\r
245         <td>CitationCharacterFormat</td>\r
246         <td>string</td>\r
247         <td><code>Default</code></td>\r
248         <td>If <code>FormatCitations</code> is set to <code>true</code>, the character format with the name\r
249             given by this property will be applied to citations. The character format must be defined in your\r
250             OpenOffice document.\r
251         </td>\r
252     </tr>\r
253     <tr>\r
254         <td>CitationSeparator</td>\r
255         <td>string</td>\r
256         <td><code>; </code></td>\r
257         <td>Text inserted between items when a citation contains multiple entries, e.g. <code>[Smith 2001; Jones\r
258             2002]</code></td>\r
259     </tr>\r
260     <tr>\r
261         <td>EtAlString</td>\r
262         <td>string</td>\r
263         <td><code> et al. </code></td>\r
264         <td>Text inserted after author names when not all authors are listed, e.g. <code>[Smith et al. 2001]</code></td>\r
265     </tr>\r
266     <tr>\r
267         <td>FormatCitations</td>\r
268         <td>boolean</td>\r
269         <td><code>false</code></td>\r
270         <td>Determines whether formatting should be applied to citations. If true, a character format will be\r
271             applied to the citations. The property <code>CitationCharacterFormat</code> controls which format\r
272             should be applied, and the given format must be defined in your OpenOffice document. Any font settings\r
273             and effects can be chosen within OpenOffice for your chosen character format.\r
274         </td>\r
275     </tr>\r
276     <tr>\r
277         <td>GroupedNumbersSeparator</td>\r
278         <td>string</td>\r
279         <td><code>-</code></td>\r
280         <td>Text inserted between numbers when numbered citations are grouped, e.g. <code>[4-6]</code></td>\r
281     </tr>\r
282     <tr>\r
283         <td>InTextYearSeparator</td>\r
284         <td>string</td>\r
285         <td>Single Space</td>\r
286         <td>Text inserted between author names and starting bracket before year in in-text citations.</td>\r
287     </tr>\r
288     <tr>\r
289         <td>ItalicEtAl</td>\r
290         <td>boolean</td>\r
291         <td><code>true</code></td>\r
292         <td>If true, the "et al." string in citation markers is italicized.</td>\r
293     </tr>\r
294     <tr>\r
295         <td>MaxAuthors</td>\r
296         <td>integer</td>\r
297         <td><code>3</code></td>\r
298         <td>The maximum number of authors to list in a citation that has appeared earlier in the document.</td>\r
299     </tr>\r
300     <tr>\r
301         <td>MaxAuthorsFirst</td>\r
302         <td>integer</td>\r
303         <td><code>3</code></td>\r
304         <td>The maximum number of authors to list in a citation when appearing for the first time.</td>\r
305     </tr>\r
306     <tr>\r
307         <td>MinimumGroupingCount</td>\r
308         <td>integer</td>\r
309         <td><code>3</code></td>\r
310         <td>The minimum number of consecutive entries a citation should contain before the numbers are grouped,\r
311             e.g. <code>[4-6]</code> vs. <code>[4; 5; 6]</code>.\r
312         </td>\r
313     </tr>\r
314     <tr>\r
315         <td>MultiCiteChronological</td>\r
316         <td>boolean</td>\r
317         <td><code>true</code></td>\r
318         <td>If <code>true</code>, multiple entries in the same citation are sorted chronologically, otherwise\r
319             they are sorted alphabetically.\r
320         </td>\r
321     </tr>\r
322     <tr>\r
323         <td>PageInfoSeparator</td>\r
324         <td>string</td>\r
325         <td><code>; </code></td>\r
326         <td>For citations with extra information, e.g. page numbers, this string is inserted between the year\r
327             (for author-year citations) or the citation number (for numbered citations) and the extra information.\r
328             E.g. the text between <code>2001</code> and <code>p. 301</code> in <code>[Smith 2001; p. 301]</code>.\r
329         </td>\r
330     </tr>\r
331     <tr>\r
332         <td>UniquefierSeparator</td>\r
333         <td>string</td>\r
334         <td><code>, </code></td>\r
335         <td>Text inserted between letters used to differentiate citations with similar authors and year. E.g.\r
336             the text between <code>a</code> and <code>b</code> in <code>[Smith 2001a, b]</code>.\r
337         </td>\r
338     </tr>\r
339     <tr>\r
340         <td>YearField</td>\r
341         <td>string</td>\r
342         <td><code>year</code></td>\r
343         <td>The BibTeX field to get publication year from.</td>\r
344     </tr>\r
345     <tr>\r
346         <td>YearSeparator</td>\r
347         <td>string</td>\r
348         <td>Single Space</td>\r
349         <td>Text inserted between author names and year in parenthesis citations such as <code>[Smith 2001]</code>.</td>\r
350     </tr>\r
351 </table>\r
352 \r
353 <p>If numbered entries are used, the <code>BracketBefore</code> and <code>BracketAfter</code> properties\r
354     are the most important - they define which characters the citation number is wrapped in. The citation is composed\r
355     as follows:<br/>\r
356     <code>[BracketBefore][Number][BracketAfter]</code><br/>\r
357     where [Number] is the number of the citation, determined according to the ordering of the bibliography and/or\r
358     the position of the citation in the text. If a citation refers to several entries, these will be separated\r
359     by the string given in the property <code>CitationSeparator</code> (for instance, if <code>CitationSeparator</code>=;,\r
360     the citation could look like <code>[2;4;6]</code>). If two or more of the entries have a series of consecutive\r
361     numbers, the numbers can be grouped (for instance <code>[2-4]</code> for 2, 3 and 4 or <code>[2;5-7]</code> for\r
362     2, 5, 6 and 7). The property <code>GroupedNumbersSeparator</code> (default <code>-</code>) determines which string\r
363     separates the first and last\r
364     of the grouped numbers. The integer property <code>MinimumGroupingCount</code> (default 3) determines what number of\r
365     consecutive numbers is required before entries are grouped. If <code>MinimumGroupingCount</code>=3, the numbers\r
366     2 and 3 will not be grouped, while 2, 3, 4 will be. If <code>MinimumGroupingCount</code>=0, no grouping will be\r
367     done regardless of the number of consecutive numbers.\r
368 </p>\r
369 \r
370 <p>If numbered entries are not used, author-year citations will be created based on the citation properties.\r
371     A parenthesis citation is composed as follows:<br/>\r
372     <code>[BracketBefore][Author][YearSeparator][Year][BracketAfter]</code><br/>\r
373     where [Author] is the result of looking up the field or fields given in the <code>AuthorField</code> property,\r
374     and formatting a list of authors. The list can contain up to <code>MaxAuthors</code> names - if more are present,\r
375     the list will be composed as the first author plus the text specified in the property <code>EtAlString</code>.\r
376     If the property <code>MaxAuthorsFirst</code> is given, it overrides <code>MaxAuthors</code> the first time each\r
377     citation appears in the text.</p>\r
378 \r
379 <p>If several, slash-separated, fields are given in the <code>AuthorField</code> property, they will be looked up\r
380     successively if the first field is empty for the given BibTeX entry. In the example above, the "author" field will\r
381     be used, but if empty, the "editor" field will be used as a backup.</p>\r
382 \r
383 <p>The names in the author list will be separated by the text given by the <code>AuthorSeparator</code>\r
384     property, except for the last two names, which will be separated by the text given by\r
385     <code>AuthorLastSeparator</code>.\r
386     If the property <code>AuthorLastSeparatorInText</code> is given, it overrides the former for citations of the\r
387     in-text\r
388     type. This makes it possible to get citations like <code>(Olsen &amp; Jensen, 2008)</code> and <code>Olsen and\r
389         Jensen (2008)</code>\r
390     for the same style.\r
391 </p>\r
392 \r
393 <p>[Year] is the result of looking up the field or fields given in the [YearField] property.</p>\r
394 \r
395 <p>An in-text citation is composed as follows:<br/>\r
396     <code>[Author][InTextYearSeparator][BracketBefore][Year][BracketAfter]</code><br/>\r
397     where [Author] and [Year] are resolved in exactly the same way as for the parenthesis citations.\r
398 </p>\r
399 \r
400 <p>If two different cited sources have the same authors and publication year, and author-year citations are used,\r
401     their markers will need modification in order to be distinguishable. This is done automatically by appending a\r
402     letter after the year for\r
403     each of the publications; 'a' for the first cited reference, 'b' for the next, and so on.\r
404     For instance, if the author "Olsen" has two cited papers from 2005, the citation markers will be modified to\r
405     <code>(Olsen, 2005a)</code> and <code>(Olsen, 2005b)</code>. In the bibliography\r
406     layout, the placement of the "uniquefier" letter is indicated explicitly by inserting the virtual field\r
407     <code>uniq</code>.</p>\r
408 \r
409 <p>If several entries that have been "uniquefied" are cited together, they will be grouped in the citation\r
410     marker. For instance, of the two entries in the example above are cited together, the citation marker will\r
411     be <code>(Olsen, 2005a, b)</code> rather than <code>Olsen, 2005a; Olsen, 2005b)</code>. The grouped uniquefier\r
412     letters (a and b in our example) will be separated by the string specified by the <code>UniquefierSeparator</code>\r
413     property.\r
414 </p>\r
415 \r
416 <p>Author-year citations referring more than one entry will by default be sorted chronologically. If you wish them\r
417     to be sorted alphabetically, the citation property <code>MultiCiteChronological</code> should be set to\r
418     <code>false.</code>.</p>\r
419 \r
420 \r
421 <h3>Reference list layout</h3>\r
422 \r
423 <p>The <b>LAYOUT</b> section describes how the bibliography entry for each entry type in JabRef\r
424     should appear. Each line should start with either the name of a BibTeX entry type, or the word\r
425     <code>default</code>, followed by a '='. The <code>default</code> layout will be used for all\r
426     entry types for which an explicit layout hasn't been given.</p>\r
427 \r
428 <p>The remainder of each line defines the layout, with normal text and spaces appearing literally\r
429     in the bibliography entry. Information from the BibTeX entry is inserted by adding <code>\field</code> markers\r
430     with the appropriate field name (e.g. <code>\author</code> for inserting the author names). Formatting\r
431     information for the field can be included here, following JabRef's standard export layout syntax.\r
432     Refer to <a href="http://jabref.sourceforge.net/help/CustomExports.php">JabRef's documentation on custom export\r
433         filters</a>\r
434     for more information about which formatters are available.</p>\r
435 \r
436 <p>If author-year citations are used, you have to explicitly specify the position of the "uniquefier" letter\r
437     that is added to distinguish similar-looking citations. This is done by including a marker for the virtual field\r
438     <code>uniq</code>, typically right after the year (as shown in the example style file). The <code>uniq</code>\r
439     field is automatically set correctly for each entry before its reference text is laid out.\r
440 </p>\r
441 \r
442 <p>To indicate formatting in the bibliography, you can use the HTML-like tag pairs &lt;b&gt; &lt;/b&gt;,\r
443     &lt;i&gt; &lt;/i&gt;, &lt;sup&gt; &lt;/sup&gt; and &lt;sub&gt; &lt;/sub&gt; to specify bold text,\r
444     italic text, superscript and subscript, respectively.</p>\r
445 \r
446 <p>If you are using numbered citations, the number for each entry will be automatically inserted at the start\r
447     of each entry in the reference list. By default, the numbers will be enclosed in the same brackets defined for\r
448     citations. The optional citation properties <code>BracketBeforeInList</code> and\r
449     <code>BracketAfterInList</code> override <code>BracketBefore</code> and <code>BracketAfter</code> if set. These\r
450     can be used if you want different types of brackets (or no brackets) in the reference list. Note that these need\r
451     not be brackets as such - they can be any combination of characters.</p>\r
452 \r
453 <h2>Known issues</h2>\r
454 \r
455 <ul>\r
456     <li>Make sure to save your Writer document in OpenDocument format (odt). Saving to Word format will lose your\r
457         reference marks.\r
458     </li>\r
459     <li>There is currently no support for footnote based citations.</li>\r
460     <li>The cursor may be poorly positioned after inserting a citation.</li>\r
461     <li>Copy-pasting the example style file directly from this page can give an unparseable file. To avoid this, instead\r
462         download the example file from the link in the download section.\r
463     </li>\r
464 </ul>\r
465 \r
466 </body>\r
467 </html>\r