Imported Upstream version 2.11~beta1+ds
[debian/jabref.git] / src / main / resources / help / in / 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>Penapis ekspor atursendiri</h1>
9
10     <p>Dalam JabRef, anda dapat mengatur sendiri
11     penapis ekspor sesuai dengan kehendak anda sendiri,
12     dengan cara seperti yang digunakan penapis standar lainnya.
13     Penapis ekspor didefinisikan dengan satu atau beberapa
14     <i>berkas tataletak</i>, yang dapat disiapkan dengan cara
15     merubah dari rutin pemformat sudah ada. Berkas tataletak 
16     anda perlu disiapkan dengan penyunting teks lain di luar JabRef.</p>
17
18     <h2>Menambah penapis ekspor atursendiri</h2>
19
20     <p>Berkas penapis ekspor yang sah harus mempunyai
21     ekstensi <b>.layout</b>. Untuk menambahkan penapis ekspor atursendiri
22     baru, <b>Pengaturan -&gt; Pengaturan ekspor atursendiri</b>,
23     kemudian klik <b>Tambah baru</b>. Kotak dialog pengaturan akan muncul.
24     Anda perlu menuliskan nama penapis ekspor (yang akan muncul
25     dalam pilihan ketika anda menggunakan menu <b>Berkas -&gt;
26     Ekspor</b>), lokasi berkas <b>.layout</b>, serta ekstensi berkas untuk
27     penapis ekspor (yang akan disarankan ketika anda menggunakan penapis
28     ekspor atursendiri yang anda buat).</p>
29
30     <h2>Membuat penapis ekspor</h2>
31
32     <p>Untuk melihat contoh bagaimana membuat penapis ekspor, anda perlu
33     mencari berkas tataletak <b>.layout</b> untuk penapis ekspor yang ada
34     di situs web muaturun kami.</p>
35
36     <h3>Berkas tataletak (.layout)</h3>
37
38     <p>Sebagai contoh kami menganggap sekarang kita membuat
39     penapis ekspor HTML.</p>
40
41     <p>Berkas penapis ekspor hanya mempunyai satu berkas utama
42     <b>.layout</b> saja, sehingga untuk contoh ini bisa diberi nama
43     <i>html.layout</i>. Disamping itu, anda bisa menambah dua berkas lagi
44     <i>html.begin.layout</i> dan <i>html.end.layout</i>. Berkas pertama
45     mengatur bagian awal dari keluaran, sedangkan berkas kedua
46     mengatur bagian akhir. JabRef akan mencari dua berkas ini setiap kali
47     penapis ekspor digunakan, dan jika ditemukan, akan menyalin persis
48     ke keluaran sebelum atau sesudah tiap entri dituliskan.</p>
49
50     <p>Catatan kedua berkas tambahan harus berada di direktori yang sama
51     dengan direktori dimana berkas <i>html.layout</i> berada, dan harus
52     mempunyai nama tambahan <b>.begin</b> dan <b>.end</b>.</p>
53
54     <p>Contoh berkas penapis tambahan tadi dapat berbentuk 
55     seperti berikut:</p>
56
57     <p><i>html.begin.layout</i>:<br />
58     <code>&lt;HTML&gt;<br />
59      &lt;BODY&gt; text="#275856"&gt;<br />
60     &lt;basefont size="4" color="#2F4958"
61     face="arial"&gt;</code></p>
62
63     <p><i>html.end.layout</i>:<br />
64     <code>&lt;/BODY&gt;<br />
65      &lt;/HTML&gt;</code></p>
66
67     <p>Berkas <i>html.layout</i> mengatur templet <i>bawaan</i>
68     untuk mengekspor satu entri. Apabila anda ingin menggunakan
69     beberapa templet untuk tipe entri yang berbeda, anda perlu
70     menambahkan berkas entri khusus <b>.layout</b>. Berkas tataletak ini 
71     harus berada di direktori yang sama dengan berkas tataletak utama,
72     serta diberi nama dengan menyisipkan <b>.entrytype</b> dalam
73     berkas tata letak utama. Nama tipe entri harus ditulis dengan 
74     huruf kecil semuanya. Pada contoh yang kami berikan, kami akan
75     menambahkan templet untuk entri buku, dan akan disimpan dalam 
76     berkas <i>html.book.layout</i>. Untuk PhD thesis, akan ditambahkan
77     dalam berkas <i>html.phdthesis.layout</i>, dll.
78     Berkas-berkas ini mirip dengan berkas tataletak bawaan, kecuali
79     hanya akan digunakan untuk entri yang mempunyai tipe sama.
80     Catatan, berkas bawaan dapat dengan mudah dibuat umum untuk
81     memenuhi semua tipe entri yang bisa digunakan di hampir semua
82     penapis ekspor.</p>
83
84     <h3>Format berkas tataletak</h3>
85
86     <p>Berkas tataletak dibuat menggunakan format markup sederhana
87     dimana perintah dikenali dengan awalan coret miring (\).
88     Teks lain yang tidak ada tanda perintah akan disalin secara
89     verbatim ke berkas keluaran.</p>
90
91     <h3>Perintah bidang</h3>
92
93     <p>Merupakan kata bebas yang dimulai dengan coret miring, misal
94     <code>\author</code>, <code>\editor</code>, <code>\title</code>
95     atau <code>\year</code>, akan diartikan sebagai acuan ke 
96     bidang terkait, yang disalin langsung ke berkas keluaran.</p>
97
98     <h3>Pemformat bidang</h3>
99
100     <p>Seringkali, ada perlunya melakukan pra proses isi bidang sebelum
101     keluaran. Hal ini dilakukan menggunakan <i>pemformat bidang</i> -
102     yaitu berupa kelas java yang mempunyai metoda tunggal untuk memipulasi
103     isi dari suatu bidang.</p>
104
105     <p>Pemformat digunakan dengan cara menyisipkan perintah <code>\format</code>
106     yang diikuti dengan nama pemformat dalam kurung kotak, dan
107     perintah bidang dalam kurung kurawal, misalnya:</p>
108
109     <p><code>\format[ToLowerCase]{\author}</code></p>
110
111     <p>Anda juga bisa menggunakan beberapa pemformat  yang dipisahkan dengan tanda
112     koma. Pemformat ini akan dipanggil berurutan, dari kiri ke kanan,
113     misalnya</p>
114
115     <p><code>\format[ToLowerCase,HTMLChars]{\author}</code></p>
116
117     <p>akan memanggil pemformat <b>ToLowerCase</b> terlebih dahulu,
118     kemudian <b>HTMLChars</b> untuk memformat hasil. 
119     Anda dapat menggunakan beberapa pemformat dengan cara ini.</p>
120
121     <p>Argumen untuk pemformat, dalam kurung kurawal,
122     tidak harus dalam bentuk perintah bidang. Anda dapat menyisipkan
123     teks normal, yang akan dibaca oleh pemformat
124     bukan sebagai isi dari bidang manapun. Hal ini sangat berguna untuk
125     bebrapa pemformat, misalnya pemformat CurrentDate (dijelaskan
126     dibawah).</p>
127
128     <p>Beberapa pemformat memerlukan argumen ekstra, memerlukan tanda kurung
129     setelah nama pemformat. Argumen boleh menggunakan tanda petik, yang diperlukan
130     jika menggunakan karakter kurung. Misalnya, <code>\format[Replace("\s,_")]{\journal}</code>
131     memanggil pemformat <b>Replace</b> dengan argumen <b>\s,_</b> (yang menghasilkan
132     bidang "journal" setelah mengganti semua spasi dengan garis bawah).
133     </p>
134
135     <p>Lihat dibawah ini daftar pemformat ekspor yang sudah dibuat.</p>
136
137     <h3>Keluaran kondisional</h3>
138
139     <p>Beberapa keluaran statik hanya mungkin dibuat
140     apabila ditentukan bidang spesifik. Sebagai contoh, kita ingin menulis
141     nama editor yang diikuti dengan teks <code>(Ed.)</code>. Hal ini bisa dilakukan
142     dengan cara berikut:</p>
143
144     <p><code>\format[HTMLChars,AuthorFirstFirst]{\editor}
145     (Ed.)</code></p>
146
147     <p>Namun demikian, jika bidang <code>editor</code> tidak ditentukan -
148     ketika dilakukan ekspor informasinya akan membingungkan - Kata
149     <code>(Ed.)</code> akan berada di sebelah kiri. Hal ini bisa dihindari
150     dengan menggunakan perintah <code>\begin</code> dan <code>\end</code>
151     :</p>
152
153     <p><code>\begin{editor}<br />
154     \format[HTMLChars,AuthorFirstFirst]{\editor} (Ed.)<br />
155      \end{editor}</code></p>
156
157     <p>Perintah <code>\begin</code> dan <code>\end</code> akan memastikan
158     teks yang berada diantaranya dicetak hanya jika bidang dalam tanda kurung kurawal 
159     didefinisikan untuk entri yang diekspor.</p>
160
161     <p>Blok kondisional bisa tergantung pada lebih dari satu bidang. Pada kasus ini
162     isi dalam blok hanya dicetak jika semua bindangnya didefinisikan terlebih dahulu.
163     Untuk membuat blok, caranya adalah dengan menulis bidang-bidang dengan pemisah titik koma.
164     Sebagai contoh, untuk menulis keluaran <code>year</code> dam <code>month</code>, gunakan
165     blok seperti dibawah ini:</p>
166
167     <p><code>\begin{year;month}Month: \format[HTMLChars]{\month}\end{year;month}</code></p>
168
169     <p>yang akan mencetak "Month: " ditambah denngan bidang <code>month</code>, jika
170     bidang <code>year</code> didefinisikan.</p>
171
172     <p><b>Catatan:</b> Perintah <code>\begin</code> dan
173     <code>\end</code> adalah perintah umum untuk membuat berkas tataletak
174     yang bisa digunakan untuk berbagai tipe entri.</p>
175
176     <h3>Keluaran grup</h3>
177
178     <p>If you wish to separate your entries
179     into groups based on a certain field, use the grouped output
180     commands. Grouped output is very similar to conditional output,
181     except that the text in between is printed only if the field
182     referred in the curly braces has changed value.</p>
183
184     <p>For example, let's assume I wish to group by keyword. Before
185     exporting the file, make sure you have sorted your entries
186     based on keyword. Now use the following commands to group by
187     keyword:</p>
188
189     <p><code>\begingroup{keywords}New Category:
190     \format[HTMLChars]{\keywords}<br />
191      \endgroup{keywords}</code></p>
192
193     <h2>Sharing your work</h2>
194
195     <p>With external layout files, it's
196     fairly simple to share custom export formats between users. If
197     you write an export filter for a format not supported by
198     JabRef, or an improvement over an existing one, we encourage
199     you to post your work on our SourceForge.net page. The same
200     goes for formatter classes that you write. We'd be happy to
201     distribute a collection of submitted layout files, or to add to
202     the selection of standard export filters and formatters.</p>
203
204     <p>Starting with JabRef 2.4 you can also package your 
205         ExportFormat or LayoutFormatter as a plug-in. If you do so,
206         you can provide a single zip-file to other user to make use
207         of your ExportFormat. For an example download the JabRef
208         source release and have a look at the directory
209         <code>src/resources/plugins/</code>. Don't hesitate to stop by the
210         forums on Sourceforge, since we don't have extensive documentation, yet.</p>
211
212
213     <h2>Built-in export formatters</h2>
214
215     <p>JabRef provides the following set of formatters:</p>
216
217     <ul>
218         <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>
219
220         <li><code>CreateDocBookAuthors</code> : formats the author
221         field in DocBook style.</li>
222
223         <li><code>CreateDocBookEditors</code> : to be
224         documented.</li>
225
226         <li><code>CurrentDate</code> : outputs the current date.
227         With no argument, this formatter outputs the current date
228         and time in the format "yyyy.MM.dd hh:mm:ss z" (date, time
229         and time zone). By giving a different format string as
230         argument, the date format can be customized. E.g.
231         <code>\format[CurrentDate]{yyyy.MM.dd}</code> will give the
232         date only, e.g. 2005.11.30.</li>
233
234         <li><code>Default</code> : takes a single argument, which serves as a default value.
235         If the string to format is non-empty, it is output without changes. If it is empty,
236         the default value is output. For instance, <code>\format[Default(unknown)]{\year}</code>
237         will output the entry's year if set, and "unknown" if no year is set.</li>
238         
239         <li><code>DOIStrip</code> : strips any prefixes from the DOI string.</li>
240         <li><code>DOICheck</code> : provides the full url for a DOI link.</li>
241
242         <li><code>FileLink(filetype)</code> : if no argument is given, this formatter outputs
243         the first external file link encoded in the field. To work, the formatter must
244         be supplied with the contents of the "file" field.
245         <p>This formatter takes the name of an external file type as an optional argument,
246         specified in parentheses after the formatter name. For instance,
247         <code>\format[FileLink(pdf)]{\file}</code> specifies <code>pdf</code> as an
248         argument. When an argument is given, the formatter selects the first file
249         link of the specified type. In the example, the path to the first PDF link will
250         be output.</p></li>
251
252         <li><code>FirstPage</code> : returns the first page from the "pages" field, if set.
253             For instance, if the pages field is set to "345-360" or "345--360",
254             this formatter will return "345".</li>
255
256         <li><code>FormatPagesForHTML</code> : replaces "--" with "-".</li>
257
258         <li><code>FormatPagesForXML</code> : replaces "--" with an XML en-dash.</li>
259
260         <li><code>GetOpenOfficeType</code> : returns the number used by the OpenOffice.org
261         bibliography system (versions 1.x and 2.x) to denote the type of this entry.</li>
262
263         <li><code>HTMLChars</code> : replaces TeX-specific special
264         characters (e.g. {\^a} or {\"{o}}) with their HTML
265         representations, and translates LaTeX commands \emph, \textit,
266         \textbf into HTML equivalents.</li>
267
268         <li><code>HTMLParagraphs</code> : interprets two
269         consecutive newlines (e.g. \n \n) as the beginning of a new
270         paragraph and creates paragraph-html-tags accordingly.</li>
271
272         <li><code>IfPlural</code> : outputs its first argument if the input field looks
273         like an author list with two or more names, or its second argument otherwise.
274         E.g. <code>\format[IfPlural(Eds.,Ed.)]{\editor}</code> will output "Eds." if there
275         is more than one editor, and "Ed." if there is only one.</li>
276
277         <li><code>LastPage</code> : returns the last page from the "pages" field, if set.
278             For instance, if the pages field is set to "345-360" or "345--360",
279             this formatter will return "360".</li>
280
281         <li><code>Number</code> : outputs the 1-based sequence number of the current entry in the
282         current export. This formatter can be used to make a numbered list of entries. The
283         sequence number depends on the current entry's place in the current sort order, not on
284         the number of calls to this formatter.</li>
285
286         <li><code>RemoveBrackets</code> : removes all curly brackets "{" or "}".</li>
287
288         <li><code>RemoveBracketsAddComma</code> : to be documented.</li>
289
290         <li><code>RemoveLatexCommands</code> : removes LaTeX
291         commands like <code>\em</code>, <code>\textbf</code>, etc.
292         If used together with <code>HTMLChars</code> or
293         <code>XMLChars</code>, this formatter should be called
294         last.</li>
295
296         <li><code>RemoveTilde</code> : replaces the tilde character
297         used in LaTeX as a non-breakable space by a regular space.
298         Useful in combination with the NameFormatter discussed in
299         the next section.</li>
300
301         <li><code>RemoveWhitespace</code> : removes all whitespace characters.</li>
302
303         <li><code>Replace(regexp,replacewith)</code> : does a regular expression replacement.
304         To use this formatter, a two-part argument must be given. The parts are
305         separated by a comma. To indicate the comma character, use an escape
306         sequence: \,<br/>&nbsp;<br/>
307         The first part is the regular expression to search for. Remember that any commma
308         character must be preceded by a backslash, and consequently a literal backslash must
309         be written as a pair of backslashes. A description of Java regular expressions can be
310         found at:<br/>
311         &nbsp;http://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html
312          <br/>&nbsp;<br/>
313         The second part is the text to replace all matches with.</li>
314
315         <li><code>RTFChars</code> : replaces TeX-specific special
316         characters (e.g. {\^a} or {\"{o}}) with their RTF
317         representations, and translates LaTeX commands \emph, \textit,
318         \textbf into RTF equivalents.</li>
319
320         <li><code>ToLowerCase</code> : turns all characters into
321         lower case.</li>
322
323         <li><code>ToUpperCase</code> : turns all characters into
324         upper case.</li>
325
326         <li><code>WrapContent</code> : This formatter outputs the input value after adding a
327         prefix and a postfix, as long as the input value is non-empty. If the input value
328         is empty, an empty string is output (the prefix and postfix are not output in this case).
329         The formatter requires an argument containing the prefix and postix separated
330         by a comma. To include the comma character in either, use an escape sequence
331         (\,).</li>
332
333         <li><code>WrapFileLinks</code> : See below.</li>
334
335         <li><code>XMLChars</code> : replaces TeX-specific special
336         characters (e.g. {\^a} or {\"{o}}) with their XML
337         representations.</li>
338
339     </ul>
340
341 <h3>The <code>Authors</code> formatter</h3>
342
343 <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>
344 <dl>
345 <dt><code>AuthorSort = [ {FirstFirst} | LastFirst | LastFirstFirstFirst ]</code></dt>
346 <dd>specifies the order in which the author names are formatted.
347         <ul>
348                 <li><code>FirstFirst</code> : first names are followed by the surname.</li>
349                 <li><code>LastFirst</code> : the authors' surnames are followed by their first names, separated by a comma.</li>                
350                 <li><code>LastFirstFirstFirst</code> : the first author is formatted as LastFirst, the subsequent authors as FirstFirst.</li>
351         </ul>
352 </dd>
353
354 <dt><code>AuthorAbbr = [ FullName | LastName | {Initials} | InitialsNoSpace | FirstInitial | MiddleInitial ]</code></dt>
355 <dd>specifies how the author names are abbreviated.
356         <ul>
357                 <li><code>FullName</code> : shows full author names; first names are not abbreviated.</li>
358                 <li><code>LastName</code> : show only surnames, first names are removed.</li> 
359                 <li><code>Initials</code> : all first names are abbreviated.</li> 
360                 <li><code>InitialsNospace</code> : as Initials, with any spaces between initials removed.</li>
361                 <li><code>FirstInitial</code> : only first initial is shown.</li> 
362                 <li><code>MiddleInitial</code> : first name is shown, but all middle names are abbreviated.</li>
363         </ul>   
364 </dd>
365
366 <dt><code>AuthorPunc = [ {FullPunc} | NoPunc | NoComma | NoPeriod ]</code></dt>
367 <dd>specifies the punctuation used in the author list when <code>AuthorAbbr</code> is used
368         <ul>
369                 <li><code>FullPunc</code> : no changes are made to punctuation.</li>
370                 <li><code>NoPunc</code> : all full stops and commas are removed from the author name.</li>
371                 <li><code>NoComma</code> : all commas are removed from the author name.</li>
372                 <li><code>NoPeriod</code> : all full stops are removed from the author name.</li>
373         </ul>   
374 </dd>
375
376 <dt><code>AuthorSep = [ {Comma} | And | Colon | Semicolon | Sep=&lt;string&gt; ]</code></dt>
377 <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> 
378
379 <dt><code>AuthorLastSep = [ Comma | {And} | Colon | Semicolon | Amp | Oxford | LastSep=&lt;string&gt; ]</code></dt>
380 <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>
381
382 <dt><code>AuthorNumber = [ {inf} | &lt;integer&gt; ]</code></dt>
383 <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, followed by <code>EtAlString</code>.</dd>
384
385 <dt><code>EtAlString = [ { et al.} | EtAl=&lt;string&gt; ]</code></dt>
386 <dd>specifies the string used to replace multiple authors. Any string can be given, using <code>EtAl=&lt;string&gt;</code></dd>
387
388 </dl>
389
390 <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>
391 <p><code>\format[Authors(Initials,Oxford)]{\author}</code></p>
392 <p>is equivalent to</p>
393 <p><code>\format[Authors(Oxford,Initials)]{\author}</code></p>
394 <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>
395
396 <h4>Examples</h4>
397 <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>
398 <dl>
399 <dt><code>Authors()</code>, or equivalently, <code>Authors(FirstFirst,Initials,FullPunc,Comma,And,inf,EtAl= et al.)</code></dt>
400 <dd><pre>J. J. Doe, M. Jane, B. Bar and A. Kay</pre></dd>
401
402 <dt><code>Authors(LastFirstFirstFirst,MiddleInitial,Semicolon)</code></dt>
403 <dd><pre>Doe, Joe J.; Mary Jane; Bruce Bar and Arthur Kay</pre></dd>
404
405 <dt><code>Authors(LastFirst,InitialsNoSpace,NoPunc,Oxford)</code></dt>
406 <dd><pre>Doe JJ, Jane M, Bar B, and Kay A</pre></dd>
407
408 <dt><code>Authors(2,EtAl= and others)</code></dt>
409 <dd><pre>J. J. Doe and others</pre></dd>
410 </dl>
411 <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>
412
413 <h3>The <code>WrapFileLinks</code> formatter</h3>
414
415 <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>
416 <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>
417 <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>
418 <p>The escape sequences for embedding information are as follows:</p>
419 <ul>
420         <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>
421         <li><code>\p</code> : This inserts the file path of the file link.</li>
422         <li><code>\f</code> : This inserts the name of the file link's type.</li>
423         <li><code>\x</code> : This inserts the file's extension, if any.</li>
424         <li><code>\d</code> : This inserts the file link's description, if any.</li>
425 </ul>
426 <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>
427 <p><code>\format[WrapFileLinks(\i. \d (\p))]{\file}</code></p>
428 <p>would give the following output:</p>
429 <pre>
430     1. John's final report (/home/john/report.pdf)
431
432 </pre>
433 <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>
434 <pre>
435     1. John's final report (/home/john/report.pdf)
436     2. An early "draft" (/home/john/draft.txt)
437
438 </pre>
439 <p>If the formatter was called with a second argument, the list would be filtered. For instance:</p>
440 <p><code>\format[WrapFileLinks(\i. \d (\p),,text file)]{\file}</code></p>
441 <p> would show only the text file:</p>
442 <pre>
443     1. An early "draft" (/home/john/draft.txt)
444
445 </pre>
446 <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>
447 <p><code>\format[WrapFileLinks(\i. \d (\p),,text file,",&amp;quot;)]{\file}</code></p>
448 <p>would give the following output:</p>
449 <pre>
450     1. An early &quot;draft&quot; (/home/john/draft.txt)
451
452 </pre>
453 <p>Additional pairs of replacements could be added.</p>
454
455
456     <h3>Custom formatters</h3>
457     <p>If none of the available formatters can do what you want to
458     achieve, you can add your own by implementing the
459     <code>net.sf.jabref.export.layout.LayoutFormatter</code>
460     interface. If you insert your class into the
461     <code>net.sf.jabref.export.layout.format</code> package, you
462     can call the formatter by its class name only, like with the
463     standard formatters. Otherwise, you must call the formatter by
464     its fully qualified name (including package name). In any case,
465     the formatter must be in your classpath when running
466     JabRef.</p>
467
468     <h2><a name="NameFormatter"
469        id="NameFormatter">Using Custom Name Formatters</a></h2>
470
471     <p>From JabRef 2.2, it is possible to define custom name
472     formatters using the bibtex-sty-file syntax. This allows
473     ultimate flexibility, but is a cumbersome to write</p>
474
475     <p>You can define your own formatter in the preference tab
476     "Name Formatter" using the following format and then use it
477     with the name given to it as any other formatter</p>
478     <code>&lt;case1&gt;@&lt;range11&gt;@&lt;format&gt;@&lt;range12&gt;@&lt;format&gt;@&lt;range13&gt;...@@<br />
479
480      &lt;case2&gt;@&lt;range21&gt;@... and so on.</code>
481
482     <p>This format first splits the task to format a list of author
483     into cases depending on how many authors there are (this is
484     since some formats differ depending on how many authors there
485     are). Each individual case is separated by @@ and contains
486     instructions on how to format each author in the case. These
487     instructions are separated by a @.</p>
488
489     <p>Cases are identified using integers (1, 2, 3, etc.) or the
490     character * (matches any number of authors) and will tell the
491     formatter to apply the following instructions if there are a
492     number of less or equal of authors given.</p>
493
494     <p>Ranges are either
495     <code>&lt;integer&gt;..&lt;integer&gt;</code>,
496     <code>&lt;integer&gt;</code> or the character <code>*</code>
497     using a 1 based index for indexing authors from the given list
498     of authors. Integer indexes can be negative to denote them to
499     start from the end of the list where -1 is the last author.</p>
500
501     <p>For instance with an authorlist of "Joe Doe and Mary Jane
502     and Bruce Bar and Arthur Kay":</p>
503
504     <ul>
505         <li>1..3 will affect Joe, Mary and Bruce</li>
506
507         <li>4..4 will affect Arthur</li>
508
509         <li>* will affect all of them</li>
510
511         <li>2..-1 will affect Mary, Bruce and Arthur</li>
512     </ul>
513
514     <p>The <code>&lt;format&gt;</code>-strings use the Bibtex
515     formatter format:</p>
516
517     <p>The four letters v, f, l, j indicate the name parts von,
518     first, last, jr which are used within curly braces. A single
519     letter v, f, l, j indicates that the name should be
520     abbreviated. If one of these letters or letter pairs is
521     encountered JabRef will output all the respective names
522     (possibly abbreviated), but the whole expression in curly
523     braces is only printed if the name part exists.</p>
524
525     <p>For instance if the format is "{ll} {vv {von Part}} {ff}"
526     and the names are "Mary Kay and John von Neumann", then JabRef
527     will output "Kay Mary" (with two space between last and first)
528     and "Neuman von von Part John".</p>
529
530     <p>I give two examples but would rather point you to the bibtex
531     documentation.</p>
532
533     <p>Small example: <code>"{ll}, {f.}"</code> will turn
534     <code>"Joe Doe"</code> into <code>"Doe, J."</code></p>
535
536     <p>Large example:</p>
537
538     <blockquote>
539         <p>To turn:</p>
540
541         <p><code>"Joe Doe and Mary Jane and Bruce Bar and Arthur
542         Kay"</code></p>
543
544         <p>into</p>
545
546         <p><code>"Doe, J., Jane, M., Bar, B. and Kay,
547         A."</code></p>
548
549         <p>you would use</p>
550
551         <p><code>1@*@{ll}, {f}.@@2@1@{ll}, {f}.@2@ and {ll},
552         {f}.@@*@1..-3@{ll}, {f}., @-2@{ll}, {f}.@-1@ and {ll},
553         {f}.</code></p>
554     </blockquote>
555
556     <p>If somebody would like to write a better tutorial about
557     this: Write a mail to one of the JabRef mailinglists!</p>
558
559
560 </body>
561 </html>