moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-23 01:32:22 -05:00
Code Issues Releases Wiki Activity

XEP-0393: update glossary/security considerations

Browse Source
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/>
<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,72 +229,73 @@
<li>**</li>
<li>****</li>
</ul>
</section2>
<section2 topic='Strong' anchor='strong'>
<p>
Text enclosed by '*' (U+002A ASTERISK) is strong SHOULD be displayed as
bold.
</p>
<example caption='Strong'><![CDATA[
<section3 topic='Strong' anchor='strong'>
<p>
Text enclosed by '*' (U+002A ASTERISK) is strong SHOULD be displayed as
bold.
</p>
<example caption='Strong'><![CDATA[
<body>
The full title is "Twelfth Night, or What You Will" but
*most* people shorten it.
</body>
]]></example>
</section2>
<section2 topic='Emphasis' anchor='emph'>
<p>
Text enclosed by '_' (U+005F LOW LINE) is emphasized and SHOULD be
displayed in italics.
</p>
<example caption='Italic'><![CDATA[
</section3>
<section3 topic='Emphasis' anchor='emph'>
<p>
Text enclosed by '_' (U+005F LOW LINE) is emphasized and 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.
</body>
]]></example>
</section2>
<section2 topic='Strike through' anchor='strike'>
<p>
Text enclosed by '~' (U+007E TILDE) SHOULD be displayed with a horizontal
line through the middle.
</p>
<example caption='Strike through'><![CDATA[
</section3>
<section3 topic='Strike through' anchor='strike'>
<p>
Text enclosed by '~' (U+007E TILDE) SHOULD be displayed with a horizontal
line through the middle.
</p>
<example caption='Strike through'><![CDATA[
<body>
Everyone ~dis~likes cake.
</body>
]]></example>
</section2>
<section2 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.
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:
</p>
<ul>
<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>
</ul>
<example caption='Monospace text'><![CDATA[
</section3>
<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.
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:
</p>
<ul>
<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>
</ul>
<example caption='Monospace text'><![CDATA[
<body>
Wow, I can write in `monospace`!
</body>
]]></example>
</section3>
</section2>
<section2 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
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.
</p>
<example caption='Preformatted block text'><![CDATA[
<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
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.
</p>
<example caption='Preformatted block text'><![CDATA[
<body>
```ignored
(println &quot;Hello, world!&quot;)
@ -272,7 +304,7 @@
This should show up as monospace, preformatted text ⤴
</body>
]]></example>
<example caption='No closing preformatted text sequence'><![CDATA[
<example caption='No closing preformatted text sequence'><![CDATA[
<body>
&gt; ```
&gt; (println &quot;Hello, world!&quot;)
@ -281,23 +313,23 @@
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).
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.
</p>
<example caption='Quotation (LTR)'><![CDATA[
</section3>
<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).
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.
</p>
<example caption='Quotation (LTR)'><![CDATA[
<body>
&gt; That that is, is.
Said the old hermit of Prague.
</body>
]]></example>
<example caption='Nested Quotation'><![CDATA[
<example caption='Nested Quotation'><![CDATA[
<body>
&gt;&gt; That that is, is.
&gt; Said the old hermit of Prague.
@ -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.
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.
</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>