src/help/CustomExports.html

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