Update README.markdown

[x_status_git] / README.markdown

diff --git a/README.markdown b/README.markdown
index 2c71b22eba03e1c05f00378b55782dabbf3e3b12..a03f40a5f5a25b6e1eab3ff668e206780e56bbcd 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -1,6 +1,6 @@
-# Status.git
+# x_status_git

 
 

-A minimal git‐based self‐hosted status publishing solution.
+A minimal git‐based microblog.

 
 ## What It Is
 
 
 ## What It Is
 


@@ -71,7 +71,9 @@ You’ll need to supply some variables there, too :—
 ## Server Configuration
 
 Your server should be configured to serve the following files from the
 ## Server Configuration
 
 Your server should be configured to serve the following files from the

-  provided `PUBLIC_DIRECTORY` in response to the following requests :—
+  provided `PUBLIC_DIRECTORY` in response to the following requests.
+For people using Caddy to serve their content, a sample `Caddyfile` is
+  included in this repository.

 
 ### H·T·M·L responses
 
 
 ### H·T·M·L responses
 


@@ -81,6 +83,15 @@ Note that these paths **do not** have a trailing slash.
 
  +  **`GET /`**:
     Serve the file at `/index.html`.
 
  +  **`GET /`**:
     Serve the file at `/index.html`.

+    A `Link` header with the value
+      `</about.jsonld>;rel=meta;type="application/ld+json"` (or
+      equivalent) **must** be provided.
+
+ +  **`GET /about`**:
+    Serve the file at `/.about.html`.
+    A `Link` header with the value
+      `</about.jsonld>;rel=meta;type="application/ld+json"` (or
+      equivalent) **must** be provided.

 
  +  **`GET /statuses`**:
     Serve the file at `/.statuses.html`.
 
  +  **`GET /statuses`**:
     Serve the file at `/.statuses.html`.


@@ -88,13 +99,13 @@ Note that these paths **do not** have a trailing slash.
       `</statuses.jsonld>;rel=meta;type="application/ld+json"` (or
       equivalent) **must** be provided.
 
       `</statuses.jsonld>;rel=meta;type="application/ld+json"` (or
       equivalent) **must** be provided.
 

- +  **`GET /$YYYY-MM`** (where `$YYYY-MM` is an `xsd:gYearMonth`):
+ +  **`GET /statuses/$YYYY-MM`** (where `$YYYY-MM` is an `xsd:gYearMonth`):

     Serve the file at `/.topic.html`.
     A `Link` header with the value
       `</$YYYY-MM.jsonld>;rel=meta;type="application/ld+json"` (or
       equivalent) **must** be provided.
 
     Serve the file at `/.topic.html`.
     A `Link` header with the value
       `</$YYYY-MM.jsonld>;rel=meta;type="application/ld+json"` (or
       equivalent) **must** be provided.
 

- +  **`GET /$YYYY-MM/*`** (where `$YYYY-MM` is an `xsd:gYearMonth`):
+ +  **`GET /statuses/$YYYY-MM/*`** (where `$YYYY-MM` is an `xsd:gYearMonth`):

     Serve the file at `/.status.html`.
     A `Link` header with the value
       `</$YYYY-MM.jsonld>;rel=meta;type="application/ld+json"` (or
     Serve the file at `/.status.html`.
     A `Link` header with the value
       `</$YYYY-MM.jsonld>;rel=meta;type="application/ld+json"` (or


@@ -126,10 +137,13 @@ These responses **should** be served with a `Content-Type` of
 In all cases, for `/$PATH.jsonld`, this just serves the file at
   `/$PATH/index.jsonld`.
 
 In all cases, for `/$PATH.jsonld`, this just serves the file at
   `/$PATH/index.jsonld`.
 

+ +  **`GET /about.jsonld`**:
+    Serve the file at `/about/index.jsonld`.
+

  +  **`GET /statuses.jsonld`**:
     Serve the file at `/statuses/index.jsonld`.
 
  +  **`GET /statuses.jsonld`**:
     Serve the file at `/statuses/index.jsonld`.
 

- +  **`GET /$YYYY-MM.jsonld`** (where `$YYYY-MM` is an
+ +  **`GET /statuses/$YYYY-MM.jsonld`** (where `$YYYY-MM` is an

       `xsd:gYearMonth`):
     Serve the file at `/$YYYY-MM/index.jsonld`.
 
       `xsd:gYearMonth`):
     Serve the file at `/$YYYY-MM/index.jsonld`.
 


@@ -140,6 +154,24 @@ In all cases, for `/$PATH.jsonld`, this just serves the file at
       `[0-9A-Za-z_-]+`):
     Serve the file at `/topics/$TOPIC/index.jsonld`.
 
       `[0-9A-Za-z_-]+`):
     Serve the file at `/topics/$TOPIC/index.jsonld`.
 

+### Atom responses
+
+These responses **should** be served with a `Content-Type` of
+  `application/atom+xml`.
+In all cases, for `/$PATH.atom`, this just serves the file at
+  `/$PATH/index.atom`.
+
+ +  **`GET /statuses.atom`**:
+    Serve the file at `/statuses/index.atom`.
+
+ +  **`GET /statuses/$YYYY-MM.atom`** (where `$YYYY-MM` is an
+      `xsd:gYearMonth`):
+    Serve the file at `/$YYYY-MM/index.atom`.
+
+ +  **`GET /topics/$TOPIC.atom`** (where `$TOPIC` matches
+      `[0-9A-Za-z_-]+`):
+    Serve the file at `/topics/$TOPIC/index.atom`.
+

 ### Other Headers
 
 All responses **should** have a `Access-Control-Allow-Origin` header
 ### Other Headers
 
 All responses **should** have a `Access-Control-Allow-Origin` header


@@ -195,6 +227,13 @@ The files which represent a status are as follows :—
     The contents of this file **must** give the author’s URL,
       optionally followed by a trailing newline.
 
     The contents of this file **must** give the author’s URL,
       optionally followed by a trailing newline.
 

+ +  **`2=TITLE`** (where `TITLE` might be anything):
+    This file is **optional** and indicates the title of the status.
+    The value of `TITLE` **should** be a file·system‐friendly version
+      of the title, but is ignored.
+    The contents of this file **must** give the title of the status,
+      optionally followed by a trailing newline.
+

  +  **`3=YYYY-MM-DD`** (where `YYYY-MM-DD` is a date):
     This file is **required** and indicates the date of the status.
     Only one date is currently supported.
  +  **`3=YYYY-MM-DD`** (where `YYYY-MM-DD` is a date):
     This file is **required** and indicates the date of the status.
     Only one date is currently supported.


@@ -219,7 +258,7 @@ The files which represent a status are as follows :—
 Files with names that begin with the strings `2=` or `x_status_git_`
   are reserved for backwards‐compatible extensions.
 
 Files with names that begin with the strings `2=` or `x_status_git_`
   are reserved for backwards‐compatible extensions.
 

-Status.git has no opinion on how these files make their way into the
+x_status_git has no opinion on how these files make their way into the

   Git repository, except that all the files for a single status should
   be added in the same commit.
 The intention is that the simple nature of these files will make them
   Git repository, except that all the files for a single status should
   be added in the same commit.
 The intention is that the simple nature of these files will make them


@@ -227,41 +266,92 @@ The intention is that the simple nature of these files will make them
 
 ## I Am Computer, How Do I Get Status?
 
 
 ## I Am Computer, How Do I Get Status?
 

-Assume you are given a U·R·L to a status collection, like `/statuses`,
-  `/YYYY-MM`, or `/topics/my_topic`.
-Make a `HEAD` request to this U·R·L.
-If there is a `Link` header with a `rel` of `meta` and a `type` of
-  `application/ld+json`, make a `GET` request to that U·R·L instead.
-Otherwise, make a `GET` request to the U·R·L you were given.
+Assume you are given a U·R·L `resource_url` which you think points to
+  some kind of x_status_git resource.
+Start by resolving it as follows :—

 
 

-Assuming the U·R·L you were given was valid, you will receive a
-  Json‐L·D response with a `@type` which is either an
-  `OrderedCollection` or an `OrderedCollectionPage`.
-One of the following will be true :—
+01. Make a `HEAD` request to `resource_url`.

 
 

- +  The response is an `OrderedCollectionPage`.
-    Its `items` will be an array of statuses, and the `prev` and
-      `next` properties will give U·R·Ls for previous and next
-      pages of statuses (if any exist).
+02. If there is a `Link` header with a `rel` of `meta` and a `type` of
+      `application/ld+json`, set `resource_url` to the URL provided in
+      that header and restart these steps from step 1.

 
 

- +  The response is an `OrderedCollection` with `first` and
-      `current` properties.
-    These properies give the U·R·Ls for the first and latest pages
-      of statuses, which you can fetch and process as above.
+03. Make a `GET` request to `resource_url` and let `response` be the
+      response.

 
 

- +  Otherwise, the `items` property will be an array of every
-      status in the collection.
+04. Set `document` as follows :—

 
 

- >  If you receive a `Collection` instead of an `OrderedCollection`,
- >    you are probably looking at a topics listing.
- >  You will need to choose a topic from the `items` and then fetch it
- >    to receive the list of statuses.
+    01. If the `Content-Type` header of `response` has a type of `text`
+          and subtype of `html`, let `document` be the result of
+          processing the body of `response` into a D·O·M tree as an
+          H·T·M·L document .
+        It is an error if this process fails.
+
+    02. If the `Content-Type` header of `response` has a type of
+          `application` and a subtype which is `xml` or which ends in
+          `+xml`, let `document` be the result of processing the body
+          of `response` into a D·O·M tree as an X·M·L document .
+        It is an error if this process fails.
+
+    03. Otherwise, let `document` be null.
+
+05. If `document` is not null :—
+
+    01. If there is a `<link>` element in either the H·T·M·L namespace
+          or the Atom namespace in `document` with a `rel` of `meta`
+          and a `type` of `application/ld+json`, set `resource_url` to
+          the `href` of that `<link>` element and restart these steps
+          from step 1.
+        If multiple such elements exist, choose the first one.
+
+    02. Otherwise, it is an error.
+
+06. If the body of `response` is not a Json document, it is an error.
+
+Assuming the U·R·L you were given was valid, you will end this
+  algorithm with a Json‐L·D response, and you can use the `@type`
+  attribute to determine the response type.
+`@type` will be either a string or an array.
+
+ +  If the `@type` is or contains `Forum`, the resource is a collection
+      of topics.
+
+ +  If the `@type` is or contains `Thread`, the resource is a
+      collection of statuses.
+
+ +  If the `@type` is or contains `Microblog`, the resource describes
+      this site as a whole.
+    The `streams` property will contain a list of available `Forum`s
+      and `Thread`s, as objects with an `@id` and `@type`.
+
+The items in the collection (`Forum` or `Thread`) may be determined
+  through one of the following methods :—
+
+ +  If the `@type` is or contains `CollectionPage` or
+      `OrderedCollectionPage`, then its `items` will contain resources.
+    This is a partial collection, and the `prev` and `next` properties
+      can be used to access further items from the parent collection
+      (indicated by `partOf`).
+    `first` and `current`, in this scenario, point “horizontally” to
+      the first and latest pages of items, not to subpages.
+
+ +  If the `@type` is or contains `Collection` or `OrderedCollection`
+      and the resource has `first` and/or `current` properties, then
+      the `items` property will not be present.
+    `first` and `current` can be accessed to provide
+      `OrderedCollectionPage`s listing the items of the collection.
+
+ +  Otherwise, the `items` property will contain every item in the
+      collection.

 
 Statuses themselves have the following properties :—
 
  +  **`@id`**:
     The identifier of the status.
 
 
 Statuses themselves have the following properties :—
 
  +  **`@id`**:
     The identifier of the status.
 

+ +  **`@type`**:
+    The value `MicroblogPost`.
+

  +  **`created`** [`dcterms:created`]:
     The creation date for the status, as an `xsd:dateTime`.
 
  +  **`created`** [`dcterms:created`]:
     The creation date for the status, as an `xsd:dateTime`.
 


@@ -277,5 +367,8 @@ Statuses themselves have the following properties :—
  +  **`subject`** [`dcterms:subject`] (optional):
     The topic of the status, for topic statuses.
 
  +  **`subject`** [`dcterms:subject`] (optional):
     The topic of the status, for topic statuses.
 

+ +  **`title`** [`dcterms:title`] (optional):
+    The title of the status.
+

  +  **`content`** [`sioc:content`]:
     The content of the status, as an `rdf:XMLLiteral`.
  +  **`content`** [`sioc:content`]:
     The content of the status, as an `rdf:XMLLiteral`.