moparisthebest
/
xeps
mirror of https://github.com/moparisthebest/xeps
1
0
Fork 0
Code Issues Releases Wiki Activity

XEP-0393: update glossary/security considerations

This commit is contained in:
Sam Whited 2018-01-12 12:19:48 -06:00
parent e404807349
commit c5f85cba0d
1 changed files with 125 additions and 93 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

218
xep-0393.xml
View File

@ -25,6 +25,17 @@
<supersededby/> <supersededby/>
<shortname>styling</shortname> <shortname>styling</shortname>
&sam; &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> <revision>
<version>0.1.0</version> <version>0.1.0</version>
<date>2017-11-22</date> <date>2017-11-22</date>
@ -95,6 +106,20 @@
The term "formatted text" is defined in &rfc7764;. The term "formatted text" is defined in &rfc7764;.
</p> </p>
<dl> <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> <di>
<dt>Formal markup language</dt> <dt>Formal markup language</dt>
<dd> <dd>
@ -110,6 +135,37 @@
the text by computer programs. the text by computer programs.
</dd> </dd>
</di> </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> <di>
<dt>Whitespace character</dt> <dt>Whitespace character</dt>
<dd> <dd>
@ -136,32 +192,7 @@
</ul> </ul>
</section1> </section1>
<section1 topic='Business Rules' anchor='rules'> <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'> <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> <p>
Matches of spans between two styling directives MUST contain some text Matches of spans between two styling directives MUST contain some text
between the two styling directives and the opening styling directive MUST between the two styling directives and the opening styling directive MUST
@ -198,72 +229,73 @@
<li>**</li> <li>**</li>
<li>****</li> <li>****</li>
</ul> </ul>
</section2> <section3 topic='Strong' anchor='strong'>
<section2 topic='Strong' anchor='strong'> <p>
<p> Text enclosed by '*' (U+002A ASTERISK) is strong SHOULD be displayed as
Text enclosed by '*' (U+002A ASTERISK) is strong SHOULD be displayed as bold.
bold. </p>
</p> <example caption='Strong'><![CDATA[
<example caption='Strong'><![CDATA[
<body> <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. *most* people shorten it.
</body> </body>
]]></example> ]]></example>
</section2> </section3>
<section2 topic='Emphasis' anchor='emph'> <section3 topic='Emphasis' anchor='emph'>
<p> <p>
Text enclosed by '_' (U+005F LOW LINE) is emphasized and SHOULD be Text enclosed by '_' (U+005F LOW LINE) is emphasized and SHOULD be
displayed in italics. displayed in italics.
</p> </p>
<example caption='Italic'><![CDATA[ <example caption='Italic'><![CDATA[
<body> <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. _most_ people shorten it.
</body> </body>
]]></example> ]]></example>
</section2> </section3>
<section2 topic='Strike through' anchor='strike'> <section3 topic='Strike through' anchor='strike'>
<p> <p>
Text enclosed by '~' (U+007E TILDE) SHOULD be displayed with a horizontal Text enclosed by '~' (U+007E TILDE) SHOULD be displayed with a horizontal
line through the middle. line through the middle.
</p> </p>
<example caption='Strike through'><![CDATA[ <example caption='Strike through'><![CDATA[
<body> <body>
Everyone ~dis~likes cake. Everyone ~dis~likes cake.
</body> </body>
]]></example> ]]></example>
</section2> </section3>
<section2 topic='Preformatted Span' anchor='mono'> <section3 topic='Preformatted Span' anchor='mono'>
<p> <p>
Text enclosed by a '`' (U+0060 GRAVE ACCENT) is a preformatted span SHOULD Text enclosed by a '`' (U+0060 GRAVE ACCENT) is a preformatted span SHOULD
be displayed inline in a monospace font. be displayed inline in a monospace font.
A preformatted span may only contain plaintext. A preformatted span may only contain plaintext.
Inline formatting directives inside the preformatted span are not Inline formatting directives inside the preformatted span are not
rendered. rendered.
For example, the following all contain valid preformatted spans: For example, the following all contain valid preformatted spans:
</p> </p>
<ul> <ul>
<li>This is <tt>`monospace`</tt></li> <li>This is <tt>`monospace`</tt></li>
<li>This is <tt>`*monospace*`</tt></li> <li>This is <tt>`*monospace*`</tt></li>
<li>This is <strong><tt>*`monospace and bold`*</tt></strong></li> <li>This is <strong><tt>*`monospace and bold`*</tt></strong></li>
</ul> </ul>
<example caption='Monospace text'><![CDATA[ <example caption='Monospace text'><![CDATA[
<body> <body>
Wow, I can write in `monospace`! Wow, I can write in `monospace`!
</body> </body>
]]></example> ]]></example>
</section3>
</section2> </section2>
<section2 topic='Preformatted Block' anchor='pre-block'> <section2 topic='Blocks' anchor='block'>
<p> <section3 topic='Preformatted Block' anchor='pre-block'>
A preformatted text block is started by a line beginning with "```" <p>
(U+0060 GRAVE ACCENT), and ended by a line containing only three grave A preformatted text block is started by a line beginning with "```"
accents or the end of the parent block (whichever comes first). (U+0060 GRAVE ACCENT), and ended by a line containing only three grave
Preformatted text blocks cannot contain child blocks and other styling accents or the end of the parent block (whichever comes first).
MUST NOT be rendered inside the block. Preformatted text blocks cannot contain child blocks and other styling
Text inside a preformatted block SHOULD be displayed in a monospace font. MUST NOT be rendered inside the block.
</p> Text inside a preformatted block SHOULD be displayed in a monospace font.
<example caption='Preformatted block text'><![CDATA[ </p>
<example caption='Preformatted block text'><![CDATA[
<body> <body>
```ignored ```ignored
(println &quot;Hello, world!&quot;) (println &quot;Hello, world!&quot;)
@ -272,7 +304,7 @@
This should show up as monospace, preformatted text ⤴ This should show up as monospace, preformatted text ⤴
</body> </body>
]]></example> ]]></example>
<example caption='No closing preformatted text sequence'><![CDATA[ <example caption='No closing preformatted text sequence'><![CDATA[
<body> <body>
&gt; ``` &gt; ```
&gt; (println &quot;Hello, world!&quot;) &gt; (println &quot;Hello, world!&quot;)
@ -281,23 +313,23 @@
plaintext! plaintext!
</body> </body>
]]></example> ]]></example>
</section2> </section3>
<section2 topic='Quotations' anchor='quote'> <section3 topic='Quotations' anchor='quote'>
<p> <p>
A quotation is indicated by one or more lines with a byte stream beginning A quotation is indicated by one or more lines with a byte stream beginning
with a '&gt;' (U+003E GREATER-THAN SIGN). with a '&gt;' (U+003E GREATER-THAN SIGN).
Block quotes may contain any child block, including other quotations. Block quotes may contain any child block, including other quotations.
Lines inside the block quote MUST have leading spaces trimmed before Lines inside the block quote MUST have leading spaces trimmed before
parsing the child block. parsing the child block.
</p> </p>
<example caption='Quotation (LTR)'><![CDATA[ <example caption='Quotation (LTR)'><![CDATA[
<body> <body>
&gt; That that is, is. &gt; That that is, is.
Said the old hermit of Prague. Said the old hermit of Prague.
</body> </body>
]]></example> ]]></example>
<example caption='Nested Quotation'><![CDATA[ <example caption='Nested Quotation'><![CDATA[
<body> <body>
&gt;&gt; That that is, is. &gt;&gt; That that is, is.
&gt; Said the old hermit of Prague. &gt; Said the old hermit of Prague.
@ -305,17 +337,17 @@
Who? Who?
</body> </body>
]]></example> ]]></example>
</section3>
</section2> </section2>
</section1> </section1>
<section1 topic='Implementation Notes' anchor='impl'> <section1 topic='Implementation Notes' anchor='impl'>
<p> <p>
This document does not define a regular grammar and thus styling cannot be This document does not define a regular grammar and thus styling cannot be
matched by a regular expression. 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>
<p> <p>
It is RECOMMENDED that formatting characters be displayed and formatted in It is RECOMMENDED that formatting characters be displayed and formatted in
@ -336,11 +368,11 @@
exclude formatting characters from being read. exclude formatting characters from being read.
</p> </p>
</section1> </section1>
<section1 topic='Internationalization Considerations' anchor='i18n'>
<p>OPTIONAL.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'> <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>
<section1 topic='IANA Considerations' anchor='iana'> <section1 topic='IANA Considerations' anchor='iana'>
<p> <p>