1 <html xmlns="http://www.w3.org/1999/xhtml">
10 <p>Groups allow to structure a BibTeX database in a
11 tree-like way that is similar to organizing files on disk in
12 directories and subdirectories. The two main differences are:</p>
15 <li>While a file is always located in exactly one
16 directory, an entry may be contained in more than one
19 <li>Groups may use certain criteria to dynamically define
20 their content. New entries that match these criteria are
21 automatically contained in these groups. This feature is
22 not available in common file systems, but in several Email
23 clients (e.g. Thunderbird and Opera).</li>
24 </ul>Selecting a group shows the entries contained in that
25 group. Selecting multiple groups shows the entries contained in
26 any group (union) or those contained in all groups
27 (intersection), depending on the current settings. All this is
28 explained in detail below.
30 <p>Group definitions are database-specific; they are saved as a
31 <tt>@COMMENT</tt> block in the <tt>.bib</tt>-file and are
32 shared among all users. (Future versions of JabRef might
33 support user-dependent groups.)</p>
37 <p>The groups interface is shown in the side
38 pane on the left of the screen. It can be toggled on or off by
39 pressing <tt>CTRL-SHIFT-G</tt> or by the groups button in the
40 toolbar. The interface has several buttons, but most functions
41 are accessed via a context ("right-click") menu. Drag and Drop
42 is also supported.</p>
44 <table cellspacing="0"
50 <h2>Some quick examples</h2>
52 <p>You might want to...</p>
54 <h3>...just create a group and assign some entries
57 <p>Ensure that the groups interface is
58 visible. Press the <b>New Group</b> button, enter a
59 name for the group, then press OK, leaving all
60 values at their defaults. Now select the entries to
61 be assigned to the group and use Drag and Drop to
62 the group, or the option <b>Add to group</b> in the
63 context menu. Finally select the group to see its
64 content (which should be the entries you just
67 <h3>...use the <tt>keywords</tt> field to group the
70 <p>Ensure that the groups interface is
71 visible. Press the <b>New Group</b> button, enter a
72 name for the group, and select the option to
73 dynamically group entries by searching a field for
74 a keyword. Enter the keyword to search for, then
75 click OK. Finally select the group to see its
76 content (which should be all entries whose
77 <tt>keywords</tt> field contains the keyword you
80 <h3>...use a free-form search expression to define
83 <p>Ensure that the groups interface is
84 visible. Press the <b>New Group</b> button, enter a
85 name for the group, and select the option to
86 dynamically group entries by a free-form search
87 expression. Enter <tt>author=smith</tt> as a search
88 expression (replace <tt>smith</tt> with a name that
89 actually occurs in your database) and click
90 <b>OK</b>. Finally select the group to see its
91 content (which should be all entries whose
92 <tt>author</tt> field contains the name you
95 <h3>...combine multiple groups</h3>
98 different groups (e.g. as described above). Click
99 the <b>Settings</b> button and make sure that
100 <b>Union</b> is selected. Now select both groups.
101 You should see all entries contained in any of the
102 two groups. Click <b>Settings</b> again and select
103 <b>Intersection</b>. Now you should see only those
104 entries contained in both groups (which might be
105 none at all, or exactly the same entries as before
106 in case both groups contain the same entries).</p>
108 <h3>...identify overlapping groups</h3>
110 <p>JabRef allows you to easily identify groups that overlap
111 with the currently selected groups (i.e. that
112 contain at least one entry that is also contained
113 in the currently selected groups). Click
114 <b>Settings</b> and activate the option to
115 highlight overlapping groups. Then select a group
116 that overlaps with other groups. The other groups
117 should be highlighted.</p>
122 <h2>Types of groups</h2>
124 <p>In JabRef there are four different types of groups:</p>
127 <li>The group <b>All Entries</b>, which -- as the name
128 suggests -- contains all entries, is always present and
129 cannot be edited or removed.</li>
131 <li><b>Static groups</b> behave like directories on disk
132 and contain only those entries that you explicitly assign
135 <li><b>Dynamic groups based on keyword search</b> contain
136 entries in which a certain BibTeX field (e.g.
137 <tt>keywords</tt>) contains a certain keyword (e.g.
138 <tt>electrical</tt>). This method does not require manual
139 assignment of entries, but uses information that is already
140 present in the database. If all entries in your database
141 have suitable keywords in their <tt>keywords</tt> field,
142 using this type of group might be the best choice.</li>
144 <li><b>Dynamic groups based on free-form search
145 expressions</b> contain entries that match a specified
146 search expression, using the same syntax as the
147 <a href="SearchHelp.html">search panel</a> on the side
148 pane. This <a href="SearchHelp.html#advanced">syntax</a>
149 supports logical operators (<tt>AND</tt>, <tt>OR</tt>,
150 <tt>NOT</tt>) and allows to specify one or more BibTeX
151 fields to search, facilitating more flexible group
152 definitions than a keyword search (e.g. <tt>author=smith
153 and title=electrical</tt>).</li>
154 </ol>Every group that you create is of one of the last three
155 types. The group editing dialog, which is invoked by
156 double-clicking on a group, shows a short description of the
157 selected/edited group in plain English.
159 <h2>Groups structure, creating and removing groups</h2>
161 <p>Just like directories, groups are structured like a tree, with the
162 group <b>All Entries</b> at the root. By right-clicking on a
163 group you can add a new group to the tree, either at the same
164 level as the selected group or as a subgroup of it. The <b>New
165 Group</b> button lets you create a new subgroup of the group
166 <b>All Entries</b>, regardless of the currently selected
167 group(s). The context menu also allows to remove groups and/or
168 subgroups, to sort subgroups alphabetically, or to move groups
169 to a different location in the tree. The latter can also be
170 done by Drag and Drop, with the restriction that Drag and Drop
171 does not support changing the order of a group's subgroups.</p>
173 <p>Undo and redo is supported for all edits.</p>
175 <h3>Static groups</h3>
177 <p>Static groups are populated only by
178 explicit manual assignment of entries. After creating a static
179 group you select the entries to be assigned to it, and use
180 either Drag and Drop or the main table's context menu to
181 perform the assignment. To remove entries from a static group,
182 select them and use the main table's context menu. There are no
183 options to be configured.</p>
185 <p>This method of grouping requires that all entries have a
186 unique BibTeX key. In case of missing or duplicate BibTeX keys,
187 the assignment of the affected entries cannot be correctly
188 restored in future sessions.</p>
190 <h3>Dynamic groups</h3>
192 <p>The content of a dynamic group is
193 defined by a logical condition. Only entries that meet this
194 condition are contained in the group. This method uses the
195 information stored in the database itself, and updates
196 dynamically whenever the database changes.</p>
198 <p>Two types of conditions can be used:</p>
201 <dt><b>Searching a field for a keyword</b></dt>
203 <dd>This method groups entries in which a specified BibTeX
204 field (e.g. <tt>keywords</tt>) contains a specified search
205 term (e.g. <tt>electrical</tt>). Obviously, for this to
206 work, the grouping field must be present in every entry,
207 and its content must be accurate. The above example would
208 group all entries referring to something electrical. Using
209 the field <tt>author</tt> allows to group entries by a
210 certain author, etc. The search can either be done as a
211 plain-text or a regular expression search. In the former
212 case, JabRef allows to manually assign/remove entries
213 to/from the group by simply appending/removing the search
214 term to/from the content of the grouping field. This makes
215 sense only for the <tt>keywords</tt> field or for
216 self-defined fields, but obviously not for fields like
217 <tt>author</tt> or <tt>year</tt>.</dd>
219 <dt><b>Using a free-form search expression</b></dt>
221 <dd>This is similar to the above, but rather than search a
222 single field for a single search term, the
223 <a href="SearchHelp.html#advanced">search expression
224 syntax</a> can be used, which supports logical operators
225 (<tt>AND</tt>, <tt>OR</tt>, <tt>NOT</tt>) and allows to
226 search multiple BibTeX fields. For example, the search
227 expression <tt>keywords=regression and not
228 keywords=linear</tt> groups entries concerned with
229 non-linear regression.</dd>
230 </dl>In the groups view, dynamic groups are shown in
231 <i>italics</i> by default. This can be turned off in the
232 preferences (Options -> Preferences -> Groups, box "Show
233 dynamic groups in italics").
235 <h3>Hierarchical context</h3>
237 <p>By default, a group is
238 <b>independent</b> of its position in the groups tree: When
239 selected, only the group's contents are shown. However,
240 especially when using dynamic groups, it is often useful to
241 define a subgroup that <b>refines its supergroup</b>, i.e.,
242 when selected, entries contained in both groups are displayed.
243 For example, create a supergroup containing entries with the
244 keyword <tt>distribution</tt> and a subgroup containing entries
245 with the keyword <tt>gauss</tt> that refines this supergroup.
246 Selecting the subgroup now displays entries that match both
247 conditions, i.e. are concerned with Gaussian distributions. By
248 adding another refining subgroup for <tt>laplace</tt> to the
249 original supergroup, the grouping can easily be extended. In
250 the groups tree, refining groups have a special icon (this can
251 be turned off in the preferences).</p>
253 <p>The logical complement to a refining group is a group that
254 <b>includes its subgroups</b>, i.e. when selected, not only the
255 group's own entries, but also its subgroups' entries are shown.
256 In the groups tree, this type of group has a special icon (this
257 can be turned off in the preferences).</p>
259 <h2>Viewing a group's entries, combining multiple
262 <p>Selecting a group shows the entries contained in
263 that group by highlighting them and, depending on the settings
264 (accessible by clicking the <b>Settings</b> button), moving
265 them to the top of the list and/or selecting them. These
266 options are identical to those available for the regular
269 <p>When multiple groups are selected, either the union or the
270 intersection of their content is shown, depending on the
271 current settings. This allows to quickly combine multiple
272 conditions, e.g. if you have a static group <tt>Extremely
273 Important</tt> to which you assign all extremely important
274 entries, you can view the extremely important entries in any
275 other group by selecting both groups (this requires to have
276 <b>Intersection</b> selected in the settings).</p>
278 <h2>Groups and searching</h2>
280 <p>When viewing the contents of the
281 selected group(s), a search can be performed within these
282 contents using the regular search facility.</p>
284 <h2>Highlighting overlapping groups</h2>
286 <p>The <b>Settings</b>
287 button offers an option to highlight overlapping groups. If
288 this is activated, upon selection of one or more groups, all
289 groups that contain at least one of the entries contained in
290 the currently selected group(s) are highlighted. This quickly
291 identifies overlap between the groups' contents. You might, for
292 example, create a group <tt>To Read</tt> that contains all
293 entries which you plan to read. Now, whenever you select any
294 group, the group <tt>To Read</tt> is highlighted if the
295 selected group contains entries that you plan to read.</p>
297 <h2>Advanced features</h2>
299 <p>After mastering the grouping concepts
300 described above, the following advanced features might come in
303 <h3>Automatically creating dynamic groups</h3>
306 <b>Automatically create groups for database</b> button, you can
307 quickly create a set of groups appropriate for your database.
308 This feature will gather all words found in a specific field of
309 your choice, and create a group for each word. This is useful
310 for instance if your database contains suitable keywords for
311 all entries. By autogenerating groups based on the
312 <tt>keywords</tt> field, you should have a basic set of groups
315 <p>You can also specify characters to ignore, for instance
316 commas used between keywords. These will be treated as
317 separators between words, and not part of them. This step is
318 important for combined keywords such as <tt>laplace
319 distribution</tt> to be recognized as a single semantic unit.
320 (You cannot use this option to remove complete words. Instead,
321 delete the unwanted groups manually after they were created
324 <h3>Refreshing the groups view</h3>
326 <p>The <b>Refresh</b> button
327 updates the entry table to reflect the current groups
328 selection. This is usually done automatically, but in rare
329 occasions (e.g. after a group-related undo/redo) a manual
330 refresh is required.</p>
332 <h3>Mixing refining groups with including groups</h3>
334 <p>If a refining group is a subgroup of a group that includes its
335 subgroups -- the refining group's siblings --, these siblings
336 are ignored when the refining group is selected.</p>