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.</li>
 146
 147         <li><code>HTMLParagraphs</code> : interprets two
 148         consecutive newlines (e.g. \n \n) as the beginning of a new
 149         paragraph and creates paragraph-html-tags accordingly.</li>
 150
 151         <li><code>XMLChars</code> : replaces TeX-specific special
 152         characters (e.g. {\^a} or {\"{o}}) with their XML
 153         representations.</li>
 154
 155         <li><code>CreateDocBookAuthors</code> : formats the author
 156         field in DocBook style.</li>
 157
 158         <li><code>CreateDocBookEditors</code> : to be
 159         documented.</li>
 160
 161         <li><code>CurrentDate</code> : outputs the current date.
 162         With no argument, this formatter outputs the current date
 163         and time in the format "yyyy.MM.dd hh:mm:ss z" (date, time
 164         and time zone). By giving a different format string as
 165         argument, the date format can be customized. E.g.
 166         <code>\format[CurrentDate]{yyyy.MM.dd}</code> will give the
 167         date only, e.g. 2005.11.30.</li>
 168
 169         <li><code>AuthorFirstFirst</code> : formats author/editor
 170         fields with the first names first.</li>
 171
 172         <li><code>AuthorFirstFirstCommas</code> : formats
 173         author/editor fields with the first names first, and
 174         deliminated by commas.</li>
 175
 176         <li><code>AuthorFirstAbbrLastCommas</code> : to be
 177         documented.</li>
 178
 179         <li><code>AuthorFirstAbbrLastOxfordCommas</code> : to be
 180         documented.</li>
 181
 182         <li><code>AuthorFirstLastOxfordCommas</code> : to be
 183         documented.</li>
 184
 185         <li><code>AuthorLastFirst</code> : formats author/editor
 186         fields with the last names first.</li>
 187
 188         <li><code>AuthorAbbreviator</code> or <code>AuthorLastFirstAbbreviator</code>
 189             : abbreviates first and middle names of all authors. This formatter
 190         returns names with the last name first. Follow this formatter with
 191         AuthorFirstFirst to get abbreviated names with the initials first.</li>
 192
 193         <li><code>AuthorLastFirstCommas</code> : to be
 194         documented.</li>
 195
 196         <li><code>AuthorLastFirstOxfordCommas</code> : to be
 197         documented.</li>
 198
 199         <li><code>AuthorLastFirstAbbrCommas</code> : to be
 200         documented.</li>
 201
 202         <li><code>AuthorLastFirstAbbrOxfordCommas</code> : to be
 203         documented.</li>
 204
 205         <li><code>AuthorAndsReplacer</code> : replaces "and"
 206         between names with ";", and "&amp;" between the last
 207         two.</li>
 208
 209         <li><code>AuthorAndsCommaReplacer</code> : replaces "and"
 210         between names with ",", and "&amp;" between the last
 211         two.</li>
 212
 213         <li><code>AuthorOrgSci</code> : first author is in "last,
 214         first" all others in "first last". First names are
 215         abbreviated.</li>
 216
 217         <li><code>AuthorNatBib</code> : formats author names in
 218         NatBib style, with last names only, separating names by
 219         "and" if there are two authors, and giving the first author
 220         followed by "et al." if there are more than two
 221         authors.</li>
 222
 223         <li><code>NoSpaceBetweenAbbreviations</code> : spaces
 224         between multiple abbreviated first names are removed.</li>
 225
 226         <li><code>FileLink(filetype)</code> : if no argument is given, this formatter outputs
 227             the first external file link encoded in the field. To work, the formatter must
 228             be supplied with the contents of the "file" field.
 229             <p>This formatter takes the name of an external file type as an optional argument,
 230                 specified in parentheses after the formatter name. For instance,
 231                 <code>\format[FileLink(pdf)]{\file}</code> specifies <code>pdf</code> as an
 232                 argument. When an argument is given, the formatter selects the first file
 233                 link of the specified type. In the example, the path to the first PDF link will
 234                 be output.</p></li>
 235
 236         <li><code>FormatPagesForHTML</code> : replaces "--" with
 237         "-".</li>
 238
 239         <li><code>FormatPagesForXML</code> : replaces "--" with an
 240         XML en-dash.</li>
 241
 242     <li><code>Replace(regexp,replacewith)</code> : does a regular expression replacement.
 243         To use this formatter, a two-part argument must be given. The parts are
 244         separated by a comma. To indicate the comma character, use an escape
 245         sequence: \,<br>&nbsp;<br>
 246         The first part is the regular expression to search for. The regular expression
 247         is written normally, without extra escape sequences for backslashes. A description
 248         of Java regular expressions can be found at:<br>
 249         &nbsp;http://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html
 250          <br>&nbsp;<br>
 251         The second part is the text to replace all matches with.</li>
 252
 253         <li><code>RemoveBrackets</code> : removes all curly
 254         brackets "{" or "}".</li>
 255
 256         <li><code>RemoveBracketsAddComma</code> : to be
 257         documented.</li>
 258
 259         <li><code>RemoveWhitespace</code> : to be documented.</li>
 260
 261         <li><code>RemoveLatexCommands</code> : removes LaTeX
 262         commands like <code>\em</code>, <code>\textbf</code>, etc.
 263         If used together with <code>HTMLChars</code> or
 264         <code>XMLChars</code>, this formatter should be called
 265         last.</li>
 266
 267         <li><code>RemoveTilde</code> : replaces the tilde character
 268         used in LaTeX as a non-breakable space by a regular space.
 269         Useful in combination with the NameFormatter discussed in
 270         the next section.</li>
 271
 272         <li><code>ToLowerCase</code> : turns all characters into
 273         lower case.</li>
 274
 275         <li><code>CompositeFormat</code> : to be documented.</li>
 276
 277         <li><code>GetOpenOfficeType</code> : to be documented.</li>
 278
 279         <li><code>RTFChars</code> : to be documented.</li>
 280
 281         <li><code>ResolvePDF</code> : to be documented.</li>
 282
 283     <li></li>
 284     </ul>
 285
 286     <p>If none of the available formatters can do what you want to
 287     achieve, you can add your own by implementing the
 288     <code>net.sf.jabref.export.layout.LayoutFormatter</code>
 289     interface. If you insert your class into the
 290     <code>net.sf.jabref.export.layout.format</code> package, you
 291     can call the formatter by its class name only, like with the
 292     standard formatters. Otherwise, you must call the formatter by
 293     its fully qualified name (including package name). In any case,
 294     the formatter must be in your classpath when running
 295     JabRef.</p>
 296
 297     <h2><a name="NameFormatter"
 298        id="NameFormatter">Using Custom Name Formatters</a></h2>
 299
 300     <p>With JabRef 2.2 it is now possible to define custom name
 301     formatters using the bibtex-sty-file syntax. This allows
 302     ultimate flexibility, but is a cumbersome to write</p>
 303
 304     <p>You can define your own formatter in the preference tab
 305     "Name Formatter" using the following format and then use it
 306     with the name given to it as any other formatter</p>
 307     <code>&lt;case1&gt;@&lt;range11&gt;@&lt;format&gt;@&lt;range12&gt;@&lt;format&gt;@&lt;range13&gt;...@@<br />
 308
 309      &lt;case2&gt;@&lt;range21&gt;@... and so on.</code>
 310
 311     <p>This format first splits the task to format a list of author
 312     into cases depending on how many authors there are (this is
 313     since some formats differ depending on how many authors there
 314     are). Each individual case is separated by @@ and contains
 315     instructions on how to format each author in the case. These
 316     instructions are separated by a @.</p>
 317
 318     <p>Cases are identified using integers (1, 2, 3, etc.) or the
 319     character * (matches any number of authors) and will tell the
 320     formatter to apply the following instructions if there are a
 321     number of less or equal of authors given.</p>
 322
 323     <p>Ranges are either
 324     <code>&lt;integer&gt;..&lt;integer&gt;</code>,
 325     <code>&lt;integer&gt;</code> or the character <code>*</code>
 326     using a 1 based index for indexing authors from the given list
 327     of authors. Integer indexes can be negative to denote them to
 328     start from the end of the list where -1 is the last author.</p>
 329
 330     <p>For instance with an authorlist of "Joe Doe and Mary Jane
 331     and Bruce Bar and Arthur Kay":</p>
 332
 333     <ul>
 334         <li>1..3 will affect Joe, Mary and Bruce</li>
 335
 336         <li>4..4 will affect Arthur</li>
 337
 338         <li>* will affect all of them</li>
 339
 340         <li>2..-1 will affect Mary, Bruce and Arthur</li>
 341     </ul>
 342
 343     <p>The <code>&lt;format&gt;</code>-strings use the Bibtex
 344     formatter format:</p>
 345
 346     <p>The four letters v, f, l, j indicate the name parts von,
 347     first, last, jr which are used within curly braces. A single
 348     letter v, f, l, j indicates that the name should be
 349     abbreviated. If one of these letters or letter pairs is
 350     encountered JabRef will output all the respective names
 351     (possibly abbreviated), but the whole expression in curly
 352     braces is only printed if the name part exists.</p>
 353
 354     <p>For instance if the format is "{ll} {vv {von Part}} {ff}"
 355     and the names are "Mary Kay and John von Neumann", then JabRef
 356     will output "Kay Mary" (with two space between last and first)
 357     and "Neuman von von Part John".</p>
 358
 359     <p>I give two examples but would rather point you to the bibtex
 360     documentation.</p>
 361
 362     <p>Small example: <code>"{ll}, {f.}"</code> will turn
 363     <code>"Joe Doe"</code> into <code>"Doe, J."</code></p>
 364
 365     <p>Large example:</p>
 366
 367     <blockquote>
 368         <p>To turn:</p>
 369
 370         <p><code>"Joe Doe and Mary Jane and Bruce Bar and Arthur
 371         Kay"</code></p>
 372
 373         <p>into</p>
 374
 375         <p><code>"Doe, J., Jane, M., Bar, B. and Kay,
 376         A."</code></p>
 377
 378         <p>you would use</p>
 379
 380         <p><code>1@*@{ll}, {f}.@@2@1@{ll}, {f}.@2@ and {ll},
 381         {f}.@@*@1..-3@{ll}, {f}., @-2@{ll}, {f}.@-1@ and {ll},
 382         {f}.</code></p>
 383     </blockquote>
 384
 385     <p>If somebody would like to write a better tutorial about
 386     this: Write a mail to one of the JabRef mailinglists!</p>
 387
 388     <h3>Conditional output</h3>
 389
 390     <p>Some static output might only make
 391     sense if a specific field is set. For instance, say we want to
 392     follow the editor names with the text <code>(Ed.)</code>. This
 393     can be done with the following text:</p>
 394
 395     <p><code>\format[HTMLChars,AuthorFirstFirst]{\editor}
 396     (Ed.)</code></p>
 397
 398     <p>However, if the <code>editor</code> field has not been set -
 399     it might not even make sense for the entry being exported - the
 400     <code>(Ed.)</code> would be left hanging. This can be prevented
 401     by instead using the <code>\begin</code> and <code>\end</code>
 402     commands:</p>
 403
 404     <p><code>\begin{editor}<br />
 405     \format[HTMLChars,AuthorFirstFirst]{\editor} (Ed.)<br />
 406      \end{editor}</code></p>
 407
 408     <p>The <code>\begin</code> and <code>\end</code> commands make
 409     sure the text in between is printed if and only if the field
 410     referred in the curly braces is defined for the ently being
 411     exported.</p>
 412
 413     <p><b>Note:</b> Use of the <code>\begin</code> and
 414     <code>\end</code> commands is a key to creating layout files
 415     that work well with a variety of entry types.</p>
 416
 417     <h3>Grouped output</h3>
 418
 419     <p>If you wish to separate your entries
 420     into groups based on a certain field, use the grouped output
 421     commands. Grouped output is very similar to conditional output,
 422     except that the text in between is printed only if the field
 423     referred in the curly braces has changed value.</p>
 424
 425     <p>For example, let's assume I wish to group by keyword. Before
 426     exporting the file, make sure you have sorted your entries
 427     based on keyword. Now use the following commands to group by
 428     keyword:</p>
 429
 430     <p><code>\begingroup{keywords}New Category:
 431     \format[HTMLChars]{\keywords}<br />
 432      \endgroup{keywords}</code></p>
 433
 434     <h2>Sharing your work</h2>
 435
 436     <p>With external layout files, it's
 437     fairly simple to share custom export formats between users. If
 438     you write an export filter for a format not supported by
 439     JabRef, or an improvement over an existing one, we encourage
 440     you to post your work on our SourceForge.net page. The same
 441     goes for formatter classes that you write. We'd be happy to
 442     distribute a collection of submitted layout files, or to add to
 443     the selection of standard export filters and formatters.</p>
 444 </body>
 445 </html>