|
review: An On-Line Document Review Tool
What review Is
review is an application for reviewing on-line documents and files. review allows you to see the comments other reviewers have made to the document and to add your own review comments.
Quick Reference
review [-h] filename
-h Display command syntax help
filename Name of the document (file) to be reviewed (using a relative or absolute path)
Using review
review displays a copy of the document you are reviewing. The document itself is read only. Any comments already made in the document are included as an annot inset, appearing as rectangular boxes containing the reviewer's userid. You can display (to see the contents) or iconify (to collapse) a comment by clicking on the title area of the box (where the userid is shown). You can add new comments to the document and save them for others to see (assuming write (rlidwk) access to the appropriate directory where comments are stored). You can update and save comments previously made by you.
Comments are placed in the document using an annot inset. This inset contains a normal ATK text object, which holds the actual comment text. Therefore everything allowed in a text object is allowed inside a comment, such as styled fonts, imbedded rasters, etc. The text object will automatically be loaded with the default template, though others can be loaded manually using the Add Template item on the File menu card.
There are menu items and default key bindings to perform such functions as finding the next or previous comment, displaying or iconifying all comments, displaying an index of all comments in the lower portion of the window, displaying a summary of review information, printing the document, etc... See details below for full explanations of these and other features.
The Comment Index
An index of all comments in the document can be displayed in the lower portion of the review window. By default this index is not shown. When shown, the index displays for each comment the reviewer's userid, the date and time it was last modified and the beginning portion of the comment text. It can optionally display the attributes of each comment as well.
Any comments made by you which have been modified but not saved will have an asterisk (*) following your userid. Any comments made by others which have been modifed since the last time you loaded the document from disk will have a changed style over the userid (this style shows as bold when using the default review.tpl template). By clicking the mouse on one of the index lines, the corresponding comment will be opened and the document positioned so that it is visible.
The styles used to display the index entries can be customized by copying /usr/tools/tpls/review.tpl into your own ~/tpls directory and modifying it (see help on templates for details on how to do this).
For more information on how to show or hide the comment index, see details below for the Toggle Comment Index menu item and the review.ShowIndex preference.
Status Information for the Document
review attempts to keep track of certain status information about each reviewer of a document. This information includes the total time spent reviewing the document, whether the reviewer has stated they are finished reviewing the document, and the time the reviewer last loaded the document and comments into review.
In order to approximate the total time a reviewer has spent in reviewing a particular document, review attempts to determine when the reviewer is actively using the review window. When review sees some activity in the window, it starts a timer. When review has seen no activity for approximately two minutes, it stops the timer and alters the window's mouse cursor to indicate it considers the window inactive. By default the inactive cursor is a sleeping cat, but this can be altered to be most any character from any font by using the review.CursorFont and review.CursorChar preferences. The running total of time spent reviewing the document is thus saved periodically, such as when quitting review or switching to another document. The reviewer has the ability to alter this value using the Alter Time Spent menu item. In addition, the reviewer can ask to always be prompted before a new time is saved by using the review.PromptWhenSavingTime preference. The time spent reviewing a document is shown when using the Show Document Status menu item, or on a header page when printing.
There are two menu items, named All Done Reviewing and Not Done Reviewing, which allow the reviewer to register or unregister that they are finished reviewing the document. This information is shown when using the Show Document Status menu item, or on a header page when printing.
The time the reviewer last loaded the document and comments into review is used to decide which comments to highlight in the comment index. Any comments which were made by someone other than this reviewer and have a last changed time greater than when the document was last loaded will be highlighted.
The status information is stored in a separate file for each reviewer, in the same directory where comments are stored. Therefore if a user does not have write (rlidwk) access to this directory, then no status can be kept.
Setting up a Document for Review
Because comments made against a document are not actually stored in the original file, but are instead associated with a particular byte offset within the file, it is important to ensure that the file being reviewed is not modified during the review period. If the file is modified, the comments will appear to 'float', since the byte position they are associated with is no longer the same place in the data. The best practice is therefore to create a special copy of the file to be reviewed if there is any chance that the original will be modified.
Before a document can be reviewed using the review tool, a review profile must be created indicating where comments should be stored. To set up a review for a document, perform the following steps:
1. Put a copy of the file to be reviewed in the directory where you want reviewers to see the file. Take away write access to that file and/or directory to prevent inadvertent changes from being made to the file (by other tools; review itself won't modify the document). Make sure that all the reviewers have read access to that directory.
Note: These directories should be in a shared filesystem, such as DFS or AFS. Refer to the filesystem documentation for instructions on setting directory permissions (For example, the acl_edit command for DFS, or the fs sa command for AFS).
2. Decide where reviewers' comments should be placed. This is the directory which all reviewers need write access to. The directory can have any name you choose. Continuing the above example, you might decide to have a subdirectory under ~/reviews called comments. Create it and grant write authority for all (or at least the authorized reviewers).
3. Create a review profile in the same directory as the file to be reviewed. The profile must either have the name filename.review, where filename is the name of the file to be reviewed, or simply be .review (which will apply to any file in that directory). Edit the profile and put the following lines of text in it:
Include $DV2TOOLSDIR/doc/global.review
CommentDir commentdirectory
commentdirectory is the name of the directory you decided on in step 2, either as an absolute path or a path relative to the directory where the document resides. For the above example file, you would create a review profile with the filename whatsup.doc.review (or .review to also cover other documents in the same directory being reviewed) containing:
Include $DV2TOOLSDIR/doc/global.review
CommentDir comments
(note that using an absolute path, it is important to include your userid, rather than simply a '~/'. This is because when other users review the document, a simple '~/' would expand to their userid, not yours.)
Additional features are available to configure in the .review setup file, such as allowing comments of different attributes to be added, or adding menu items. See the Advanced Review Setup section below.
4. The document is now ready for review. Just inform the reviewers that they can review the document using a command such as:
review ~youruserid/reviews/whatsup.doc
review y:\home\youruserid\reviews\whatsup.doc
review y:\home\youruserid\reviews\whatsup.doc
When you wish to end review of the document, you can simply take away the reviewers' write access to the comment directory, and once you are finished viewing the comments yourself then remove the filename.review file.
Setting Dimensions of Comments
When you insert a new comment in the document the dimensions of the new comment box are set to a default width and height of 160x100. This default can be overridden with the review.AnnotGeometry preference (see below).
You can resize the dimensions of any exposed comment box by selecting either the bottom or right edge of the box with the left mouse button and dragging it to a new location (the edges are very small and require a steady hand to grab - it takes a little finesse, but itis possible). When a comment is saved, this current size is saved along with it, and anyone subsequently viewing the comment will see this new size. This allows the author of a comment to decide if it deserves a small or large amount of screen space. If you wish to save a new size on a comment which has already been saved, you must modify the contents to cause it to be resaved (an asterisk will appear in the title portion of the box). Since you cannot modify comments made by someone else, you can likewise not save a new size for their comments (although you can alter the size for the remainder of yourreview session).
Comment Attributes
A comment can have "attributes" set in it. For example, a comment that merely flags a typo could be given a "type=typo" attribute, while a comment requiring feedback could be given a "type=issue" attribute, and the owner's response would have a "type=answer" attribute. Attributes can optionally appear in the Comment Index, or can be displayed and modified on a per-comment basis using the View Attributes and Modify Attribute items on the Comment menu card.
Considerations when Reviewing Files in CMVC/6000
There are no special actions which must take place to review a file which is contained in CMVC/6000. As mentioned above in the section entitled Setting up a document for review, it is generally a good practice to make a copy of the file to be reviewed, rather than to reference the original. Therefore it is suggested that to review a CMVC/6000 file that it be copied from the appropriate AFS library shadow directory into another location in AFS. The .review file would then be created at that new location, and the file would be left there for the duration of the review. Alternatively a symbolic link could be created which points to a file in the AFS library shadow, however if there is any chance that the CMVC/6000 file will be modified during the review period this would be an unwise choice.
Pop-up Menu Meanings
Add Comment(esc-c)
Creates a new comment at the present cursor location. Type your comment in the text area of the inset. See Setting dimensions of comments above for details about resizing comment boxes. Specialized comments can be added using items on the Comment menu described below.
Next Comment
Moves to the first comment following the present cursor location. The comment number and total number of comments is displayed on the message line.
Previous Comment
Moves to the first comment preceding the present cursor location. The comment number and total number of comments is displayed on the message line.
Save Comments
Saves any new or changed comments from the current review session. If a comment is completely empty, it will be removed at this time.
Display All Comments
Displays, or 'de-iconifies', all comments in the document.
Iconify All Comments
Hides the contents of all comments in the document, leaving only boxes with the creator's userid visible.
Refresh Document
Refreshes the entire document and any comments from disk, including any new or changed comments since the last refresh. Since this operation will discard any unsaved comments, a prompt is issued if any exist.
Switch Document
Prompts for a new document to review. Since this operation will discard any unsaved comments in the existing document, a prompt is issued if any exist.
Toggle Comment Index
Toggles between showing and not showing the comment index in the bottom portion of the window, below the document being reviewed.
All Done Reviewing
Registers that you are now finished reviewing the current document.
Not Done Reviewing
Removes any previous registration that you are finished reviewing the current document.
Alter Time Spent
Prompts for a new number of minutes to be logged as the time you have spent reviewing the current document. The default answer will be the number of minutes which review has detected activity by you in the document.
Quit(cntl-x cntl-c)
Quits the review application. If the document being reviewed contains unsaved comments, a prompt is issued. Note that quitting the application is not the same as registering as being finished using the All Done Reviewing menu item, just as that menu item does not quit the application.
Review / Show Document Status
Displays the document status in the comment index portion of the window. This includes the list of reviewers, how much time they have spent reviewing, and whether they have stated they are finished.
Review / Save As w/Comments
Prompts for a filename to which to save the document with all comments imbedded as annot insets. This allows the file to later be viewed with ez with the comments intact.
Review / Print Document
Prints the document, with comments, to the currently selected printer (as set by the PRINTER environment variable). Comments will be printed as footnotes, appearing at the bottom of each page.
Review / Set Printer
Allows selection of a different printer than that inherited at startup time via the PRINTER environment variable.
Comment / Add Comment
Adds a comment with the attribute "type=comment", typically a generic comment.
Comment / Identify Typo
Adds a comment with the attribute "type=typo", for simple misspellings and keyboarding errors.
Comment / Ask Question
Adds a comment with the attribute "type=question", thereby requesting the owner of the document to add a comment in reply.
Comment / Open Issue
Adds a comment with the attribute "type=issue", and prompts for a unique issue number. The owner's answer and any followup replies will have the same "number" attribute.
Comment / ...
[depending on the site config and customization in the .review profile, other menus may appear here]
Comment / owner: Answer
This menu will give the comment that has focus the attribute "status=answered", and create a comment following it with the attribute "type=answer" where the document owner can address the question or issue that was raised by the reviewer.
Comment / Hide...
Prompts for characteristics and then hides all comments fitting that description. "Hidden" comments are completely invisible in the document, unlike "Iconified" comments which still display the creator's userid in a box.
Entering "*" will match ALL comments, entering "." will match the comment that currently has focus, entering a userid will match all comments created by that user, and entering "attributename=value" will match all comments that have the specified attribute set to that value (Examples: "type=question", "status=open").
Comment / Unhide...
Unhides any hidden comments fitting the description as entered. (See description of Comment / Hide... menu above)
Comment / Modify Attribute
Adds or changes the value of an attribute in the comment that has input focus.
Comment / View Attributes
Displays the values of all attributes that are set in the comment that has input focus.
Preferences Entries
In addition to the standard ~/preferences entries for all Andrew applications, the following ones have special meaning for review:
review.ShowIndex: yes | no
Specifies whether to show the comment index at startup. The default is no.
review.VisibleAttributes: attname attname ...
Lists the attributes that should be made visible in the comment index. attname%width can be used to truncate the values at a size other than the default 3, e.g. status%5 will display the first 5 characters of the status attribute for each comment in the index.
review.PromptWhenSavingTime: yes | no
Specifies whether or not you wish to be prompted every time review is about to save a new value for the time spent reviewing a particular document. The default is no.
review.CursorFont: font_name
review.CursorChar: num
Specifies the font name and the character number within that font to be used for the 'inactive' cursor, which is displayed when review considers the window to be inactive. The default is a font name of icon12 and the character 22 (decimal), which should display as a sleeping cat. Another likely possibilty is the character 23 (decimal) in the icon12 font, which is a sleeping Snoopy.
review.PassHitsToIndex: yes | no
Specifies whether mouse hits in the comment index window should be passed to the window, or whether they should simply select the clicked-on comment. When set to yes, the right mouse button can be used to mark a region in the comment index. This is because the left mouse button will still select the comment, and give it the input focus. The right mouse button however will allow the input focus to remain in the index, thus allowing the region to be copied to the cut buffer. The default is no, which causes both mouse buttons to select the comment, but does not allow the input focus into the comment window.
review.AnnotGeometry: widthxheight
Specifies the dimensions which a newly added comment (which is actually an annot inset) should have. The default is 160x100.
review.AnnotTitleFont: font_name
Specifies the font to be used in the title area of a comment (which is actually an annot inset). The default is andysans8b.
review.AnnotTitleForegroundColor: color_name
Specifies the color used to write in the title area of a comment (which is actually an annot inset). The default is whatever the foreground color is for the overall review application. Note that when a comment has the input focus, the title area is inversed (that is, the background and foreground colors are reversed).
review.AnnotTitleBackgroundColor: color_name
Specifies the background color used in the title area of a comment (which is actually an annot inset). The default is whatever the background color is for the overall review application. Note that when a comment has the input focus, the title area is inversed (that is, the background and foreground colors are reversed).
review.AnnotBodyForegroundColor: color_name
Specifies the foreground color used in the body of a comment (which is actually an annot inset). The default is whatever the foreground color is for the overall review application.
review.AnnotBodyBackgroundColor: color_name
Specifies the background color used in the body of a comment (which is actually an annot inset). The default is whatever the background color is for the overall review application.
review.AnnotBorderColor: color_name
Specifies the color used to draw the borders around a comment (which is actually an annot inset). The default is the current AnnotForegroundColor.
Advanced Review Setup
As the document owner (setting up the .review profile for the file being reviewed), you can customize the menus and available options for the attributes on comments in the review. The default $DV2TOOLSDIR/doc/global.review file sets up some common ones, but these items in the .review profile can extend those capabilities further:
CommentDir commentdirectory
Specifies an absolute or relative path for the comments. See Setting up a document for review above.
Attribute attributename allowedval allowedval ...
Adds an attribute that can be assigned to comments in this review, and specifies the legal values it can have. For example, the global.review file has an entry that defines an attribute named "type" which can have the values "typo", "issue", "answer", etc.
If one of the allowedvals is "*", people reviewing the document can give that attribute an arbitrary value. If attributename is "*", no allowedvals need to be specified; it means that arbitrary attributes can be defined by the people reviewing the document.
Include filename
Loads another profile and parses it as if it were actually part of this .review profile. Besides the usual inclusion of $DV2TOOLSDIR/doc/global.review, this is useful for including local or departmental customizations.
Initfile filename
This forces the specified initfile to be loaded (as though in ~/.reviewinit). This is used to define keys and menus that will take advantage of the attributes defined.
VisibleAttributes attname attname ...
Lists the attributes that should appear in the Comment Index. If the person reviewing the document set the review.VisibleAttributes preference, the lists are merged and all of the specified attributes are shown in the comment index. As with the preference, attname%width can be used to truncate the values at a size other than the default 3, e.g. status%5 will display the first 5 characters of the status attribute for each comment in the index.
Also available as an advanced feature are parameters that can be passed to the procs described below.
The review-comment proc accepts an optional string with a space-separated list of "attributename=value" pairs. If "value" is "?", the user will be prompted for a value when using that menu or key. If "value" is "?#", the user will be prompted for a unique numeric value (useful for "type=issue" comments).
The review-edit-attribute proc accepts an optional string with either "attributename=value" (no need to prompt) or "attributename" (it will only prompt for the value). If no parameter is given, the user will be prompted for both an attribute to modify, and the new value for it.
The review-hide-comments and review-unhide-comments both accept string parameters, and will prompt if none was provided. The allowed formats for the parameter are the same as for the prompt: "*" for ALL comments, "." for the comment with input focus, "userid" for all comments created by that user, or "attributename=value" for all comments with attributes set to that value. Used in conjunction with ezprocs-multi (see the ezprocs help), custom menus such as these are possible:
addmenu ezprocs-multi "Comment,Hide all answered~67" textview ezprocs inherit "review-hide-comments'type=answer', review-hide-comments'status=answered'"
addmenu ezprocs-multi "Comment,Show only billybob's~68" textview ezprocs inherit "review-hide-comments'*', review-unhide-comments'billybob'"
They could be in a user's ~/.reviewinit, or the document owner could create a custom initfile that defines them and specify that initfile in the .review profile.
Proc Table Entry Names
There are a number of proc table entries for the review application, which a user may wish to bind to a unique menu item or key. Most of these procs are already bound to a menu item, either on the front or Review menu card. Note that executing some of these procs will result in the user being prompted for some information. The proc table entries specific to review are:
review-comment - Add a comment on the document
review-delete - Delete a comment from the document
review-edit-attribute - Change attributes of a comment
review-hide-comments - Hide comments. Parm: '*' for all, '.' for input focus, 'userid' to hide by creator, 'attr=val' to hide based on attributes
review-iconify-all - Display/Iconify all comments (parm of "1" or "0" respectively)
review-index - Show/Hide index of comments
review-next - Select the next comment after the cursor position
review-prev - Select the previous comment before the cursor position
review-print - Print the document with comments included
review-quit - Quit review
review-refresh - Refresh all comments from disk
review-register - Set whether or not finished with document
review-save - Write comments to disk
review-saveas - Save document with comments included as insets
review-setpr - Select the current printer
review-status - Display the document status
review-switch - Switch to another document
review-time - Alter the time spent reviewing document
review-unhide-comments - Unhide comments. Parm: '*' for all, '.' for input focus, 'userid' to unhide by creator, 'attr=val' to unhide based on attributes
review-view-attributes - Display attributes of a comment
review-visible-attributes - Change which attributes are visible in the comment index
Related Topics
|
