La Quadrature du Net


General Presentation

co-ment is a web based text annotation system. COMT is the open source software behind it. See for more details.



Notification and feeds


co-ment 2 collaboration is based on assigning roles for users. Click here for more details. The basic assumption in the collaboration model is that some users will have an overall management role, while others will have roles that are defined in relationship with texts or a given text.


Comment moderation is the process of editing/removing comments from a text. The moderator role is the collection of permissions required to edit/remove a comment submitted by users of the workspace. Although this is not the default, you can require comments to be approved before becoming public by unticking the "a posteriori moderation" box in the settings for the text. If you do so, comments from users with an Observer or Commentator role won't be visible to users who do not have moderation permissions before a user (with at least Moderator role) approves them.
co-ment uses states to implement moderation policies. Click here for more details. Unapproved or pending comments are visible only to Managers, Editors and Moderators. Approved comments are visible to users with any role. The pending state exists only when a priori moderation is selected in settings.
We believe that an adequate use of tags is sufficient to implement a variety of workflows for processing comments. You can use tags for signalling TODOs or decisions on future revisions. You can also use them to classify comments according to the issues or topics they address.
Linking to a comment
You may find yourself needing to link to a comment from another one. In such case you can do so by copying your target comment's permalink that shows up when you hover over the paragraph (¶) sign at the end of the comment title.
The scope of the comment is the part of the text to which it applies. A comment's scope can be modified by anyone who has a role allowing to modify the comment.
Keeping your comments across versions
When you create a new version of the text, comments are duplicated. In case the text edition did not change the scope of the comment, it will be kept "as is". If the text of the comment scope has been modified then a decision has to be made regarding the conservation of such comments in the new version: you'll be given a choice of either keep them in the new version as "detached" from the text (they do not have a scope in the new version's but are still visible when browsing, and you can give them a new scope) or simply removed from the new version.

Notification and feeds

Email notification
Email notifications are a way for users to be informed by email when a new comment is added on a text or a text is edited and a new version gets created.
Web feed definition on Wikipedia. You can subscribe to the feed for a specific text or to a global feed for the full workspace.
Public and private feeds
The public feed includes all the events publically accessible on the workspace or a specific text. The private feed includes all events: do not publicize it to people who are not registered in your workspace unless you really want them to know what's happening in it.
Text embedding
You can embed your text into a page of your own website. Visitors will be able to add comments without leaving your website if the anonymous users' roles on the text allow it. For a proper test condition when embedding in your own site, in particular for experiencing links referencing comments in the same or different text, be sure you are not logged into your workspace in another tab of your browser.


Roles are predefined sets of permissions.
A text is visible to the public (non-logged-in visitors, aka anonymous users) only if anonymous users are given a role on the text.
Text role
A text role is a role that is set for a specific user on a specific text. It can be used to override a possibly existing workspace-level role or to give a user a role on a text (and not on every text in the workspace).
Role model
A role model is a role set useful in a specific use case. When you set up a co-ment service, you have to select a role model. The default model addresses most cases. A specialized role model such as "teacher" includes specific roles making in this particular case possible for comments to be privately shared between a teacher and each student.


Create or upload?
There are 3 main ways to produce a text in co-ment. If you start from scratch, create your text in markdown format. If you start from an existing file upload it to a markdown format. If you start from a Web page, create a text with HTML as format, and copy and paste the full Web page into the editor.
Text formats
There are at this date 3 text formats: markdown (default/preferred format), HTML and RST.
Unless some import needs make it preferable to use HTML, we recommend that you use markdown for creating or importing texts. Our software and Web services use the pandoc extended version of markdown. Read more about this.