<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
  <header>
    <title>Spoiler messages</title>
    <abstract>
      This specification defines an XMPP protocol extension that provides a
      method for indicating a message is a spoiler and should be displayed as
      such.
    </abstract>
    &LEGALNOTICE;
    <number>0382</number>
    <status>Experimental</status>
    <type>Standards Track</type>
    <sig>Standards</sig>
    <approver>Council</approver>
    <dependencies>
      <spec>XMPP Core</spec>
    </dependencies>
    <supersedes/>
    <supersededby/>
    <shortname>spoilers</shortname>
    <author>
      <firstname>Severino</firstname>
      <surname>Ferrer de la Peñita</surname>
      <email>soul@blastersklan.com</email>
      <jid>soul@blastersklan.com</jid>
    </author>
    <author>
      <firstname>Xavier</firstname>
      <surname>Ferrer de la Peñita</surname>
      <email>vaulor@openmailbox.org</email>
      <jid>vaulor@blastersklan.com</jid>
    </author>
    <revision>
      <version>0.1</version>
      <date>2016-12-07</date>
      <initials>XEP Editor: ssw</initials>
      <remark><p>Initial version approved by the council.</p></remark>
    </revision>
    <revision>
      <version>0.0.2</version>
      <date>2016-10-31</date>
      <initials>sfp, xfp</initials>
      <remark><p>First draft.</p></remark>
    </revision>
  </header>
  <section1 topic='Introduction' anchor='intro'>
    <p>
      Sometimes, people have the need to send large texts related to the current
      topic but because of their length, make it hard to follow the conversation
      (specially on mobile devices). On other occasions, people may want to
      discuss or just make a little quick comment related to a film or a book in
      a conversation with multiple people that may or may not know the plot.
      Also, every now and then, people may want to send a private message (in
      the sense that people near the receiver must not be able to read) or
      inline images to someone is known is in a public enviroment like
      libraries, coffehouses, bars, etc.
    </p>

    <p>
      This specification defines a way to indicate message's content does not
      have to be displayed until receiver requests to do so.
    </p>
  </section1>
  <section1 topic='Discovering support' anchor='disco'>
    <p>
      If a client implements spoiler messages, it MUST specify the
      'urn:xmpp:spoiler:0' feature in its service discovery information
      features as specified in &xep0030; and the Entity Capabilities profile
      specified in &xep0115;.
    </p>
    <example caption='Client requests information about a chat partner&apos;s client'><![CDATA[
<iq from='romeo@montague.net/orchard'
    id='disco1'
    to='juliet@capulet.lit/balcony'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>]]></example>
    <example caption='Partner&apos;s client advertises support for spoiler messages'><![CDATA[
<iq to='romeo@montague.net/orchard'
    id='disco1'
    from='juliet@capulet.lit/balcony'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
…
    <feature var='urn:xmpp:spoiler:0'/>
…
  </query>
</iq>]]></example>
  </section1>
  <section1 topic='Use Cases' anchor='usecases'>
    <p>
      Messages user wants to be sent as spoilers, MUST contain a &lt;spoiler&gt; element qualified by the
      'urn:xmpp:spoiler:0' namespace and optionally, &lt;spoiler&gt; elements may contain character data as
      a hint that warns about the topic of the spoiler message. They may also possess the 'xml:lang'
      attribute.
    </p>
    <example caption='User sends a spoiler message without the hint'><![CDATA[
<message to='romeo@montague.net/orchard' from='juliet@capulet.net/balcony' id='spoiler1'>
  <body>This is a very long message so I'm going to hide inside a spoiler [...] </body>
  <spoiler xmlns='urn:xmpp:spoiler:0'/>
</message>
]]></example>
    <example caption='User sends a spoiler message with the hint'><![CDATA[
<message to='romeo@montague.net/orchard' from='juliet@capulet.net/balcony' id='spoiler2'>
  <body>And at the end of the story, both of them die! It is so tragic!</body>
  <spoiler xmlns='urn:xmpp:spoiler:0'>Love story end</spoiler>
</message>
]]></example>
    <example caption='User sends a spoiler message with the hint in two languages'><![CDATA[
<message to='romeo@montague.net/orchard' from='juliet@capulet.net/balcony' id='spoiler3'>
  <body>holidays.png</body>
  <spoiler xml:lang='en' xmlns='urn:xmpp:spoiler:0'>Trip to the beach</spoiler>
  <spoiler xml:lang='ca' xmlns='urn:xmpp:spoiler:0'>Viatge a la platja</spoiler>
</message>
]]></example>
    <example caption='User sends a spoiler message with the hint and body in two languages'><![CDATA[
<message to='romeo@montague.net/orchard' from='juliet@capulet.net/balcony' id='spoiler4'>
  <body xml:lang='en'>And at the end of the story, both of them die! It is so tragic!</body>
  <body xml:lang='ca'>I al final de la història, els dos moren! És tan tràgic!</body>
  <spoiler xml:lang='en' xmlns='urn:xmpp:spoiler:0'>Love story end</spoiler>
  <spoiler xml:lang='ca' xmlns='urn:xmpp:spoiler:0'>Fi de la història d'amor</spoiler>
</message>
]]></example>
    </section1>
  <section1 topic='Business Rules' anchor='rules'>
    <ol>
      <li>It MUST be clear that a message is in fact a spoiler and its content MUST only be displayed upon
        user's request.</li>
      <li>Clients MAY provide a way to display spoilers always uncovered, without the need of interaction
        by the user (e.g. in the client's settings).</li>
      <li>Clients SHOULD display spoiler's hint, if any, before showing message's content.</li>
      <li>Clients MAY display spoiler's hint even after showing message's content (e.g. as a header or
        title of the message).</li>
      <li>Users SHOULD uncover or hide a spoiler message at will, anytime.</li>
    </ol>
  </section1>
  <section1 topic='Security Considerations' anchor='security'>
    <p>
      This document introduces no additional security considerations above and
      beyond those defined in the documents on which it depends.
    </p>
  </section1>
  <section1 topic='IANA Considerations' anchor='iana'>
    <p>This document requires no interaction with &IANA;.</p>
  </section1>
  <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
    <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
      <p>This specification defines the following XML namespace:</p>
      <ul>
        <li>'urn:xmpp:spoiler:0'</li>
      </ul>
      <p>
        Upon advancement of this specification to draft status, the &REGISTRAR;
        shall include the foregoing namespaces in its registry of protocol
        namespaces &NAMESPACES; and in its disco features registry
        &DISCOFEATURES; as defined in &xep0030;.
      </p>
      <code caption='Registration'><![CDATA[
<var>
  <name>urn:xmpp:spoiler:0</name>
  <desc>Indicates that a message's content should not be displayed by default.</desc>
  <doc>0382</doc>
</var>
]]></code>
    </section2>
  </section1>
  <section1 topic='XML Schema' anchor='schema'>
    <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:spoiler:0'
    xmlns='urn:xmpp:spoiler:0'
    elementFormDefault='qualified'>

  <xs:element name='spoiler'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='xs:string'>
          <xs:attribute ref='xml:lang' use='optional'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>


</xs:schema>
]]></code>
  </section1>
</xep>
