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