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>