Okay/Spec: Difference between revisions

Line 22:

== connections ==

Connections in Okay should happen over HTTPS, but plaintext HTTP will do in a pinch (TODO: elaborate).

Connections in Okay <span class="should">should</span> happen over HTTPS, but plaintext HTTP will do in a pinch (TODO: elaborate).

A typical connection to an never before seen space usually goes like this:

Line 49:

==== ok-space ====

Spaces are declared using the '''ok-space''' micro-format. Upon retrieving a document, the client must scan for elements with the <code>ok-space</code> class, as well as [[Okay#linking to other spaces|links and anchors]] with the <code>ok-space</code> rel attribute. Here's an example of valid <code>ok-space</code> markup:

Spaces are declared using the '''ok-space''' micro-format. Upon retrieving a document, the client <span class="must">must</span> scan for elements with the <code>ok-space</code> class, as well as [[Okay#linking to other spaces|links and anchors]] with the <code>ok-space</code> rel attribute. Here's an example of valid <code>ok-space</code> markup:

Line 58:

</nav></syntaxhighlight>

For an element to be considered valid <code>ok-space</code> markup, it must be a non-void element (ideally a <code><nav /></code>) with the <code>ok-space</code> class and contain anchor elements with valid <code>rel</code> and <code>href</code> attributes. Any invalid anchors or elements not specified in the format <span class="must">must</span> be ignored by the client. The inner text of the anchor elements is not significant and <span class="must">must</span> be ignored by clients.

For an element to be considered valid <code>ok-space</code> markup, it <span class="must">must</span> be a non-void element (ideally a <code><nav /></code>) with the <code>ok-space</code> class and contain anchor elements with valid <code>rel</code> and <code>href</code> attributes. Any invalid anchors or elements not specified in the format <span class="must">must</span> be ignored by the client. The inner text of the anchor elements is not significant and <span class="must">must</span> be ignored by clients.

A list of valid anchor <code>rel</code> attributes and their purposes is described below:

Line 79:

==== linking to other spaces ====

A document ~~can~~ direct ~~a client~~ to another document containing a space using an <code><a /></code> or <code><link /></code> element with the <code>rel="ok-space"</code> attribute. The client must scan the linked document for valid <code>ok-space</code> markup, but it must not follow any further links or anchors with the <code>rel="ok-space"</code> attribute.

A document <span class="may">may</span> direct clients to another document containing a space using an <code><a /></code> or <code><link /></code> element with the <code>rel="ok-space"</code> attribute. The client <span class="must">must</span> scan the linked document for valid <code>ok-space</code> markup, but it <span class="mustnt">must not</span> follow any further links or anchors with the <code>rel="ok-space"</code> attribute.

The URI provided may include a fragment component to specify which element the client should treat as [[Okay#ok-space|ok-space]] markup (e.g., <code><nowiki>https://example.com/#my-elem</nowiki></code>). The linked element must be valid <code>ok-space</code> markup. If the fragment is specified and the corresponding element is present in the linked document, the client must not scan any other part of the document for <code>ok-space</code> markup. <syntaxhighlight lang="html">

The URI provided <span class="may">may</span> include a fragment component to specify which element the client should treat as [[Okay#ok-space|ok-space]] markup (e.g., <code><nowiki>https://example.com/#my-elem</nowiki></code>). The linked element <span class="must">must</span> be valid <code>ok-space</code> markup. If the fragment is specified and the corresponding element is present in the linked document, the client <span class="mustnt">must not</span> scan any other part of the document for <code>ok-space</code> markup. <syntaxhighlight lang="html">

<!-- anchors work, too. this one forces the client to rummage around

Line 90:

==== metadata ====

Spaces ~~can~~ provide metadata about themselves to help users identify them.<syntaxhighlight lang="html"><nav class="ok-space">

Spaces <span class="may">may</span> provide metadata about themselves to help users identify them.<syntaxhighlight lang="html"><nav class="ok-space">

Line 100:

== initiation ==

A client must register itself with a space before it can send messages to rooms.

A client <span class="must">must</span> register itself with a space before it can send messages to rooms.

=== keys ===

When registering with a space, a client should transparently generate a key pair (TODO: what type(s)?) and store it for use in subsequent requests.

When registering with a space, a client <span class="should">should</span> transparently generate a key pair (TODO: what type(s)?) and store it for use in subsequent requests.

=== registration the page ===

Line 109:

== the directory ==

The '''Room Directory''' is a list of every room contained within the space. This list may be [[Okay#pagination|paginated]].

The '''Room Directory''' is a list of every room contained within the space. This list <span class="may">may</span> be [[Okay#pagination|paginated]].

The path to the space's room directory <span class="must">must</span> be defined in its [[Okay#the element thereof|discovery element]] with the <code>ok-rooms</code> rel value.

@@ Line 22: / Line 22: @@
 == connections ==
-Connections in Okay should happen over HTTPS, but plaintext HTTP will do in a pinch (TODO: elaborate).
+Connections in Okay <span class="should">should</span> happen over HTTPS, but plaintext HTTP will do in a pinch (TODO: elaborate).
 A typical connection to an never before seen space usually goes like this:
@@ Line 49: / Line 49: @@
 ==== ok-space ====
-Spaces are declared using the '''ok-space''' micro-format. Upon retrieving a document, the client must scan for elements with the <code>ok-space</code> class, as well as [[Okay#linking to other spaces|links and anchors]] with the <code>ok-space</code> rel attribute. Here's an example of valid <code>ok-space</code> markup:
+Spaces are declared using the '''ok-space''' micro-format. Upon retrieving a document, the client <span class="must">must</span> scan for elements with the <code>ok-space</code> class, as well as [[Okay#linking to other spaces|links and anchors]] with the <code>ok-space</code> rel attribute. Here's an example of valid <code>ok-space</code> markup:
 <syntaxhighlight lang="html"><nav class=“ok-space”>
@@ Line 58: / Line 58: @@
 </nav></syntaxhighlight>
-For an element to be considered valid <code>ok-space</code> markup, it must be a non-void element (ideally a <code><nav /></code>) with the <code>ok-space</code> class and contain anchor elements with valid <code>rel</code> and <code>href</code> attributes. Any invalid anchors or elements not specified in the format <span class="must">must</span> be ignored by the client. The inner text of the anchor elements is not significant and <span class="must">must</span> be ignored by clients.
+For an element to be considered valid <code>ok-space</code> markup, it <span class="must">must</span> be a non-void element (ideally a <code><nav /></code>) with the <code>ok-space</code> class and contain anchor elements with valid <code>rel</code> and <code>href</code> attributes. Any invalid anchors or elements not specified in the format <span class="must">must</span> be ignored by the client. The inner text of the anchor elements is not significant and <span class="must">must</span> be ignored by clients.
 A list of valid anchor <code>rel</code> attributes and their purposes is described below:
@@ Line 79: / Line 79: @@
 ==== linking to other spaces ====
-A document can direct a client to another document containing a space using an <code><a /></code> or <code><link /></code> element with the <code>rel="ok-space"</code> attribute. The client must scan the linked document for valid <code>ok-space</code> markup, but it must not follow any further links or anchors with the <code>rel="ok-space"</code> attribute.
+A document <span class="may">may</span> direct clients to another document containing a space using an <code><a /></code> or <code><link /></code> element with the <code>rel="ok-space"</code> attribute. The client <span class="must">must</span> scan the linked document for valid <code>ok-space</code> markup, but it <span class="mustnt">must not</span> follow any further links or anchors with the <code>rel="ok-space"</code> attribute.
-The URI provided may include a fragment component to specify which element the client should treat as [[Okay#ok-space|ok-space]] markup (e.g., <code><nowiki>https://example.com/#my-elem</nowiki></code>). The linked element must be valid <code>ok-space</code> markup. If the fragment is specified and the corresponding element is present in the linked document, the client must not scan any other part of the document for <code>ok-space</code> markup. <syntaxhighlight lang="html"><!-- link to a space with the id "space" -->
+The URI provided <span class="may">may</span> include a fragment component to specify which element the client should treat as [[Okay#ok-space|ok-space]] markup (e.g., <code><nowiki>https://example.com/#my-elem</nowiki></code>). The linked element <span class="must">must</span> be valid <code>ok-space</code> markup. If the fragment is specified and the corresponding element is present in the linked document, the client <span class="mustnt">must not</span> scan any other part of the document for <code>ok-space</code> markup. <syntaxhighlight lang="html"><!-- link to a space with the id "space" -->
 <link rel="ok-space" href="https://example.ok/#space" />
 <!-- anchors work, too. this one forces the client to rummage around
@@ Line 90: / Line 90: @@
 ==== metadata ====
-Spaces can provide metadata about themselves to help users identify them.<syntaxhighlight lang="html"><nav class="ok-space">
+Spaces <span class="may">may</span> provide metadata about themselves to help users identify them.<syntaxhighlight lang="html"><nav class="ok-space">
      <h1 class="title"></h1>
      <p class="subtitle"></p>
@@ Line 100: / Line 100: @@
 == initiation ==
-A client must register itself with a space before it can send messages to rooms.
+A client <span class="must">must</span> register itself with a space before it can send messages to rooms.
 === keys ===
-When registering with a space, a client should transparently generate a key pair (TODO: what type(s)?) and store it for use in subsequent requests.
+When registering with a space, a client <span class="should">should</span> transparently generate a key pair (TODO: what type(s)?) and store it for use in subsequent requests.
 === registration the page ===
@@ Line 109: / Line 109: @@
 == the directory ==
-The '''Room Directory''' is a list of every room contained within the space. This list may be [[Okay#pagination|paginated]].
+The '''Room Directory''' is a list of every room contained within the space. This list <span class="may">may</span> be [[Okay#pagination|paginated]].
 The path to the space's room directory <span class="must">must</span> be defined in its [[Okay#the element thereof|discovery element]] with the <code>ok-rooms</code> rel value.