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