Expansion of a section of the page on comment posts on how to display received comments.
How comments are presented, should be, and who is doing what.
How to display
Goal: display received comments in high fidelity, at least as nicely designed as the comments that are "natively" displayed on blog posts and silo posts (e.g. replies on Twitter posts, comments on Facebook posts, Flickr/Instagram photos, etc. - see Silos below for analysis of their practices).
Per Accept a comment, your system should already be:
- Listening for webmention on your server (have your server software support it)
And when your server receives a webmention URL:
- parse the h-entry at that URL (only use the first h-entry if there's more than one, seriously, it's supposed to be a permalink) - use a microformats2 parser to do so.
- if its hyperlink to the original post lacks in-reply-to markup, then add it to the "Related Articles" or "Mentions" section in the post footer, otherwise keep going:
- get commenter information to display
- if the h-entry has a p-author, use its h-card:
- otherwise get the first* rel-author link on the page, retrieve the URL it points to, and use its representative h-card:
- url (of commenter profile/homepage)
- get the text of the comment to display
- if the h-entry has an e-content, use that (after filtering out unsafe HTML)
- if no e-content or it's too long (per your own site UI preference/design), then
- if the h-entry has a p-summary, use that (useful author crafted summary or for longer posts where only a part of it is the comment)
- if the p-summary is too long (per your own site UI preference/design)
- then truncate the p-summary yourself.
- else truncate the e-content if any yourself.
- otherwise (no e-content and no p-summary), if it has a p-name, use that
- if the p-name is too long (per your own site UI preference/design)
- then truncate the p-name yourself.
- if the text of the comment is too long (your site, your judgment), abbreviate it with some intelligent ellipsing code (e.g. see POSSEing an abbreviated note to Twitter for some thinking) and provide a "See more" link to the permalink.
- get more comment info to display
- use the h-entry dt-published for the time of the reply
- additionally, its dt-updated could be used for an "edited: datetime" annotation in your display
- use its u-url for the permalink (hyperlink the time of reply to the permalink)
- optional location brainstorm - because not many have implemented location info in posted replies
- use the h-entry p-geo / p-latitude / p-longitude for location - you may need to use a service to translate that into a human readable neighborhood / city / state / country name. perhaps hyperlink to a map, or an aggregation on your site of all posts (and comments) near that location.
- (Issue: perhaps h-entry could use a p-location property similar to h-event that would permit embedding of an h-adr with structured address information.)
With that information a sufficiently rich display should be possible in a "Comments" section in the footer on the original post permalink. Add to that for each comment:
And you've hopefully got a comment display of similar fidelity to anything the silos have.
Note: some of this has been implemented!
- Storytlr receives comment posts via pingback, then parses the post content and author information from the h-entry and h-card on the page, and then displays:
- ... what implementation will be next?
- is good enough because a) there aren't many multiauthor blogs, comparatively speaking, and more importantly b) this is retrieving a *reply* post, and those are always written by a single person, so there should only be a single rel-author on *that* page. Real-world counter-examples welcome.
How to markup
The post the comments are in reply to should be a top-level h-entry, and comments on it should be marked up as h-cites nested under the comment property. For example:
<h1 class="p-name">The Main Entry</div>
<p class="p-author h-card">John Smith</p>
<p class="e-content">Blah blah blah blah</p>
<div class="p-comment h-cite">
<p class="p-author h-card">Jane Bloggs</p>
<p class="p-summary">Ha ha ha great article John</p>
In addition, since the displayed comments are on the page with the URL that they are "in-reply-to", you can add an empty u-in-reply-to property which will automatically become the permalink when parsed due to URL absolute canonicalization rules. E.g. this inside each displayed comment:
<a href="" class="u-in-reply-to"></a>
Why would you want to do this? See: http://microformats.org/wiki/comment-brainstorming#Use_case_for_same_page_u-in-reply-to
- I think the h-cite markup only works for comments via pingback/webmention, but what about comments made directly on the post using a comment-form? -- pfefferle
How to delete
How to delete comments received from other sites.
If an indie web reply/comment post is deleted, that user's site is expected to send another webmention accordingly.
If when attempting to retrieve the reply permalink URL your server receives a 410 GONE, then your server is expected to delete the existing syndicated copy of that comment.
See handling deleted posts for details.
Current Indiewebcamp Practices
List of links in a post footer section:
- Tantek used to maintain lists of links to his posts of people’s names linked to comment permalinks:
In general existing blog/silo posts display comments (in either chronological or reverse chronological order) with the following details:
- commenter logo/photo
- commenter name
- hyperlinked to commenter profile
- full text of comment
- time of comment
- often in relative time since rather than absolute datetime
- hyperlinked to comment permalink
- commenter location (variable granularity) at time of comment writing
- hyperlinked to silo aggregation of activity at that location
- like/favorite button (to like or favorite the comment/@-reply)
Tumblr groups various different response types into a generic “notes” feed, at the bottom of each post (example). They show:
- The author’s username
- The author’s profile photo
Twitter shows all tweets which are both in-reply-to a particular tweet AND contain the original tweeters @name below the tweet metadata in chronological order. They provide a “reply” box above (?) the reply feed (example). The tweets have:
- The authors name
- The author’s @name
- The author’s profile photo
- A relative timestamp
- The tweet content
- A bunch of actions (on hover)
Facebook treats comments as completely secondary to “full” posts, showing them in chronological order beneath the post’s action bar. Facebook only show the latest ~4 comments if there are more, and display the leave-a-comment box below. They have:
- The author’s name
- The author’s profile photo
- The comment content
- A relative timestamp
- 'via mobile' if applicable
- Like button w/ like counter
Existing specifications for display
Included here for thoroughness / historical purposes - a critique of existing specifications for display.
Summary: Existing specifications either don't say much or provide bad advice for what to display (if anything) in response to receiving a webmention.
WebMention (the specification) does not say what to do with successfully received & verified webmentions.
Pingback (the specification) is very vague and somewhat contradictory. It says things like:
- "include this information on her site"
- could mean the link, the comment post, a portion thereof?
- "Bob's blogging system then includes a link back to Alice's post on his original post."
- implying that perhaps only links show-up from pingbacks
- "Reader's [sic] of Bob's article can follow this link to Alice's post to read her opinion."
- implying that readers can't see Alice's opinion on Bob's article, and have to follow the link to Alice's post to read it. seems a bit inconvenient, and not how comment presentation works on typical blogs, or silo posts.
- the "Conformance Requirements" do not mention any requirement for displaying pingback links or content therefrom on the original post
- in the "Example", it says:
"Bob's blog also retrieves other data required from the content of Alice's new post, such as the page title, an extract of the page content surrounding the link to Bob's post, any attributes indicating which language the page is in, and so forth.
"Finally, Bob's post records the pingback in its database, and regenerates the static pages referring to Bob's post so that they mention the pingback."emphasis added.
- This is vague but provides some additional display guidance which is unfortunately not very well thought out and leaves much to be desired:
- page title - this is odd as typical comments displayed on post pages don't have titles, just comment text.
- extract of the page content surrounding the link - in practice this is unreadable and unfriendly. It doesn't look at all like a comment and usually has both leading and trailing ellipses making you wonder what the broader context of the comment is.
- which language the page is in - this could be useful for marking up the display of the comment with a
lang attribute, and the link to the comment permalink with the
Pingback displays are nearly always useless, e.g.
- "Pingback from" is jargon - provides no value to the user - only noise
- the title of the comment blog post is useless as it provides a summary of the original blog post
- the [...] ... [...] summary text is nearly unreadable without more context, and doesn't even show what phrase linked to the original blog post
- in the first pingback, even just including the entire first paragraph of the comment post would have been better.And if it wasn't a reply then it should just be a list of related articles (date, author, linked post name, all marked up with h-cite), rather than including cryptic broken summaries.
- the overall visual design is very dated and has fallen behind modern comment presentation designs
Why use p-summary when I can truncate e-content
Q: I guess if I grab the e-content and think it's too long, I might as well just truncate it myself. why would I need the p-summary?
A: Because the p-summary is likely (or even just possibly) explicitly crafted by the author/publishers to be a more meaningfully truncated version of the e-content than you could yourself automatically truncate.
- Long posts where only a part of it is in-reply-to another post and a large chuck of it is a tangent should not be published as a reply/comment and instead should be published as a mention. Noting this here because this is accounted for above in the "How to display > get the text of the comment to display" section and it might wrongly send the message that (largely tangential) posts like these should be marked up with in-reply-to. (See )