From c5f85cba0d869a432a0c8df66f915b11aff33684 Mon Sep 17 00:00:00 2001 From: Sam Whited Date: Fri, 12 Jan 2018 12:19:48 -0600 Subject: [PATCH] XEP-0393: update glossary/security considerations --- xep-0393.xml | 218 +++++++++++++++++++++++++++++---------------------- 1 file changed, 125 insertions(+), 93 deletions(-) diff --git a/xep-0393.xml b/xep-0393.xml index 0144c3d3..45701a8a 100644 --- a/xep-0393.xml +++ b/xep-0393.xml @@ -25,6 +25,17 @@ styling &sam; + + 0.1.1 + 2018-01-12 + ssw + +

+ Minor clarifications and updates, add security considerations, and + expand the glossary. +

+ + 0.1.0 2017-11-22 @@ -95,6 +106,20 @@ The term "formatted text" is defined in &rfc7764;.

+ +
Block
+
+ 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: +
    +
  • A single line of text comprising one or more spans
    • +
  • A block quotation
    • +
  • A preformatted code block
    • +
+
+
Formal markup language
@@ -110,6 +135,37 @@ the text by computer programs.
+ +
Span
+
+ 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: +
    +
  • (plain span)
    • +
  • (*strong span*)
    • +
  • (_emphasized span_)
    • +
  • (_emphasized span containing (*strong span*)_)
    • +
  • (span one )(*span two*)
    • +
+
+ + +
Styling directive
+
+ 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. +
+
Whitespace character
@@ -136,32 +192,7 @@ - -

- A block is any chunk of text that can be parsed unambiguously in one pass. -

-
    -
  • A single line of text comprising one or more spans
    • -
  • A block quotation
    • -
  • A preformatted code block
    • -
- -

- 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: -

-
    -
  • (plain span)
    • -
  • (*strong span*)
    • -
  • (_emphasized span_)
    • -
  • (_emphasized span containing (*strong span*)_)
    • -
  • (span one )(*span two*)
    • -

Matches of spans between two styling directives MUST contain some text between the two styling directives and the opening styling directive MUST @@ -198,72 +229,73 @@

  • **
  • ****
    • -     - -

    - Text enclosed by '*' (U+002A ASTERISK) is strong SHOULD be displayed as - bold. -

    - +

    + Text enclosed by '*' (U+002A ASTERISK) is strong SHOULD be displayed as + bold. +

    + The full title is "Twelfth Night, or What You Will" but *most* people shorten it. ]]> -     - -

    - Text enclosed by '_' (U+005F LOW LINE) is emphasized and SHOULD be - displayed in italics. -

    - + +

    + Text enclosed by '_' (U+005F LOW LINE) is emphasized and SHOULD be + displayed in italics. +

    + The full title is _Twelfth Night, or What You Will_ but _most_ people shorten it. ]]> -     - -

    - Text enclosed by '~' (U+007E TILDE) SHOULD be displayed with a horizontal - line through the middle. -

    - + +

    + Text enclosed by '~' (U+007E TILDE) SHOULD be displayed with a horizontal + line through the middle. +

    + Everyone ~dis~likes cake. ]]> -     - -

    - Text enclosed by a '`' (U+0060 GRAVE ACCENT) is a preformatted span SHOULD - be displayed inline in a monospace font. - A preformatted span may only contain plaintext. - Inline formatting directives inside the preformatted span are not - rendered. - For example, the following all contain valid preformatted spans: -

    -
      -
    • This is `monospace`
      • -
    • This is `*monospace*`
      • -
    • This is *`monospace and bold`*
      • -
    - + +

    + Text enclosed by a '`' (U+0060 GRAVE ACCENT) is a preformatted span SHOULD + be displayed inline in a monospace font. + A preformatted span may only contain plaintext. + Inline formatting directives inside the preformatted span are not + rendered. + For example, the following all contain valid preformatted spans: +

    +
      +
    • This is `monospace`
      • +
    • This is `*monospace*`
      • +
    • This is *`monospace and bold`*
      • +
    + Wow, I can write in `monospace`! ]]> +     - -

    - A preformatted text block is started by a line beginning with "```" - (U+0060 GRAVE ACCENT), and ended by a line containing only three grave - accents or the end of the parent block (whichever comes first). - Preformatted text blocks cannot contain child blocks and other styling - MUST NOT be rendered inside the block. - Text inside a preformatted block SHOULD be displayed in a monospace font. -

    - + +

    + A preformatted text block is started by a line beginning with "```" + (U+0060 GRAVE ACCENT), and ended by a line containing only three grave + accents or the end of the parent block (whichever comes first). + Preformatted text blocks cannot contain child blocks and other styling + MUST NOT be rendered inside the block. + Text inside a preformatted block SHOULD be displayed in a monospace font. +

    + ```ignored (println "Hello, world!") @@ -272,7 +304,7 @@ This should show up as monospace, preformatted text ⤴ ]]> - > ``` > (println "Hello, world!") @@ -281,23 +313,23 @@ plaintext! ]]> -     - -

    - A quotation is indicated by one or more lines with a byte stream beginning - with a '>' (U+003E GREATER-THAN SIGN). - Block quotes may contain any child block, including other quotations. - Lines inside the block quote MUST have leading spaces trimmed before - parsing the child block. -

    - + +

    + A quotation is indicated by one or more lines with a byte stream beginning + with a '>' (U+003E GREATER-THAN SIGN). + Block quotes may contain any child block, including other quotations. + Lines inside the block quote MUST have leading spaces trimmed before + parsing the child block. +

    + > That that is, is. Said the old hermit of Prague. ]]> - >> That that is, is. > Said the old hermit of Prague. @@ -305,17 +337,17 @@ Who? ]]> +

    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. - 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. + Instead, 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 individual lines, and by returning the text + inside preformatted blocks without modification.

    It is RECOMMENDED that formatting characters be displayed and formatted in @@ -336,11 +368,11 @@ exclude formatting characters from being read.

    - -

    OPTIONAL.

    -     -

    REQUIRED.

    +

    + Authors of message styling parsers should take care that improperly + formatted messages cannot lead to buffer overruns or code execution. +