Skip to content

Commit

Permalink
copy @dissolve first cut at translating from wiki, add a bit
Browse files Browse the repository at this point in the history 
Copy https://github.com/dissolve/post-type-discovery/blob/master/index.html @dissolve first cut at translating from wiki https://indiewebcamp.com/post-type-discovery, add some more headers for issues, repo etc.
  • Loading branch information
@tantek
tantek committed Jun 7, 2016
1 parent ccda96a commit a2335cf
Showing 1 changed file with 348 additions and 0 deletions.
348 changes: 348 additions & 0 deletions index.html
View file
@@ -0,0 +1,348 @@
<!DOCTYPE html>
<html>
<head>
<title>Post Type Discovery</title>
<meta charset='utf-8'>
<script src='https://www.w3.org/Tools/respec/respec-w3c-common'
async class='remove'></script>
<script class='remove'>
var respecConfig = {
license: "w3c-software-doc",
specStatus: "ED",
shortName: "ptd",
edDraftURI: "https://www.w3.org/wiki/Post-type-discovery",
editors: [
{ name: "Tantek Çelik",
url: "http://tantek.com/"},
],
wg: "Social Web Working Group",
wgURI: "http://www.w3.org/Social/WG",
wgPublicList: "public-socialweb",
wgPatentURI: "http://www.w3.org/2004/01/pp-impl/72531/status",
license: "w3c-software-doc",
otherLinks: [{
key: 'Repository',
data: [
{
value: 'Github',
href: 'https://github.com/tantek/post-type-discovery'
},
{
value: 'Issues',
href: 'https://github.com/tantek/post-type-discovery/issues'
},
{
value: 'Commits',
href: 'https://github.com/tantek/post-type-discovery/commits/master'
}
]
}],
localBiblio: {
"AS1": {
title: "JSON Activity Streams 1.0",
href: "http://activitystrea.ms/specs/json/1.0/",
authors: [
"J. Snell",
"M. Atkins",
"W. Norris",
"C. Messina",
"M. Wilkinson",
"R. Dolin"
],
status: "unofficial",
publisher: "http://activitystrea.ms"
},
"h-entry": {
title: "Microformats h-entry draft specification",
href: "http://microformats.org/wiki/h-entry",
authors: [ "Tantek Çelik"],
status: "Living Specification",
publisher: "http://microformats.org"
},
"microformats2": {
title: "Microformats 2 draft specification",
href: "http://microformats.org/wiki/microformats2",
authors: [ "Tantek Çelik"],
status: "Living Specification",
publisher: "http://microformats.org"
}
}

};
</script>
<link rel="webmention" href="https://webmention.io/w3c/webmention">
</head>
<body>
<section id='abstract'>
<p>
Post Type Discovery specifies an algorithm for determining the type of a post
by what properties it has and potentially what value(s) they have, which helps
avoid the need for explicit post types that are being abandoned by modern post
creation UIs.
</p>
</section>

<section id='sotd'>
<p>
This is a W3C Editor's Draft, and a snapshot of the IndieWebCamp specification
of the same name, as of 2015-10-14
</p>
</section>

<section class='informative'>
<h2>Introduction</h2>
<p>
Post type discovery is an explicit algorithm for inferring the type of a post from other properties of that post.
</p>
<p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [[!RFC2119]].</p>
</section>

<section id='usecases' class='informative'>
<h2>Use Cases</h2>
<p>
Both creation user interfaces, and post presentation designs are evolving to
directly use the presence or absence of specific properties (and their values)
directly, rather than depending on any kind of explicit "post type", thus why
bother discovering a post type in the first place? This section documents the
(few) use-case(s) that is/are known to date.

</p>
<section id='synthesizing' class='informative'>
<h3>Synthesizing explicit type formats</h3>
<p>
There are existing formats that require explicit post types
(e.g. ActivityStreams [[AS1]]), and code that consumes them expects explicit
post types. Post type discovery enabling automatic synthesizing of such
formats from posts that merely have a set of content related properties.
</p>

</section>
</section>

<section id='algorithm' >
<h2>Algorithm</h2>
<p>
The Post Type Discovery algorithm ("the algorithm") discovers the type of a
post given a data structure representing a post with a flat set of properties
(e.g. Activity Streams (1.0 or 2.0) JSON, or JSON output from parsing
[[microformats2]]), each with one or more values, by following these steps
until reaching the first "it is a(n) ... post" statement at which point the
"..." is the discovered post type.
</p>

<p>
<ul>
<li>If the post has an "rsvp" property with a valid value,
<br>Then it is an RSVP post.</li>
<li>If the post has an "in-reply-to" property with a valid URL,
<br>Then it is a reply post.</li>
<li>If the post has a "repost-of" property with a valid URL,
<br>Then it is a repost (AKA "share") post.</li>
<li>If the post has a "like-of" property with a valid URL,
<br>Then it is a like (AKA "favorite") post.</li>
<li>If the post has a "photo" property with a valid URL,
<br>Then it is a photo post. </li>
<li>If the post has a "content" property with a non-empty value,
<br>Then use its first non-empty value as the content</li>
<li>Else if the post has a "summary" property with a non-empty value,
<br>Then use its first non-empty value as the content</li>
<li>Else it is a note post.</li>
<li>If the post has no "name" property
<br>&nbsp;&nbsp;or has a "name" property with an empty string value (or no value)
<br>Then it is a note post.</li>
<li>Take the first non-empty value of the "name" property</li>
<li>Trim all leading/trailing whitespace</li>
<li>Collapse all sequences of internal whitespace to a single space (0x20) character each</li>
<li>Do the same with the content</li>
<li>If this processed "name" property value is NOT a prefix of the processed content,
<br>Then it is an article post.</li>
<li>It is a note post.</li>

</ul>

</p>

<p>
Quoted property names in the algorithm are defined in [h-entry].
</p>

</section>

<section id='methodology' class='informative'>
<h2>Methodology</h2>
<p>
There are two important aspects to the methodology of the Post Type Discovery
algorithm: scope (why is something explicitly in the algorithm), and order
(why is something where it is in the algorithm).
</p>

<section id="scope">
<h3>Scope</h3>
<p>
The algorithm could attempt to cover innumerable potential hypothetical post
types, or take an evidence based approach, focusing on real world publishing
practices. This specification does the latter, specifically by placing a
minimum bar of documented real world publishing practices of different visually
apparent post types on the open web at recent (&lt; 1 year old) permalinks, each
with at least three independent implementations that have converged on what
properties (and potentially values thereof) they have to imply their visually
apparent post types. As a result of being evidence based, it is likely this
specification will expand over time as more apparent post types are published by
more convergent implementations.
</p>
</section>

<section id="order">
<h3>Order</h3>
<p>
The algorithm must also specify an order (e.g. of precedence) that various
properties (and their values) imply various post types. The algorithm is
ordered by post types that are in general "richer" in terms of content as
well as show greater cognitive effort by the author.
</p>
</section>
</section>

<section id='othertypes' class='informative'>
<h2>Other Types Under Consideration</h2>
<p>
Other types are being considered and will be included in the future iterations
of the algorithm based on convergence of publishing patterns and critical mass
of adoption thereof.
</p>

<p>
<ul>
<li><a href="http://indiewebcamp.com/delete">delete</a>
<li><a href="http://indiewebcamp.com/event">event</a>
<li><a href="http://indiewebcamp.com/checkin">checkin</a>
<li><a href="http://indiewebcamp.com/bookmark">bookmark</a>
<li><a href="http://indiewebcamp.com/quotation">quotation</a>
<li><a href="http://indiewebcamp.com/video">video</a>
<li><a href="http://indiewebcamp.com/audio">audio</a>
<li><a href="http://indiewebcamp.com/jam">jam</a>
<li><a href="http://indiewebcamp.com/invitation">invitation</a>
<li><a href="http://indiewebcamp.com/tag-of">tag-of</a>
</ul>

</p>
</section>
<section id='examples' class='informative'>
<h2>Examples</h2>
<section id="ex-like">
<h3>Like Post</h3>
<p>
Here is an example [[h-entry]] post from [http://www.w3.org/TR/activitystreams-vocabulary/#dfn-like Activity Streams 2.0 Vocabulary examples]:
</p>
<pre>
&lt;div class="h-entry p-name"&gt;
&lt;span class="p-author h-card"&gt;Sally&lt;/span&gt;
liked
&lt;a class="u-like-of"
href="http://example.org/notes/1"&gt;
http://example.org/notes/1
&lt;/a&gt;
&lt;/div&gt;</pre>

<p>
Following the algorithm, the step "If the post has a "like-of" property with
a valid URL" is satisfied and thus the algorithm returns that the post is a
"<a href="http://indiewebcamp.com/like">like</a>" post.
</p>

<p>
Given this semantic, an implementation can generate (or process as if generated
and consumed) the following AS2 JSON, in particular the <code>"@type": "Like"</code>
in this output is what is determined by this algorithm:
</p>
<pre>{
"@type": "Like",
"actor": {
"@type": "Person",
"displayName": "Sally"
},
"object": "http://example.org/notes/1"
} </pre>
</section>
</section>


<section id='faq' class='informative'>
<h2>FAQ</h2>
<section>
<h3>What about a photo reply</h3>

<p>
Q: What about a reply that includes a photo?
</p>

<p>
A: It's a reply.
</p>

<p>
Q2: Should that show up as a "photo" post?
</p>

<p>
A2: It should show up as a "reply" and not be in a user's published feed of their
photos. The user-centric design here is to treat replies separately, because in
practice, when users post replies to others' posts, and include a photo, the photos
typically assume the context of that other post, and would look odd outside of it
(e.g. in a generic "photos" feed). In addition, by not including reply photos in a
user's feed of their photos, it gives the user the freedom to reply to other posts
with whatever they wish, including photos, and not have those reply-specific photos
pollute their streams of "their stuff" that their followers subscribe to.
</p>

<p>
A2a: From a presentation perspective, a reply should primarily be displayed as a
reply first, and then adapt accordingly to whatever other properties it may have.
</p>

</section>
</section>


<section id="implementations" class="informative">
<h2>Implementations</h2>
<p>
Implementations, in progress, partial, or complete, of Post Type Discovery.
</p>

<section id="granary">
<h3>Granary</h3>
<p>
[https://github.com/snarfed/granary/ Granary] synthesizes ActivityStreams [[AS1]],
[[microformats2]], and Atom [[RFC4287]] from various input feeds and sources, and
as such has some code that can be considered in progress or even a partial
implementation of Post Type Discovery:
</p>
<p>
<ul>
<li>Live public demo site: https://granary-demo.appspot.com/ </li>
<li>Issue(s) related to implementing Post Type Discovery: [https://github.com/snarfed/granary/issues/41 #41]</li>
</ul>
</p>
</section>

<section id="p3k">
<h3>p3k</h3>
<p>
<a href="https://indiewebcamp.com/p3k">p3k</a> (a CMS) implements Post Type
Discovery internally within its [[micropub]] endpoint to automatically add
posts to various collections. E.g.: if this post is a reply, it goes in the
"replies" collection. if it's an RSVP, it goes in the "rsvps" and "replies"
collections.
</p>
<p>
<ul>
<li>Live example: http://aaronparecki.com/</li>
</ul>
</p>
</section>
</section>
</body>
</html>

0 comments on commit a2335cf

Please sign in to comment.