Documentation for ucomment

Hide comments

How the comment system works

Note

This section is incomplete. Expanded documentation on how ucomment works will be coming soon.

How a web visitor leaves a comment

Visitors to the site must click on the side bar, next to the node they wish to comment on.

../_images/start-a-comment.png

Start a comment by clicking on the blue speech bubble.

Once they have typed in their comment, they must preview it before submitting it. They can click the Submit your comment button once they are satisfied with their comment’s accuracy.

../_images/preview-comment-then-submit.png

Visitors must first preview their comment before submitting it.

Server processing after a web visitor leaves a comment

The Django application will execute the submit_and_store_comment(...) function after a visitor has clicked the Submit your comment button. Quite a bit of processing takes place on the web server from this point.

  • The comment is compiled to HTML using the RST source entered by the visitor.

  • A CommentPoster entry will be created in the Django database, using the visitor’s email address and name. If an email address was not submitted, then an entry is still created using the user’s IP address and user agent string.

  • The reStructuredText (RST source code for the document is updated at the point where the comment was created.

    ../_images/comment-in-RST.png

    A reStructuredText directive is added to the document’s source as shown in the figure.

    The 6-digit code is a comment reference, while the 2-letter code is the comment node. More details on these are provided below.

    If you do not like your document’s source being altered, then ucomment may not be suitable for you. There are two advantages to this approach though - it allows you to trivially delete or move a visitor’s comment to another part of the document.

  • Of course we also must store the actual comment in the database, which is defined by the Comment class in the Django models.py file.

    This object has 3 foreign keys: a CommentPoster object, already discussed above; a CommentReference object and a Page object.

  • The CommentReference object stores the name of the RST source file, and the line number for the node which was commented on. It also stores the type of node (e.g. paragraph, title, list_item, image, literal_block), and the distributed version control system (DVCS) revision number for the file.

    In fact the CommentReference object, coupled with the DVCS is what makes this entire application work.

    For example: a user might load a webpage, commenting on a certain paragraph. In the mean time, the author commits a new version of the page, which changes the line number of the paragraph the user is commenting on. If the user submits the comment, and we only used line numbers to track the comment location, then is a risk the comment will attach to the wrong paragraph. (And of course all existing comments below the current one will also have to have their line numbers updated.)

    Comment references allow the comment to be successfully made to the correct paragraph, since we can always revert the state of the document to the version that the web visitor made the comment (we checkout an earlier revision). Then we rely on the DVCS to merge previous and current revisions.

    Below is a screenshot of the Django administration page for the CommentReference objects, illustrating the various types of nodes, their line number and their revision changeset number.

    ../_images/comment-reference-admin.png

    Note

    It is highly recommended that you use the built-in Django admin interface to view and understand how ucomment works. You can see all comments, document pages, people making the comments, etc.

    You will need to edit your Django project (not application) urls.py and settings.py files to enable the admin interface.

Workflow by the author to revise and republish the document

The intention of ucomment is that the author can frequently update the document. As comments are added by visitors to the site, the author might wish to incorporate their contributions to the document. Similarly, the author might want to remove any comments that are not relevant anymore, or, move the comments to an alternate location.

The approach is simple:

  1. Alter the RST sources for the document.

  2. Commit the updated document to the revision control system.

  3. Push the changes to the remote server.

  4. Republish the document by visiting the sites _admin page, e.g. http://example.com/document_root_page/_admin

Consider this documentation snippet as an example:

Django's primary goal is to ease the creation of complex, database-driven
websites. Django emphasizes reusability and "pluggability" of components,
rapid development, and the principle of `DRY (Don't Repeat Yourself)
<http://en.wikipedia.org/wiki/Don%27t_repeat_yourself>`_. Python is used
throughout, even for settings, files, and data models.

.. ucomment:: af2kpQ: 5t, r6,

This paragraph has 2 comments associated with it. The af2kpQ is the CommentReference for this paragraph, and the two nodes, 5t and r6, help the author locate the two comments in the database.

If the author wanted to remove both comments, s/he simply removes the ucomment directive line from the document. If the author would like to remove the 5t comment, s/he just deletes that portion, so that the directive remaining is just .. ucomment:: af2kpQ: r6,

When the document is republished, the Django database will automatically update the document, as desired.

Likewise, if the author wanted to move both comment nodes to another part of the document, s/he would just append that directive to that other part of the document, and then follow the 4 steps above.

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:      http://ucomment.org shows up as http://ucomment.org
  • 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.