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