<?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>Body Markup Hints</title>
  <abstract>This document specifies hints about the markup language used in &BODY; elements.</abstract>
  &LEGALNOTICE;
  <number>xxxx</number>
  <status>ProtoXEP</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>bmh</shortname>
  &flow;
  <revision>
    <version>0.0.1</version>
    <date>2017-10-14</date>
    <initials>fs</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>

<section1 topic='Introduction' anchor='intro'>

  <p>This document specifies hints about the markup language used in &BODY; elements found in
  &MESSAGE; stanzas. It also specifies a mechanism to discover support of various markup
  dialects</p>

</section1>

<section1 topic="Markup Languages" anchor='languages'>

  <p>This list is not comprehensive and not meant to be.</p>

  <table caption="Defined Markup Languages">
    <tr>
      <th>Language Identifier</th>
      <th>Name</th>
      <th>Specification Link</th>
    </tr>
    <tr>
      <td>urn:xmpp:bmh:commonmark:0</td>
      <td>CommonMark</td>
      <td><link url='http://spec.commonmark.org/'>http://spec.commonmark.org/</link></td>
    </tr>
    <tr>
      <td>urn:xmpp:bmh:rst:0</td>
      <td>reStructuredText</td>
      <td><link   url='http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html'>http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html</link></td>
    </tr>
  </table>

  <p>TODO: Shall we define your own subset of e.g. CommonMark, XMPPMark? :)</p>

</section1>

<section1 topic='Exchanging messages with markup formatted bodies' anchor='exchanging'>

  <p>If the &BODY; element contains text which is "formatted" with a markup language, then the
  sending client MAY adds a &lt;body-markup-hint/&gt; element qualified by the 'https://xmpp.org/extensions/bmh/0/'
  namespace with the 'language' attribute set to the Language Identifier of the used markup
  language.</p>

  <example caption='A message stanza with a body markup hint'><![CDATA[
<message from='holden@rocinante.example.org' to='naomi@rocinante.example.org'>
  <body>
1. Ingredients

    - spaghetti
    - marinara sauce
    - salt

2. Cooking

   Bring water to boil, add a pinch of salt and spaghetti. Cook until pasta is **tender**.

3. Serve

   Drain the pasta on a plate. Add heated sauce.

   > No man is lonely eating spaghetti; it requires so much attention.

*Bon appetit!*
  </body>
  <body-markup-hint xmlns='https://xmpp.org/extensions/bmh/0/'
                    language='urn:xmpp:bmh:commonmark:0'/>
</message>
]]></example>

</section1>

<section1 topic='Discovering Support' anchor='discovery'>

  <p>It is RECOMMENDED that entities announce the supported body markup languages in its service
  discovery information as specified in &xep0030;. Every markup language is announced as a
  &lt;feature/&gt; element with the 'var' attribute set to the language identifier of the supported
  language.</p>

      <example caption='A service discovery information with the supported body markup languages'><![CDATA[
<iq from='julie@eros.example.org'
    to='miller@rocinante.example.org'
    id='info1'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    ...
    <feature var='urn:xmpp:bmh:commonmark:0'/>
    ...
  </query>
</iq>]]>
</example>

</section1>

<section1 topic='Business Rules' anchor='rules'>

  <p>There MUST be only one &lt;body-markup-hint/&gt; per &MESSAGE; stanza, and it applies to all
  &BODY; elements within the same stanza.</p>

</section1>

<section1 topic='Security Considerations' anchor='security'>

  <p>TODO: Discuss.</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'>

  <p>TODO: Is it sensible to establish a registry for this?</p>

</section1>

<section1 topic='XML Schema' anchor='schema'>

  <p>TODO: Add after the XEP leaves the 'experimental' state.</p>

</section1>

<section1 topic='Acknowledgements' anchor='acknowledgements'>

  <p>Thanks to everyone who provided feedback.</p>

</section1>

</xep>

<!-- Local Variables: -->
<!-- fill-column: 100 -->
<!-- indent-tabs-mode: nil -->
<!-- End: -->