From a2335cf2049390c4db7401b200caf1ef847898f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tantek=20=C3=87elik?= Date: Tue, 7 Jun 2016 13:18:31 -0700 Subject: [PATCH] copy @dissolve first cut at translating from wiki, add a bit 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. --- index.html | 348 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 348 insertions(+) create mode 100644 index.html diff --git a/index.html b/index.html new file mode 100644 index 0000000..5f3c63e --- /dev/null +++ b/index.html @@ -0,0 +1,348 @@ + + + + Post Type Discovery + + + + + + +
+

+ 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. +

+
+ +
+

+ This is a W3C Editor's Draft, and a snapshot of the IndieWebCamp specification + of the same name, as of 2015-10-14 +

+
+ +
+

Introduction

+

+ Post type discovery is an explicit algorithm for inferring the type of a post from other properties of that post. +

+

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]].

+
+ +
+

Use Cases

+

+ 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. + +

+
+

Synthesizing explicit type formats

+

+ 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. +

+ +
+
+ +
+

Algorithm

+

+ 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. +

+ +

+

+ +

+ +

+ Quoted property names in the algorithm are defined in [h-entry]. +

+ +
+ +
+

Methodology

+

+ 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). +

+ +
+

Scope

+

+ 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 (< 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. +

+
+ +
+

Order

+

+ 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. +

+
+
+ +
+

Other Types Under Consideration

+

+ 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. +

+ +

+

+ +

+
+
+

Examples

+
+

Like Post

+

+ Here is an example [[h-entry]] post from [http://www.w3.org/TR/activitystreams-vocabulary/#dfn-like Activity Streams 2.0 Vocabulary examples]: +

+ 
+<div class="h-entry p-name">
+  <span class="p-author h-card">Sally</span>
+  liked
+  <a class="u-like-of"
+    href="http://example.org/notes/1">
+    http://example.org/notes/1
+  </a>
+</div>
+ +

+ 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 + "like" post. +

+ +

+ Given this semantic, an implementation can generate (or process as if generated + and consumed) the following AS2 JSON, in particular the "@type": "Like" + in this output is what is determined by this algorithm: +

+ 
{
+  "@type": "Like",
+  "actor": {
+    "@type": "Person",
+    "displayName": "Sally"
+  },
+  "object": "http://example.org/notes/1"
+}
+
+
+ + +
+

FAQ

+
+

What about a photo reply

+ +

+ Q: What about a reply that includes a photo? +

+ +

+ A: It's a reply. +

+ +

+ Q2: Should that show up as a "photo" post? +

+ +

+ 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. +

+ +

+ 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. +

+ +
+
+ + +
+

Implementations

+

+ Implementations, in progress, partial, or complete, of Post Type Discovery. +

+ +
+

Granary

+

+ [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: +

+

+

    +
  • Live public demo site: https://granary-demo.appspot.com/
    • +
  • Issue(s) related to implementing Post Type Discovery: [https://github.com/snarfed/granary/issues/41 #41]
    • +
+

+
+ +
+

p3k

+

+ p3k (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. +

+

+

    +
  • Live example: http://aaronparecki.com/
    • +
+

+
+
+ +