comment-brainstorming

See instead: https://indieweb.org/reply and https://indieweb.org/comments

This is a brainstorm for comment microformat. Examples of a comment can be found here comment-examples

Problem

Shortform: How do you publish comments on your own site, and how do you publish comments others have made on your posts?

Longform: How do you publish your own comments, others' comments on your stuff, and how do you track comments? How do you track the comments you have made on blogs, comments made on blogs you're interested in and comments other people have made on your own blog?

How can you do this in a pragmatic way, ingested into some kind of data store, searched or aggregated?

Distinction between Comment and List of Comments

Ideally, each comment/reply should have its own permalink page, but also get copied into the markup of the post it's in reply to. Should the markup of the two cases differ? We should be able to solve both problems by extending h-entry a little.

• A reply on its own page is just another h-entry. The presence of u-in-reply-to implies its a reply (of a sort, could also be a special reply like an RSVP).
• If a comment does have its own permalink page and also copied to a list of comments on a post, it should likely be marked up as an h-cite in the list of comments, and link to its canonical copy on its own page.
• If a comment only exists as part of a list of comments, then using h-entry for it there seems fine, since that's likely the (only?) canonical copy of the comment. Tantek 21:27, 12 July 2015 (UTC)

Discovered Elements

Based on the analysis of 25 real world examples of a comment, the results can be found at the Comment Analysis section

The following properties occur most regularly across all examples (84% or more)

• comment 100%
• author 96%
• published 96%
• author-url 84%

Other achievable elements

• comment-link (permalink) 60%

microformats2 p-comment h-entry

For publishing others' comments on your posts, including syndicating in others' comment posts onto your posts:

Proposal

How to:

• post h-entry with property p-comment h-entry (child) for a comment
• one such p-comment h-entry per comment
• each comment should have an ID attribute and a u-url permalink inside
  • maybe with dt-published on same element or child <time> element
  • if comment was syndicated in, link to original with u-url rather than local ID.
• u-in-reply-to on the child comments so they can be easily extracted out of context
  • e.g. a simple <a href="" class="u-in-reply-to"></a> inside the p-comment h-entry would connect the context of the page URL (post permalink) as what is being replied to.
• p-content for the contents of plain text comments
  • e-content if you trust the markup from others' comments (or your comment entry HTML stripping/simplifying code)
• explicit p-name markup either the whole p-content of the comment, or perhaps the first sentence as a simple abbreviation (perhaps useful for syndicating the comments into a feed).
• should have p-author h-card for the comment author

Notes:

• no need for h-feed because p-comment property value can already be an array
• any consumer of the comments can decide sort order for themselves, i.e.
  • published order (order in the p-comment array)
  • chronological order by dt-published of the p-comment h-entry elements
  • or reverse chronological order using the same
• No real need for h-comment on the child h-entries as h-entry already covers everything a comment needs
  • • and simply adding u-in-reply-to isn't really sufficient to justify the overhead/complexity of a new root microformat "h-comment"

<div class="h-entry">
  <h1 class="p-name">A Blog Post</h1>
  
  •••

  <div class="p-comment h-entry" id="comment-1"><a href="" class="u-in-reply-to"></a>
    <a class="p-author h-card" href=...><img alt=author1 src=...></a> 
    <span class="p-name p-content">The First Comment</span>
    (<a class="u-url dt-published" href="#comment-1">YYYY-DD-MM HH:MM</a>)
  </div>
  <div class="p-comment h-entry" id="comment-2"><a href="" class="u-in-reply-to"></a>
    <a class="p-author h-card" href=...><img alt=author2 src=...></a> 
    <span class="p-name p-content">The Second Comment</span>
    (<a class="u-url dt-published" href="#comment-2">YYYY-DD-MM HH:MM</a>)
  </div>
  •
  •
  •
</div>

Questions

Use case for same page u-in-reply-to

Q: What is the use-case for the same page u-in-reply-to?

A: The use-case for the same page u-in-reply-to is applications/sites that may subscribe to the comments as a feed, perhaps mix them in with other comments/entries. Having an explicit u-in-reply-to makes the comment portable. It's not critical, but it is also a simple/good pattern that encourages extracted data to be self-contained in general.

• Note: this use-case is currently theoretical, no one is actually doing or asking to do this yet. Tantek 20:09, 12 July 2015 (UTC)

Notes

Note simplifications from microformats2 h-feed p-comments proposal:

• no h-feed
• one fewer div / less hierarchy than proposal above

microformats2 h-feed p-comments

For publishing others' comments on your posts:

Proposal

• h-entry with child h-feed p-comments
  • h-feed because it’s a bunch of h-entries in (reverse) chronological order
  • p-comments to explicitly declare the children as comments, expose array on hEntryObject.comments
  • No real need for h-comment on the child h-entries as h-entry already covers everything a comment needs
• Each comment should have an ID attribute and a u-url
• Perhaps u-in-reply-to on the child comments so they can be taken out of context and still used?
  • Where would it go in markup?

<div class="h-entry">
  <h1 class="p-name">A Blog Post</h1>
  
  •••
   
  <div class="h-feed p-comments">
    <div class="h-entry" id="comment-1">
      <h2 class="p-name">The First Comment</h2>
    </div>
    <div class="h-entry" id="comment-2">
      <h2 class="p-name">The Second Comment</h2>
    </div>
    •
    •
    •
  </div>
</div>

• -1 for too much markup compared to .h-entry > .h-entry.p-comment --bw 09:54, 13 May 2013 (UTC)

older pre-microformats2 proposals

Schema I

Proposal:

• hentry (root class name)
  • The hentry element represents an individual entry for a comment.
    1. http://microformats.org/wiki/hatom#Entry

• author (author) 96%
  • an Entry Author element MUST be encoded in a hCard
    1. http://microformats.org/wiki/hatom#Entry_Author

• url (author-url) 84%
  • Use the url value of a hcard

• entry-content (comment) 100%
  • The "logical Entry Content" of an Entry is the concatenation, in order of appearance, of all the Entry Contents within the Entry
    1. http://microformats.org/wiki/hatom#Entry_Content

• updated (date) 96%
  • use the datetime-design-pattern to encode the updated datetime
    1. http://microformats.org/wiki/hatom#Entry_Updated

• bookmark (comment-link) 60%
  • By adding "bookmark" the author is indicating that the page http://someblog/post#comment-001 is a link to a key entry point within an extended document.

Example

• source: [1]
• See also Working Examples

<div class="comment hentry" id="comment-7">
	<p><span class="entry-title">
      <cite class="author vcard">
        <a class="url fn" href="http://notizblog.org" rel="contact external" title="Link to Matthias Pfefferle">Matthias Pfefferle</a>
      </cite> said
    </span> 
    <span class="comment-date">about: 
        <abbr class="updated" title="2008-09-02T01:20:32+01:00">85 days ago</abbr>
    </span></p>
	<div class="entry-content">
      <q cite="http://notizblog.org">Awesome! It works perfect for me. 
      Do you know if its possible to use the firefox microformats api with ubiquity? 
      And by the way... nice webslices implementation on your blog.</q>
  </div>
  <p><a rel="bookmark" href="http://weborganics.co.uk/articles/show/ubiquity-the-best-thing-since-web2-0#comment-7" title="Permalink to this comment">Permalink</a></p>
</div>

Transformation

<entry>
    <title>Matthias Pfefferle said</title>
    <id>http://weborganics.co.uk/articles/show/ubiquity-the-best-thing-since-web2-0#comment-7</id>
    <link rel="alternate" href="http://weborganics.co.uk/articles/show/ubiquity-the-best-thing-since-web2-0#comment-7" 
          title="Permalink to this comment" type="text/html"/>
    <updated>2008-09-02T01:20:32+01:00</updated>
    <content type="xhtml">
      <div xmlns="http://www.w3.org/1999/xhtml">
        <q cite="http://notizblog.org">
        Awesome! It works perfect for me. 
        Do you know if its possible to use the firefox microformats api with ubiquity? 
        And by the way... nice webslices implementation on your blog.</q>
      </div>
    </content>
    <author>
      <name>Matthias Pfefferle</name>
      <uri>http://notizblog.org</uri>
    </author>
</entry>

Working Examples

• Comments Marked up using just hatom example
  • hAtom to Atom transformation example
  • Screen grab of atom feed viewed in Safari web browser example

• Comments marked up using hAtom example (note: rel="in-reply-to" usage in comments)
  • hAtom to Atom transformation example

Parser Notes

• If the entry-title element is not used, the atom:title element SHOULD use the author value of the hentry presented in a contextual way, for example by prefixing the author value with "by" or appending it with "said" or "says".
• The entry-title element SHOULD provide textual content and not be an empty string.

Summary

• This proposal means that on the whole nothing much is needed for a comment microformat, a comment can re-use terms outlined in the hAtom Microformat

References

• Comment Formats
• hAtom Microformat

Design Notes

• Linked Data (Tim Berners-Lee 2006)
• Dereferenceable Uniform Resource Identifier (Wikipedia)

Schema II

Proposal:

• reuse hAtom
• if Entry "B" is in an Entry Comments element of Entry "A", then Entry "B" is a comment on Entry "A"
• an Entry Comments element is identified by using both class names "hfeed comments"

<div class="hentry">
   <h3 class="entry-title">The blog post title</h3>
   <div class="entry-content">The blog post text</div>
   (etc)
   <div class="hfeed comments">
       <div class="hentry" id="p0001">
          <div class="entry-content">Comment #1</div>
          (etc)
       </div>
       <div class="hentry" id="p0002">
          <div class="entry-content">Comment #2</div>
          (etc)
       </div>
   </div>
</div>

Details

• if there is no Entry Title for a comment it can be assumed to be empty, it can be invented by the parser
• this was discussed at SGFooCamp, see: http://www.flickr.com/photos/90594399@N00/2271787498/

Specific Example from the Wild

hAtom Comments changes are marked IN UPPER CASE LETTERS FOR VISIBILITY. Assume them to be the normal case in otherwise

(section to be completed)

Feedback

If we can indicate that the hAtom entries are also comments, we could add an indicator beside hAtom.

<div class="hfeed hcomment">

hAtom pattern goes here.

</div>

Alternatively, we could add hcomment with hentry to indicate that the following hentry can be treated also as a comment.

<div class="hentry hcomment">

hEntry pattern goes here.

</div>

--Sarven Capadisli 11:59, 25 Sep 2008 (PDT)

• If an hfeed is embedded in an hEntry, that could be enough context to show "these items are replies to the one they're embedded in" singpolyma 12:20, 25 Sep 2008 (PDT)

hAtom and in-reply-to

A user comment (e.g., in blogs, wikis, forms) can be marked as an hAtom since it has a similar content pattern. A way to differentiate an hEntry (e.g., a blog post) from another hEntry (e.g., a user comment) can be done reusing in-reply-to from Atom Threading Extensions. It provides a mechanism to indicate that an entry is a response to another resource. rel="in-reply-to" can indicate that the current hEntry is a reply to another hEntry and has a reference point @href:

<a rel="in-reply-to" href="#comment_20080902144745">Parent</a>

hEntries that use rel="in-reply-to" can be considered as a comment entry in response to a parent entry in the threaded conversation (e.g., in blogs, wikis, forms).

hEntries that are chronologically listed can all use rel="in-reply-to" and refer to the root hEntry (e.g., blog post, form post)

By reusing in-reply-to, we can solve the microformats representation for user comments [2], [3], [4].

Example comment using in-reply-to: http://www.csarven.ca/my-responses-are-in-white

--Sarven Capadisli 21:25, 3 Oct 2008 (PDT)

Idea Consolidation

This is a list of all the various "micro-ideas" that have been discussed on the mailing list in the Wiki, to capture everyone's thoughts and preferences.

• "examples covered" indicates the percentage of examples that can be marked up without presentation changes
• Add your comments, objections and votes (-1, 0, +1) as a sublist in "comments" with your wikiname.

use hAtom Entry for a comment

• notes:
• test cases covered: 95%
  • the blogger comments marked as a definition list is problematic, as there is no object that wraps an entire comment
• comments and votes:
  • +1 Martin McEvoy
  • +1 TobyInk
  • +1 David Janes
  • +1 Sarven Capadisli
  • +1 Singpolyma

mark the comment permalink with rel="reply"

• notes:
  • By adding "rel-reply" the author is indicating that the resource indicated by the href is a "reply" to the current document.
• test cases covered:
  • 60%
• comments and votes:
  • -0.5 David Janes I have several objections: this seems to be a proper subset of what could be covered by marking a comment hEntry with class="comment", and it seems to being opening up a general "reply/threading" microformat that should be completely and independently analyzed. I have doubt too about how well this will work if the document that's being replied to is specified with hashed URL.
    • Agreed, this needs separate analysis with more use cases Martin McEvoy

mark the comment permalink with rel="in-reply-to"

• notes:
• test cases covered:
• comments and votes:
  • Who proposed this? Sounds like an an abuse of the meaning of rel. -1 from me. TobyInk

add an independent rel="in-reply-to" link

• notes:
• test cases covered:
• comments and votes:
  • As long as it's optional (i.e. not the only way to mark that an hentry is a reply to something), my vote is +1. TobyInk
  • David Janes -1. This seems be inventing something that for the most part is already covered, i.e. is entirely an orthogonal solution. I do not deny this could be of great utility as part of a general threading microformat, but that would have to be independently analyzed.
  • Sarven Capadisli +1 for optional because it has potential to handle various types of commenting where an hentry is a response to another hentry (anywhere):
    • chronological comments
    • threaded comments
    • a blog entry as a reaction to another blog entry
    • microblogging replies

add class="comment" to the comment Entry

• notes:
  • All the examples studied were the concept of a comment
• test cases covered:
  • 95% (note the usual DL/DT issues in some Blogger templates)
• comments and votes:
  • +1 Martin McEvoy
  • 0 David Janes although it covers 100% of the examples, hAtom does have the concept of a cluster of related Entries, and thus I feel it would be better modeled that way.

add hAtom Entry Feed around all comments

• notes:
• test cases covered:
• comments and votes:
  • +1 TobyInk
  • -1 un-necessary just use class="comments" Martin McEvoy
  • 0 unnecessary where there is an indicator for each comment entry if they are chronologically listed as a response to the main post. Perhaps for threaded comments, however, in that case, class="replies" or class="comments" may be more suitable. Sarven Capadisli

add class="comments" (or similar) to a element around all comments

• notes:
• test cases covered: 10)%
• comments and votes:
  • +1, but would prefer class="replies" because of analogy with Atom. Better to reuse an existing vocabulary than pull terms out of a hat. TobyInk
  • +1 David Janes. I'm thinking of this as Entry Replies, which would be physically represented as whatever. Using Entry Replies around all comments would reflect the fact that in 100% of the examples comments come in bunches.
  • +1 There is no reason why not Martin McEvoy
  • +1 Sarven Capadisli. I also prefer class="replies" as it is consistent with the vocabulary in Atom Threaded Extensions.
  • -1 class=hfeed is more generic and conveys the meaning of "reply" when nested Singpolyma

use XOXO to mark up comments

• notes:
• test cases covered:
• comments and votes:

Twitter is a comments system

• notes:
• comments and votes:
  • Indeedy. TobyInk
  • -1 David Janes. Twitter has nothing in common with the other comments system listed. In particular, all replies on Twitter are first class "posts" on your own twitter stream, are done in your own user context, and may not even be replies as they may be conversation initiations.
  • +1 Sarven Capadisli. Microblogging notices that only lead with the "@" character (see twitter.com or identi.ca: e.g., "@username Monkey see monkey do") can be considered as replies. If replies are considered to be comments then the system caters user commenting. However, not all notices are comments (responses, replies) because they are standalone messages. The "@" convention is considered to be a reply since the notice also ends up in that user's replies stream. A side note here: using rel="in-reply-to" on the "in reply to" anchor in notices that lead with "@" creates a linkable comment.

A comment microformat should deal with hierarchically nested comments

• notes:
• comments and votes:
  • assuming that there is some kind of explicit, programmably-discoverable link between the comments and the thing being commented on (be it through nesting, an anchor link or some other method), then it is almost unavoidable that a comment microformat would be able to deal with hierarchical comments. After all, a hierarchical set of comments is merely a set of comments such that some of the comments are comments commenting on other comments. (I wonder if I could have avoided using the word "comment" six times in that previous sentence?) TobyInk
  • +1 Yes As all comments that I have looked at DO have a hierarchical structure, some nested inside each other as replies to other comments. I believe in "most" cases xoxo (<ol> and <ul>) can address the problems of structure and hierarchy, this SHOULD however be totally optional, or maybe just a design note Martin McEvoy

if hAtom Entry is used, the Entry Title if not present should be X

• comments and votes:
  • +1 Use the author value of the hentry presented in a contextual way, for example by prefixing the author value with "by" or appending it with "said" or "says" Martin McEvoy
  • David Janes I'm happy to have whatever made up by parser implementers, which seems to be the way Atom feeds happen today. I have issues with specing English words, as it's non-I18N friendly.
  • -1 because entry-title doesn't have to be an explicit title that is entered by the commenter. entry-title could be based on the information that already exists e.g., "John Smith commented on 2008-11-24". I don't think making up data (even if it is "X" or null) from thin air to satisfy the parsers is the right approach. This also wasn't the case for regular (non-comment) hAtom Entries. Sarven Capadisli

suggested usage template for above

• notes
  • bla bla bla
• test cases covered:
  • 50%
• comments and votes:
  • +1 this is a great idea - SomeUser
  • -1 this doesn't even work in have the cases - SomebodyElse
    • you don't even know how to spell "half" - SomeUser

See Also

• comment problem
• comment-examples
• comment-formats
• comment-brainstorming
• comment-issues

Related:

• hAtom
• hAtom comment brainstorming.