In order to create an Annotation, you need to be a registered user. Once registered, you can create Annotations anywhere you like, but by default these Annotations are only visible to you. To change this, you need to understand the group-authentication method that controls the visibility of all Annotations in PBOS (see below). The contents of the Annotations themselves, however, are only changeable by their creator.
Each Annotation that a user creates can be (and must be) placed into one or more groups. Each user has at the very least a "Private" and a "Public" group that they can put Annotations into. New groups may be created to allow any level of categorization that is desired, and these groups may be kept private, shared with selected individuals, or shared with everyone. Also, each book has a special book-group that holds Annotations that the book's author deemed to be worthy of being visible by default (even to unregistered users). Any Annotations that you have made potentially visible by everyone may be promoted by the book author to be visible by default.
An Annotation group holds a list of user-names and the permissions that each user has to see or change the group. The permissions are as follows:
When reading the book, a user can turn the visibility of Annotations on and off in the margin by manipulating the visibility of the Annotation groups for which they have "View" permissions. By default all book-group Annotations are visible to everyone unless hidden. Personal Annotations are visible by default to the user that created them unless hidden. Other Annotations may be optionally made visible as long as the user has "View" permissions.
To allow you to make your Annotations available for everyone to potentially view, there is a special user-name of "Everyone" that may be added to a group with view permissions (no other permissions are honored for this user).
The two groups that each user starts with, "Private" and "Public", are provided with View and Add/Remove permissions (but not Cull or Admin). This ensures that these groups will always exist and that they will always be locked into categorizing Annotations as private (current user only) or public (all users), respectively.
If one or more Annotations ever lose their last associated group (typically when a group is deleted), the associated Annotation(s) will also be deleted (there will be a warning confirmation should this occur).
Every group must have at least one Admin-permissions user associated with it (with the exception of each user's Private & Public groups, which have no Admin). If you attempt to remove the final Admin user from a group, your request will fail.
A process that creates multiple Annotations at once (such as the search function) defaults to creating the Annotations in a new personal group. This makes it easy to deal with them as a cluster (such as removing them all by deleting the group, or categorizing them en masse).
The full name for a group is USER/NAME, where USER is the user-name of the person who created the group, NAME is a unique (for the user) group- name, and the "/" is a literal slash (user-names and group-names cannot contain slashes). If the "USER" part of the name is omitted, the NAME is assumed to belong to the current user. For instance, user Foo's two default groups are really named Foo/Private and Foo/Public, but Foo will see them referenced as just "/Private" and "/Public". Other users will be able to see the group "Foo/Public" (if it has any Annotations in it) on the page where they can choose to make view-authorized groups visible.
Note that a book-group (which is automatically created when a new book is created) has the following differences from a manually created group: (1) the Annotations associated with a book-group must all refer to a single book, (2) Annotations default to being visible to others, not invisible (3) the group's admin permission does not allow you to delete the group (since book-groups may not be deleted without deleting the book), (4) if an Annotation that is in a book-group is edited (by someone in its list of editors, of course) AND the editor is not listed in the book-group's "add" permissions, the Annotation will be removed from the book-group (and perhaps deleted, but only if it is a member of no other group). This prevents someone from changing a good Annotation into a bad Annotation after it has been elevated to book-group status.
Any Annotation that is in a group that makes it potentially visible by "Everyone" may get upgraded by the Book's author to being a member of the book's always-visible Annotations. When this happens, the annotation will be visible to all by default (rather than needing to be made visible by each registered reader). However, if the Annotation's creator edits it, it will drop off the list of book-default Annotations (though the book's author might review it again and restore it to its public state).
Here are some common activities and how you would use groups to accomplish them:
Temporary Annotations: If you wish some Annotations to exist for only a brief time, create them in a new group (such as "tmp"). Then, when you're finished with them, delete that group.
Shared Annotations: If you wish to share some Annotations with a select group of friend(s), create a new group (such as "friends") and add one or more user-names to the list of people with view access to the group. The system may send them email when this happens (if they have notifications enabled), or you may wish to send them the name of your new group so that they can make it visible. If you want your friends to be able to add their own Annotations to the group, or to cull Annotations from the group, give them the appropriate extra permissions. You may also allow others help you maintain the group's user-name list and permissions by assigning the Administrate permission.
Private Annotations: To create Annotations that are for you alone, either add them to your "Private" group, or create a new group (which defaults to being visible by only the creator) and use that. Feel free to create as many groups as you need.
Public Annotations: Any Annotation that you want to be viewable by everyone should generally be added to your "Public" group, even if you add it to another, more topical group. This allows people to enable all your Annotations en masse, if they so desire.