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>