[svn-upgrade] Integrating new upstream version, jabref (2.3.1)
[debian/jabref.git] / src / help / GroupsHelp.html
1 <html xmlns="http://www.w3.org/1999/xhtml">
2
3 <body text="#275856">
4     <basefont size="4"
5           color="#2F4958"
6           face="arial">
7
8     <h1>Groups</h1>
9
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>
13
14     <ul>
15         <li>While a file is always located in exactly one
16         directory, an entry may be contained in more than one
17         group.</li>
18
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.
29
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>
34
35     <h2>Interface</h2>
36
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>
43
44     <table cellspacing="0"
45            cellpadding="5"
46            border="0"
47            bgcolor="#C0FFC0">
48         <tr>
49             <td>
50                 <h2>Some quick examples</h2>
51
52                 <p>You might want to...</p>
53
54                 <h3>...just create a group and assign some entries
55                 to it</h3>
56
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
65                 assigned).</p>
66
67                 <h3>...use the <tt>keywords</tt> field to group the
68                 entries</h3>
69
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
78                 specified).</p>
79
80                 <h3>...use a free-form search expression to define
81                 a group</h3>
82
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
93                 specified).</p>
94
95                 <h3>...combine multiple groups</h3>
96
97                 <p>Create two
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>
107
108                 <h3>...identify overlapping groups</h3>
109
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>
118             </td>
119         </tr>
120     </table>
121
122     <h2>Types of groups</h2>
123
124     <p>In JabRef there are four different types of groups:</p>
125
126     <ol>
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>
130
131         <li><b>Static groups</b> behave like directories on disk
132         and contain only those entries that you explicitly assign
133         to them.</li>
134
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>
143
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.
158
159     <h2>Groups structure, creating and removing groups</h2>
160
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>
172
173     <p>Undo and redo is supported for all edits.</p>
174
175     <h3>Static groups</h3>
176
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>
184
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>
189
190     <h3>Dynamic groups</h3>
191
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>
197
198     <p>Two types of conditions can be used:</p>
199
200     <dl>
201         <dt><b>Searching a field for a keyword</b></dt>
202
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>
218
219         <dt><b>Using a free-form search expression</b></dt>
220
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 -&gt; Preferences -&gt; Groups, box "Show
233     dynamic groups in italics").
234
235     <h3>Hierarchical context</h3>
236
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>
252
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>
258
259     <h2>Viewing a group's entries, combining multiple
260     groups</h2>
261
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
267     search.</p>
268
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>
277
278     <h2>Groups and searching</h2>
279
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>
283
284     <h2>Highlighting overlapping groups</h2>
285
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>
296
297     <h2>Advanced features</h2>
298
299     <p>After mastering the grouping concepts
300     described above, the following advanced features might come in
301     handy.</p>
302
303     <h3>Automatically creating dynamic groups</h3>
304
305     <p>By clicking the
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
313     at no cost.</p>
314
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
322     automatically.)</p>
323
324     <h3>Refreshing the groups view</h3>
325
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>
331
332     <h3>Mixing refining groups with including groups</h3>
333
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>
337 </body>
338 </html>