PDF Document Review¶
Often, writing code is only a small part of a software development project. Along the way, numerous documents are produced and discussed, including requirements documents, feature specifications, and technical documentation for end-users. The PDF Document Review feature in Power Pack allows you to apply the same peer review process to all of these as you do for your source code.
Creating a Document Review¶
To review a document, you need to start with a review request. In order to start a new review request for a document, select New Review Request, and then choose (None - File attachments only) when selecting a repository.
Once you have a review request, attach a PDF file, either by dragging and dropping the file onto the browser window, or using . This will add the file to the review request, and will be reviewable once the review request is published.
Note
Documents must be in the PDF format to be reviewable. If you have a document in another format (such as Microsoft Word), save it as a PDF before uploading it to Review Board.
Browsing a Document¶
To open up the document review page, simply click on the thumbnail for the file attachment on the review request page. This will bring up an interface for browsing the document.
This interface has several controls for browsing through the document.
At the top left is a toggle for a sidebar which can be used to browse through the document. When the sidebar is open, it can show either a list of pages or the table of contents. Not all documents contain a browsable table of contents; if a document does not, the sidebar will only contain the page list.
In the center of the top bar are controls for jumping to a specific page or moving back or forward a page.
At the top right are controls for zooming in and out of the document.
Commenting On a Document¶
To place a new comment on part of a document, simply click and drag to select the desired area. This will pop open a new comment dialog, just like in the diff viewer.
Comments support rich text using the Markdown language. See Using Markdown for more information.
The file attachment comment dialog supports issue tracking. See the section on Issue Tracking for more information.
Once you’re done writing your comment in the text area, click Save to save the comment.
A rectangle with a green number box will appear in the region you selected to indicate that you have a comment in that area. Click the box to pop open the comment box for your existing comment again.
Reading Existing Comments¶
When your mouse cursor is over the document, regions representing other comments may appear with blue number boxes in the corner. Each of these is a comment someone has made on another review.
If you move the mouse cursor over the region, a tooltip will appear showing a summary of the comments made.
If you click on the region, the comment dialog will appear, along with a blue side panel on the left showing those existing comments. You can still write new comments in the green area of the comment box.
Note
It’s important to note that this is not the place to reply to those comments. When you add a comment from the PDF viewer, it’s creating a new top-level review (akin to a new thread). If you want to reply to existing comments, you can do so from the Reviews page. The Reply link here is a shortcut to jump directly to the relevant comment on the Reviews page.
The view here is meant to be used only as a reference to see if other people have already said what you plan to say.
Viewing Other Document Revisions¶
New in version 3.0.
As explained in Reviewing File Attachments, you can view and compare revisions of a PDF file attachment. When multiple revisions are present, a slider will be available to allow you to select either a single revision to view or two revisions to compare.
When comparing two revisions, the two documents are shown side by side, much like in Review Board’s diff viewer. The differences between the revisions are displayed in two ways: highlighted regions on each of the documents, and in a sidebar mode.
Note
Due to the complexity of the PDF format, comparing two revisions for the first time can take a while, especially for large documents. During this time, a spinner will be shown next to the revision selector. Subsequent loads of the same diff will load much more quickly.
The highlighted regions will show red blocks on the left for text that was deleted, and green blocks on the right for text that was added. Moved text will be shown as deleted from the left and added to the right. The list of diffs can be seen in the sidebar by clicking on the columns icon. Each entry in the sidebar corresponds to a region on a page, and will additionally show whether those regions represent text that was moved instead of just added or removed. Clicking on an entry will scroll to the relevant position in both documents.
Note
Most document editing software will create PDFs that work well with the diff display in Review Board, but not all. The PDF format is fundamentally designed as a display and printing format, and not for document editing and management. Depending on how your PDFs are created, they may not actually contain usable text content with which to compute diffs.
For example, most scanned documents only contain images of the text rather than the text itself, and some publishing software will create PDFs which represent each letter as a shape instead of as a computer-readable character with an embedded font. There may also be cases where saving some documents can cause text to be incorrectly detected as moved (such as filling out some PDF forms).