[svn-upgrade] Integrating new upstream version, jabref (2.4.2)
[debian/jabref.git] / src / help / CustomExports.html
1 <html xmlns="http://www.w3.org/1999/xhtml">
2
3 <body text="#275856">
4     <basefont size="4"
5           color="#2F4958"
6           face="arial" />
7
8     <h1>Custom export filters</h1>
9
10     <p>JabRef allows you to define and
11     use your own export filters, in the same way as the standard
12     export filters are defined. An export filter is defined by one
13     or more <i>layout files</i>, which with the help of a
14     collection of built-in formatter routines specify the format of
15     the exported files. Your layout files must be prepared in a
16     text editor outside of JabRef.</p>
17
18     <h2>Adding a custom export filter</h2>
19
20     <p>The only requirement for
21     a valid export filter is the existence of a file with the
22     extension <b>.layout</b>. To add a new custom export filter,
23     open the dialog box <b>Options -&gt; Manage custom exports</b>,
24     and click <b>Add new</b>. A new dialog box will appear,
25     allowing you to specify a name for the export filter (which
26     will appear as one of the choices in the File type dropdown
27     menu of the file dialog when you use the <b>File -&gt;
28     Export</b> menu choice in the JabRef window), the path to the
29     <b>.layout</b> file, and the preferred file extension for the
30     export filter (which will be the suggested extension in the
31     file dialog when you use the export filter).</p>
32
33     <h2>Creating the export filter</h2>
34
35     <p>To see examples of how export filters are made, look for
36     the package containing the layout files for the standard
37     export filters on our download page.</p>
38
39     <h3>Layout files</h3>
40
41     <p>Let us assume that we are creating an HTML export filter.</p>
42
43     <p>While the export filter only needs to consist of a single
44     <b>.layout</b> file, which in this case could be called
45     <i>html.layout</i>, you may also want to add two files called
46     <i>html.begin.layout</i> and <i>html.end.layout</i>. The former
47     contains the header part of the output, and the latter the
48     footer part. JabRef will look for these two files whenever the
49     export filter is used, and if found, either of these will be
50     copied verbatim to the output before or after the individual
51     entries are written.</p>
52
53     <p>Note that these files must reside in the same directory as
54     <i>html.layout</i>, and must be named by inserting
55     <b>.begin</b> and <b>.end</b>, respectively.</p>
56
57     <p>In our example export filter, these could look like the
58     following:</p>
59
60     <p><i>html.begin.layout</i>:<br />
61     <code>&lt;HTML&gt;<br />
62      &lt;BODY&gt; text="#275856"&gt;<br />
63     &lt;basefont size="4" color="#2F4958"
64     face="arial"&gt;</code></p>
65
66     <p><i>html.end.layout</i>:<br />
67     <code>&lt;/BODY&gt;<br />
68      &lt;/HTML&gt;</code></p>
69
70     <p>The file <i>html.layout</i> provides the <i>default</i>
71     template for exporting one single entry. If you want to use
72     different templates for different entry types, you can do this
73     by adding entry-specific <b>.layout</b> files. These must also
74     reside in the same directory as the main layout file, and are
75     named by inserting <b>.entrytype</b> into the name of the main
76     layout file. The entry type name must be in all lowercase. In
77     our example, we might want to add a template for book entries,
78     and this would go into the file <i>html.book.layout</i>. For a
79     PhD thesis we would add the file <i>html.phdthesis.layout</i>,
80     and so on. These files are similar to the default layout file,
81     except that they will only be used for entries of the matching
82     type. Note that the default file can easily be made general
83     enough to cover most entry types in most export filters.</p>
84
85     <h3>The layout file format</h3>
86
87     <p>Layout files are created using a
88     simple markup format where commands are identified by a
89     preceding backslash. All text not identified as part of a
90     command will be copied verbatim to the output file.</p>
91
92     <h3>Field commands</h3>
93
94     <p>An arbitrary word preceded by a backslash, e.g.
95     <code>\author</code>, <code>\editor</code>, <code>\title</code>
96     or <code>\year</code>, will be interpreted as a reference to
97     the corresponding field, which will be copied directly to the
98     output.</p>
99
100     <h3>Field formatters</h3>
101
102     <p>Often there will be a need for some preprocessing of the
103     field contents before output. This is done using a <i>field
104     formatter</i> - a java class containing a single method that
105     manipulates the contents of a field.</p>
106
107     <p>A formatter is used by inserting the <code>\format</code>
108     command followed by the formatter name in square braces, and
109     the field command in curly braces, e.g.:</p>
110
111     <p><code>\format[ToLowerCase]{\author}</code></p>
112
113     <p>You can also specify multiple formatters separated by
114     commas. These will be called sequentially, from left to right,
115     e.g.</p>
116
117     <p><code>\format[ToLowerCase,HTMLChars]{\author}</code></p>
118
119     <p>will cause the formatter <b>ToLowerCase</b> to be called
120     first, and then <b>HTMLChars</b> will be called to format the
121     result. You can list an arbitrary number of formatters in this
122     way.</p>
123
124     <p>The argument to the formatters, withing the curly braces,
125     does not have to be a field command. Instead, you can insert
126     normal text, which will then be passed to the formatters
127     instead of the contents of any field. This can be useful for
128     some fomatters, e.g. the CurrentDate formatter (described
129     below).</p>
130
131     <p>Some formatters take an extra argument, given in parentheses
132     immediately after the formatter name. The argument can be enclosed
133     in quotes, which is necessary if it includes the parenthesis characters.
134     For instance, <code>\format[Replace("\s,_")]{\journal}</code> calls
135     the <b>Replace</b> formatter with the argument <b>\s,_</b> (which results
136     in the "journal" field after replacing all whitespace by underscores).
137     </p>
138
139     <p>JabRef provides the following set of formatters, some of
140     which depend on the others:</p>
141
142     <ul>
143         <li><code>HTMLChars</code> : replaces TeX-specific special
144         characters (e.g. {\^a} or {\"{o}}) with their HTML
145         representations, and translates LaTeX commands \emph, \textit,
146         \textbf into HTML equivalents.</li>
147
148         <li><code>HTMLParagraphs</code> : interprets two
149         consecutive newlines (e.g. \n \n) as the beginning of a new
150         paragraph and creates paragraph-html-tags accordingly.</li>
151
152         <li><code>XMLChars</code> : replaces TeX-specific special
153         characters (e.g. {\^a} or {\"{o}}) with their XML
154         representations.</li>
155
156         <li><code>CreateDocBookAuthors</code> : formats the author
157         field in DocBook style.</li>
158
159         <li><code>CreateDocBookEditors</code> : to be
160         documented.</li>
161
162         <li><code>CurrentDate</code> : outputs the current date.
163         With no argument, this formatter outputs the current date
164         and time in the format "yyyy.MM.dd hh:mm:ss z" (date, time
165         and time zone). By giving a different format string as
166         argument, the date format can be customized. E.g.
167         <code>\format[CurrentDate]{yyyy.MM.dd}</code> will give the
168         date only, e.g. 2005.11.30.</li>
169
170         <li><code>AuthorFirstFirst</code> : formats author/editor
171         fields with the first names first.</li>
172
173         <li><code>AuthorFirstFirstCommas</code> or <code>AuthorFirstLastCommas</code>
174         : formats author/editor fields with the first names first, delimited by
175         commas, with "and" between the last two names.</li>
176
177         <li><code>AuthorFirstLastOxfordCommas</code> : similar
178         to <code>AuthorFirstLastCommas</code>, except that the "and"
179         between the last two names is preceded by a comma.</li>
180
181         <li><code>AuthorFirstAbbrLastCommas</code> : formats
182         author/editor fields with abbreviated first names first, delimited by
183         commas, with "and" between the last two names.</li>
184
185         <li><code>AuthorFirstAbbrLastOxfordCommas</code> : similar
186         to <code>AuthorFirstAbbrLastCommas</code>, except that the "and"
187         between the last two names is preceded by a comma.</li>
188
189         <li><code>AuthorLastFirst</code> : formats author/editor
190         fields with the last names first.</li>
191
192         <li><code>AuthorAbbreviator</code> or <code>AuthorLastFirstAbbreviator</code>
193             : abbreviates first and middle names of all authors. This formatter
194         returns names with the last name first. Follow this formatter with
195         AuthorFirstFirst to get abbreviated names with the initials first.</li>
196
197         <li><code>AuthorLastFirstCommas</code> : formats
198         author/editor fields with the last names first, delimited by
199         commas, with "and" between the last two names.</li>
200
201         <li><code>AuthorLastFirstOxfordCommas</code> : similar
202         to <code>AuthorLastFirstCommas</code>, except that the "and"
203         between the last two names is preceded by a comma.</li>
204
205         <li><code>AuthorLastFirstAbbrCommas</code> : formats
206         author/editor fields with last names first and abbreviated first names
207         last, delimited by commas, with "and" between the last two names.</li>
208
209         <li><code>AuthorLastFirstAbbrOxfordCommas</code> : similar
210         to <code>AuthorLastFirstAbbrCommas</code>, except that the "and"
211         between the last two names is preceded by a comma.</li>
212
213         <li><code>AuthorAndsReplacer</code> : replaces "and"
214         between names with ";", and "&amp;" between the last
215         two.</li>
216
217         <li><code>AuthorAndsCommaReplacer</code> : replaces "and"
218         between names with ",", and "&amp;" between the last
219         two.</li>
220
221         <li><code>AuthorOrgSci</code> : first author is in "last,
222         first" all others in "first last". First names are
223         abbreviated.</li>
224
225         <li><code>AuthorNatBib</code> : formats author names in
226         NatBib style, with last names only, separating names by
227         "and" if there are two authors, and giving the first author
228         followed by "et al." if there are more than two
229         authors.</li>
230
231         <li><code>NoSpaceBetweenAbbreviations</code> : spaces
232         between multiple abbreviated first names are removed.</li>
233
234         <li><code>FileLink(filetype)</code> : if no argument is given, this formatter outputs
235             the first external file link encoded in the field. To work, the formatter must
236             be supplied with the contents of the "file" field.
237             <p>This formatter takes the name of an external file type as an optional argument,
238                 specified in parentheses after the formatter name. For instance,
239                 <code>\format[FileLink(pdf)]{\file}</code> specifies <code>pdf</code> as an
240                 argument. When an argument is given, the formatter selects the first file
241                 link of the specified type. In the example, the path to the first PDF link will
242                 be output.</p></li>
243
244         <li><code>FormatPagesForHTML</code> : replaces "--" with
245         "-".</li>
246
247         <li><code>FormatPagesForXML</code> : replaces "--" with an
248         XML en-dash.</li>
249
250     <li><code>Replace(regexp,replacewith)</code> : does a regular expression replacement.
251         To use this formatter, a two-part argument must be given. The parts are
252         separated by a comma. To indicate the comma character, use an escape
253         sequence: \,<br>&nbsp;<br>
254         The first part is the regular expression to search for. The regular expression
255         is written normally, without extra escape sequences for backslashes. A description
256         of Java regular expressions can be found at:<br>
257         &nbsp;http://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html
258          <br>&nbsp;<br>
259         The second part is the text to replace all matches with.</li>
260
261         <li><code>RemoveBrackets</code> : removes all curly
262         brackets "{" or "}".</li>
263
264         <li><code>RemoveBracketsAddComma</code> : to be
265         documented.</li>
266
267         <li><code>RemoveWhitespace</code> : removes all whitespace characters.</li>
268
269         <li><code>RemoveLatexCommands</code> : removes LaTeX
270         commands like <code>\em</code>, <code>\textbf</code>, etc.
271         If used together with <code>HTMLChars</code> or
272         <code>XMLChars</code>, this formatter should be called
273         last.</li>
274
275         <li><code>RemoveTilde</code> : replaces the tilde character
276         used in LaTeX as a non-breakable space by a regular space.
277         Useful in combination with the NameFormatter discussed in
278         the next section.</li>
279
280         <li><code>ToLowerCase</code> : turns all characters into
281         lower case.</li>
282
283         <li><code>ToUpperCase</code> : turns all characters into
284         upper case.</li>
285
286         <li><code>GetOpenOfficeType</code> : returns the number used by the OpenOffice.org
287             bibliography system (versions 1.x and 2.x) to denote the type of this entry.</li>
288
289         <li><code>RTFChars</code> : replaces TeX-specific special
290         characters (e.g. {\^a} or {\"{o}}) with their RTF
291         representations, and translates LaTeX commands \emph, \textit,
292         \textbf into RTF equivalents.</li>
293
294     </ul>
295
296     <p>If none of the available formatters can do what you want to
297     achieve, you can add your own by implementing the
298     <code>net.sf.jabref.export.layout.LayoutFormatter</code>
299     interface. If you insert your class into the
300     <code>net.sf.jabref.export.layout.format</code> package, you
301     can call the formatter by its class name only, like with the
302     standard formatters. Otherwise, you must call the formatter by
303     its fully qualified name (including package name). In any case,
304     the formatter must be in your classpath when running
305     JabRef.</p>
306
307     <h2><a name="NameFormatter"
308        id="NameFormatter">Using Custom Name Formatters</a></h2>
309
310     <p>With JabRef 2.2 it is now possible to define custom name
311     formatters using the bibtex-sty-file syntax. This allows
312     ultimate flexibility, but is a cumbersome to write</p>
313
314     <p>You can define your own formatter in the preference tab
315     "Name Formatter" using the following format and then use it
316     with the name given to it as any other formatter</p>
317     <code>&lt;case1&gt;@&lt;range11&gt;@&lt;format&gt;@&lt;range12&gt;@&lt;format&gt;@&lt;range13&gt;...@@<br />
318
319      &lt;case2&gt;@&lt;range21&gt;@... and so on.</code>
320
321     <p>This format first splits the task to format a list of author
322     into cases depending on how many authors there are (this is
323     since some formats differ depending on how many authors there
324     are). Each individual case is separated by @@ and contains
325     instructions on how to format each author in the case. These
326     instructions are separated by a @.</p>
327
328     <p>Cases are identified using integers (1, 2, 3, etc.) or the
329     character * (matches any number of authors) and will tell the
330     formatter to apply the following instructions if there are a
331     number of less or equal of authors given.</p>
332
333     <p>Ranges are either
334     <code>&lt;integer&gt;..&lt;integer&gt;</code>,
335     <code>&lt;integer&gt;</code> or the character <code>*</code>
336     using a 1 based index for indexing authors from the given list
337     of authors. Integer indexes can be negative to denote them to
338     start from the end of the list where -1 is the last author.</p>
339
340     <p>For instance with an authorlist of "Joe Doe and Mary Jane
341     and Bruce Bar and Arthur Kay":</p>
342
343     <ul>
344         <li>1..3 will affect Joe, Mary and Bruce</li>
345
346         <li>4..4 will affect Arthur</li>
347
348         <li>* will affect all of them</li>
349
350         <li>2..-1 will affect Mary, Bruce and Arthur</li>
351     </ul>
352
353     <p>The <code>&lt;format&gt;</code>-strings use the Bibtex
354     formatter format:</p>
355
356     <p>The four letters v, f, l, j indicate the name parts von,
357     first, last, jr which are used within curly braces. A single
358     letter v, f, l, j indicates that the name should be
359     abbreviated. If one of these letters or letter pairs is
360     encountered JabRef will output all the respective names
361     (possibly abbreviated), but the whole expression in curly
362     braces is only printed if the name part exists.</p>
363
364     <p>For instance if the format is "{ll} {vv {von Part}} {ff}"
365     and the names are "Mary Kay and John von Neumann", then JabRef
366     will output "Kay Mary" (with two space between last and first)
367     and "Neuman von von Part John".</p>
368
369     <p>I give two examples but would rather point you to the bibtex
370     documentation.</p>
371
372     <p>Small example: <code>"{ll}, {f.}"</code> will turn
373     <code>"Joe Doe"</code> into <code>"Doe, J."</code></p>
374
375     <p>Large example:</p>
376
377     <blockquote>
378         <p>To turn:</p>
379
380         <p><code>"Joe Doe and Mary Jane and Bruce Bar and Arthur
381         Kay"</code></p>
382
383         <p>into</p>
384
385         <p><code>"Doe, J., Jane, M., Bar, B. and Kay,
386         A."</code></p>
387
388         <p>you would use</p>
389
390         <p><code>1@*@{ll}, {f}.@@2@1@{ll}, {f}.@2@ and {ll},
391         {f}.@@*@1..-3@{ll}, {f}., @-2@{ll}, {f}.@-1@ and {ll},
392         {f}.</code></p>
393     </blockquote>
394
395     <p>If somebody would like to write a better tutorial about
396     this: Write a mail to one of the JabRef mailinglists!</p>
397
398     <h3>Conditional output</h3>
399
400     <p>Some static output might only make
401     sense if a specific field is set. For instance, say we want to
402     follow the editor names with the text <code>(Ed.)</code>. This
403     can be done with the following text:</p>
404
405     <p><code>\format[HTMLChars,AuthorFirstFirst]{\editor}
406     (Ed.)</code></p>
407
408     <p>However, if the <code>editor</code> field has not been set -
409     it might not even make sense for the entry being exported - the
410     <code>(Ed.)</code> would be left hanging. This can be prevented
411     by instead using the <code>\begin</code> and <code>\end</code>
412     commands:</p>
413
414     <p><code>\begin{editor}<br />
415     \format[HTMLChars,AuthorFirstFirst]{\editor} (Ed.)<br />
416      \end{editor}</code></p>
417
418     <p>The <code>\begin</code> and <code>\end</code> commands make
419     sure the text in between is printed if and only if the field
420     referred in the curly braces is defined for the ently being
421     exported.</p>
422
423     <p><b>Note:</b> Use of the <code>\begin</code> and
424     <code>\end</code> commands is a key to creating layout files
425     that work well with a variety of entry types.</p>
426
427     <h3>Grouped output</h3>
428
429     <p>If you wish to separate your entries
430     into groups based on a certain field, use the grouped output
431     commands. Grouped output is very similar to conditional output,
432     except that the text in between is printed only if the field
433     referred in the curly braces has changed value.</p>
434
435     <p>For example, let's assume I wish to group by keyword. Before
436     exporting the file, make sure you have sorted your entries
437     based on keyword. Now use the following commands to group by
438     keyword:</p>
439
440     <p><code>\begingroup{keywords}New Category:
441     \format[HTMLChars]{\keywords}<br />
442      \endgroup{keywords}</code></p>
443
444     <h2>Sharing your work</h2>
445
446     <p>With external layout files, it's
447     fairly simple to share custom export formats between users. If
448     you write an export filter for a format not supported by
449     JabRef, or an improvement over an existing one, we encourage
450     you to post your work on our SourceForge.net page. The same
451     goes for formatter classes that you write. We'd be happy to
452     distribute a collection of submitted layout files, or to add to
453     the selection of standard export filters and formatters.</p>
454
455     <p>Starting with JabRef 2.4b1 you can also package your
456         ExportFormat or LayoutFormatter as a plug-in. If you do so,
457         you can provide a single zip-file to other user to make use
458         of your ExportFormat. For an example download the JabRef
459         source release and have a look at the directory
460         <code>src/plugins/</code>. Don't hesitate to stop by the
461         forums on Sourceforge, since we don't have extensive documentation, yet.</p>
462
463
464 </body>
465 </html>