CommentPress

About CommentPress

ben vershbow — Tue, 21 Aug 2007 19:45:57 +0000

CommentPress 1.0 release: July 25, 2007\\r\\n\\r\\nFor far too long electronic documents have been saddled with ill-fitting metaphors from the realm of print: e-books, e-ink, e-paper etc. Publishers expect us to purchase, own and consume e-books (or articles, papers, journals) in basically the same way we do paper books, failing to reckon with the fact that texts take on different values and assume different properties when placed in the digital environment—especially when that environment is part of a network. Institute for the Future of the Book was founded in 2004 to, among other things, try to redress this failure of imagination by stimulating a broad rethinking—in publishing, academia and the world at large—of books as networked objects. CommentPress is a happy byproduct of this process, the result of a series of "networked book" experiments run by the Institute in 2006-7. The goal of these was to see whether a popular net-native publishing form, the blog, which, most would agree, is very good at covering the present moment in pithy, conversational bursts but lousy at handling larger, slow-developing works requiring more than chronological organization—whether this form might be refashioned to enable social interaction around long-form texts.\\r\\n\\r\\nThe first of these projects was McKenzie Wark\\\'s GAM3R 7H30RY 1.1 (Gamer Theory), a book (then in draft form) whose aphoristic style and modular structure (Wark writes in numbered paragraphs) lent it readily to "chunking" into digestible units for online discussion. This is how it ended up looking:
\\r\\n\\r\\n\\r\\nIn the course of our tinkering, we achieved one small but important innovation. Placing the 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. Several readers remarked that it was no longer solely the author speaking, but the book as a whole (author and reader, in concert). \\r\\n\\r\\nOne might point out that this is nothing particularly new, that people have been writing in the margins of texts for centuries:
\\r\\n
\\r\\n
\\r\\nThis is of course true. But situating this practice in a digital network, allowing multiple readers to engage with a text simultaneously, and to engage with one another across time and distance, is something profoundly new. Also, the "fixity" of the text is called into question since it can constantly being revised. How to moor commentary to a shifting text is a major conceptual problem to be tackled.\\r\\n\\r\\nToying with the placement of comments was relatively easy to do with Gamer Theory because of its unusual mathematical structure (25 paragraphs per chapter, 250 words or less per paragraph), but the question remained of how this format could be applied to expository texts of more variable shapes and sizes. The breakthrough came with Mitchell Stephens\\\' paper, The Holy of Holies: On the Constituents of Emptiness. The solution we found was to have the comment area move with you in the right hand column as you scrolled down the page, changing its contents depending on which paragraph in the left hand column you selected. This format was inspired in part by a WordPress commenting system developed by Jack Slocum and by the Free Software Foundation\\\'s site for community review of drafts of the GNU General Public License. Drawing on these terrific examples, we at last managed to construct a template that might eventually be exported as a simple toolset applicable to any text.\\r\\n\\r\\n\\r\\n\\r\\nEver since "Holy of Holies," people have been clamoring for us to release CommentPress as a plugin so they could start playing with it, improving it and customizing it for more specialized purposes. Now it\\\'s finally here, with a cleaned-up codebase and a simpler interface, and we can\\\'t wait to see how people start putting it to use. We can imagine a number of possibilities:\\r\\n\\r\\n— scholarly contexts: working papers, conferences, annotation projects, journals, collaborative glosses\\r\\n— educational: virtual classroom discussion around readings, study groups\\r\\n— journalism/public advocacy/networked democracy: social assessment and public dissection of government or corporate documents, cutting through opaque language and spin (like the Iraq Study Group Report, a presidential speech, the federal budget, a Walmart or Google press release)\\r\\n— creative writing: workshopping story drafts, collaborative storytelling\\r\\n— recreational: social reading, book clubs
\\r\\n(Post links to your CommentPress projects on our Examples page.)\\r\\n\\r\\nOnce again, there are dozens of little details we want to improve, and no end of features we would love to see developed. Our greatest hope for CommentPress is that it take on a life of its own in the larger community. Who knows, it could provide a base for something far more ambitious.\\r\\n\\r\\nAn important last thought, however. While CommentPress presents exciting possibilities for social reading and writing on the Web, it is still very much bound by its technical origins, the blog. This presents significant limitations both in the flexibility of document structures and in the range of media that can be employed in writing and response. Sure, even in the current, ultra-basic version, there\\\'s no reason a CommentPress document can\\\'t incorporate image, video and sound embeds, but they must be fit into the narrow and brittle textual template dictated by the blog.\\r\\n\\r\\nAll of which is to say that we do not view CommentPress or whatever might grow out of it as an end goal but rather as a step along the way. In fact, this and all of the experiments mentioned above were undertaken in large part as field research for Sophie, and they have had a tremendous impact on its development. While there is still much work to be done, the ultimate goal of the Sophie project is to make a tool that handles all the social network interactions (and more) that CommentPress does but within a far more fluid and easy-to-use composition/reading space where media can mix freely. That\\\'s the larger prize. For the moment,though, let\\\'s keep hacking the blog to within an inch of its life and seeing what we can discover.\\r\\n\\r\\nA million thanks go out to our phenomenal corps of first-run testers, particularly Kathleen Fitzpatrick, Karen Schneider, Manan Ahmed, Tom Keays, Luke Rodgers, Peter Brantley and Shana Kimball, for all the thoughtful and technically detailed feedback they\\\'ve showered upon us in the days preceding launch. Thanks to you guys, we\\\'re getting this out of the gate on solid legs and our minds are now churning with ideas for future development.\\r\\n\\r\\nA chronology of CommentPress projects leading up to the open source release (July 25, 2007):\\r\\nGAM3R 7H30RY 1.1 by McKenzie Wark (launched May 22, 2006)\\r\\nThe Holy of Holies: On the Constituents of Emptiness by Mitchell Stephens (December 6, 2006)\\r\\nThe Iraq Study Group Report with Lapham\\\'s Quarterly (December 21, 2006)\\r\\nThe President\\\'s Address to the Nation, January 10th, 2007 with Lapham\\\'s Quarterly (together, the Address and the ISG Report comprised Operation Iraqi Quagmire) (January 10, 2007)\\r\\nThe Future of Learning Institutions in a Digital Age with HASTAC (Humanities, Arts, Science, and Technology Advanced Collaboratory) (January 17, 2007)\\r\\nScholarly Publishing in the Age of the Internet by Kathleen Fitzpatrick, published at MediaCommons (March 30, 2007)\\r\\n(All the above are best viewed in Firefox. The new release works in all major browsers and we\\\'re continuing to work on compatibility.)

Skins

Eddie Tejeda — Tue, 21 Aug 2007 19:44:20 +0000

download

Roadmap

Eddie Tejeda — Tue, 24 Jul 2007 22:18:30 +0000

Here's what we'll be working on for future releases of CommentPress:

now
• cleaning up functions
• widgetizing (support for widgets and creating CommentPress specific widgets)
• cleaning up and standardizing the sidebars (part of widgetizing)

soon
We need some feedback. We'd like to make it possible for people to view all the comments on a page at once, but we thought might change things in CommentPress. So here's a document that illustrates a few of those changes. Does anyone see any problems?
All Comments Draft (pdf)

later
• Get our code to validate as XHTML
• View all comments on a page
• Remove "comments-by-user" and "comments-by-section" and "general-comments" files and add them to functions.php
• "bookmarking" feature allowing readers to save places in a doc
• More style sheet organization, standardization and cleanup, and more explanatory comments
• *Use regular expression to do the replacing of content instead of the array exploding - (we could use some help on this one)

done
• Rename subtheme files to standard theme filenames
• Create a sub-theme folder and allow subthemes to extend CP (more than 'document' and 'blog' modes)
• Link/blogroll area in right sidebar
• Redesign the back end options interface and add more options to micro-manage functionality
• Style sheet organization, standardization and cleanup, and add explanatory comments
• Add panel to detect new versions from commentpress site
• Remove non-standard wordpress functions (hacks)

For a list of bugs that we're currently fixing, see the bug reports.

Examples

Eddie Tejeda — Fri, 20 Jul 2007 21:55:27 +0000

Show us what you've done with CommentPress! Use the comment thread for this paragraph to post links to your sites...

The projects listed below were all developed by or in partnership with the Institute for the Future of the Book using earlier versions of CommentPress:

— GAM3R 7H30RY 1.1 by McKenzie Wark
— The Holy of Holies: On the Constituents of Emptiness by Mitchell Stephens
— The Iraq Study Group Report with Lapham's Quarterly
— The President's Address to the Nation, January 10th, 2007 with Lapham's Quarterly
— The Future of Learning Institutions in a Digital Age with HASTAC (Humanities, Arts, Science, and Technology Advanced Collaboratory)
— Scholarly Publishing in the Age of the Internet by Kathleen Fitzpatrick
— Call to Action with the Canadian Education Association (bilingual!)

Development

Eddie Tejeda — Fri, 20 Jul 2007 21:54:42 +0000

More coming soon...

The important files
commentpress/javascript/frivolous.js - The javascript that allows for all the magic that happens in CommentPress around reading and writing comments, indicating active paragraphs, and other niftyness throughout the theme.
commentpress/functions.php - The PHP that handles installation and implements/extends Wordpress functions.
commentpress/comments.php - This file is the template for the comment box that is at the center of the CommentPress interaction. It has the code for the default state (including the "How to read/write a comment" text), and the code for reading and writing comments (in conjunction with frivolous.js).
commentpress/comments-by-user.php - This file lists each person who has contributed an approved comment, and the comments themselves. Included by commentpress/page.php
commentpress/comments-by-section.php - lists each section or post and the comments associated with that post, organized by date posted.

The style sheets
commentpress/reset.css Resets browser defaults so that every browser is on an equal playing field.
commentpress/master.css Basic styles for html tags, and the basic structural containers of the style (container, header, footer, page, sidebar)
commentpress/style.css Where most of the commentpress specific styles reside. It has all the classes for the styles we use in this theme.
commentpress/style_ie.css Any IE related styles necessary to bring it into line. So far, only one declaration necessary. We hope to eliminate this entirely.
commentpress/subthemes/blog/style.css Styles specific to the blog theme (only a few to manage differences on the front page)
commentpress/subthemes/document/style.css Styles specific to the document theme. Even fewer than the blog theme.

The subthemes
commentpress/document/*.* - These files are included by the CommentPress document subtheme. The document subtheme presents content as a unified document broken into sections. It is meant to be used for finite works - not ongoing works like a blog. That's next.
commentpress/blog/*.* - These files are included by the CommentPress blog subtheme. The blog subtheme present content as a blog.

Bug reports

Eddie Tejeda — Fri, 20 Jul 2007 21:53:55 +0000

Our running list of bug fixes.
Looking for a place to tell us about a bug?
Email us at eddie [at] futureofthebook {dot} org.

For an idea of the features we're planning for CommentPress, see the RoadMap.

Formatting Your Document

Eddie Tejeda — Fri, 20 Jul 2007 21:52:27 +0000

CommentPress breaks up content into a commentable form according to paragraph breaks (

). Wordpress automatically inserts paragraph tags into your document when it detects two line breaks. This works well for most texts, but if you'd like more flexibility in determining how you break things up into commentable units, you can insert your own

to group together multiple paragraphs.

To keep two or more paragraphs within a single comment block, try separating them with two break tags
instead of using paragraph tags

. That's how we kept this paragraph inside the same commenting block as the one above.

We realize that when you reorganize things in this way the term "paragraph" begins to get a bit wobbly. We thought of calling them "lexias" (units of reading) but that seemed a little too obscure. Let us know if you have any other ideas.

Also, a heads up: you may encounter minor problems if you use lists, blockquotes and other more elaborate formatting. We also don't know how well this plays with video embeds. These are areas we hope to improve in the not-too-distant future.

One further note about structure. In "document" mode (i.e. not "blog" with a steady inflow of new content), the order of pages is determined by the time the posts were created (oldest to newest). To reoder your table of contents simply edit the post timestamps into the desired chronological sequence.

Installation

Eddie Tejeda — Fri, 20 Jul 2007 21:51:33 +0000

Before you use CommentPress, you need to have Wordpress properly installed and configured, FTP access to your server, and permissions to install themes.

To install CommentPress, follow these steps:
  1. Download the .zip or .tar file and extract the folder.
  2. Connect to your web host with an FTP client and access the directory wp-content/themes in your Wordpress directory.
  3. Upload the folder into wp-content/themes.
  4. Log in to your WordPress Administration Panel.
  5. Select the "Options" tab from the administrative menu.
  6. Select the "Permalinks" from the sub-tab.
  7. Under the "Common options", select your URL format (anything but "Default").
  8. Next, select the "Presentation" tab from the administrative menu.
  9. Under "Available Themes," select "CommentPress."
  10. A new sub-tab will appear under "Presentation" called "CommentPress Options."

  OPTIONALLY: You can click on "CommentPress Options" to change presentation mode (from "document" to "blog" mode).

And that's it! Your installation and configuration is complete. Now, click on "View Site" in the header to see things in action.

NOTES

Please read the comments on paragraph 2 if you are having a problem with "unexpected end;". Thanks to ToddG we've discovered that all our coding shortcuts can cause problems if your PHP setup isn't equipped to handle them. I'm not sure about all the details just yet, but I'll post more when I do.

Download

Eddie Tejeda — Fri, 20 Jul 2007 21:51:19 +0000

commentpress-1.4.1.zip

commentpress-1.4.1.tar

View installation instructions.

See the changes for CommentPress 1.4.1

Changes in version 0.9.0
• Initial Release

Changes in version 0.9.1
• Fixed IE style bug that extended the margins
• Removed unused development files to make download smaller

Changes in version 0.9.2
• Fixed hardcoded URL in sidebar

Changes in version 0.9.3
• Changed hardcoded tagline to bloginfo('description'). -Thanks Kathleen F.
• Changed "a project of..." to "CommentPress is a project of...", so that it doesn't appear installed sites are if:book projects. -Thanks Kathleen F.
• Fixed hardcoded /commentpress path in sidebar. -Thanks Karen G.S
• Fixed query in comments-by-user (getUsersWhoHaveCommented(), getCommentsFromUser() ) to retrieve only approved comments. -Thanks Karen G.S
• Deprecated userBioPopUp() function
• Added version number in the footer

Changes in version 0.9.4
• Fixed comment count in Table of Comments (as of the last release, did not count properly)
• ~~Fixed javascript problem that did not hide "No comments yet" field when page was loaded from cookie~~
• Added 'General Comments' to table of comments
• Added message in comment area of comments being held in moderation
• Added list numbers the title of posts in the sidebar
• Added support to limit/allow registration and limit/allow registered and unregistered users to comment
• New CommentPress Option: Ability to change the title of table of contents. More of these options coming later.
• Style clean to General Comments and fix broken permalink to content.• Included micro-version number to stylesheet.

Changes in version 1.0
• Fixed bug that blocked the comment form from appearing when the option to register users is enabled
• Fixed bug that caused linked images to have to comment bubbles
• Added the time() to comments in comment index
• Fixed problems with queries not respecting privacy settings in posts
• For now, disabled the cookie that saves the state of each selected paragraph on each page
• Added an option to select the welcome page
• Added a links box on the sidebar in blog mode
• Added a proper description of the theme to style.css
• Fixed broken layout when search returned nothing
• Autodetection of latest version built into the backend control panel

Changes in version 1.1
• Fixed IE7 highlighting bug
• Added subtheme support inside CommentPress in the skins directory. Skins are automatically detected by backend
• Deleted development junk files that were not being used to decrease download size.
• Restructured directory and now have a directory called "javascript", "skins" and "plugins", for CommentPress specific plugins and javascript
• Renamed files in skins from document_style.css, document_index.css, document_single.css to skin.css, index.php and single.php, respectively
• Logout link appears in commentbox box when logged in
• Took database calls and queries outside of comments-by-* and added them to functions.php
• Changed index.php to support dynamic subtheme selection (managed by backend)
• After you post a comment, you stay in thread of that paragraph, rather than resetting the page.
• renamed container_* styles to match default Wordpress styles
• sidebar style: overflow changed to hidden to crop long words. (temporary fix for long words breaking the box)
• finessed recent comments excerpting: excerpt is first 90 characters or less. If it's longer than 90 char, adds [...] which is linked to comment.
• small edits to wording on the general_comments.php page
• changed the way theme specific files are included. Now uses the variable $commentpress_settings in the string instead of a switch case based on the variable

Changes in version 1.2
• Added Widget support! The widget implementation in Wordpress is a great first step in the direction of ease-of-use for non-technical users, but there are some very important things missing (can't duplicate, still need to hit the code to get multiple sidebars). Widget support in CommentPress 1.2 isn't totally nailed down. Widgets are implemented in the sidebar only. Widgets aren't currently supported on the blog index page (but they can be). We also need to do more work on widgetizing sections of the sidebar (one big one that's missing: the "Browse by"). This will be in the next release. See http://automattic.com/code/widgets/ for help with widgets.
• We've added a content license selector on the CommentPress options page. This will let you choose a CreativeCommons license for your own licensing needs.
• We've added internationalization support—we don't yet have any translations of the CommentPress interface, but we could.
• We've incorporated the standard Wordpress content functions [the_title(), the_content(), the_excerpt()], making CommentPress compatible with other plugins that use these functions.
• We have get_template() in place, so that you can rename a theme
• The options page got some flair.
• Skin stylesheet renamed to style.css, so metadata for your theme is automatically detected
• The CommentPress updater function wasn't working. Now it is.

Changes in version 1.3
Please delete your old CommentPress files before installing this version. Old files will mess with this version. This release of CommentPress introduces a new feature in the comment area: the Comment Overview. The Overview shows you a list of all the paragraphs on the page and a count of the comments on that paragraph. Clicking on the title of the paragraph will make it the active paragraph and open its comment stream. Also, the overview replaces the Help instructions; get help by clicking on the link at the top right of the comment area.
• Added a comment overview on each page.
• Detection for required plugins that are already enabled, so CommentPress doesn't overwrite that lovingly tailored plugin of yours. We do need to take over Brian's Threaded Comments though.
• Included the 'Skinner' plugin to change the look of your CommentPress install. This makes switching looks its own menu in the administrative interface, instead of an option on the CommentPress options page.
• Included 404 error page.
• All the titles are linked now.
• Widget sidebar is consolidated and the display changes to accommodate widgets if you're using them.
• New styles for comment streams and comment index pages. Hope you like it!
• Page jumping: active paragraphs align with the top of the comment area when you get to a post using a permalink, or click from the comment index pages. Known bug: We haven't gotten it working when you click from the comment overview. It will highlight and open the right stream, but it will jump the paragraph to the top of the browser window, above the comment area. Oops. We'll get it soon.
• Threading is working again
• call strip_tags on the_excerpt before trimming the paragraph number
• created a proper commentpress_post class
• before, installtion after the front page was loaded, which required a refresh to complete install. now installation is complete in the backend.
• fixed broken links when blog not in same path as install
• comments query fixed
• disabled the disabling of rich_editing
• Links in the table of contents are always black, and links in the Browse Comments box in the sidebar match the rest of the sidebar

Changes in version 1.4
(commentpress-1.4.zip)
(commentpress-1.4.tar)
• Fixed option to "revert to original settings" in the backend. Nothing happened in previous version.
• New Feature: Permalinks structures were required in previous versions. Now websites work without requiring mod_rewrite
• Fixed state issue on "overview", which disappeared when paragraph was selected
• Minor bug: reverting deletes commentpress_id_general_comments
• Fixed bug with cropped the first letter of an excerpt
• Search button was hardcoded and did not direct to form (thanks Dylan)
• When visiting a hyperlink with the suffix "#respond", the page or paragraph comment icons break (thanks Dylan)
• Fix link color in content from black to the blue
• Order by of comments is set to comment's date, not the comment ID
• Fixed return_comment() function in javascript
• Fixed jumps to align better with commentbox
• Fixed javascript that was reported when clicking "go to thread" in comment index
• Fixed error in whole page/paragraph number on the sidebar
• Fixed javascript:void(0) bug on Internet Explorer
• Discontinued the use of "short tags" in code, for wider compatibility ( • Added dashes at the end hardcoded URL paths, like "comments-by-user"
• Fixed comment submission: the function bnc_altertable() was commented out in previous version. This prevented comment submissions from working on new install - (thanks ToddG)
• Style changes: Redid padding for TOC list in document mode
• Style changes: Increased line-height for "lexia p" to and document intro text.

Changes in version 1.4.1
(released 1/21/08)
• Fixed WP 2.3 compatibility bug.