[svn-upgrade] Integrating new upstream version, jabref (2.3~beta1)
[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 as one of the choices in the File type dropdown menu of the file dialog
21 when you use the <b>File -> Export</b> menu choice in the JabRef window),
22 the path to the <b>.layout</b> file, and the preferred file extension for the export
23 filter (which will be the suggested extension in the file dialog when you use the
24 export filter).
25
26 <H2>Creating the export filter</H2>
27
28 To see examples of how export filters are made, look for the package containing the layout files
29 for the standard export filters on our download page.
30
31 <H3>Layout files</H3>
32
33 Let us assume that we are creating an HTML export filter.
34
35 <P>While the export filter only needs to consist of a single <b>.layout</b> file, which in this case
36 could be called <i>html.layout</i>, you may also want to add two files called
37 <i>html.begin.layout</i> and <i>html.end.layout</i>. The former contains the header part
38 of the output, and the latter the footer part. JabRef will look for these two files whenever
39 the export filter is used, and if found, either of these will be copied verbatim to the output
40 before or after the individual entries are written.
41
42 <P>Note that these files must reside in the same directory as <i>html.layout</i>, and must be
43 named by inserting <b>.begin</b> and <b>.end</b>, respectively.
44
45 <P>In our example export filter, these could look like the following:
46
47 <p><i>html.begin.layout</i>:<br>
48 <code>&lt;HTML&gt;<br>
49   &lt;BODY&gt; text="#275856"&gt;<br>
50 &lt;basefont size="4" color="#2F4958" face="arial"&gt;</code>
51
52 <p><i>html.end.layout</i>:<br>
53 <code>&lt;/BODY&gt;<br>
54   &lt;/HTML&gt;</code>
55
56 <P>The file <i>html.layout</i> provides the <i>default</i> template for exporting one single entry. If
57 you want to use different templates for different entry types, you can do this by adding entry-specific
58 <b>.layout</b> files. These must also reside in the same directory as the main layout file, and
59 are named by inserting <b>.entrytype</b> into the name of the main layout file. The entry type name
60 must be in all lowercase. In our example, we might want to add a template for book entries, and this
61 would go into the file <i>html.book.layout</i>. For a PhD thesis we would add the file
62 <i>html.phdthesis.layout</i>, and so on. These files are similar to the default layout file, except that
63 they will only be used for entries of the matching type. Note that the default file can easily be made
64 general enough to cover most entry types in most export filters.
65
66 <H3>The layout file format</H3>
67
68 Layout files are created using a simple markup format where commands are identified by a preceding
69 backslash. All text not identified as part of a command will be copied verbatim to the output file.
70
71 <H3>Field commands</H3>
72
73 <p>An arbitrary word preceded by a backslash, e.g. <code>\author</code>, <code>\editor</code>,
74 <code>\title</code> or <code>\year</code>, will be interpreted as a reference to the corresponding field,
75 which will be copied directly to the output.
76
77 <H3>Field formatters</H3>
78
79 <p>Often there will be a need for some preprocessing of the field contents before output. This is
80   done using a <i>field formatter</i> - a java class containing a single method that manipulates the
81   contents of a field.
82 <p>A formatter is used by inserting the <code>\format</code> command followed by the formatter name in
83   square braces, and the field command in curly braces, e.g.:
84
85   <p><code>\format[ToLowerCase]{\author}</code>
86
87 <p>You can also specify multiple formatters separated by commas. These will be called sequentially,
88   from left to right, e.g.
89
90   <p><code>\format[ToLowerCase,HTMLChars]{\author}</code>
91
92 <p>will cause the formatter <b>ToLowerCase</b> to be called first, and then <b>HTMLChars</b> will be
93   called to format the result. You can list an arbitrary number of formatters in this way.
94
95 <p>The argument to the formatters, withing the curly braces, does not have to be a field command. Instead,
96 you can insert normal text, which will then be passed to the formatters instead of the contents of any field.
97 This can be useful for some fomatters, e.g. the CurrentDate formatter (described below).
98
99 <p>JabRef provides the following set of formatters, some of which depend on the others:
100 <ul>
101 <li><code>HTMLChars</code> : replaces TeX-specific special characters (e.g. {\^a} or {\"{o}})
102   with their HTML representations.
103 <li><code>HTMLParagraphs</code> : interprets two consecutive newlines (e.g. \n   \n) as the beginning of a new paragraph and creates paragraph-html-tags accordingly.
104 <li><code>XMLChars</code> : replaces TeX-specific special characters (e.g. {\^a} or {\"{o}})
105   with their XML representations.
106
107 <li><code>CreateDocBookAuthors</code> : formats the author field in DocBook style.
108 <li><code>CreateDocBookEditors</code> : to be documented.
109
110 <li><code>CurrentDate</code> : outputs the current date. With no argument, this formatter outputs the
111     current date and time in the format "yyyy.MM.dd hh:mm:ss z" (date, time and time zone). By giving a
112     different format string as argument, the date format can be customized. E.g.
113     <code>\format[CurrentDate]{yyyy.MM.dd}</code> will give the date only, e.g. 2005.11.30.
114
115 <li><code>AuthorFirstFirst</code> : formats author/editor fields with the first names first.
116 <li><code>AuthorFirstFirstCommas</code> : formats author/editor fields with the first names first, and deliminated by commas.
117 <li><code>AuthorFirstAbbrLastCommas</code> : to be documented.
118 <li><code>AuthorFirstAbbrLastOxfordCommas</code> : to be documented.
119 <li><code>AuthorFirstLastOxfordCommas </code> : to be documented.
120
121 <li><code>AuthorLastFirst</code> : formats author/editor fields with the last names first.
122 <li><code>AuthorLastFirstAbbreviator</code> : abbreviates first and middle names of all authors. This formatter requires AuthorLastFirst
123 to have been run earlier.
124 <li><code>AuthorLastFirstCommas</code> : to be documented.
125 <li><code>AuthorLastFirstOxfordCommas</code> : to be documented.
126 <li><code>AuthorLastFirstAbbrCommas</code> : to be documented.
127 <li><code>AuthorLastFirstAbbrOxfordCommas</code> : to be documented.
128
129 <li><code>AuthorAndsReplacer</code> : replaces "and" between names with ";", and "&" between the last two.
130 <li><code>AuthorAndsCommaReplacer</code> : replaces "and" between names with ",", and "&" between the last two.
131 <li><code>AuthorOrgSci</code> : first author is in "last, first" all others in "first last". First names are abbreviated.
132 <li><code>AuthorAbbreviator</code> : to be documented.
133 <li><code>AuthorNatBib</code> : formats author names in NatBib style, with last names only, separating names by "and"
134     if there are two authors, and giving the first author followed by "et al." if there are more than
135     two authors.
136 <li><code>NoSpaceBetweenAbbreviations</code> : spaces between multiple abbreviated first names are removed.
137 <li><code>FormatPagesForHTML</code> : replaces "--" with "-".
138   <li><code>FormatPagesForXML</code> : replaces "--" with an XML en-dash.
139
140 <li><code>RemoveBrackets</code> : removes all curly brackets "{" or "}".
141 <li><code>RemoveBracketsAddComma</code> : to be documented.
142 <li><code>RemoveWhitespace</code> : to be documented.
143 <li><code>RemoveLatexCommands</code> : removes LaTeX commands like <code>\em</code>, <code>\textbf</code>, etc. If
144   used together with <code>HTMLChars</code> or <code>XMLChars</code>, this formatter should be called last.
145 <li><code>RemoveTilde</code> : replaces the tilde character used in LaTeX as a non-breakable space by a regular space. Useful 
146 in combination with the NameFormatter discussed in the next section.
147 <li><code>ToLowerCase</code> : turns all characters into lower case.
148
149 <li><code>CompositeFormat</code> : to be documented.
150 <li><code>GetOpenOfficeType</code> : to be documented.
151 <li><code>RTFChars</code> : to be documented.
152 <li><code>ResolvePDF</code> : to be documented.
153
154 </ul>
155
156 <p>If none of the available formatters can do what you want to achieve, you can add your own by implementing
157   the <code>net.sf.jabref.export.layout.LayoutFormatter</code> interface. If you insert your class
158   into the <code>net.sf.jabref.export.layout.format</code> package, you can call the formatter by its
159   class name only, like with the standard formatters. Otherwise, you must call the formatter by its fully
160   qualified name (including package name). In any case, the formatter must be in your classpath when running
161   JabRef.</p>
162   
163 <a name="NameFormatter">
164 <H2>Using Custom Name Formatters</H2>
165
166 <p>With JabRef 2.2 it is now possible to define custom name formatters using the bibtex-sty-file syntax. 
167 This allows ultimate flexibility, but is a cumbersome to write</p>
168 <p>You can define your own formatter in the preference tab "Name Formatter" using the following format
169 and then use it with the name given to it as any other formatter</p>
170
171 <code>
172   &lt;case1&gt;@&lt;range11&gt;@&lt;format&gt;@&lt;range12&gt;@&lt;format&gt;@&lt;range13&gt;...@@<br>
173   &lt;case2&gt;@&lt;range21&gt;@... and so on.
174 </code>
175
176 <p>This format first splits the task to format a list of author into cases depending on
177 how many authors there are (this is since some formats differ depending on how many authors there are). 
178 Each individual case is separated by @@ and contains instructions on how to format each author in the case.
179 These instructions are separated by a @.</p>
180 <p>Cases are identified using integers (1,2,3,etc.) or the character * (matches any number of authors) and will tell 
181 the formatter to apply the following instructions if there are a number of less or equal of authors given.
182 </p>
183 <p>
184   Ranges are either <code>&lt;integer&gt;..&lt;integer&gt;</code>, <code>&lt;integer&gt;</code> or the character <code>*</code> using a 1 based index for indexing 
185   authors from the given list of authors. Integer indexes can be negative to denote them to start from 
186   the end of the list where -1 is the last author.
187 </p>
188
189 <p>For instance with an authorlist of "Joe Doe and Mary Jane and Bruce Bar and Arthur Kay":</p>
190 <ul>
191   <li> 1..3 will affect Joe, Mary and Bruce</li>
192   <li> 4..4 will affect Arthur </li>
193   <li> * will affect all of them</li>
194   <li> 2..-1 will affect Mary, Bruce and Arthur</li>
195 </ul>
196
197 <p>The <code>&lt;format&gt;</code>-strings use the Bibtex formatter format:</p>
198  
199 <p> 
200   The four letter v, f, l, j indicate the name parts von, first, last, jr which 
201   are used within curly braces. A single letter v, f, l, j indicates that the name should be abbreviated.
202   If one of these letters or letter pairs is encountered JabRef will output all the respective names 
203   (possibly abbreviated), but the whole expression in curly braces is only printed if the name part exists.</p>
204
205 <p>For instance if the format is "{ll} {vv {von Part}} {ff}" and the names are "Mary Kay and John von Neumann",
206   then JabRef will output "Kay  Mary" (with two space between last and first) and "Neuman von von Part John".</p>
207   
208 <p>I give two examples but would rather point you to the bibtex documentation.</p>
209
210 <p>Small example: <code>"{ll}, {f.}"</code> will turn <code>"Joe Doe"</code> into <code>"Doe, J."</code></p>
211
212 <p>Large example:</p>
213 <blockquote>
214 <p> To turn: </p>
215 <p><code>"Joe Doe and Mary Jane and Bruce Bar and Arthur Kay"</code></p>
216 <p>into</p>
217 <p><code>"Doe, J., Jane, M., Bar, B. and Kay, A."</code></p>
218 <p>you would use</p>
219 <p><code>1@*@{ll}, {f}.@@2@1@{ll}, {f}.@2@ and {ll}, {f}.@@*@1..-3@{ll}, {f}., @-2@{ll}, {f}.@-1@ and {ll}, {f}.</code></p>
220 </blockquote>
221 <p>If somebody would like to write a better tutorial about this: Write a mail to one of the JabRef mailinglists!</p>
222
223 <H3>Conditional output</H3>
224
225 Some static output might only make sense if a specific field is set. For instance, say we want to follow
226 the editor names with the text <code>(Ed.)</code>. This can be done with the following text:
227
228 <p><code>\format[HTMLChars,AuthorFirstFirst]{\editor} (Ed.)</code>
229
230 <p>However, if the <code>editor</code> field has not been set - it might not even make sense for the entry
231   being exported - the <code>(Ed.)</code> would be left hanging. This can be prevented by instead using the
232 <code>\begin</code> and <code>\end</code> commands:
233
234 <p><code>\begin{editor}<br>\format[HTMLChars,AuthorFirstFirst]{\editor} (Ed.)
235 <br>\end{editor}</code>
236
237 <p>The <code>\begin</code> and <code>\end</code> commands make sure the text in between is printed if and
238 only if the field referred in the curly braces is defined for the ently being exported.
239
240 <p><b>Note:</b> Use of the <code>\begin</code> and <code>\end</code> commands is a key to creating
241   layout files that work well with a variety of entry types.
242
243 <H3>Grouped output</H3>
244
245 If you wish to separate your entries into groups based on a certain field, use the grouped output commands.
246 Grouped output is very similar to conditional output, except that the text in between is printed only if the
247 field referred in the curly braces has changed value.
248
249 <p>For example, let's assume I wish to group by keyword.  Before exporting the file, make sure you have sorted
250 your entries based on keyword.  Now use the following commands to group by keyword:
251
252 <p><code>\begingroup{keywords}New Category: \format[HTMLChars]{\keywords}
253 <br>    \endgroup{keywords}</code>
254
255 <H2>Sharing your work</H2>
256
257 With external layout files, it's fairly simple to share custom export formats between users.
258 If you write an export filter for a format not supported by JabRef, or an improvement over an
259 existing one, we encourage you to post your work on our SourceForge.net page. The same goes for
260 formatter classes that you write. We'd be happy to distribute a collection of submitted
261 layout files, or to add to the selection of standard export filters and formatters.
262
263 </HTML>