XEP-0393: update glossary/security considerations

xep-0393.xml

@@ -25,6 +25,17 @@
   <supersededby/>
   <shortname>styling</shortname>
   &sam;
+  <revision>
+    <version>0.1.1</version>
+    <date>2018-01-12</date>
+    <initials>ssw</initials>
+    <remark>
+      <p>
+        Minor clarifications and updates, add security considerations, and
+        expand the glossary.
+      </p>
+    </remark>
+  </revision>
   <revision>
     <version>0.1.0</version>
     <date>2017-11-22</date>
@@ -95,6 +106,20 @@
     The term "formatted text" is defined in &rfc7764;.
   </p>
   <dl>
+    <di>
+      <dt>Block</dt>
+      <dd>
+        Any chunk of text that can be parsed unambiguously in one pass.
+        Blocks may contain one or more children which may be other blocks or
+        spans.
+        For example:
+        <ul>
+          <li>A single line of text comprising one or more spans</li>
+          <li>A block quotation</li>
+          <li>A preformatted code block</li>
+        </ul>
+      </dd>
+    </di>
     <di>
       <dt>Formal markup language</dt>
       <dd>
@@ -110,6 +135,37 @@
         the text by computer programs.
       </dd>
     </di>
+    <di>
+      <dt>Span</dt>
+      <dd>
+        A group of text that is rendered inline and where the entire group is
+        rendered in the same manner.
+        Spans may be either plain text with no formatting applied, or may be
+        formatted text that is enclosed by two styling directives.
+        Spans are always children of blocks and may not escape from their
+        containing block.
+        The following all contain spans marked by parenthesis:
+        <ul>
+          <li>(plain span)</li>
+          <li>(<strong>*strong span*</strong>)</li>
+          <li>(<em>_emphasized span_</em>)</li>
+          <li>(<em>_emphasized span containing </em>(<em><strong>*strong span*</strong></em>)<em>_</em>)</li>
+          <li>(span one )(<strong>*span two*</strong>)</li>
+        </ul>
+      </dd>
+    </di>
+    <di>
+      <dt>Styling directive</dt>
+      <dd>
+        A character or set of characters that indicates the beginning of a span
+        or block.
+        For example, in certain contexts the characters '*' (U+002A ASTERISK),
+        and '_' (U+005F LOW LINE) may be styling directives that indicate the
+        beginning of a strong or emphasis span and the string '```'  (U+0060
+        GRAVE ACCENT) may be a styling directive that indicate the beginning of
+        a preformatted code block.
+      </dd>
+    </di>
     <di>
       <dt>Whitespace character</dt>
       <dd>
@@ -136,32 +192,7 @@
   </ul>
 </section1>
 <section1 topic='Business Rules' anchor='rules'>
-  <section2 topic='Blocks' anchor='block'>
-    <p>
-      A block is any chunk of text that can be parsed unambiguously in one pass.
-    </p>
-    <ul>
-      <li>A single line of text comprising one or more spans</li>
-      <li>A block quotation</li>
-      <li>A preformatted code block</li>
-    </ul>
-  </section2>
   <section2 topic='Spans' anchor='span'>
-    <p>
-      A span is a group of text that is rendered inline and where the entire
-      group is rendered in the same manner.
-      Spans may be either plain text with no formatting applied, or may be
-      formatted text that is enclosed by two styling directives.
-      Spans may not escape from their containing block.
-      The following all contain spans marked by parenthesis:
-    </p>
-    <ul>
-      <li>(plain span)</li>
-      <li>(<strong>*strong span*</strong>)</li>
-      <li>(<em>_emphasized span_</em>)</li>
-      <li>(<em>_emphasized span containing </em>(<em><strong>*strong span*</strong></em>)<em>_</em>)</li>
-      <li>(span one )(<strong>*span two*</strong>)</li>
-    </ul>
     <p>
       Matches of spans between two styling directives MUST contain some text
       between the two styling directives and the opening styling directive MUST
@@ -198,8 +229,7 @@
       <li>**</li>
       <li>****</li>
     </ul>
-  </section2>
+    <section3 topic='Strong' anchor='strong'>
-  <section2 topic='Strong' anchor='strong'>
       <p>
         Text enclosed by '*' (U+002A ASTERISK) is strong SHOULD be displayed as
         bold.
@@ -210,8 +240,8 @@
   *most* people shorten it.
 </body>
 ]]></example>
-  </section2>
+    </section3>
-  <section2 topic='Emphasis' anchor='emph'>
+    <section3 topic='Emphasis' anchor='emph'>
       <p>
         Text enclosed by '_' (U+005F LOW LINE) is emphasized and SHOULD be
         displayed in italics.
@@ -222,8 +252,8 @@
   _most_ people shorten it.
 </body>
 ]]></example>
-  </section2>
+    </section3>
-  <section2 topic='Strike through' anchor='strike'>
+    <section3 topic='Strike through' anchor='strike'>
       <p>
         Text enclosed by '~' (U+007E TILDE) SHOULD be displayed with a horizontal
         line through the middle.
@@ -233,8 +263,8 @@
   Everyone ~dis~likes cake.
 </body>
 ]]></example>
-  </section2>
+    </section3>
-  <section2 topic='Preformatted Span' anchor='mono'>
+    <section3 topic='Preformatted Span' anchor='mono'>
       <p>
         Text enclosed by a '`' (U+0060 GRAVE ACCENT) is a preformatted span SHOULD
         be displayed inline in a monospace font.
@@ -253,8 +283,10 @@
   Wow, I can write in `monospace`!
 </body>
 ]]></example>
+    </section3>
   </section2>
-  <section2 topic='Preformatted Block' anchor='pre-block'>
+  <section2 topic='Blocks' anchor='block'>
+    <section3 topic='Preformatted Block' anchor='pre-block'>
       <p>
         A preformatted text block is started by a line beginning with "```"
         (U+0060 GRAVE ACCENT), and ended by a line containing only three grave
@@ -281,8 +313,8 @@
   plaintext!
 </body>
 ]]></example>
-  </section2>
+    </section3>
-  <section2 topic='Quotations' anchor='quote'>
+    <section3 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).
@@ -305,17 +337,17 @@
   Who?
 </body>
 ]]></example>
+    </section3>
   </section2>
 </section1>
 <section1 topic='Implementation Notes' anchor='impl'>
   <p>
     This document does not define a regular grammar and thus styling cannot be
     matched by a regular expression.
-    Instead, a predictive recursive descent or LALR parser may be constructed.
+    Instead, a simple parser can be constructed by first parsing all text into
-    For instance, a simple parser can be constructed by first parsing all text
+    blocks and then recursively parsing the child-blocks inside block
-    into blocks and then recursively parsing the child-blocks inside block
+    quotations, the spans inside individual lines, and by returning the text
-    quotations, the spans inside plain lines, and by returning the text inside
+    inside preformatted blocks without modification.
-    preformatted blocks without modification.
   </p>
   <p>
     It is RECOMMENDED that formatting characters be displayed and formatted in
@@ -336,11 +368,11 @@
     exclude formatting characters from being read.
   </p>
 </section1>
-<section1 topic='Internationalization Considerations' anchor='i18n'>
-  <p>OPTIONAL.</p>
-</section1>
 <section1 topic='Security Considerations' anchor='security'>
-  <p>REQUIRED.</p>
+  <p>
+    Authors of message styling parsers should take care that improperly
+    formatted messages cannot lead to buffer overruns or code execution.
+  </p>
 </section1>
 <section1 topic='IANA Considerations' anchor='iana'>
   <p>