mirror of
https://github.com/moparisthebest/xeps
synced 2024-12-21 07:08:51 -05:00
XEP-0393: update glossary/security considerations
This commit is contained in:
Sam Whited
parent
e404807349
commit
c5f85cba0d
218
xep-0393.xml
218
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,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 "Hello, world!")
|
||||
@ -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>
|
||||
> ```
|
||||
> (println "Hello, world!")
|
||||
@ -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 '>' (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 '>' (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>
|
||||
> That that is, is.
|
||||
|
||||
Said the old hermit of Prague.
|
||||
</body>
|
||||
]]></example>
|
||||
<example caption='Nested Quotation'><![CDATA[
|
||||
<example caption='Nested Quotation'><![CDATA[
|
||||
<body>
|
||||
>> That that is, is.
|
||||
> 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>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user