XEP-0393: clarify quote and plain behavior

This commit is contained in:
Sam Whited 2018-01-13 12:50:03 -06:00
parent d7bbbc330e
commit b391222d92
1 changed files with 69 additions and 26 deletions

View File

@ -25,6 +25,16 @@
<supersededby/>
<shortname>styling</shortname>
&sam;
<revision>
<version>0.1.2</version>
<date>2018-01-13</date>
<initials>ssw</initials>
<remark>
<p>
Clarify block quote and plain text parsing and formatting behavior.
</p>
</remark>
</revision>
<revision>
<version>0.1.1</version>
<date>2018-01-12</date>
@ -98,6 +108,22 @@
</li>
</ul>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<ul>
<li>
As a user sending an instant message to a friend, I want to be able to
emphasize an important part of my message.
</li>
<li>
As a software developer, I want to be able to send code as pre-formatted,
monospace, block or inline text to another developer.
</li>
<li>
As a multi-user chat user I want to add context to my reply by quoting an
earlier message in the chat.
</li>
</ul>
</section1>
<section1 topic='Glossary' anchor='glossary'>
<p>
Many important terms used in this document are defined in &unicode;.
@ -175,32 +201,15 @@
</di>
</dl>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<ul>
<li>
As a user sending an instant message to a friend, I want to be able to
emphasize an important part of my message.
</li>
<li>
As a software developer, I want to be able to send pre-formatted,
monospace, block or inline text to another developer.
</li>
<li>
As a multi-user chat user I want to quote something someone said earlier
in the chat and make it evident that the text is a quotation.
</li>
</ul>
</section1>
<section1 topic='Business Rules' anchor='rules'>
<section2 topic='Spans' anchor='span'>
<p>
Matches of spans between two styling directives MUST contain some text
between the two styling directives and the opening styling directive MUST
be located at the beginning of the line, or after a whitespace character.
The opening styling directive MUST also not be followed by a whitespace
character.
The closing styling directive MUST NOT be preceeded by a whitespace
character.
The opening styling directive MUST NOT be followed by a whitespace
character and the closing styling directive MUST NOT be preceeded by a
whitespace character.
Spans are always parsed from the beginning of the byte stream to the end
and are lazily matched.
Characters that would be styling directives but do not follow these rules
@ -229,10 +238,21 @@
<li>**</li>
<li>****</li>
</ul>
<section3 topic='Plain' anchor='plain'>
<p>
Any text inside of a block that is not part of another span is
implicitly considered to be inside of a "plain text" span.
</p>
<example caption='Plain'><![CDATA[
<body>
(Two spans, both )(*alike in dignity*)
</body>
]]></example>
</section3>
<section3 topic='Strong' anchor='strong'>
<p>
Text enclosed by '*' (U+002A ASTERISK) is strong SHOULD be displayed as
bold.
Text enclosed by '*' (U+002A ASTERISK) is strong and SHOULD be displayed
with a heavier font weight than the surrounding text (bold).
</p>
<example caption='Strong'><![CDATA[
<body>
@ -268,7 +288,7 @@
<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.
A preformatted span may only contain a single plain span.
Inline formatting directives inside the preformatted span are not
rendered.
For example, the following all contain valid preformatted spans:
@ -286,7 +306,28 @@
</section3>
</section2>
<section2 topic='Blocks' anchor='block'>
<section3 topic='Preformatted Block' anchor='pre-block'>
<p>
Parsers implementing message styling will first parse blocks and then
parse child blocks or spans if allowed by the specific block type.
</p>
<section3 topic='Plain' anchor='line-block'>
<p>
Groups of lines that are not part of any other block are considered a
"plain" block, as are individual lines of text that are not inside of a
preformatted text block.
Plain blocks are not bound by styling directives and do not imply
formatting themselves, but they may contain spans which imply
formatting.
</p>
<example caption='Plain block text'><![CDATA[
<body>
((There are four blocks in this body marked by parens,)
(but there is no *formatting)
(as spans* may not escape blocks.))
</body>
]]></example>
</section3>
<section3 topic='Preformatted Text' 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
@ -316,11 +357,13 @@
</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).
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.
It is RECOMMENDED that text inside of a block quote be indented or
distinguished from the surrounding text in some other way.
</p>
<example caption='Quotation (LTR)'><![CDATA[
<body>