Imported Upstream version 2.10+ds
[debian/jabref.git] / src / help / LabelPatterns.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>Customizing the BibTeX key generator</h1>
9
10     <p>In the &lsquo;Key pattern&rsquo; tab in Preferences, one can set the fields
11     used in auto generation of BibTex labels. The pattern can be
12     set for each of the standard entry types.</p>
13
14     <h2>Key patterns</h2>
15
16     <p>The pattern can contain any text you wish,
17     in addition to field markers that indicate that a specific
18     field of the entry should be inserted at that position of the
19     key. A field marker generally consists of the field name
20     enclosed in square braces, e.g. <b>[volume]</b>. If the field
21     is undefined in an entry at the time of key generation, no text
22     will be inserted by the field marker.</p>
23
24     <p>Several special field markers are offered, which extract
25     only a specific part of a field. These are listed below. Feel
26     free to suggest new special field markers.</p>
27
28     <p>Special field markers:</p>
29
30     <ul>
31         <li><b>[<code>auth</code>]</b>: The last name of the first
32         author<br /></li>
33
34         <li><b>[<code>authors</code>]</b>: The last name of all
35         authors<br /></li>
36
37         <li><b>[<code>authorLast</code>]</b>: The last name of the last
38         author<br /></li>
39
40         <li><b>[<code>authorsN</code>]</b>: The last name of up to
41         N authors. If there are more authors, &ldquo;EtAl&rdquo; is
42         appended.<br /></li>
43         
44         <li><b>[<code>authorsAlpha</code>]</b>: Corresponds to the BibTeX
45         style &ldquo;alpha&rdquo;. One author: First three letters of the last name.
46         Two to four authors: First letters of last names concatenated.
47         More than four authors: First letters of last names of first three
48         authors concatenated. &ldquo;+&rdquo; at the end. <br /></li>
49
50         <li><b>[<code>authIniN</code>]</b>: The beginning of each
51         author's last name, using no more than N
52         characters.<br /></li>
53
54         <li><b>[<code>authorIni</code>]</b>: The first 5 characters
55         of the first author's last name, and the last name initials
56         of the remaining authors.<br /></li>
57
58         <li><b>[<code>authN</code>]</b>: The first N characters of
59         the first author's last name<br /></li>
60
61         <li><b>[<code>authN_M</code>]</b>: The first N characters
62         of the Mth author's last name<br /></li>
63
64         <li><b>[<code>auth.auth.ea</code>]</b>: The last name of
65         the first two authors, and &ldquo;.ea&rdquo; if there are more than
66         two.<br /></li>
67
68         <li><b>[<code>auth.etal</code>]</b>: The last name of the
69         first author, and the last name of the second author if
70         there are two authors or &ldquo;.etal&rdquo; if there are more than
71         two.<br /></li>
72
73         <li><b>[<code>authEtAl</code>]</b>: The last name of the
74         first author, and the last name of the second author if
75         there are two authors or &ldquo;EtAl&rdquo; if there are more than
76         two. This is similar to <code>auth.etal</code>. The
77         difference is  that the authors are not separated by &ldquo;.&rdquo;
78         and in case of more than 2 authors &ldquo;EtAl&rdquo; instead of &ldquo;.etal&rdquo;
79         is appended.<br /></li>
80
81         <li><b>[<code>authshort</code>]</b>: The last name if one
82         author is given; the first character of up to three
83         authors' last names if more than one author is given. A
84         plus character is added, if there are more than three
85         authors.<br /></li>
86
87         <li><b>[<code>authForeIni</code>]</b>: The forename initial 
88         of the first author.<br /></li>
89
90         <li><b>[<code>authorLastForeIni</code>]</b>: The forename initial 
91         of the last author.<br /></li>
92
93     </ul><b>Note:</b> If there is no author (as in the case of an
94     edited book), then all of the above
95     <b><code>[auth...]</code></b> markers will use the editor(s)
96     (if any) as a fallback. Thus, the editor(s) of a book with no
97     author will be treated as the author(s) for label-generation
98     purposes. If you do not want this behaviour, i.e. you require a
99     marker which expands to nothing if there is no author, use
100     <b><code>pureauth</code></b> instead of
101     <b><code>auth</code></b> in the above codes. For example,
102     <b><code>[pureauth]</code></b>, or
103     <b><code>[pureauthors3]</code></b>.
104
105     <ul>
106         <li><b>[<code>edtr</code>]</b>: The last name of the first
107         editor<br /></li>
108
109         <li><b>[<code>edtrIniN</code>]</b>: The beginning of each
110         editor's last name, using no more than N
111         characters<br /></li>
112
113         <li><b>[<code>editors</code>]</b>: The last name of all
114         editors<br /></li>
115
116         <li><b>[<code>editorLast</code>]</b>: The last name of the last
117         editor<br /></li>
118
119         <li><b>[<code>editorIni</code>]</b>: The first 5 characters
120         of the first editor's last name, and the last name initials
121         of the remaining editors.<br /></li>
122
123         <li><b>[<code>edtrN</code>]</b>: The first N characters of
124         the first editor's last name<br /></li>
125
126         <li><b>[<code>edtrN_M</code>]</b>: The first N characters
127         of the Mth editor's last name<br /></li>
128
129         <li><b>[<code>edtr.edtr.ea</code>]</b>: The last name of
130         the first two editors, and &ldquo;.ea&rdquo; if there are more than
131         two.<br /></li>
132
133         <li><b>[<code>edtrshort</code>]</b>: The last name if one
134         editor is given; the first character of up to three
135         editors' last names if more than one editor is given. A
136         plus character is added, if there are more than three
137         editors.<br /></li>
138
139         <li><b>[<code>edtrForeIni</code>]</b>: The forename initial 
140         of the first editor.<br /></li>
141
142         <li><b>[<code>editorLastForeIni</code>]</b>: The forename initial 
143         of the last editor.<br /></li>
144
145         <li><b>[<code>firstpage</code>]</b>: The number of the
146         first page of the publication (Caution: this will return 
147         the lowest number found in the pages field, since bibtex 
148         allows <code>7,41,73--97</code> or <code>43+</code>.)<br /></li>
149
150         <li><b>[<code>keywordN</code>]</b>: Keyword number N from
151         the &ldquo;keywords&rdquo; field, assuming keywords are separated by
152         commas or semicolons.<br /></li>
153
154         <li><b>[<code>lastpage</code>]</b>: The number of the last
155         page of the publication (See the remark on 
156         <code>firstpage</code>)<br /></li>
157
158         <li><b>[<code>shorttitle</code>]</b>: The first 3 words of
159         the title<br /></li>
160
161         <li><b>[<code>shortyear</code>]</b>: The last 2 digits of
162         the publication year<br /></li>
163
164         <li><b>[<code>veryshorttitle</code>]</b>: The first word of
165         the title, discounting &lsquo;the&rsquo;, &lsquo;a&rsquo;, &lsquo;an&rsquo;.<br /></li>
166     </ul>
167
168     <p>A field name (or one of the above pseudo-field names) may
169     optionally be followed by one or more modifiers. Modifiers are
170     applied in the order they are specified.</p>
171
172     <ul>
173         <li><b>:abbr</b>: Abbreviates the text produced by the
174         field name or spcial field marker. Only the first character
175         and subsequent characters following white space will be
176         included. For example, <b>[journal:abbr]</b> would from the
177         journal name &ldquo;Journal of Fish Biology&rdquo; produce
178         &ldquo;JoFB&rdquo;.<br /></li>
179
180         <li><b>:lower</b>: Forces the text inserted by the field
181         marker to be in lowercase. For example, <b>[auth:lower]</b>
182         expands the last name of the first author in
183         lowercase.<br /></li>
184
185         <li><b>:upper</b>: Forces the text inserted by the field
186         marker to be in uppercase. For example, <b>[auth:upper]</b>
187         expands the last name of the first author in
188         uppercase.<br /></li>
189
190         <li><b>:(x)</b>: Replace x by any string. The string between
191         the parentheses will be inserted if the field marker preceding this
192         modifier resolves to an empty value. For instance, the marker
193         <b>[volume:(unknown)]</b> will return the entry's volume if set, and the
194         string <b>unknown</b> if the entry's <code>volume</code> field is not set.
195         </li>
196     </ul>
197
198     <p>If you haven't defined a key pattern for a certain entry
199     type, the <b>Default key pattern</b> will be used. You can
200     change the default pattern - its setting is above the list of
201     entry types in the <b>Key pattern</b> section of the
202     <b>Preferences</b> dialog.</p>
203
204     <p>The default key pattern is [auth][year], and this could
205     produce keys like e.g. <code>Yared1998</code> If the key is not
206     unique in the current database, it is made unique by adding one
207     of the letters a-z until a unique key is found. Thus, the
208     labels might look like:</p>
209
210     <p style="margin-left: 28pt">
211         <code>Yared1998</code><br />
212         <code>Yared1998a</code><br />
213         <code>Yared1998b</code>
214     </p>
215
216     <h2>Regular expression replace</h2>
217
218     <p>After the key pattern has
219     been applied to produce a key, you can choose to have the key
220     generator search for occurrences of a specific regular
221     expression, and replace it with a string. The regular
222     expression and replacement string are entered in the text
223     fields below the list of key patterns. If the replacement
224     string is empty, matches of the regular expression will simply
225     be removed from the generated key. For instance,
226     <code>\p{Punct}</code> or <code>[:/%]</code> can be replaced
227     by nothing to remove unwanted characters from the key.
228     This may be useful when naming PDFs according to BibTeX keys.</p>
229 </body>
230 </html>