fep-b2b8-updates (#591)

Two updates on FEP-B2B8 to respond to open issues: Discourage embedding "Read more..." links in the summary, content, and preview of an Article, and how to use the `sensitive` flag to indicate sensitive content.

Reviewed-on: https://codeberg.org/fediverse/fep/pulls/591
Co-authored-by: Evan Prodromou <codeberg@evanprodromou.name>
Co-committed-by: Evan Prodromou <codeberg@evanprodromou.name>

fep/b2b8/fep-b2b8.md

@@ -65,7 +65,7 @@ This property provides the same functionality as the `link` property in RSS 2.0.
 
 This property provides a brief description, teaser, abstract or "lede" for the text. It should be a maximum of about 500 characters; a few sentences; or a short paragraph.
 
-This property can include HTML markup. It should not include embedded media like images, video or audio.
+This property can include HTML markup. It should not include embedded media like images, video or audio. It should not include navigation or interaction elements like "favourite", "like", "bookmark" or other buttons. It should not include links to the publisher's home page or category pages. It should not include a "Read more..." link to the full text.
 
 This property provides the same functionality as the `description` property in RSS 2.0.
 
@@ -132,7 +132,7 @@ the full HTML element set. It should not include any CSS or JavaScript. This sub
 - `<rt>`
 - `<rp>`
 
-The HTML should only include the content of the text. Additional navigation to other pages on the originating site, like category links or home page links, should not be included. Other affordances like "favourite", "like", "bookmark" or other buttons should not be included.
+The HTML should only include the content of the text. Additional navigation to other pages on the originating site, like category links or home page links, should not be included. Other affordances like "favourite", "like", "bookmark" or other buttons should not be included. It should not include a "Read more..." link to the full article.
 
 Any embedded media like images, video or audio in the `content` property should also be listed in the `attachment` property so that consumers can pre-fetch the media.
 
@@ -179,7 +179,11 @@ For an article, the `preview` can be a `Note` that gives a well-formatted previe
 
 The `content` property of the `preview` should include a minimal set of HTML elements, as described in [ActivityPub Primer HTML](https://www.w3.org/wiki/ActivityPub/Primer/HTML).
 
-Metadata on the `Article` that applies equally to the preview, such as `attributedTo`, `published`, `updated`, and `tag` should be repeated in the `preview` property.
+The HTML should only include an excerpt or summary of the full article text. Additional navigation to other pages on the originating site, like category links, home page links. Other affordances like "favourite", "like", "bookmark" or other buttons should not be included.
+
+The `preview` property should not include a link to the full article with a "Read more..." link. The consumer should use the `url` property of the `Article` to link to the full article.
+
+Metadata on the `Article` that applies equally to the preview, such as `attributedTo`, `published`, `updated`, and `tag` can be repeated in the `preview` property. The consumer should fall back to the `Article` properties if they are not present in the `preview`.
 
 The `image` property of the `Article` may be included in the `preview` property as `attachment` items.
 
@@ -191,6 +195,19 @@ As with other AS2 object types, the `to`, `cc`, `bcc`, `bto`, and `audience` pro
 
 The addressing properties provide an access control mechanism for AS2. Publishers and consumers should not disclose the properties of any AS2 object type, including the `Article` type, with anyone except the addressees, listed in these addressing properties, or the creator(s), listed in the `attributedTo` property.
 
+### `sensitive`
+
+[sensitive](https://swicg.github.io/miscellany/#sensitive) marks an article as potentially sensitive, controversial, or disturbing in the author's opinion. As a non-exhaustive list and depending on context, nudity, sexual activity, violence, or spoilers for a movie or book may be considered sensitive.
+
+If the sensitive flag is set, the consumer should obscure the content of the article until the user conveys intent to read the article or view embedded media.
+
+To help the user decide whether to read the article or view its media, the consumer should show these properties, if provided, in order:
+
+- [`dcterms:subject`](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/#http://purl.org/dc/terms/subject): a property from the [Dublin Core metadata terms](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/). Value should be a string or array of strings indicating the topic or topics discussed in the article.
+- `tag`: in particular, `Hashtag` names. (`subject` is preferred because hashtags are often less human-readable).
+- `name`: as described above, the title of the `Article`. Authors are more likely to leak sensitive material in the title, so the subject and/or hashtags should be used first.
+- `summary`: as described above. Only as a last resort when other properties are not defined; a well-written summary is likely to include significant excerpts or summation of the sensitive content.
+
 ## Examples
 
 This section includes examples of long-form text objects. Note that for brevity, the content is not actually multi-paragraph text.
@@ -360,6 +377,32 @@ This section includes examples of long-form text objects. Note that for brevity,
 }
 ```
 
+### Long-form text with senstive content
+
+This article includes a spoiler about the 1941 film *Citizen Kane*. The `sensitive` property is set to `true`, and the `dcterms:subject` property is used to indicate the topic of the article.
+
+```json
+{
+  "@context": [
+    "https://www.w3.org/ns/activitystreams",
+    "https://purl.archive.org/miscellany",
+    {"dcterms": "http://purl.org/dc/terms/"}
+  ],
+  "id": "https://example.com/article/1",
+  "type": "Article",
+  "name": "Spoiler for Citizen Kane",
+  "summary": "<p>I am going to tell you what Rosebud was.</p>",
+  "sensitive": true,
+  "dcterms:subject": ["Citizen Kane"],
+  "contents": "<p>Rosebud was his sled!</p>",
+  "tag": {
+    "id": "https://example.com/tag/citizenkane",
+    "name": "citizenkane",
+    "type": "Hashtag"
+  }
+}
+```
+
 ## User interface guidance
 
 Consumers should use their native interfaces to handle `Article` objects in an intuitive way that integrates well with other object types. The following illustrations provide examples of how `Article` objects might be displayed in a stream-oriented social web interface, such as a microblogging application. The UI elements are labelled with the properties of the `Article` object that most likely correspond to them.
@@ -382,6 +425,12 @@ An example of a long-form text object without a `name` property displayed in a s
 
 ![Article in stream, no title](in-stream-no-title.drawio.svg)
 
+### In stream, sensitive content
+
+An example of a long-form text object with a `sensitive` property displayed in a social stream with a content warning.
+
+![Article in stream, sensitive content](content-warning.drawio.svg)
+
 ## References
 
 - James Snell, Evan Prodromou, [Activity Streams 2.0][AS2], 2017