[svn-upgrade] Integrating new upstream version, jabref (2.5)
[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     <p>See below for a list of built-in export formatters.</p>
138
139     <h3>Conditional output</h3>
140
141     <p>Some static output might only make
142     sense if a specific field is set. For instance, say we want to
143     follow the editor names with the text <code>(Ed.)</code>. This
144     can be done with the following text:</p>
145
146     <p><code>\format[HTMLChars,AuthorFirstFirst]{\editor}
147     (Ed.)</code></p>
148
149     <p>However, if the <code>editor</code> field has not been set -
150     it might not even make sense for the entry being exported - the
151     <code>(Ed.)</code> would be left hanging. This can be prevented
152     by instead using the <code>\begin</code> and <code>\end</code>
153     commands:</p>
154
155     <p><code>\begin{editor}<br />
156     \format[HTMLChars,AuthorFirstFirst]{\editor} (Ed.)<br />
157      \end{editor}</code></p>
158
159     <p>The <code>\begin</code> and <code>\end</code> commands make
160     sure the text in between is printed if and only if the field
161     referred in the curly braces is defined for the entry being
162     exported.</p>
163
164     <p>A conditional block can also be dependent on more than one field. In this case
165     the contents of the block are printed only if all the fields are defined. To make
166     such a block, simply give the list of fields separated by semicolons. For instance,
167     to output text only if both <code>year</code> and <code>month</code> are set, use
168     a block like the following:</p>
169
170     <p><code>\begin{year;month}Month: \format[HTMLChars]{\month}\end{year;month}</code></p>
171
172     <p>which will print "Month: " plus the contents of the <code>month</code> field, but
173     only if also the <code>year</code> field is defined.</p>
174
175     <p><b>Note:</b> Use of the <code>\begin</code> and
176     <code>\end</code> commands is a key to creating layout files
177     that work well with a variety of entry types.</p>
178
179     <h3>Grouped output</h3>
180
181     <p>If you wish to separate your entries
182     into groups based on a certain field, use the grouped output
183     commands. Grouped output is very similar to conditional output,
184     except that the text in between is printed only if the field
185     referred in the curly braces has changed value.</p>
186
187     <p>For example, let's assume I wish to group by keyword. Before
188     exporting the file, make sure you have sorted your entries
189     based on keyword. Now use the following commands to group by
190     keyword:</p>
191
192     <p><code>\begingroup{keywords}New Category:
193     \format[HTMLChars]{\keywords}<br />
194      \endgroup{keywords}</code></p>
195
196     <h2>Sharing your work</h2>
197
198     <p>With external layout files, it's
199     fairly simple to share custom export formats between users. If
200     you write an export filter for a format not supported by
201     JabRef, or an improvement over an existing one, we encourage
202     you to post your work on our SourceForge.net page. The same
203     goes for formatter classes that you write. We'd be happy to
204     distribute a collection of submitted layout files, or to add to
205     the selection of standard export filters and formatters.</p>
206
207     <p>Starting with JabRef 2.4b1 you can also package your
208         ExportFormat or LayoutFormatter as a plug-in. If you do so,
209         you can provide a single zip-file to other user to make use
210         of your ExportFormat. For an example download the JabRef
211         source release and have a look at the directory
212         <code>src/plugins/</code>. Don't hesitate to stop by the
213         forums on Sourceforge, since we don't have extensive documentation, yet.</p>
214
215
216     <h2>Built-in export formatters</h2>
217
218     <p>JabRef provides the following set of formatters, some of
219     which depend on the others:</p>
220
221     <ul>
222
223         <li><code>AuthorAbbreviator</code> or <code>AuthorLastFirstAbbreviator</code>
224             : abbreviates first and middle names of all authors. This formatter
225         returns names with the last name first. Follow this formatter with
226         AuthorFirstFirst to get abbreviated names with the initials first.</li>
227
228         <li><code>AuthorAndsCommaReplacer</code> : replaces "and"
229         between names with ",", and "&amp;" between the last
230         two.</li>
231
232         <li><code>AuthorAndsReplacer</code> : replaces "and"
233         between names with ";", and "&amp;" between the last
234         two.</li>
235
236         <li><code>AuthorFirstFirst</code> : formats author/editor
237         fields with the first names first.</li>
238
239         <li><code>AuthorFirstFirstCommas</code> or <code>AuthorFirstLastCommas</code>
240         : formats author/editor fields with the first names first, delimited by
241         commas, with "and" between the last two names.</li>
242
243         <li><code>AuthorFirstLastOxfordCommas</code> : similar
244         to <code>AuthorFirstLastCommas</code>, except that the "and"
245         between the last two names is preceded by a comma.</li>
246
247         <li><code>AuthorFirstAbbrLastCommas</code> : formats
248         author/editor fields with abbreviated first names first, delimited by
249         commas, with "and" between the last two names.</li>
250
251         <li><code>AuthorFirstAbbrLastOxfordCommas</code> : similar
252         to <code>AuthorFirstAbbrLastCommas</code>, except that the "and"
253         between the last two names is preceded by a comma.</li>
254
255         <li><code>AuthorLastFirst</code> : formats author/editor
256         fields with the last names first.</li>
257
258         <li><code>AuthorLastFirstAbbrCommas</code> : formats
259         author/editor fields with last names first and abbreviated first names
260         last, delimited by commas, with "and" between the last two names.</li>
261
262         <li><code>AuthorLastFirstAbbrOxfordCommas</code> : similar
263         to <code>AuthorLastFirstAbbrCommas</code>, except that the "and"
264         between the last two names is preceded by a comma.</li>
265
266         <li><code>AuthorLastFirstCommas</code> : formats
267         author/editor fields with the last names first, delimited by
268         commas, with "and" between the last two names.</li>
269
270         <li><code>AuthorLastFirstOxfordCommas</code> : similar
271         to <code>AuthorLastFirstCommas</code>, except that the "and"
272         between the last two names is preceded by a comma.</li>
273
274         <li><code>AuthorLF_FF</code> : formats
275         author/editor fields with last name first for the first author,
276         and the first name first for the remaining authors. Returns
277         names delimited with "and".</li>
278
279         <li><code>AuthorLF_FFAbbr</code> : same as <code>AuthorLF_FF</code>,
280         but abbreviates first names.</li>
281                 
282         <li><code>AuthorNatBib</code> : formats author names in
283         NatBib style, with last names only, separating names by
284         "and" if there are two authors, and giving the first author
285         followed by "et al." if there are more than two
286         authors.</li>
287
288         <li><code>AuthorOrgSci</code> : first author is in "last,
289         first" all others in "first last". First names are
290         abbreviated.</li>
291
292         <li><code>CreateDocBookAuthors</code> : formats the author
293         field in DocBook style.</li>
294
295         <li><code>CreateDocBookEditors</code> : to be
296         documented.</li>
297
298         <li><code>CurrentDate</code> : outputs the current date.
299         With no argument, this formatter outputs the current date
300         and time in the format "yyyy.MM.dd hh:mm:ss z" (date, time
301         and time zone). By giving a different format string as
302         argument, the date format can be customized. E.g.
303         <code>\format[CurrentDate]{yyyy.MM.dd}</code> will give the
304         date only, e.g. 2005.11.30.</li>
305
306         <li><code>FileLink(filetype)</code> : if no argument is given, this formatter outputs
307         the first external file link encoded in the field. To work, the formatter must
308         be supplied with the contents of the "file" field.
309         <p>This formatter takes the name of an external file type as an optional argument,
310         specified in parentheses after the formatter name. For instance,
311         <code>\format[FileLink(pdf)]{\file}</code> specifies <code>pdf</code> as an
312         argument. When an argument is given, the formatter selects the first file
313         link of the specified type. In the example, the path to the first PDF link will
314         be output.</p></li>
315
316         <li><code>FirstPage</code> : returns the first page from the "pages" field, if set.
317             For instance, if the pages field is set to "345-360" or "345--360",
318             this formatter will return "345".</li>
319
320         <li><code>FormatPagesForHTML</code> : replaces "--" with
321         "-".</li>
322
323         <li><code>FormatPagesForXML</code> : replaces "--" with an
324         XML en-dash.</li>
325
326         <li><code>GetOpenOfficeType</code> : returns the number used by the OpenOffice.org
327         bibliography system (versions 1.x and 2.x) to denote the type of this entry.</li>
328
329         <li><code>HTMLChars</code> : replaces TeX-specific special
330         characters (e.g. {\^a} or {\"{o}}) with their HTML
331         representations, and translates LaTeX commands \emph, \textit,
332         \textbf into HTML equivalents.</li>
333
334         <li><code>HTMLParagraphs</code> : interprets two
335         consecutive newlines (e.g. \n \n) as the beginning of a new
336         paragraph and creates paragraph-html-tags accordingly.</li>
337
338         <li><code>LastPage</code> : returns the last page from the "pages" field, if set.
339             For instance, if the pages field is set to "345-360" or "345--360",
340             this formatter will return "360".</li>
341
342         <li><code>NoSpaceBetweenAbbreviations</code> : spaces
343         between multiple abbreviated first names are removed.</li>
344
345         <li><code>Number</code> : outputs the 1-based sequence number of the current entry in the
346         current export. This formatter can be used to make a numbered list of entries. The
347         sequence number depends on the current entry's place in the current sort order, not on
348         the number of calls to this formatter.</li>
349
350         <li><code>RemoveBrackets</code> : removes all curly brackets "{" or "}".</li>
351
352         <li><code>RemoveBracketsAddComma</code> : to be
353         documented.</li>
354
355         <li><code>RemoveLatexCommands</code> : removes LaTeX
356         commands like <code>\em</code>, <code>\textbf</code>, etc.
357         If used together with <code>HTMLChars</code> or
358         <code>XMLChars</code>, this formatter should be called
359         last.</li>
360
361         <li><code>RemoveTilde</code> : replaces the tilde character
362         used in LaTeX as a non-breakable space by a regular space.
363         Useful in combination with the NameFormatter discussed in
364         the next section.</li>
365
366         <li><code>RemoveWhitespace</code> : removes all whitespace characters.</li>
367
368         <li><code>Replace(regexp,replacewith)</code> : does a regular expression replacement.
369         To use this formatter, a two-part argument must be given. The parts are
370         separated by a comma. To indicate the comma character, use an escape
371         sequence: \,<br>&nbsp;<br>
372         The first part is the regular expression to search for. The regular expression
373         is written normally, without extra escape sequences for backslashes. A description
374         of Java regular expressions can be found at:<br>
375         &nbsp;http://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html
376          <br>&nbsp;<br>
377         The second part is the text to replace all matches with.</li>
378
379         <li><code>RTFChars</code> : replaces TeX-specific special
380         characters (e.g. {\^a} or {\"{o}}) with their RTF
381         representations, and translates LaTeX commands \emph, \textit,
382         \textbf into RTF equivalents.</li>
383
384         <li><code>ToLowerCase</code> : turns all characters into
385         lower case.</li>
386
387         <li><code>ToUpperCase</code> : turns all characters into
388         upper case.</li>
389
390         <li><code>WrapContent</code> : This formatter outputs the input value after adding a
391         prefix and a postfix, as long as the input value is non-empty. If the input value
392         is empty, an empty string is output (the prefix and postfix are not output in this case).
393         The formatter requires an argument containing the prefix and postix separated
394         by a comma. To include the comma character in either, use an escape sequence
395         (\,).</li>
396
397         <li><code>WrapFileLinks</code> : See below.</li>
398
399         <li><code>XMLChars</code> : replaces TeX-specific special
400         characters (e.g. {\^a} or {\"{o}}) with their XML
401         representations.</li>
402
403
404
405     </ul>
406
407     <h3>The <code>WrapFileLinks</code> formatter</h3>
408
409     This formatter iterates over all file links, or all file links of a specified
410     type, outputting a format string given as the first argument. The format string
411     can contain a number of escape sequences indicating file link information to
412     be inserted into the string.
413     <p/>
414     This formatter can take an optional second argument specifying the name of a file
415     type. If specified, the iteration will only include those files with a file type
416     matching the given name (case-insensitively). If specified as an empty argument,
417     all file links will be included.
418     <p/>
419     After the second argument, pairs of additional arguments can be added in order to
420     specify regular expression replacements to be done upon the inserted link information
421     before insertion into the output string. A non-paired argument will be ignored.
422     In order to specify replacements without filtering on file types, use an empty second
423     argument.
424     <p/>
425     The escape sequences for embedding information are as follows:
426     <p/>
427     \i   : This inserts the iteration index (starting from 1), and can be useful if
428     the output list of files should be enumerated.<br>
429     \p   : This inserts the file path of the file link.<br>
430     \f   : This inserts the name of the file link's type.<br>
431     \x   : This inserts the file's extension, if any.<br>
432     \d   : This inserts the file link's description, if any.<br>
433     <p/>
434     For instance, an entry could contain a file link to the file "/home/john/report.pdf"
435     of the "PDF" type with description "John's final report".
436     <p/>
437     Using the WrapFileLinks formatter with the following argument:
438     <p/>
439     \format[WrapFileLinks(\i. \d (\p))]{\file}
440     <p/>
441     would give the following output:<br>
442     <pre>1. John's final report (/home/john/report.pdf)</pre>
443     <p/>
444     If the entry contained a second file link to the file "/home/john/draft.txt" of the
445     "Text file" type with description 'An early "draft"', the output would be as follows:<br>
446     <pre>1. John's final report (/home/john/report.pdf)</pre>
447     <pre>2. An early "draft" (/home/john/draft.txt)</pre>
448     <p/>
449     If the formatter was called with a second argument, the list would be filtered.
450     For instance:<br>
451     <pre>\format[WrapFileLinks(\i. \d (\p),,text file)]{\file}</pre>
452     <p/>
453     would show only the text file:<br>
454     <pre>1. An early "draft" (/home/john/draft.txt)</pre>
455     <p/>
456     If we wanted this output to be part of an XML styled output, the quotes in the
457     file description could cause problems. Adding two additional arguments to translate
458     the quotes into XML characters solves this:<br>
459     \format[WrapFileLinks(\i. \d (\p),,text file,",&quot;)]{\file}
460     <p/>
461     would give the following output:<br>
462     <pre>1. An early &quot;draft&quot; (/home/john/draft.txt)</pre>
463     <p/>Additional pairs of replacements could be added.
464
465
466     <h3>Custom formatters</h3>
467
468     <p>If none of the available formatters can do what you want to
469     achieve, you can add your own by implementing the
470     <code>net.sf.jabref.export.layout.LayoutFormatter</code>
471     interface. If you insert your class into the
472     <code>net.sf.jabref.export.layout.format</code> package, you
473     can call the formatter by its class name only, like with the
474     standard formatters. Otherwise, you must call the formatter by
475     its fully qualified name (including package name). In any case,
476     the formatter must be in your classpath when running
477     JabRef.</p>
478
479     <h2><a name="NameFormatter"
480        id="NameFormatter">Using Custom Name Formatters</a></h2>
481
482     <p>From JabRef 2.2, it is possible to define custom name
483     formatters using the bibtex-sty-file syntax. This allows
484     ultimate flexibility, but is a cumbersome to write</p>
485
486     <p>You can define your own formatter in the preference tab
487     "Name Formatter" using the following format and then use it
488     with the name given to it as any other formatter</p>
489     <code>&lt;case1&gt;@&lt;range11&gt;@&lt;format&gt;@&lt;range12&gt;@&lt;format&gt;@&lt;range13&gt;...@@<br />
490
491      &lt;case2&gt;@&lt;range21&gt;@... and so on.</code>
492
493     <p>This format first splits the task to format a list of author
494     into cases depending on how many authors there are (this is
495     since some formats differ depending on how many authors there
496     are). Each individual case is separated by @@ and contains
497     instructions on how to format each author in the case. These
498     instructions are separated by a @.</p>
499
500     <p>Cases are identified using integers (1, 2, 3, etc.) or the
501     character * (matches any number of authors) and will tell the
502     formatter to apply the following instructions if there are a
503     number of less or equal of authors given.</p>
504
505     <p>Ranges are either
506     <code>&lt;integer&gt;..&lt;integer&gt;</code>,
507     <code>&lt;integer&gt;</code> or the character <code>*</code>
508     using a 1 based index for indexing authors from the given list
509     of authors. Integer indexes can be negative to denote them to
510     start from the end of the list where -1 is the last author.</p>
511
512     <p>For instance with an authorlist of "Joe Doe and Mary Jane
513     and Bruce Bar and Arthur Kay":</p>
514
515     <ul>
516         <li>1..3 will affect Joe, Mary and Bruce</li>
517
518         <li>4..4 will affect Arthur</li>
519
520         <li>* will affect all of them</li>
521
522         <li>2..-1 will affect Mary, Bruce and Arthur</li>
523     </ul>
524
525     <p>The <code>&lt;format&gt;</code>-strings use the Bibtex
526     formatter format:</p>
527
528     <p>The four letters v, f, l, j indicate the name parts von,
529     first, last, jr which are used within curly braces. A single
530     letter v, f, l, j indicates that the name should be
531     abbreviated. If one of these letters or letter pairs is
532     encountered JabRef will output all the respective names
533     (possibly abbreviated), but the whole expression in curly
534     braces is only printed if the name part exists.</p>
535
536     <p>For instance if the format is "{ll} {vv {von Part}} {ff}"
537     and the names are "Mary Kay and John von Neumann", then JabRef
538     will output "Kay Mary" (with two space between last and first)
539     and "Neuman von von Part John".</p>
540
541     <p>I give two examples but would rather point you to the bibtex
542     documentation.</p>
543
544     <p>Small example: <code>"{ll}, {f.}"</code> will turn
545     <code>"Joe Doe"</code> into <code>"Doe, J."</code></p>
546
547     <p>Large example:</p>
548
549     <blockquote>
550         <p>To turn:</p>
551
552         <p><code>"Joe Doe and Mary Jane and Bruce Bar and Arthur
553         Kay"</code></p>
554
555         <p>into</p>
556
557         <p><code>"Doe, J., Jane, M., Bar, B. and Kay,
558         A."</code></p>
559
560         <p>you would use</p>
561
562         <p><code>1@*@{ll}, {f}.@@2@1@{ll}, {f}.@2@ and {ll},
563         {f}.@@*@1..-3@{ll}, {f}., @-2@{ll}, {f}.@-1@ and {ll},
564         {f}.</code></p>
565     </blockquote>
566
567     <p>If somebody would like to write a better tutorial about
568     this: Write a mail to one of the JabRef mailinglists!</p>
569
570
571 </body>
572 </html>