src/main/resources/help/CustomExports.html

   1 <html xmlns="http://www.w3.org/1999/xhtml">
   2 <head>
   3 <link rel="stylesheet" type="text/css" href="jabref_help.css"/>
   4 </head>
   5
   6 <body>
   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.
  42      While the export filter only needs to consist of a single
  43     <b>.layout</b> file, which in this case could be called
  44     <i>html.layout</i>, you may also want to add two files called
  45     <i>html.begin.layout</i> and <i>html.end.layout</i>. The former
  46     contains the header part of the output, and the latter the
  47     footer part. JabRef will look for these two files whenever the
  48     export filter is used, and if found, either of these will be
  49     copied verbatim to the output before or after the individual
  50     entries are written.</p>
  51
  52     <p>Note that these files must reside in the same directory as
  53     <i>html.layout</i>, and must be named by inserting
  54     <b>.begin</b> and <b>.end</b>, respectively.
  55     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;!DOCTYPE html&gt;<br/>&lt;html&gt;<br /> &lt;body style="color:#275856; font-family: Arial, sans-serif;"&gt;</code>
  60     </p>
  61
  62     <p><i>html.end.layout</i>:<br />
  63     <code>&lt;/body&gt;<br />&lt;/html&gt;</code></p>
  64
  65     <p>The file <i>html.layout</i> provides the <i>default</i>
  66     template for exporting one single entry. If you want to use
  67     different templates for different entry types, you can do this
  68     by adding entry-specific <b>.layout</b> files. These must also
  69     reside in the same directory as the main layout file, and are
  70     named by inserting <b>.entrytype</b> into the name of the main
  71     layout file. The entry type name must be in all lowercase. In
  72     our example, we might want to add a template for book entries,
  73     and this would go into the file <i>html.book.layout</i>. For a
  74     PhD thesis we would add the file <i>html.phdthesis.layout</i>,
  75     and so on. These files are similar to the default layout file,
  76     except that they will only be used for entries of the matching
  77     type. Note that the default file can easily be made general
  78     enough to cover most entry types in most export filters.</p>
  79
  80     <h3>The layout file format</h3>
  81
  82     <p>Layout files are created using a
  83     simple markup format where commands are identified by a
  84     preceding backslash. All text not identified as part of a
  85     command will be copied verbatim to the output file.</p>
  86
  87     <h3>Field commands</h3>
  88
  89     <p>An arbitrary word preceded by a backslash, e.g.
  90     <code>\author</code>, <code>\editor</code>, <code>\title</code>
  91     or <code>\year</code>, will be interpreted as a reference to
  92     the corresponding field, which will be copied directly to the
  93     output.</p>
  94
  95     <h3>Field formatters</h3>
  96
  97     <p>Often there will be a need for some preprocessing of the
  98     field contents before output. This is done using a <i>field
  99     formatter</i> - a java class containing a single method that
 100     manipulates the contents of a field.</p>
 101
 102     <p>A formatter is used by inserting the <code>\format</code>
 103     command followed by the formatter name in square braces, and
 104     the field command in curly braces, e.g.:</p>
 105
 106     <p><code>\format[ToLowerCase]{\author}</code></p>
 107
 108     <p>You can also specify multiple formatters separated by
 109     commas. These will be called sequentially, from left to right,
 110     e.g.</p>
 111
 112     <p><code>\format[ToLowerCase,HTMLChars]{\author}</code></p>
 113
 114     <p>will cause the formatter <b>ToLowerCase</b> to be called
 115     first, and then <b>HTMLChars</b> will be called to format the
 116     result. You can list an arbitrary number of formatters in this
 117     way.</p>
 118
 119     <p>The argument to the formatters, withing the curly braces,
 120     does not have to be a field command. Instead, you can insert
 121     normal text, which will then be passed to the formatters
 122     instead of the contents of any field. This can be useful for
 123     some fomatters, e.g. the CurrentDate formatter (described
 124     below).</p>
 125
 126     <p>Some formatters take an extra argument, given in parentheses
 127     immediately after the formatter name. The argument can be enclosed
 128     in quotes, which is necessary if it includes the parenthesis characters.
 129     For instance, <code>\format[Replace("\s,_")]{\journal}</code> calls
 130     the <b>Replace</b> formatter with the argument <b>\s,_</b> (which results
 131     in the "journal" field after replacing all whitespace by underscores).
 132     </p>
 133
 134     <p>See below for a list of built-in export formatters.</p>
 135
 136     <h3>Conditional output</h3>
 137
 138     <p>Some static output might only make
 139     sense if a specific field is set. For instance, say we want to
 140     follow the editor names with the text <code>(Ed.)</code>. This
 141     can be done with the following text:</p>
 142
 143     <p><code>\format[HTMLChars,AuthorFirstFirst]{\editor}
 144     (Ed.)</code></p>
 145
 146     <p>However, if the <code>editor</code> field has not been set -
 147     it might not even make sense for the entry being exported - the
 148     <code>(Ed.)</code> would be left hanging. This can be prevented
 149     by instead using the <code>\begin</code> and <code>\end</code>
 150     commands:</p>
 151
 152     <p><code>\begin{editor}<br />
 153     \format[HTMLChars,AuthorFirstFirst]{\editor} (Ed.)<br />
 154      \end{editor}</code></p>
 155
 156     <p>The <code>\begin</code> and <code>\end</code> commands make
 157     sure the text in between is printed if and only if the field
 158     referred in the curly braces is defined for the entry being
 159     exported.</p>
 160
 161     <p>A conditional block can also be dependent on more than one field, and the content is only printed when simple boolean conditions are satisfied. Two boolean operator are provided:</p>
 162     <ul>
 163         <li>AND operator : <code>&amp;</code>, <code>&amp;&amp;</code></li>
 164         <li>OR operator : <code>|</code>, <code>||</code></li>
 165     </ul>
 166     <p>To output text only if both <code>year</code> and <code>month</code> are set, use a block like the following:<br/><br/> <code>\begin{year&amp;&amp;month}Month: \format[HTMLChars]{\month}\end{year&amp;&amp;month}</code><br/><br/>which will print "Month: " plus the contents of the <code>month</code> field, but only if also the <code>year</code> field is defined.</p>
 167
 168     <p><b>Note:</b> Use of the <code>\begin</code> and
 169     <code>\end</code> commands is a key to creating layout files
 170     that work well with a variety of entry types.</p>
 171
 172     <h3>Grouped output</h3>
 173
 174     <p>If you wish to separate your entries
 175     into groups based on a certain field, use the grouped output
 176     commands. Grouped output is very similar to conditional output,
 177     except that the text in between is printed only if the field
 178     referred in the curly braces has changed value.</p>
 179
 180     <p>For example, let's assume I wish to group by keyword. Before
 181     exporting the file, make sure you have sorted your entries
 182     based on keyword. Now use the following commands to group by
 183     keyword:</p>
 184
 185     <p><code>\begingroup{keywords}New Category:
 186     \format[HTMLChars]{\keywords}<br />
 187      \endgroup{keywords}</code></p>
 188
 189     <h2>Sharing your work</h2>
 190
 191     <p>With external layout files, it's
 192     fairly simple to share custom export formats between users. If
 193     you write an export filter for a format not supported by
 194     JabRef, or an improvement over an existing one, we encourage
 195     you to post your work on our SourceForge.net page. The same
 196     goes for formatter classes that you write. We'd be happy to
 197     distribute a collection of submitted layout files, or to add to
 198     the selection of standard export filters and formatters.</p>
 199
 200     <p>Starting with JabRef 2.4 you can also package your
 201         ExportFormat or LayoutFormatter as a plug-in. If you do so,
 202         you can provide a single zip-file to other user to make use
 203         of your ExportFormat. For an example download the JabRef
 204         source release and have a look at the directory
 205         <code>src/resources/plugins/</code>. Don't hesitate to stop by the
 206         forums on Sourceforge, since we don't have extensive documentation, yet.</p>
 207
 208
 209     <h2>Built-in export formatters</h2>
 210
 211     <p>JabRef provides the following set of formatters:</p>
 212
 213     <ul>
 214         <li><code>Authors</code> : this formatter provides formatting options for the author and editor fields; for detailed information, see below. It deprecates a range of dedicated formatters provided in versions of JabRef prior to 2.7.</li>
 215
 216                 <li><code>CreateBibORDFAuthors</code> : formats authors for according to the requirements of the Bibliographic Ontology (bibo).</li>
 217
 218         <li><code>CreateDocBookAuthors</code> : formats the author
 219         field in DocBook style.</li>
 220
 221         <li><code>CreateDocBookEditors</code> : formats the editor field in DocBook style. </li>
 222
 223         <li><code>CurrentDate</code> : outputs the current date.
 224         With no argument, this formatter outputs the current date
 225         and time in the format "yyyy.MM.dd hh:mm:ss z" (date, time
 226         and time zone). By giving a different format string as
 227         argument, the date format can be customized. E.g.
 228         <code>\format[CurrentDate]{yyyy.MM.dd}</code> will give the
 229         date only, e.g. 2005.11.30.</li>
 230
 231         <li><code>Default</code> : takes a single argument, which serves as a default value.
 232         If the string to format is non-empty, it is output without changes. If it is empty,
 233         the default value is output. For instance, <code>\format[Default(unknown)]{\year}</code>
 234         will output the entry's year if set, and "unknown" if no year is set.</li>
 235
 236         <li><code>DOIStrip</code> : strips any prefixes from the DOI string.</li>
 237         <li><code>DOICheck</code> : provides the full url for a DOI link.</li>
 238
 239         <li><code>FileLink(filetype)</code> : if no argument is given, this formatter outputs
 240         the first external file link encoded in the field. To work, the formatter must
 241         be supplied with the contents of the "file" field.
 242         <p>This formatter takes the name of an external file type as an optional argument,
 243         specified in parentheses after the formatter name. For instance,
 244         <code>\format[FileLink(pdf)]{\file}</code> specifies <code>pdf</code> as an
 245         argument. When an argument is given, the formatter selects the first file
 246         link of the specified type. In the example, the path to the first PDF link will
 247         be output.</p></li>
 248
 249         <li><code>FirstPage</code> : returns the first page from the "pages" field, if set.
 250             For instance, if the pages field is set to "345-360" or "345--360",
 251             this formatter will return "345".</li>
 252
 253         <li><code>FormatChars</code> : This formatter converts LaTeX character sequences
 254         their equicalent unicode characters and removes other LaTeX commands without
 255         handling them.</li>
 256
 257         <li><code>FormatPagesForHTML</code> : replaces "--" with "-".</li>
 258
 259         <li><code>FormatPagesForXML</code> : replaces "--" with an XML en-dash.</li>
 260
 261         <li><code>GetOpenOfficeType</code> : returns the number used by the OpenOffice.org
 262         bibliography system (versions 1.x and 2.x) to denote the type of this entry.</li>
 263
 264         <li><code>HTMLChars</code> : replaces TeX-specific special
 265         characters (e.g. {\^a} or {\"{o}}) with their HTML
 266         representations, and translates LaTeX commands \emph, \textit,
 267         \textbf into HTML equivalents.</li>
 268
 269         <li><code>HTMLParagraphs</code> : interprets two
 270         consecutive newlines (e.g. \n \n) as the beginning of a new
 271         paragraph and creates paragraph-html-tags accordingly.</li>
 272
 273         <li><code>IfPlural</code> : outputs its first argument if the input field looks
 274         like an author list with two or more names, or its second argument otherwise.
 275         E.g. <code>\format[IfPlural(Eds.,Ed.)]{\editor}</code> will output "Eds." if there
 276         is more than one editor, and "Ed." if there is only one.</li>
 277
 278         <li><code>JournalAbbreviator</code> : The given input text is abbreviated according to the journal abbreviation lists.
 279                 If no abbreviation for input is found (e.g. not in list or already abbreviated), the input will be returned unmodified.
 280                 For instance, when using <code>\format[JournalAbbreviator]{\journal}</code>,
 281                 "Physical Review Letters" gets "Phys. Rev. Lett." </li>
 282
 283         <li><code>LastPage</code> : returns the last page from the "pages" field, if set.
 284             For instance, if the pages field is set to "345-360" or "345--360",
 285             this formatter will return "360".</li>
 286
 287         <li><code>NoSpaceBetweenAbbreviations</code> :  LayoutFormatter that removes
 288         the space between abbreviated First names. Example: J. R. R. Tolkien becomes J.R.R. Tolkien.</li>
 289
 290         <li><code>NotFoundFormatter</code> : Formatter used to signal that a formatter hasn't been found.
 291         This can be used for graceful degradation if a layout uses an undefined format.</li>
 292
 293         <li><code>Number</code> : outputs the 1-based sequence number of the current entry in the
 294         current export. This formatter can be used to make a numbered list of entries. The
 295         sequence number depends on the current entry's place in the current sort order, not on
 296         the number of calls to this formatter.</li>
 297
 298         <li><code>RemoveBrackets</code> : removes all curly brackets "{" or "}".</li>
 299
 300         <li><code>RemoveBracketsAddComma</code> : removes all curly brackets "{" or "}". The closing curly bracket
 301         is replaced by a comma.</li>
 302
 303         <li><code>RemoveLatexCommands</code> : removes LaTeX
 304         commands like <code>\em</code>, <code>\textbf</code>, etc.
 305         If used together with <code>HTMLChars</code> or
 306         <code>XMLChars</code>, this formatter should be called
 307         last.</li>
 308
 309         <li><code>RemoveTilde</code> : replaces the tilde character
 310         used in LaTeX as a non-breakable space by a regular space.
 311         Useful in combination with the <a href="#NameFormatter">NameFormatter</a> discussed in
 312         the next section.</li>
 313
 314         <li><code>RemoveWhitespace</code> : removes all whitespace characters.</li>
 315
 316         <li><code>Replace(regexp,replacewith)</code> : does a regular expression replacement.
 317         To use this formatter, a two-part argument must be given. The parts are
 318         separated by a comma. To indicate the comma character, use an escape
 319         sequence: \,<br/>&nbsp;<br/>
 320         The first part is the regular expression to search for. Remember that any commma
 321         character must be preceded by a backslash, and consequently a literal backslash must
 322         be written as a pair of backslashes. A description of Java regular expressions can be
 323         found at:<br/>
 324         &nbsp;http://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html
 325          <br/>&nbsp;<br/>
 326         The second part is the text to replace all matches with.</li>
 327
 328                 <li><code>RisAuthors</code> : to be documented.</li>
 329                 <li><code>RisKeywords</code> : to be documented.</li>
 330                 <li><code>RisMonth</code> : to be documented.</li>
 331
 332         <li><code>RTFChars</code> : replaces TeX-specific special
 333         characters (e.g. {\^a} or {\"{o}}) with their RTF
 334         representations, and translates LaTeX commands \emph, \textit,
 335         \textbf into RTF equivalents.</li>
 336
 337         <li><code>ToLowerCase</code> : turns all characters into
 338         lower case.</li>
 339
 340         <li><code>ToUpperCase</code> : turns all characters into
 341         upper case.</li>
 342
 343         <li><code>WrapContent</code> : This formatter outputs the input value after adding a
 344         prefix and a postfix, as long as the input value is non-empty. If the input value
 345         is empty, an empty string is output (the prefix and postfix are not output in this case).
 346         The formatter requires an argument containing the prefix and postix separated
 347         by a comma. To include the comma character in either, use an escape sequence
 348         (\,).</li>
 349
 350         <li><code>WrapFileLinks</code> : See below.</li>
 351
 352         <li><code>XMLChars</code> : replaces TeX-specific special
 353         characters (e.g. {\^a} or {\"{o}}) with their XML
 354         representations.</li>
 355
 356     </ul>
 357
 358 <h3>The <code>Authors</code> formatter</h3>
 359
 360 <p>To accommodate for the numerous citation styles, the <code>Authors</code> formatter allows flexible control over the layout of the author list. The formatter takes a comma-separated list of options, by which the default values can be overridden. The following option/value pairs are currently available, where the default values are given in curly brackets.</p>
 361 <dl>
 362 <dt><code>AuthorSort = [ {FirstFirst} | LastFirst | LastFirstFirstFirst ]</code></dt>
 363 <dd>specifies the order in which the author names are formatted.
 364         <ul>
 365                 <li><code>FirstFirst</code> : first names are followed by the surname.</li>
 366                 <li><code>LastFirst</code> : the authors' surnames are followed by their first names, separated by a comma.</li>
 367                 <li><code>LastFirstFirstFirst</code> : the first author is formatted as LastFirst, the subsequent authors as FirstFirst.</li>
 368         </ul>
 369 </dd>
 370
 371 <dt><code>AuthorAbbr = [ FullName | LastName | {Initials} | InitialsNoSpace | FirstInitial | MiddleInitial ]</code></dt>
 372 <dd>specifies how the author names are abbreviated.
 373         <ul>
 374                 <li><code>FullName</code> : shows full author names; first names are not abbreviated.</li>
 375                 <li><code>LastName</code> : show only surnames, first names are removed.</li>
 376                 <li><code>Initials</code> : all first names are abbreviated.</li>
 377                 <li><code>InitialsNospace</code> : as Initials, with any spaces between initials removed.</li>
 378                 <li><code>FirstInitial</code> : only first initial is shown.</li>
 379                 <li><code>MiddleInitial</code> : first name is shown, but all middle names are abbreviated.</li>
 380         </ul>
 381 </dd>
 382
 383 <dt><code>AuthorPunc = [ {FullPunc} | NoPunc | NoComma | NoPeriod ]</code></dt>
 384 <dd>specifies the punctuation used in the author list when <code>AuthorAbbr</code> is used
 385         <ul>
 386                 <li><code>FullPunc</code> : no changes are made to punctuation.</li>
 387                 <li><code>NoPunc</code> : all full stops and commas are removed from the author name.</li>
 388                 <li><code>NoComma</code> : all commas are removed from the author name.</li>
 389                 <li><code>NoPeriod</code> : all full stops are removed from the author name.</li>
 390         </ul>
 391 </dd>
 392
 393 <dt><code>AuthorSep = [ {Comma} | And | Colon | Semicolon | Sep=&lt;string&gt; ]</code></dt>
 394 <dd>specifies the separator to be used between authors. Any separator can be specified, with the <code>Sep=&lt;string&gt;</code> option. Note that appropriate spaces need to be added around <code>string</code>.</dd>
 395
 396 <dt><code>AuthorLastSep = [ Comma | {And} | Colon | Semicolon | Amp | Oxford | LastSep=&lt;string&gt; ]</code></dt>
 397 <dd>specifies the last separator in the author list. Any separator can be specified, with the <code>LastSep=&lt;string&gt;</code> option. Note that appropriate spaces need to be added around <code>string</code>.</dd>
 398
 399 <dt><code>AuthorNumber = [ {inf} | &lt;integer&gt; ]</code></dt>
 400 <dd>specifies the number of authors that are printed. If the number of authors exceeds the maximum specified, the authorlist is replaced by the first author (or any number specified by <code>AuthorNumberEtAl</code>), followed by <code>EtAlString</code>.</dd>
 401
 402 <dt><code>AuthorNumberEtAl = [ {1} | &lt;integer&gt; ]</code></dt>
 403 <dd>specifies the number of authors that are printed if the total number of authors exceeds <code>AuthorNumber</code>.
 404 This argument can only be given after <code>AuthorNumber</code> has already been given.</dd>
 405
 406 <dt><code>EtAlString = [ { et al.} | EtAl=&lt;string&gt; ]</code></dt>
 407 <dd>specifies the string used to replace multiple authors. Any string can be given, using <code>EtAl=&lt;string&gt;</code></dd>
 408
 409 </dl>
 410
 411 <p>If an option is unspecified, the default value (shown in curly brackets above) is used. Therefore, only layout options that differ from the defaults need to be specified. The order in which the options are defined is (mostly) irrelevant. So, for example,</p>
 412 <p><code>\format[Authors(Initials,Oxford)]{\author}</code></p>
 413 <p>is equivalent to</p>
 414 <p><code>\format[Authors(Oxford,Initials)]{\author}</code></p>
 415 <p>As mentioned, the order in which the options are specified is irrelevant. There is one possibility for ambiguity, and that is if both <code>AuthorSep</code> and <code>AuthorLastSep</code> are given. In that case, the first applicable value encountered would be for <code>AuthorSep</code>, and the second for <code>AuthorLastSep</code>. It is good practise to specify both when changing the default, to avoid ambiguity.</p>
 416
 417 <h4>Examples</h4>
 418 <p>Given the following authors, <i>"Joe James Doe and Mary Jane and Bruce Bar and Arthur Kay"</i> ,the <code>Authors</code> formatter will give the following results:</p>
 419 <dl>
 420 <dt><code>Authors()</code>, or equivalently, <code>Authors(FirstFirst,Initials,FullPunc,Comma,And,inf,EtAl= et al.)</code></dt>
 421 <dd><pre>J. J. Doe, M. Jane, B. Bar and A. Kay</pre></dd>
 422
 423 <dt><code>Authors(LastFirstFirstFirst,MiddleInitial,Semicolon)</code></dt>
 424 <dd><pre>Doe, Joe J.; Mary Jane; Bruce Bar and Arthur Kay</pre></dd>
 425
 426 <dt><code>Authors(LastFirst,InitialsNoSpace,NoPunc,Oxford)</code></dt>
 427 <dd><pre>Doe JJ, Jane M, Bar B, and Kay A</pre></dd>
 428
 429 <dt><code>Authors(2,EtAl= and others)</code></dt>
 430 <dd><pre>J. J. Doe and others</pre></dd>
 431 </dl>
 432 <p>Most commonly available citation formats should be possible with this formatter. For even more advanced options, consider using the Custom Formatters detailed below.</p>
 433
 434 <h3>The <code>WrapFileLinks</code> formatter</h3>
 435
 436 <p>This formatter iterates over all file links, or all file links of a specified type, outputting a format string given as the first argument. The format string can contain a number of escape sequences indicating file link information to be inserted into the string.</p>
 437 <p>This formatter can take an optional second argument specifying the name of a file type. If specified, the iteration will only include those files with a file type matching the given name (case-insensitively). If specified as an empty argument, all file links will be included.</p>
 438 <p> After the second argument, pairs of additional arguments can be added in order to specify regular expression replacements to be done upon the inserted link information before insertion into the output string. A non-paired argument will be ignored. In order to specify replacements without filtering on file types, use an empty second argument.</p>
 439 <p>The escape sequences for embedding information are as follows:</p>
 440 <ul>
 441         <li><code>\i</code> : This inserts the iteration index (starting from 1), and can be useful if the output list of files should be enumerated.</li>
 442         <li><code>\p</code> : This inserts the file path of the file link.</li>
 443         <li><code>\f</code> : This inserts the name of the file link's type.</li>
 444         <li><code>\x</code> : This inserts the file's extension, if any.</li>
 445         <li><code>\d</code> : This inserts the file link's description, if any.</li>
 446 </ul>
 447 <p>For instance, an entry could contain a file link to the file "/home/john/report.pdf" of the "PDF" type with description "John's final report". Using the WrapFileLinks formatter with the following argument:</p>
 448 <p><code>\format[WrapFileLinks(\i. \d (\p))]{\file}</code></p>
 449 <p>would give the following output:</p>
 450 <pre>
 451     1. John's final report (/home/john/report.pdf)
 452
 453 </pre>
 454 <p>If the entry contained a second file link to the file "/home/john/draft.txt" of the "Text file" type with description 'An early "draft"', the output would be as follows:</p>
 455 <pre>
 456     1. John's final report (/home/john/report.pdf)
 457     2. An early "draft" (/home/john/draft.txt)
 458
 459 </pre>
 460 <p>If the formatter was called with a second argument, the list would be filtered. For instance:</p>
 461 <p><code>\format[WrapFileLinks(\i. \d (\p),,text file)]{\file}</code></p>
 462 <p> would show only the text file:</p>
 463 <pre>
 464     1. An early "draft" (/home/john/draft.txt)
 465
 466 </pre>
 467 <p>If we wanted this output to be part of an XML styled output, the quotes in the file description could cause problems. Adding two additional arguments to translate the quotes into XML characters solves this:</p>
 468 <p><code>\format[WrapFileLinks(\i. \d (\p),,text file,",&amp;quot;)]{\file}</code></p>
 469 <p>would give the following output:</p>
 470 <pre>
 471     1. An early &quot;draft&quot; (/home/john/draft.txt)
 472
 473 </pre>
 474 <p>Additional pairs of replacements could be added.</p>
 475
 476
 477     <h3>Custom formatters</h3>
 478     <p>If none of the available formatters can do what you want to
 479     achieve, you can add your own by implementing the
 480     <code>net.sf.jabref.export.layout.LayoutFormatter</code>
 481     interface. If you insert your class into the
 482     <code>net.sf.jabref.export.layout.format</code> package, you
 483     can call the formatter by its class name only, like with the
 484     standard formatters. Otherwise, you must call the formatter by
 485     its fully qualified name (including package name). In any case,
 486     the formatter must be in your classpath when running
 487     JabRef.</p>
 488
 489     <h2 id="NameFormatter">Using Custom Name Formatters</h2>
 490
 491     <p>From JabRef 2.2, it is possible to define custom name
 492     formatters using the bibtex-sty-file syntax. This allows
 493     ultimate flexibility, but is a cumbersome to write</p>
 494
 495     <p>You can define your own formatter in the preference tab
 496     "Name Formatter" using the following format and then use it
 497     with the name given to it as any other formatter</p>
 498     <code>&lt;case1&gt;@&lt;range11&gt;@&lt;format&gt;@&lt;range12&gt;@&lt;format&gt;@&lt;range13&gt;...@@<br />
 499
 500      &lt;case2&gt;@&lt;range21&gt;@... and so on.</code>
 501
 502     <p>This format first splits the task to format a list of author
 503     into cases depending on how many authors there are (this is
 504     since some formats differ depending on how many authors there
 505     are). Each individual case is separated by @@ and contains
 506     instructions on how to format each author in the case. These
 507     instructions are separated by a @.</p>
 508
 509     <p>Cases are identified using integers (1, 2, 3, etc.) or the
 510     character * (matches any number of authors) and will tell the
 511     formatter to apply the following instructions if there are a
 512     number of less or equal of authors given.</p>
 513
 514     <p>Ranges are either
 515     <code>&lt;integer&gt;..&lt;integer&gt;</code>,
 516     <code>&lt;integer&gt;</code> or the character <code>*</code>
 517     using a 1 based index for indexing authors from the given list
 518     of authors. Integer indexes can be negative to denote them to
 519     start from the end of the list where -1 is the last author.</p>
 520
 521     <p>For instance with an authorlist of "Joe Doe and Mary Jane
 522     and Bruce Bar and Arthur Kay":</p>
 523
 524     <ul>
 525         <li>1..3 will affect Joe, Mary and Bruce</li>
 526
 527         <li>4..4 will affect Arthur</li>
 528
 529         <li>* will affect all of them</li>
 530
 531         <li>2..-1 will affect Mary, Bruce and Arthur</li>
 532     </ul>
 533
 534     <p>The <code>&lt;format&gt;</code>-strings use the Bibtex
 535     formatter format:</p>
 536
 537     <p>The four letters v, f, l, j indicate the name parts von,
 538     first, last, jr which are used within curly braces. A single
 539     letter v, f, l, j indicates that the name should be
 540     abbreviated. If one of these letters or letter pairs is
 541     encountered JabRef will output all the respective names
 542     (possibly abbreviated), but the whole expression in curly
 543     braces is only printed if the name part exists.</p>
 544
 545     <p>For instance if the format is "{ll} {vv {von Part}} {ff}"
 546     and the names are "Mary Kay and John von Neumann", then JabRef
 547     will output "Kay Mary" (with two space between last and first)
 548     and "Neuman von von Part John".</p>
 549
 550     <p>I give two examples but would rather point you to the bibtex
 551     documentation.</p>
 552
 553     <p>Small example: <code>"{ll}, {f.}"</code> will turn
 554     <code>"Joe Doe"</code> into <code>"Doe, J."</code></p>
 555
 556     <p>Large example:</p>
 557
 558     <blockquote>
 559         <p>To turn:</p>
 560
 561         <p><code>"Joe Doe and Mary Jane and Bruce Bar and Arthur
 562         Kay"</code></p>
 563
 564         <p>into</p>
 565
 566         <p><code>"Doe, J., Jane, M., Bar, B. and Kay,
 567         A."</code></p>
 568
 569         <p>you would use</p>
 570
 571         <p><code>1@*@{ll}, {f}.@@2@1@{ll}, {f}.@2@ and {ll},
 572         {f}.@@*@1..-3@{ll}, {f}., @-2@{ll}, {f}.@-1@ and {ll},
 573         {f}.</code></p>
 574     </blockquote>
 575
 576     <p>If somebody would like to write a better tutorial about
 577     this: Write a mail to one of the JabRef mailinglists!</p>
 578
 579
 580 </body>
 581 </html>