<?xml version="1.0" encoding="UTF-8"?>
<appendix id="kopete-emoticons">
<appendixinfo>
    <title>Emoticons Specification</title>
    <releaseinfo>Version 0.1</releaseinfo>
    <date>07 January 2005</date>
    <authorgroup>
      <author>
	<firstname>Olivier</firstname>
	<surname>Goffart</surname>
	<affiliation>
	  <address>
	    <email>ogoffart@tiscalinet.be</email>
	  </address>
	</affiliation>
      </author>
    </authorgroup>
  </appendixinfo>

<title>Emoticons</title>

  <sect1 id="introduction-emoticons">
    <title>Introduction</title>
    <para>
      This DRAFT document defines how to make a theme of emoticons typically used
		in instant messaging applications
    </para>
    <para>
      The basic scheme is very simple. The theme consists in one sub directory which
		contains all the pictures and an &XML; file that gives each picture ASCII symbols.
		A .directory file might be used.
    </para>
  <sect2 id="location">
    <title>File locations</title>
    <para>
      Files involved in this specification are located according to the "desktop
      base directory specification" which can be found on <ulink
      url="http://www.freedesktop.org/standards/">www.freedesktop.org</ulink>.
    </para>
    <para>
		All the files of the theme must be placed in a sub directory of
		 <varname>$XDG_DATA_DIRS</varname>/emoticons/
		 The name of the directory must be equal to the name of the theme.
		 That directory <emphasis>must</emphasis> contains a file called <varname>emoticons.xml</varname>
		 the format of that file is described below.
	</para>
	<para>
		  The theme directory may also contain a .directory file which contains
		  translations of the theme name and/or an icon for that theme.
	</para>
  </sect2>
  <sect2 id="emoticons-map-format">
    <title>Format of the emoticons.xml file</title>
    <para>
      Emoticon map files must be well-formed XML files.
		Implementations should ignore unknown tag or unknown attributes.
    </para>
    <sect3 id="emoticons-map-elements">
      <title>Elements</title>
      <para>
        <variablelist>
          <varlistentry>
					<term>&lt;messaging-emoticon-map&gt; [version="0.1"]</term>
            <listitem>
              <para>
						 The root element is &lt;messaging-emoticon-map&gt;
						 all other elements are contained by it.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>&lt;emoticon file="..."&gt;</term>
            <listitem>
              <para>
						This element represents one emoticon.
						The attribute file is the name of the image file which must be in the same directory.
						The extension may be omitted. In that case, the implementation look in that directory
						for a file with the same name in a supported format.
              </para>
				  <para>
						 There are no order for emoticon in the map.
						 But the first icon in the map is generally used to identify the theme graphically.
						 By convention the this SHOULD be :-)
				  </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>&lt;string&gt;</term>
            <listitem>
              <para>
                This element may only appear below &lt;emoticon&gt;.
					 It represents the ASCII string which will be matched in the text,
					 and replaced by the image specified by the file attribute of the emoticon.
              </para>
				  <para>
						 There may be several strings per emoticon.
				  </para>
				  <para>
						 There is no order for string inside an emoticon. But the first one SHOULD be
						 the default one, and will be taken if there is a GUI selector.
				  </para>
            </listitem>
          </varlistentry>
	    </variablelist>
  </para>
    </sect3>
  </sect2>

  <sect2 id="img-format">
    <title>Format of the image.</title>
    <para>
		All images SHOULD be in a supported format :  PNG, GIF or MNG.
    </para>
  </sect2>

  <sect2 id="implementation">
    <title>Implementations notes</title>
	 <sect3 id="impl-parser">
	  <title>Emoticon parser</title>
    <para>
		There are no real recommendation how to parse emoticons. But
		an emoticon with a longer string should have the priority over one with a shorter string.
		(Example: if both :-() and :-( are in a theme, the picture for the first one should be used
			when :-() is encountered)
    </para>
</sect3>
</sect2>

<sect2 id="example">
	  <title>Example</title>
	  <para>
			 <programlisting>
&lt;messaging-emoticon-map&gt;
	&lt;emoticon file="smile.png"&gt;
			&lt;string&gt;:-)&lt;/string&gt;
			&lt;string&gt;:)&lt;/string&gt;
			&lt;string&gt;:o)&lt;/string&gt;
	&lt;/emoticon&gt;

	&lt;emoticon file="wink.png"&gt;
			&lt;string&gt;;-)&lt;/string&gt;
			&lt;string&gt;;)&lt;/string&gt;
	&lt;/emoticon&gt;

	&lt;emoticon file="unhappy.png"&gt;
			&lt;string&gt;:-(&lt;/string&gt;
			&lt;string&gt;:(&lt;/string&gt;
	&lt;/emoticon&gt;
&lt;/messaging-emoticon-map&gt;

 </programlisting>
</para>
</sect2>

<!--sect2 id="todo">
	  <title>TODO</title>
	  <para>
			 A DTD of the XML file
	  </para>
</sect2-->
</sect1>
</appendix>