styling: update based on list feedback

inbox/styling.xml

@@ -10,8 +10,8 @@
 <header>
   <title>Message Styling</title>
   <abstract>
-    This specification defines a plain-text formatting syntax for use in
+    This specification defines a formatted text syntax for use in instant
-    exchanging instant messages with simple text styling.
+    messages with simple text styling.
   </abstract>
   &LEGALNOTICE;
   <number>xxxx</number>
@@ -39,15 +39,14 @@
     Historically, XMPP has had no system for simple text styling.
     Instead, specifications like &xep0071; that require full layout engines have
     been used, leading to numerous security issues with implementations.
-    Some clients have also performed their own formatting based on identifiers
+    Some entities have also performed their own styling based on identifiers in
-    in the body.
+    the body.
-    While this has worked well for those clients, it is not interoperable and
+    While this has worked well in the past, it is not interoperable and leads to
-    leads to clients each supporting their own informal styling languages.
+    entities each supporting their own informal styling languages.
   </p>
   <p>
-    This specification aims to provide a single, interoperable text styling
+    This specification aims to provide a single, interoperable formatted text
-    language that can be used by entities that do not require full layout
+    syntax that can be used by entities that do not require full layout engines.
-    engines.
   </p>
 </section1>
 <section1 topic='Requirements' anchor='reqs'>
@@ -89,6 +88,7 @@
     Many important terms used in this document are defined in &unicode;.
     The terms "left-to-right" (LTR) and "right-to-left" (RTL) are defined in
     &uax9;.
+    The term "formatted text" is defined in &rfc7764;.
   </p>
   <dl>
     <di>
@@ -99,14 +99,6 @@
         text style.
       </dd>
     </di>
-    <di>
-      <dt>Formatted text</dt>
-      <dd>
-        Text that includes non-textual information coded in a particular way
-        that affects the interpretation of the text by computer programs
-        (&rfc7764;).
-      </dd>
-    </di>
     <di>
       <dt>Plain text</dt>
       <dd>
@@ -126,7 +118,7 @@
 <section1 topic='Use Cases' anchor='usecases'>
   <ul>
     <li>
-      As an user sending an instant message to a friend, I want to be able to
+      As a user sending an instant message to a friend, I want to be able to
       emphasize an important part of my message.
     </li>
     <li>
@@ -139,62 +131,40 @@
     </li>
   </ul>
 </section1>
-<section1 topic='Discovering support' anchor='disco'>
-  <section2 topic='Explicit Discovery' anchor='discovery-explicit'>
-    <p>
-      If an entity supports this specification it MUST advertise the fact by
-      returning a feature of 'urn:xmpp:styling:0' &VNOTE; in response to a
-      &xep0030; information request (or by advertising this namespace in the
-      dynamic profile of service discovery defined in &xep0115;).
-    </p>
-    <example caption='Disco response'><![CDATA[
-<iq type='result'
-    from='viola@example.net/seashore-Iaqu8ith'
-    to='captain@example.net/illyria-rohJa9au'
-    id='Uw8riPhe'>
-  <query xmlns='http://jabber.org/protocol/disco#info'>
-    <feature var='urn:xmpp:styling:0' />
-  </query>
-</iq>
-]]></example>
-  </section2>
-  <section2 topic='Implicit Discovery' anchor='discovery-implicit'>
-    <p>
-      An entity supporting this specification SHOULD render all messages
-      &lt;body&gt; elements using this specification and MAY choose to send
-      messages formatted using this specification even if the other end has not
-      advertised support.
-    </p>
-  </section2>
-</section1>
 <section1 topic='Business Rules' anchor='rules'>
-  <section2 topic='Display' anchor='display'>
+  <section2 topic='Blocks' anchor='block'>
     <p>
-      Formatting characters MAY be displayed styled along with the span they
+      A block is any chunk of text that can be parsed unambiguously in one pass.
-      apply to or they may be hidden and the styling only applied to the span.
-      For instance, given the string "*emphasis*" both of the following are
-      valid renderings:
     </p>
     <ul>
-      <li><strong>*emphasis*</strong></li>
+      <li>A single line of text containing only inline spans</li>
-      <li><strong>emphasis</strong></li>
+      <li>A block quotation comprising one or more lines</li>
+      <li>A preformatted code block</li>
+    </ul>
+  </section2>
+  <section2 topic='Spans' anchor='span'>
+    <p>
+      A span are groups of text that do not result in a line break when rendered
+      (they are rendered inline) and where the entire group is rendered in the
+      same manner and in the same block.
+      Spans may be either plain text with no formatting applied, or may be
+      formatted text that is enclosed by two styling directives.
+      The following are all single spans:
+    </p>
+    <ul>
+      <li>plain span</li>
+      <li><strong>*emphasized span*</strong></li>
     </ul>
     <p>
-      Examples in this document will display the formatting characters for
+      Matches of spans between two styling directives MUST contain some text
-      clarity.
+      between the two styling directives and the opening styling directive MUST
+      be located at the beginning of the line, or after a whitespace character.
+      The opening styling directive MUST also not be followed by a whitespace
+      character.
+      Spans are always parsed from the beginning of the byte stream to the end
+      and are lazily matched.
     </p>
-  </section2>
-  <section2 topic='Inlines' anchor='emph'>
     <p>
-      Inline styling directives are evaluated lazily from the start of the byte
-      stream (the left in left-to-right languages and the right in right-to-left
-      languages).
-      Matches MUST NOT extend over newlines and MUST start with a whitespace
-      character or be the beginning of the line or the byte stream.
-      Matches MUST contain some text between the two styling directives.
-      Inline styling directives may also be doubled to allow the single
-      character version of the directive to be styled.
-      That is to say, "**emphasis**" is rendered the same as "*emphasis*".
       For example, the word "emphasized" would be styled in each of the
       following messages:
     </p>
@@ -203,53 +173,46 @@
       <li>foo <strong>*emphasized*</strong> bar</li>
       <li><strong>*emphasized*</strong>foo<strong>*emphasized*</strong></li>
       <li><strong>*emphasized*</strong>foo*</li>
-      <li><strong>**emphasi*zed**</strong> foo*</li>
+      <li>* foo <strong>*emphasized*</strong></li>
-      <li>* <strong>*emphasized*</strong></li>
     </ul>
     <p>
-      Nothing would be formatted in the following messages (where / represents a
+      Nothing would be styled in the following messages (where \n represents a
       new line):
     </p>
     <ul>
       <li>not emphasized*</li>
       <li>*not emphasized</li>
-      <li>*not / emphasized*</li>
+      <li>*not \n emphasized*</li>
       <li>**</li>
       <li>****</li>
     </ul>
   </section2>
-  <section2 topic='Order of Operations' anchor='oporder'>
-    <p>
-      Block level styling such as preformatted blocks and quotations is always
-      handled before inlines such as emphasis and inline preformatted text.
-    </p>
-  </section2>
   <section2 topic='Bold' anchor='bold'>
     <p>
-      Text enclosed by '*' (U+002A ASTERISK) MUST be displayed with a greater
+      Text enclosed by '*' (U+002A ASTERISK) SHOULD be displayed with a greater
       weight than the surrounding text (bold face).
     </p>
     <example caption='Bold'><![CDATA[
 <body>
-  The full title is **Twelfth Night, or What You Will** but
+  The full title is *Twelfth Night, or What You Will* but
   *most* people shorten it.
 </body>
 ]]></example>
   </section2>
   <section2 topic='Italic' anchor='italic'>
     <p>
-      Text enclosed by '_'(U+005F LOW LINE) MUST be displayed in italics.
+      Text enclosed by '_' (U+005F LOW LINE) SHOULD be displayed in italics.
     </p>
     <example caption='Italic'><![CDATA[
 <body>
   The full title is _Twelfth Night, or What You Will_ but
-  __most__ people shorten it.
+  _most_ people shorten it.
 </body>
 ]]></example>
   </section2>
   <section2 topic='Strike through' anchor='strike'>
     <p>
-      Text enclosed by '~'(U+007E TILDE) MUST be displayed with a horizontal
+      Text enclosed by '~' (U+007E TILDE) SHOULD be displayed with a horizontal
       line through the middle (strike through).
     </p>
     <example caption='Strike through'><![CDATA[
@@ -258,10 +221,10 @@
 </body>
 ]]></example>
   </section2>
-  <section2 topic='Preformatted Inline Text' anchor='pre-inline'>
+  <section2 topic='Inline Preformatted Text' anchor='pre-inline'>
     <p>
-      Text enclosed by a '`' (U+0060 GRAVE ACCENT) MUST be displayed inline in a
+      Text enclosed by a '`' (U+0060 GRAVE ACCENT) SHOULD be displayed inline in
-      monospace font.
+      a monospace font.
       Inline formatting directives inside the inline preformatted text are not
       rendered.
       For example, in the following the word "monospace" is valid pre-formatted
@@ -274,17 +237,20 @@
     </ul>
     <example caption='Monospace text'><![CDATA[
 <body>
-  Wow, I can write in `monospace`, even a literal ``backtick (`)``!
+  Wow, I can write in `monospace`!
 </body>
 ]]></example>
   </section2>
   <section2 topic='Preformatted Block Text' anchor='pre-block'>
     <p>
       A block of text surrounded by lines consisting of a sequence of three
-      backticks (U+0060 GRAVE ACCENT), "```", is preformatted text and should be
+      backticks, "```" (U+0060 GRAVE ACCENT), is preformatted text and should be
       displayed exactly as it was entered including whitespace.
-      No other formatting described in this document should be rendered inside
+      If no closing "```" sequence exists, the preformatted block extends to the
-      a preformatted text block.
+      end of the input stream or the end of the parent block (whichever comes
+      first).
+      No other formatting described in this document should be rendered inside a
+      preformatted text block.
     </p>
     <example caption='Preformatted block text'><![CDATA[
 <body>
@@ -292,16 +258,26 @@
   (println &quot;Hello, world!&quot;)
   ```
 
-  This should show up as monospaced, preformatted text ⤴
+  This should show up as monospace, preformatted text ⤴
+</body>
+]]></example>
+    <example caption='No closing preformatted text sequence'><![CDATA[
+<body>
+  &gt; ```
+  &gt; (println &quot;Hello, world!&quot;)
+
+  The entire blockquote is a preformatted text block, but this line is
+  plaintext!
 </body>
 ]]></example>
   </section2>
   <section2 topic='Quotations' anchor='quote'>
     <p>
       A quotation is indicated by one or more lines with a byte stream beginning
-      with a '&gt;' (U+003E GREATER-THAN SIGN) immediately followed by a
+      with a '&gt;' (U+003E GREATER-THAN SIGN).
-      whitespace character.
+      Block quotes may contain any child block, including other quotations.
-      Inline formatting is rendered inside of quotations.
+      Lines inside the block quote MUST have leading spaces trimmed before
+      parsing the child block.
     </p>
     <example caption='Quotation (LTR)'><![CDATA[
 <body>
@@ -322,9 +298,19 @@
 </section1>
 <section1 topic='Implementation Notes' anchor='impl'>
   <p>
-    The rules for inline styling form a context free grammar that cannot be
+    This document does not define a regular grammar and thus styling cannot be
     matched by a regular expression.
-    A simple stack based parser is recommended instead.
+    Instead, a predictive recursive descent or LALR parser may be constructed.
+    For instance, a simple parser can be constructed by first parsing all text
+    into blocks and then recursively parsing the child-blocks inside block
+    quotations, the spans inside plain lines, and by returning the text inside
+    preformatted blocks without modification.
+  </p>
+  <p>
+    It is RECOMMENDED that formatting characters be displayed and formatted in
+    the same manner as the text they apply to.
+    For example, the string "*emphasis*" would be rendered as
+    "<strong>*emphasis*</strong>".
   </p>
 </section1>
 <section1 topic='Accessibility Considerations' anchor='access'>
@@ -333,6 +319,11 @@
     sufficient contrast exists between styled and unstyled text so that users
     with vision deficiencies are able to distinguish between the two.
   </p>
+  <p>
+    Formatted text may also be rendered poorly by screen readers.
+    When applying formatting it may be desirable to include directives to
+    exclude formatting characters from being read.
+  </p>
 </section1>
 <section1 topic='Internationalization Considerations' anchor='i18n'>
   <p>OPTIONAL.</p>
@@ -346,20 +337,7 @@
   </p>
 </section1>
 <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
-  <p>This specification defines the following XML namespaces:</p>
+  <p>This specification requires no interaction with the &REGISTRAR;</p>
-  <ul>
-    <li>urn:xmpp:styling:0</li>
-  </ul>
-  <p>
-    The &REGISTRAR; shall include the foregoing namespaces in its disco
-    features registry as defined in &xep0030;.
-  </p>
-  <code caption='Registry Submission'><![CDATA[
-<var>
-  <name>urn:xmpp:styling:0</name>
-  <desc>Indicates support for simple message styling.</desc>
-  <doc>XEP-XXXX</doc>
-</var>]]></code>
 </section1>
 <section1 topic='XML Schema' anchor='schema'>
   <p>This document does not define any new XML structure requiring a schema.</p>