describing tagging, including things that aren't true yet

doc/tagging.rst

@@ -1,15 +1,54 @@
 Tagging
 -------
 
-Tagging is an easy way to give context to an object or create a
-collection of object that you want to recall later. For example if you
-want to collect a bunch of plants that you later want to create a
-report from you can tag them with the string "for that report i was
-thinking about". You can then select "for that report i was thinking
-about" from the tags menu to show you all the objects you tagged.
-
-Tagging can be done two ways. By selecting one or more items in the
-search results and pressing Ctrl-T or by selecting
-:menuselection:`Tag-->Tag Selection` from the menu. If you have
-selected multiple items then only that tags that are common to all the
-selected items will have a check next to it.
+Tagging is an easy way to give context to an object or create a collection
+of object that you want to recall later.
+
+The power in this tagging action is that you can share this selection with
+colleagues, who can act on it, without the need to redo all your collecting
+work.
+
+For example if you need to print accession labels of otherwise unrelated
+plants, you can group the objects by tagging them with the string
+"relabel". You or one of your colleagues can then select "relabel" from the
+tags menu, the search view will show all the objects you tagged, and
+performing a report will act on the tagged objects.
+
+Tagging acts on the active selection, that is the items in the search
+results which you have selected.
+
+Please remember: you can select all result rows by pressing Ctrl-A, you can
+deselect everything by pressing Ctrl-Shift-A, you can toggle tagging of a
+single row by Ctrl-Mouse clicking on it.
+
+Once you have an active selection, tagging can be done in two ways:
+
+dialog box tagging
+~~~~~~~~~~~~~~~~~~~
+
+Press Ctrl-T or select :menuselection:`Tag-->Tag Selection` from the menu,
+this activates a window where you can create new tags and apply any existing
+tag to the selection.
+
+The tag window is composed of three parts: the upper part mentions the list
+of objects in your active selection. This is the list of object of which you
+are editing the tags; the middle part has a list of all available tags, with
+a checkbox that you can activate for applying the tag to or removing the tag
+from the selection; the lower part only holds a link to new tag creation,
+and the Ok button for closing the dialog box.
+
+If the active selection held multiple items when opening the tag dialog box,
+then only that tags that are common to all the selected items will have a
+check next to it.  Tags that only apply to a proper subset of the active
+selection will show with an 'undecided' status.  Tags that don't apply to
+any object in the active selection will show blank.
+
+The most recently created tag, or the most recently selected tag becomes the
+active tag, and it shows with a check next to it in the tags menu.
+
+windowless tagging
+~~~~~~~~~~~~~~~~~~~
+
+Once you have an active tag, pressing Ctrl-Y applies the active tag to all
+objects in the active selection.  Ctrl-Shift-Y removes the active tag from
+all objects in the active selection.