Beta release notes

carlthewebmaster edited this page Nov 7, 2011 · 11 revisions

About this version

This is a pre-release beta version of the Annotum WordPress theme. It contains bugs and should not be used for a production system. Please refer to the known issues list for known bugs and open development tasks. Please see other important caveats in the Annotum license/

Annotum is a product of Solvitor LLC with heavy lifting by Crowd Favorite.

Annotum is free (speech and beer).

Installation

Important: Annotum is best suited for use on a new, or separate, WordPress installation. It is not recommended to install WordPress on to an existing blog or other WordPress site.

Minimum Requirements:

If you host your own Annotum-powered site using WordPress, the following are the minimum requirements necessary:

  • WordPress version 3.3
  • PHP 5.2.4 (including libxml 2.6.29 or higher)

Basic Install (existing WordPress site).

The simplest installation method is to install the Annotum theme in an existing WordPress setup (for example if your hosting provider offers a one-click WordPress setup). To do that

  1. Download the beta distribution package to your computer, and extract the two theme files annotum-base.zip and current.zip (i.e., extract these zip files from the distribution package).
  2. Log into your WordPress admin dashboard, and navigate to Appearance > Themes > Install Theme > Upload.
  3. Find the annotum-base.zip and current.zip files from step 1, and use the form to upload them to your site. You can activate either Annotum-base or Current, but you must install Annotum-base to use Annotum. See "Theme Setup" below for next steps.

Stand alone installation options

In addition to being offered as a standard zip file, we offer complete, stand-alone packages that contain all components needed to set up a working Annotum setup. Packages are offered for both Mac/OSx and for Windows. Please refer to Annotum stand alone installers for more information.

Theme Setup:

Once you've installed and activated the theme, log in as an administrator and navigate to the Themes dashboard (Dashboard > Appearance > Themes). From there, click Annotum Settings, and select the desired options:

  • Enable Workflow: This enables the Annotum workflow features. IMPORTANT: enable this or you won't get any of the workflow features.

  • Enable workflow notifications: sends an email to appropriate authors/editors/reviewers whenever workflow actions are taken.

Note: workflow notifications generate an email message to every site admin and editor for every workflow action in addition to role-specific (author, co-author) notifications. This can generate quite a bit of email on an active site!

Note: Notifications will not work unless your WordPress setup is configured to send mail. For local installations using Annotum2Go, AnnotumMAMP, or other stand-alone LAMP stacks, you must run a local mail server such as MercuryMail or install a WordPress plugin such as wp-mail-smtp.

Annotum notification matrix

Figure: Annotum email notification matrix

  • Add credentials for CrossRef DOI lookups. Get credentials (i.e., register your email) here, and then add them to the Annotum Settings screen [no password needed].

  • Allow article authors to see reviewers: This enables an "open-process" review style in which article authors can see all reviewers and their review comments. You may wish to leave this deselected for a more traditional anonymous review process.

Getting started with Annotum

Quick Start

To dive into creating articles with Annotum, follow these steps:

  1. Log into Annotum at http://YOUR_SITE_URL/PATH/wp-login.php
  2. From the top admin bar, navigate to Add New > Article.
  3. Enter a Title (required) and a Subtitle, Abstract, or other information if you wish.
  4. The main action in Annotum takes place in the article editor, a WYSIWYAATD (What-you-see-is-what-you-are-allowed-to-do) editing control with many features such as tables, images, and equations. The editor shows you where you are in the structure of the document, whether in the title of a section, a paragraph or in one of the elements of a figure.
    • Typing/editing tips:
      • Press enter to create a new paragraph, and ctrl+enter to create a new section
      • Use the full screen view to enlarge the editor to take up the whole window. But don't forget to save from time to time!
  5. Enter some text, click save, and then preview your article.
  6. Now experiment with inserting images, tables, and equations.
  7. When you're done editing, click submit for review (if you have enabled workflow. If not, you can click publish.) You can now select or invite reviewers, or if you are an admin or editor simply click approve and then publish.
  8. Finally, view the published article, and download a copy in XML format. (Annotum uses the kipling dtd, a subset of the NLM's Journal Article DTD 3.0.
    • Annotum supports round-tripping of XML content. You can export your articles in Kipling-XML format, then easily upload them on any other Annotum site.
  9. Hooray! you've just created and published your first article with Annotum.

For more specifics, please refer to the detailed Feature Walkthrough.

Additional Theme Setup

Annotum uses standard WordPress features such as widgets and menus for customization. There are also some Theme Settings such as callouts.

Annotum2go and AnnotumMAMP each provide a basic widget setup.

Note: the initial theme content is quite sparse by design. You will almost certainly want to add menus and sidebar widgets to enhance the layout of your site.

Adding Users

Annotum's workflow is based around the Articles custom post type and a few custom user permission levels: Author, Reviewer, Editor, and Admin.

About Roles

Annotum and WordPress Roles

Annotum and WordPress Roles

  1. Admin aka publication staff. Admins can perform all functions and see all comments. They can add and remove reviewers and coauthors, change authors, approve/reject/request revisions on articles, and publish approved articles. Create admins by granting them the "Admin" WordPress user level.

  2. Editor. Editors can do everything except publish articles (move from review complete/approved to published). Create Editors by granting them the "Editor" WordPress user level.

  3. Author. Authors can create articles, add and remove coauthors, and submit articles for review. Authors cannot see review comments on their articles, nor do they see who the reviewers are. Authors can be added with either the "Contributor" or "Author" WordPress user level. If "Author" is used, the user will be able to create regular posts and pages via the built-in WordPress functions. Note that Co-authors are defined at the article level (not user level) when they are added by the article author. They can be any level from Contributor on up.

  4. Reviewer. Reviewers can submit review comments and view replies to their own review comments only. Reviewers are defined at the article level when they are added by the editor. They can be any level from Contributor on up.

  5. Subscriber. Essentially a site viewer, they can make comments on published articles.

Please see Annotum permissions for more information.

Creating Articles

Create a new article via the "new article" button from the "Articles" dashboard. You'll see various sections for adding co-authors, including sections of your article, etc. NOte that future versions will have a greatly-enhanced set of authoring controls including the ability to import and export XML, structured equation/figure/table support, and other features such as robust handling of references. IN the preview-beta version only some features are available.

  • NEW! References: easily add references using PubMedIDs and CrossRef DOIs. Click the [1] toolbar button.

  • NEW! Enhanced XML export: nearly complete NLM-compliant XML output.

  • NEW! Improved image and table handling

Once you've created an article, you can:

  1. Preview the article
  2. Add Co-authors (once you do, they can also edit the article)
  3. Submit the article for review

Using Workflow

The basic workflow is:

  1. The Author creates a new article, and optionally invites co-authors to work on it. All co-authors can post internal comments on the article during this process.
  2. When ready, the Author submits the article for review via the Submit for Review button on the article editing screen.
  3. The editor assigns reviewers, each of whom can enter review comments and a recommendation: Approve, Reject, or Request Revisions. The editor may reply to review comments; reviewers can only see their own comments and replies to them.
  4. When the reviews are in, the editor can Approve or Reject the article or Request Revisions. Only Approved articles can be published.
  5. Once an article is approved, an admin (think of admins as the publication staff) can publish it to the site.

Additional Notes

Background on the project, regular updates and links to related sites and information are provided on http://annotum.wordpress.com. You can also follow @annotum on Twitter.

Support

Please visit http://annotum.wordpress.com for the latest news, downloads, and other support information. Or submit bug reports or questions via the Annotum issues list at https://github.com/Annotum/Annotum/issues

Follow @annotum on Twitter for updates.

Licence

Rights for products and code contained herein are owned by their respective copyright holders or available via the referenced license (GPL, etc).

All components in this package are believed to be open source and freely-redistributable.

Annotum is free (as in beer and speech).

Credits

Annotum is a production of Solvitor LLC with heavy lifting provided by Crowd Favorite, and special thanks to: Google, PLoS, NIH/NLM/NCBI, and Automattic.