Documentation for ucomment

Hide comments

What does this application do?

The value of a document published to the web can benefit tremendously from interaction with its readers. Their help with correcting typos, improving clarity, or enhancing the document with their experiences and notes is helpful for other readers, and the original author(s).

ucomment is a Django application that allows for web-based commenting on a document. Unlike other commenting systems, ucomment was developed specifically for commenting on evolving documentation. In other words, the comments are to be integrated (directly, or modified), into the document by the author, and then the revised document can be published again to the web. Comments can easily be moved to other locations in the document, or simply removed by the author.

ucomment will work also with documents that are static.

ucomment requires the author write the document using reStructuredText in one or more text files.

The Sphinx documentation generator is used to convert the reStructuredText to HTML output. This allows other powerful Sphinx enhancements to be used. Sphinx can also be used to generate PDF, ebook, and other output formats from your document.

A distributed version control system is used to track all revisions and comments added to the document. Currently only Mercurial is supported, others can easily be added.

Finally, Django is used to store all comments, page visits, user statistics, implement server-side search for the document, and comment administration, using the Django admin interface.

Once the document is published to the web, visitors may comment on the document. Comments must be approved by a site administrator (customizable), via a single-click URL to either accept or reject the comment. Once approved, comments will appear on the site with the next page refresh.

The Sphinx documentation generator already provides good-looking tabular output, mathematical equations, and so forth. But if you need further enhancements, simply adjust the templates and cascading style sheets elements that come with ucomment.

An example of ucomment in action is this website. The source code for this document is available here.

Other web-based commenting systems

Full credit for the idea of web-based commenting goes to various websites, particularly The Django Book which was the strongest source of ideas for ucomment. That site shows comments in a sidebar, with speech bubbles either containing a number (if there are existing comments) or no number. These bubbles invite the user to click on them to view the existing comments, or add their own comment.

The site for the book called Mercurial: The Definitive Guide follows a similar idea, but uses inline commenting. A link appears after every paragraph, figure, source code snippet, etc, that either shows “No comments” or “N comments”, where N is some integer.

ucomment implements the type of comments as used on the Django Book website. Inline commenting could be added to ucomment, but is not currently implemented. (I personally find inline commenting a bit distracting.)

Bullet point feature summary

  • Visitors to the document website can turn comments on or off (sometimes its nice to just read the document, without extra visual distraction!).

  • The document can be updated and republished on the web, and the original comments will correctly move to the updated location.

  • Links for Next, Previous and Table of Contents help the reader navigate the various sections of the document.

  • Comments are written in reStructuredText (allows for math, bullet points, tables, etc), and must be previewed by the reader before being submitted.

  • Once submitted, the comment administrator can approve or rejects new comments via email links; the comment submitter is informed of the decision by email also.

  • Email alerts are sent to the site administrator if any errors occurs.

  • The settings for comment acceptance are flexible. For example, the default settings will auto-approve future comments from a poster who has submitted 3 or more approved comments in the past.

  • Any comments can always be removed from the document’s web output by marking a checkbox in the Django admin site, or by deleting the comment from the Django database.

  • An option exists so that long tables of contents are can be shrunk and expanded using Javascript. See the TOC for this website as an example.

  • When the user navigates back to the table of contents they are shown the page they came from; to help navigate large documents.

  • Support for mathematics and comments on equations: MathJax and pngmath (a Sphinx extension) have been tested.

  • Simple, full text search of the document is available; a feature request is that other 3rd party search plugins can be used instead.

  • Search is accessible via a URL: Term/AND/case=False

    will perform a case-insensitive search for the word search and Term. The AND can be replaced with OR.

  • A customizable template is provided so that you can render the page within your existing website and surround the document content with other content. Templated items include:

    • The main content area

    • Sidebar containing the search box and the local ToC

    • Page navigation elements

    • Emails sent to users and the site administrators

  • Basic tracking of page hits (visits) and page popularity can be followed in the Django admin interface. (see code in the application’s file to modify the admin interface).

  • A server setting exists to stop all commenting on the document, and to not display any existing comments.

  • Experimental: long chapters or sections in the document can be optionally split into smaller subsections that each appear on their own HTML page.

    For now, if you wish to split up a long document you must write the section in separate RST files. The experimental features allows you to edit inside single RST files, but then automatically splits them up.

Contribute your comments (this window can be dragged out of the way)X

(Please read the help on commenting)

Want to add to the discussion? Please click here.

About this comment system

This pages uses a commenting system to obtain your feedback. Feel free to ask questions, provide your perspective, or leave a relevant comment on any block of text, bullet point, code, or chunck of content.

To get started, please click on the vertical sidebar, near the content you would like to comment on. It will highlight the section you are commenting on.

Shows how the comment system works

After being approved, your comment will appear on the website. Please provide your name and email address if you would like to receive credit for your contribution.

Please note that we reserve the right to edit or remove a comment, and that you give us permission to use your contribution.

How to comment

  • Italics:    *italic text*
  • Bold text:     **bold text**
  • monospaced text:     ``monospaced text`` (use backquotes)
  • Hyperlinks are automatically detected: shows up as
  • Unnumbered bullet points use * asterisks, while numbered points use a # hash mark.
    * This is a bulleted list.
    * It has two items, the second
      item uses two lines.
      #. Point one.
      #. Point two.
  • Mathematics: \(e^{i\pi} + 1 = 0\) will show as Euler's famous equation, \(e^{i\pi} + 1 = 0\), if the site administrator has allowed mathematics in the comments. Similarly, you can use \[ ... \] to write a stand-alone mathematical equation.

    See this page for help with writing math equations.

Tables, source code and other elements can also be added to your comment; please read more here.