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