[svn-inject] Installing original source of jabref
[debian/jabref.git] / src / help / CustomExports.html
1 <HTML>
2
3 <BODY text="#275856">
4 <basefont size="4" color="#2F4958" face="arial">
5
6 <H1>Custom export filters</H1>
7
8 JabRef allows you to define and use your own export filters, in the same way as the
9 standard export filters are defined. An export filter is defined by one or more
10 <i>layout files</i>, which with the help of a collection of built-in formatter
11 routines specify the format of the exported files. Your layout files must be prepared
12 in a text editor outside of JabRef.
13
14 <H2>Adding a custom export filter</H2>
15
16 The only requirement for a valid export filter is the existence of a file with
17 the extension <b>.layout</b>. To add a new custom export filter, open the
18 dialog box <b>Options -> Manage custom exports</b>, and click <b>Add new</b>.
19 A new dialog box will appear, allowing you to specify a name for the export filter
20 (which will appear in the <b>File -> Custom export</b> menu of the JabRef window),
21 the path to the <b>.layout</b> file, and the preferred file extension for the export
22 filter (which will be the suggested extension in the file dialog when you use the
23 export filter).
24
25 <H2>Creating the export filter</H2>
26
27 To see examples of how export filters are made, look for the package containing the layout files
28 for the standard export filters on our download page.
29
30 <H3>Layout files</H3>
31
32 Let us assume that we are creating an HTML export filter.
33
34 <P>While the export filter only needs to consist of a single <b>.layout</b> file, which in this case
35 could be called <i>html.layout</i>, you may also want to add two files called
36 <i>html.begin.layout</i> and <i>html.end.layout</i>. The former contains the header part
37 of the output, and the latter the footer part. JabRef will look for these two files whenever
38 the export filter is used, and if found, either of these will be copied verbatim to the output
39 before or after the individual entries are written.
40
41 <P>Note that these files must reside in the same directory as <i>html.layout</i>, and must be
42 named by inserting <b>.begin</b> and <b>.end</b>, respectively.
43
44 <P>In our example export filter, these could look like the following:
45
46 <p><i>html.begin.layout</i>:<br>
47 <code>&lt;HTML&gt;<br>
48   &lt;BODY&gt; text="#275856"&gt;<br>
49 &lt;basefont size="4" color="#2F4958" face="arial"&gt;</code>
50
51 <p><i>html.end.layout</i>:<br>
52 <code>&lt;/BODY&gt;<br>
53   &lt;/HTML&gt;</code>
54
55 <P>The file <i>html.layout</i> provides the <i>default</i> template for exporting one single entry. If
56 you want to use different templates for different entry types, you can do this by adding entry-specific
57 <b>.layout</b> files. These must also reside in the same directory as the main layout file, and
58 are named by inserting <b>.entrytype</b> into the name of the main layout file. The entry type name
59 must be in all lowercase. In our example, we might want to add a template for book entries, and this
60 would go into the file <i>html.book.layout</i>. For a PhD thesis we would add the file
61 <i>html.phdthesis.layout</i>, and so on. These files are similar to the default layout file, except that
62 they will only be used for entries of the matching type. Note that the default file can easily be made
63 general enough to cover most entry types in most export filters.
64
65 <H3>The layout file format</H3>
66
67 Layout files are created using a simple markup format where commands are identified by a preceding
68 backslash. All text not identified as part of a command will be copied verbatim to the output file.
69
70 <H3>Field commands</H3>
71
72 <p>An arbitrary word preceded by a backslash, e.g. <code>\author</code>, <code>\editor</code>,
73 <code>\title</code> or <code>\year</code>, will be interpreted as a reference to the corresponding field,
74 which will be copied directly to the output.
75
76 <H3>Field formatters</H3>
77
78 <p>Often there will be a need for some preprocessing of the field contents before output. This is
79   done using a <i>field formatter</i> - a java class containing a single method that manipulates the
80   contents of a field.
81 <p>A formatter is used by inserting the <code>\format</code> command followed by the formatter name in
82   square braces, and the field command in curly braces, e.g.:
83
84   <p><code>\format[ToLowerCase]{\author}</code>
85
86 <p>You can also specify multiple formatters separated by commas. These will be called sequentially,
87   from left to right, e.g.
88
89   <p><code>\format[ToLowerCase,HTMLChars]{\author}</code>
90
91 <p>will cause the formatter <b>ToLowerCase</b> to be called first, and then <b>HTMLChars</b> will be
92   called to format the result. You can list an arbitrary number of formatters in this way.
93
94 <p>The argument to the formatters, withing the curly braces, does not have to be a field command. Instead,
95 you can insert normal text, which will then be passed to the formatters instead of the contents of any field.
96 This can be useful for some fomatters, e.g. the CurrentDate formatter (described below).
97
98 <p>JabRef provides the following set of formatters, some of which depend on the others:
99 <ul>
100 <li><code>HTMLChars</code> : replaces TeX-specific special characters (e.g. {\^a} or {\"{o}})
101   with their HTML representations.
102 <li><code>XMLChars</code> : replaces TeX-specific special characters (e.g. {\^a} or {\"{o}})
103   with their XML representations.
104 <li><code>CreateDocBookAuthors</code> : formats the author field in DocBook style.
105 <li><code>CurrentDate</code> : outputs the current date. With no argument, this formatter outputs the
106     current date and time in the format "yyyy.MM.dd hh:mm:ss z" (date, time and time zone). By giving a
107     different format string as argument, the date format can be customized. E.g.
108     <code>\format[CurrentDate]{yyyy.MM.dd}</code> will give the date only, e.g. 2005.11.30.
109
110 <li><code>AuthorFirstFirst</code> : formats author/editor fields with the first names first.
111 <li><code>AuthorFirstFirstCommas</code> : formats author/editor fields with the first names first, and deliminated by commas.
112 <li><code>AuthorLastFirst</code> : formats author/editor fields with the last names first.
113 <li><code>AuthorLastFirstAbbreviator</code> : abbreviates first and middle names of all authors. This formatter requires AuthorLastFirst
114 to have been run earlier.
115 <li><code>AuthorAndsReplacer</code> : replaces "and" between names with ";", and "&" between the last two. 
116 <li><code>AuthorAndsCommaReplacer</code> : replaces "and" between names with ",", and "&" between the last two.
117 <li><code>FormatPagesForHTML</code> : replaces "--" with "-".
118   <li><code>FormatPagesForXML</code> : replaces "--" with an XML en-dash.
119 <li><code>RemoveBrackets</code> : removes all curly brackets "{" or "}".
120 <li><code>RemoveLatexCommands</code> : removes LaTeX commands like <code>\em</code>, <code>\textbf</code>, etc. If
121   used together with <code>HTMLChars</code> or <code>XMLChars</code>, this formatter should be called last.
122 <li><code>ToLowerCase</code> : turns all characters into lower case.
123 </ul>
124
125 <p>If none of the available formatters can do what you want to achieve, you can add your own by implementing
126   the <code>net.sf.jabref.export.layout.LayoutFormatter</code> interface. If you insert your class
127   into the <code>net.sf.jabref.export.layout.format</code> package, you can call the formatter by its
128   class name only, like with the standard formatters. Otherwise, you must call the formatter by its fully
129   qualified name (including package name). In any case, the formatter must be in your classpath when running
130   JabRef.
131
132 <H3>Conditional output</H3>
133
134 Some static output might only make sense if a specific field is set. For instance, say we want to follow
135 the editor names with the text <code>(Ed.)</code>. This can be done with the following text:
136
137 <p><code>\format[HTMLChars,AuthorFirstFirst]{\editor} (Ed.)</code>
138
139 <p>However, if the <code>editor</code> field has not been set - it might not even make sense for the entry
140   being exported - the <code>(Ed.)</code> would be left hanging. This can be prevented by instead using the
141 <code>\begin</code> and <code>\end</code> commands:
142
143 <p><code>\begin{editor}<br>\format[HTMLChars,AuthorFirstFirst]{\editor} (Ed.)
144 <br>\end{editor}</code>
145
146 <p>The <code>\begin</code> and <code>\end</code> commands make sure the text in between is printed if and
147 only if the field referred in the curly braces is defined for the ently being exported.
148
149 <p><b>Note:</b> Use of the <code>\begin</code> and <code>\end</code> commands is a key to creating
150   layout files that work well with a variety of entry types.
151
152 <H3>Grouped output</H3>
153
154 If you wish to separate your entries into groups based on a certain field, use the grouped output commands.
155 Grouped output is very similar to conditional output, except that the text in between is printed only if the
156 field referred in the curly braces has changed value.
157
158 <p>For example, let's assume I wish to group by keyword.  Before exporting the file, make sure you have sorted
159 your entries based on keyword.  Now use the following commands to group by keyword:
160
161 <p><code>\begingroup{keywords}New Category: \format[HTMLChars]{\keywords}
162 <br>    \endgroup{keywords}</code>
163
164 <H2>Sharing your work</H2>
165
166 With external layout files, it's fairly simple to share custom export formats between users.
167 If you write an export filter for a format not supported by JabRef, or an improvement over an
168 existing one, we encourage you to post your work on our SourceForge.net page. The same goes for
169 formatter classes that you write. We'd be happy to distribute a collection of submitted
170 layout files, or to add to the selection of standard export filters and formatters.
171
172 </HTML>