About | Project Members | Research Assistants | Contact | Posting FAQ | Credits

CommentPress Research Paper

“CommentPress” by Pehr Hovey and Renee Hudson.
(version 1.0; created 4/22/09)

About the Authors:
Pehr Hovey is an algorithmic artist and researcher interested in the intersection of arts and technology. He is studying the mapping between audio and visual domains and how visual stimuli can be tightly integrated with the aural environment. He recently graduated with degrees in Computer Science and Computer Engineering from Washington University in Saint Louis and is currently a Masters student in Media Arts & Technology at UC-Santa Barbara.

Renee Hudson received her BA in English at Stanford University and is currently a PhD student in English at UCLA. She specializes in twentieth century American literature. Her research interests include media theory, terrorism, and political violence.

Transliteracies Research Paper PDF Version PDF version of the research report.

The Institute for the Future of the Book officially launched CommentPress 1.0 on July 25, 2007 as a theme for WordPress. The initial project developed in 2006 when the Institute approached Mackenzie Wark about creating an online version of his book Gamer Theory. In order to emphasize conversation about the book, the Institute departed from the typical blogging structure by placing comments next to the text rather than directly beneath the text. The online project, called GAM3R 7H30RY was so successful that it sparked similar projects, among them Mitchell Stephen’s “Holy of Holies: On the Constituents of Emptiness,” and Lewis Lapham’s “The Iraq Study Group Report.”

As a project for The Institute for the Future of the Book, CommentPress, “an open source theme for the WordPress blogging engine,” rethinks the format of the book in an online, networked environment {1}. By treating texts in this way, the Institute emphasizes the social nature of texts by facilitating conversations between author(s) and reader(s). As part of a networked environment, “the networked book is not bound by time or space. It is an evolving entity within an ecology of readers, authors and texts. Unlike the printed book, the networked book is never finished: it is always a work in progress” {2}.

Comments can be made on a paragraph-by-paragraph basis or to the document as a whole. However, since the comments are not threaded, it can be difficult to follow multiple conversations within a comments section {3}. Interestingly, because comments are not threaded, this implies a focus on the text rather than on the conversations users have between each other about the text {4}.

CommentPress has two skins: document and blog. Document mode allows users to see a Table of Contents on the left, text in the middle, and sidebars on the right that let users browse comments, easily access the contents of the text, or preview recent comments.

Blog mode features an aligned interface with text on the left and comments on the right. The comments section remains static as a user scrolls through the text. However, clicking on the speech bubble anchor for a given paragraph reveals the comments for that paragraph and gives the user the ability to post a comment. By matching text to relevant comments (paragraph one to comments for paragraph one), users can hone in on specific sections of text. The advantage of the aligned interface model is that notes do not block the text the way handwritten notes, stickies, or a pop-up window would.

As noted by Kimberly Knight, document mode is for static documents while blog mode is for sites that frequently update their content {5}.

Research Context
Before its release, CommentPress was originally “the result of a series of ‘networked book’ experiments run by the Institute [for the Future of the Book] in 2006-7” {6}. Initial CommentPress projects were McKenzie Wark’s GAM3R 7H30RY, and Mitchell Stephens’s “Holy of Holies: On the Constituents of Emptiness,” which inspired the current format.

CommentPress may be particularly attractive to disciplines like the Humanities, but fundamentally, it appeals to all disciplines by integrating the ability to publish text along with the ability to comment on that publication. Such integration emphasizes the ability to receive feedback and is therefore important for a variety of disciplines by facilitating peer review, feedback, and commentary. By focusing on the ability to comment on a given text, CommentPress highlight’s the user’s role as an active reader and critic over a passive approach to texts.

Annotation systems like CommentPress fundamentally attempt to replicate the active reader experience by translating book margin spaces to the Internet. Joanna Wolfe, tracing the lineage of annotating texts to the familiar practice of medieval manuscript scholars, explains how print cultures depart from the medieval model of annotating by individualizing the reading experience as each person owns a copy of a text instead of passing down a single copy {7}. With the ability to have information readily available online (and increasing digitization efforts to publish print-only texts on the internet), annotation technologies like CommentPress take advantage of the ability to comment on a single text in a centralized location, thereby replicating on a larger scale the dialogs carried on in the marginalia of medieval manuscripts.

However, as Catherine Marshall notes writing about hypertext, “Many of our systems and methods are (justifiably) geared toward the initial design of a hypertext, not toward the annotation of existing materials . . . In essence, as Rosenberg points out, they are writing-oriented systems rather than reading-oriented systems” {8}. As a response to this division between capabilities on the internet — which leads Marshall to distinguish between “the reader-as-navigator” and “the reader-as-annotator” — annotation technologies like CommentPress fundamentally bridge the gap between reading and writing by underscoring the role writing plays as an act of reading {9}.

Earlier models of digital annotation technologies addressed bridging the gap in a variety of ways that continue to inform current annotation software. For instance, the CommentPress aligned interface resembles CommonSpace (no longer available as of December 2001) {10}. In CommonSpace, the primary text occupied a left-hand column and separate columns to the right distinguished commentators from each other. While CommentPress places all comments alongside the primary text in chronological order, the separation between primary text and commentary is clearly delineated. Like CritLink (1997), CommentPress allows users to anchor comments to pieces of text, though not at the level of the individual phrase or sentence {11}. Users may comment on a paragraph-by-paragraph basis or on the page as a whole.

Significantly, the representation of texts online illustrates a shift from scroll to codex to scroll again as observed by Kathleen Fitzpatrick. Fitzpatrick notes that Peter Stallybrass, in “Books and Scrolls: Navigating the Bible” remarks on “the irony in digital textuality’s regression from the kinds of manipulation that the codex made possible, reimposing the limitations of the scroll on our reading practices” {12} However, with the development of CommentPress by the Institute for the Future of the Book, Fitzpatrick suggests that annotation technology liberates “the book’s content from the form of the codex” by inserting texts into a networked environment {13}.

Texts on CommentPress, freed from both the restrictions of the isolated codex and the unwieldy scroll, allow readers to view text in manageable chunks that enables conversations to arise from the text. Interestingly, in using a “net-native publishing form, the blog,” CommentPress’s placement of “comments next to rather than below the text turned out to be a powerful subversion of the discussion hierarchy of blogs, transforming the page into a visual representation of dialog, and re-imagining the book itself as a conversation” {14}.

Because CommentPress focuses on creating dialogs around texts, it is by nature community-oriented and lends itself to particular uses of text. Such uses include peer review, as evidenced by Noah Wardrip-Fruin’s Expressive Processing, writer’s workshops, and close-reading exercises {15}. CommentPress’s emphasis on the community departs from traditional marginalia by making the private experience of annotation public, thereby encouraging feedback and a free exchange of ideas.

Although The Institute for the Future of the Book began research on CommentPress as part of another project, Sophie, the CommentPress team plans to release version 2.0 by the end of March, 2009 {16}.

Using CommentPress

Publishing in CommentPress
Before a user can post to CommentPress they need an account with posting privileges and must log into the standard WordPress Administration Panel by going to http://blog_address/wp-admin.

Publishing documents for annotation in CommentPress is as simple as posting to a regular WordPress blog. Users with posting abilities do this by using the ‘Write’ tab in the WordPress Administration Panel. The default ‘Document’ mode assumes that each post refers to a chapter or other logical section of a larger work. To post a chapter for annotation simply copy and paste the relevant text into the Post content text area and make sure it is properly formatted before publishing it.

CommentPress uses the presence of HTML paragraph tags (<p>) to automatically determine the boundaries between commentable units of text {17}. By default WordPress inserts a paragraph tag wherever there is a blank line between groupings of texts. The HTML code for a post can be manually edited using the ‘code’ view instead of the ‘visual’ view on the post editing page. Additional <p> paragraph tags can be inserted in the text as needed to create new commentable units. Two or more paragraphs can be designated as one commentable unit by separating them using two or more consecutive line break (<br>) HTML tags instead of regular paragraph tags.

Commenting in CommentPress
Comments are created and displayed in a comment pane that remains in the center of the screen while the document is scrolled. Each commentable unit and the document title has a ‘speech bubble’ that, once clicked, populates the comment pane with pre-existing comments for that unit as well as a text box for writing new comments.

Anonymous comments are enabled by default in WordPress. Depending on the goal of the CommentPress installation it may be desired for only known users to be able to comment. Anonymous comments can be disabled by an Administrator in the WordPress Administration Panel.

Spam comments may also become an issue if the CommentPress installation is findable in a search engine. WordPress has built-in spam filtering mechanisms that can be configured in the WordPress Administration Panel.

CommentPress Roles
Since CommentPress is based on WordPress there is built-in security and access control based on ‘Roles’. Each user account has an assigned role that defines what features are available.

Below is a summary of roles, from the WordPress site {18} :

  • Administrator – Somebody who has access to all of the administration features
  • Editor – Somebody who can publish posts, manage both their own posts and other people’s posts, etc.
  • Author – Somebody who can publish and manage their own posts
  • Contributor – Somebody who can write and manage their posts, but not publish posts
  • Subscriber – Somebody who can read comments/comment/receive news letters, etc.

Each role inherits the capabilities of roles beneath them.

Technical Analysis
CommentPress is broadly implemented as a theme for WordPress but it is substantially different from typical WordPress themes. Most WordPress themes simply redefine the color scheme and basic layout of a standard set of blog elements. CommentPress operates more like a hybrid between a typical theme and a WordPress plugin because it uses the plugin system to drastically alter the functional behavior of the WordPress platform, in addition to changing the appearance. CommentPress also includes other third-party WordPress plugins that are used to implement certain functionality, such as skins and comment threading.

JavaScript is used to display comments and implement other informational pop-ups such as help text. A combination of custom code and the jQuery {19} user interface library accomplishes this task. Since CommentPress is based on the WordPress platform, it is almost entirely made of PHP {20} code and uses MySQL {21} for the datastore.

Installing & Configuring CommentPress
CommentPress requires a fresh installation of the WordPress blog software. It is important to use a version of WordPress that is supported by CommentPress. WordPress 2.2 seems to be the newest version that works well with CommentPress. See the Technical Issues section for more information on CommentPress/WordPress compatibility.

CommentPress is installed in much the same way as traditional WordPress themes. The makers of CommentPress have posted installation instructions that detail the basic steps required to get CommentPress up and running {22}. The user must have FTP access to the server in order to copy the CommentPress folder into the /wp-content/themes/ folder.

By default the Unix File Permissions are set to a restricted setting that prevents outside users from accessing them which means that the theme will not function. To fix this requires access to a terminal or other method of adjusting file permissions. One way to do this in a terminal shell is to navigate to the /wp-content/themes/ folder and run the command:

chmod 755 commentpress/*

This will change the permissions on every file and folder in the CommentPress installation to be readable (but not writeable) by the public. This assumes that the user has the proper authority to change file permissions. Users should consult their network administrators if they are unsure about this operation. By default the WordPress Administrator Panel is accessed at http://blog_address/wp-admin. The user must be logged in to this section as an administrator to finish installing CommentPress.

The CommentPress installation instructions mention the need to change the permalink structure away from the default setting. This step is crucial to ensuring proper operation of CommentPress. It is recommended to select ‘Date and Name based’ on the permalinks page under the ‘Options’ tab in the WordPress Administration Panel. CommentPress is activated like a traditional theme, on ‘Presentation’ page in the WordPress Administration Panel. Additional configuration options are available on the ‘CommentPress Options’ and ‘Skins’ tabs under ‘Presentation’ page that controls the appearance of the CommentPress system.

The CommentPress system automatically checks for newer versions of CommentPress by accessing the official CommentPress website. If this check does not happen successfully it is possible that the WordPress administration area will display corrupted data. If it seems that the screen is covered with incorrect data or blank areas, see the Technical Issues section for more information on fixing this issue. Once activated, CommentPress is ready to use.

CommentPress as a WordPress Plugin
CommentPress takes advantage of the WordPress plugin ‘hook’ system that allows for custom manipulation of nearly every aspect of system behavior and appearance. Hooks are specific places within the data flow of a program that are entry points for custom third-party code. A plugin works by registering itself with the program and specifying which code to run for which hook. When the program is executing if it encounters a hook that has been registered it will run the provided plugin code in tandem with the original program code.

WordPress provides two types of hooks — Action and Filter. The WordPress documentation describes each type {23}:

  • “Actions are the hooks that the WordPress core launches at specific points during execution, or when specific events occur. Your plugin can specify that one or more of its PHP functions are executed at these points, using the Action API.”
  • “Filters are the hooks that WordPress launches to modify text of various types before adding it to the database or sending it to the browser screen. Your plugin can specify that one or more of its PHP functions is executed to modify specific types of text at these times, using the Filter API.”

WordPress allows themes to take advantage of the plugin API by looking for a file named functions.php that will specify custom code to run at certain points in the execution cycle. The functions.php included with CommentPress file registers against eight WordPress hooks in order to re-write nearly every textual aspect of the typical blog post.

CommentPress Internal Operation
The CommentPress functions.php file contains the bulk of the behavioral modifications to WordPress that enable per-paragraph annotation. CommentPress defines additional administrative pages that are accessed in the Presentation section of the WordPress Administrative Panel. These pages allow the user to change skins as well as configure properties such as the name for the Table of Contents (if using the Document skin).

Unlike most themes, CommentPress requires some installation code to be run internally that modifies the WordPress database to support its operation. The installation code is contained in the function commentpress() and is run when the user first accesses the WordPress Administration Panel and if the user selects the ‘Restore Factory Defaults’ option. CommentPress utilizes the WordPress options database table and the related add_option() & get_option() functions to safely store configuration variables controlled using the add-on administration pages. To relate a comment to a particular paragraph CommentPress modifies the database structure to add a column named ‘comment_contentIndex’ to the ‘wp_comments’ table that stores comment information. This is done using the function commentpress_altertable() that is called when CommentPress is first installed.

Three additional WordPress pages are created upon installation, which are used to dynamically display comments arranged by user, by section and general comments. The page ID numbers are stored in the WordPress options database table to be used later when the pages need to be displayed.

CommentPress uses five WordPress Action hooks and three Filter hooks during normal operation. These hooks are used to overwrite different elements of the typical page including the title, post excerpt and the content itself. The most important hook used is the filter for the_content, which is used to modify the body of a post which contains the text to be annotated. The function commentpress_the_content() is called whenever the content of a post is being constructed for display or saving to the database. This gives a plugin the chance to affect how the data is displayed or stored. CommentPress uses this hook to search through the text for HTML paragraph tags and other indications of a commentable unit. Each found block is numbered with a fixed ID that is used to provide permalinks to the paragraph and to retrieve the comments that belong to it if the user clicks on the speech bubble next to the paragraph.

A standard WordPress installation stores a numerical ID with each comment in the ‘comment_post_ID’ column to record which post the comment belongs to along with the timestamp of the comment to allow the blog software to retrieve relevant comments and list them in a coherent order. CommentPress extends this by storing the ID of the relevant paragraph in ‘comment_contentIndex’ column that was created during installation. When a page is being constructed for display the filters and hooks run code to retrieve each paragraph and attach comments to it based on the stored paragraph IDs similarly to how regular WordPress attaches comments to a regular post.

Technical Issues

WordPress Compatibility
Since CommentPress relies on more internal WordPress functionality than a typical theme it is more prone to breaking when WordPress changes. As of March 2009 WordPress is at version 2.7.1 while the CommentPress website claims that it works with WordPress 2.3.

There is PHP code within the CommentPress system that is designated specifically for keeping CommentPress working with WordPress 2.3.x due to functional changes between WordPress versions. This suggests that as WordPress evolves more compatibility code will be needed which means that it is likely that CommentPress users will have to stick with one particular legacy version of WordPress to ensure their system always works.

Besides new features, newer versions of WordPress have critical security fixes that keep the blog secure from automated hacking attempts. Using outdated versions of WordPress exposes users and their blog to these well-known security risks and is something that must be considered when using CommentPress.

WordPress 2.2 was used to evaluate CommentPress for this report because user comments on the official CommentPress website claimed that they were having trouble while using WordPress 2.3.x. Previous versions of WordPress are available from the official WordPress website {24}.

CommentPress requires JavaScript to function properly, which can cause issues with accessibility if a user does not have JavaScript installed or enabled in their web browser. While all major web browsers support JavaScript, some users disable it by default as a security precaution. Users with vision impairment may also employ automated text-to-speech software that reads the text content of the page aloud. With JavaScript being used it is possible that these programs may not be able to read all the relevant text on the screen.

JavaScript is most notably used to display the comments for a paragraph when the user clicks on the speech-bubble icon. Without JavaScript the user cannot view existing comments or post new ones. Additionally, the ‘help’ link on the page uses JavaScript to display the information. The use of JavaScript is critical for the proper implementation of the CommentPress concept as it allows the comments for a paragraph to be displayed in a variable-length container next to the document that appears to move with the text as it scrolls.

While requiring JavaScript is not unreasonable it would be better to display a prominent warning if JavaScript is not functioning in order to help users make the most of CommentPress.

CommentPress Upgrade Message Issue
The CommentPress system automatically checks for new versions of CommentPress by accessing a special version.php page on the official website {25}. This page is supposed to return only a number indicating the current version. This number is then compared to the locally installed version and if necessary, an upgrade message with a link to the newest version is displayed.

This omission was brought to light in February 2009 as the CommentPress website was experiencing configuration issues and sometimes version.php would return a full HTML page. Since PHP allows arbitrary data to be compared this HTML code was tested for equality with the installed version number which understandably evaluated as not-equal. This resulted in the entire contents of version.php being displayed in the upgrade message, obscuring all administrative functions of the WordPress Administrator Panel and making it impossible to create or edit posts.

The CommentPress team was notified of the issue and has since ensured that version.php returns the current version number (1.4.1 as of March 2009).

Evaluation of Opportunities/Limitations for the Transliteracies Site (and the Bluesky Group)
While CommentPress improves reading practices generally by centralizing the location of the text and tracking notations chronologically, it also adds to the experience of reading online precisely because of the networked nature of the text on CommentPress. The text exists amidst a wealth of information online and, through the use of annotation, can be easily linked with relevant comments and information.

With its focus on soliciting feedback and the ability to use it as tool for peer review, CommentPress highlights the increasingly collaborative nature of not just authoring, but reading in the online environment. While centralizing the text allows the author to access it from any computer, centralization also allows users in a variety of locations and time zones to provide valuable notes to the text. In this way, CommentPress takes advantage of the both the online environment and annotation technologies.

Importantly, one must note that, while the hierarchy of the blog is to a certain extent subverted by the structure of CommentPress, there still remains a clear delineation between text and commentary. As such, CommentPress privileges the text written by the author over that written by the annotator. However, this model of annotation still encourages user feedback, which underscores a dialog between the author(s) and reader(s) rather than a simple line between author and reader.

Unlike some annotation software, CommentPress does not “support annotation of annotations, navigation between annotations and annotation sharing” {26}. Aside from stressing the importance of the text over commentary, the limited options for relating annotations to each other also locates the conversation around a specific text rather than a general topic. Thus, readers of “The President’s Address to the Nation, January 10, 2007,” a project CommentPress worked with Lapham’s Quarterly to produce, structure their comments around the president’s address on January 10, 2007, rather than on the topic of presidential addresses.

Because CommentPress allows annotations on a whole page or paragraph-by-paragraph basis, users are prevented from making notes on the level of the word or the sentence. While this ensures that the text does not become cluttered and unreadable, it also suggests that notes can only aspire to a certain level of detail. For instance, while CommentPress can be used for close-reading exercises, users will have to include their interpretation in a comment on the paragraph level and potentially refer to line number in the event that the specific word they are unpacking occurs multiple times within the paragraph.

Although CommentPress does not allow users to embed images and video into their comments, Sophie, a related project undertaken by The Institute for the Future of the Book, focuses on such multimedia documents. Because the two projects exist separately (though under the same mission statement, which seeks to chronicle the shift from the page to the printed page to the networked screen), this suggests that while the Sophie software rethinks the very elements that constitute a book, CommentPress rethinks the readers relationship to the text by emphasizing writing as part of a reading process {27}.

Resources for Further Study

  • Diigo — unlike CommentPress, this is a browser-based annotation tool.
  • Commentariat — also a WordPress theme, Commentariat focuses on dividing texts into meaningful, commentable pieces.


  • {1} CommentPress. 27 Jan. 2009 .

  • {2} “Mission Statement.” Future of the Book.org. Institute for the Future of the Book. 28 Dec. 2008 .

  • {3} Kimberly Knight, “CommentPress.” Transliteracies Project. 28 Dec. 2008 .

  • {4} Joanna Wolfe, “Annotation Technologies: A Software and Research Review.” Computers and Composition 19 (2002), p. 494: “In conversational situations, an aligned interface could be dynamically combined with a threaded-reply structure after multiple readers have responded to each other’s comments.”

  • {5} Kimberly Knight, “CommentPress.” Transliteracies Project. 28 Dec. 2008 .

  • {6} “About CommentPress.” Future of the Book.org. The Institute for the Future of the Book. 27 Jan. 2009. .

  • {7} Joanna Wolfe, “Annotation Technologies: A Software and Research Review.” Computers and Composition 19 (2002), p. 471-472.

  • {8} Catherine C. Marshall, “Toward an Ecology of Hypertext Annotation.” Proceedings of ACM Hypertext ‘98, Pittsburgh, PA (June 20-24, 1998), p. 40.

  • {9} Ibid. , p. 40.

  • {10} Joanna Wolfe, “Annotation Technologies: A Software and Research Review.” Computers and Composition 19 (2002), p. 486.

  • {11} Ibid. , p. 490.

  • {12} Kathleen Fitzpatrick, “CommentPress: New (Social) Structures for New (Networked) Texts.” 15 Feb. 2009 .

  • {13} Ibid.

  • {14} “About CommentPress.” Future of the Book.org. The Institute for the Future of the Book. 27 Jan. 2009. .

  • {15} Kimberly Knight, “CommentPress.” Transliteracies Project. 28 Dec. 2008 .

  • {16} Renee Hudson, “Sophie.” Transliteracies Project. 13 Jan. 2009

  • {17} “Formatting Your Document.” Future of the Book.org. The Institute for the Future of the Book. 9 Mar. 2009. .

  • {18} “Roles and Capabilities.” WordPress Codex. WordPress. 7 Mar. 2009 .

  • {19} “jQuery JavaScript Library.” 7 Mar. 2009 .

  • {20} “PHP.” PHP: Hypertext Preprocessor. The PHP Group. 9 Mar. 2009 .

  • {21} “MySQL.” MySQL AB. 9 Mar. 2009 .

  • {22} “Installation.” Future of the Book.org. The Institute for the Future of the Book. 7 Mar. 2009 .

  • {23} “Plugin API.” WordPress Codex. WordPress. 8 Mar. 2009 .

  • {24} “Release Archive”. WordPress. 9 Mar 2009 < http://wordpress.org/download/release-archive/>.

  • {25} “Version.php.” Future of the Book.org. The Institute for the Future of the Book. 7 Mar. 2009 .

  • {26} Ilia A. Ovsiannikov, Michael A. Arbib, and Thomas H. McNeill. “Annotation Technology.” International Journal of Human-Computer Studies 50 (1999), p. 332: DIANE “also supports annotation of annotations, navigation between annotations and annotation sharing.”

  • {27} “Mission Statement.” Future of the Book.org. Institute for the Future of the Book. 28 Dec. 2008 .


  tl, 04.22.09

Comments are closed.