Git commit 782b12451f7e20539678d8c389e29f092bdf0001 by Jeremy Whiting. Committed on 29/10/2014 at 20:22. Pushed by whiting into branch 'KDE/4.14'.
Add emoticons guide to docbook. Patch by Burkhard L?ck <lueck at hube-lueck.de> (cherry picked from commit 28cee1948fc8e05ad1d08f85a9259ce11241c15d) A +163 -0 doc/emoticonspec.docbook M +2 -0 doc/index.docbook http://commits.kde.org/kopete/782b12451f7e20539678d8c389e29f092bdf0001 diff --git a/doc/emoticonspec.docbook b/doc/emoticonspec.docbook new file mode 100644 index 0000000..9599e71 --- /dev/null +++ b/doc/emoticonspec.docbook @@ -0,0 +1,163 @@ +<?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 at 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 consits 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> + </sect1> + <sect1 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 MUST contains a file called <varname>emoticons.xml</varname> + the format of that file is described bellow. + </para> + <para> + The theme directory may also contains a .directory file which contains + translations of the theme name and/or an icon for that theme. + </para> + </sect1> + <sect1 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> + <sect2 id="emoticons-map-elements"> + <title>Elements</title> + <para> + <variablelist> + <varlistentry> + <term><messaging-emoticon-map> [version="0.1"]</term> + <listitem> + <para> + The root element is <messaging-emoticon-map> + all other elements are contained by it. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><emoticon file="..."></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><string></term> + <listitem> + <para> + This element may only appear below <emoticon>. + It represent 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 string per emoticons. + </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> + </sect2> + </sect1> + + <sect1 id="img-format"> + <title>Format of the image.</title> + <para> + All image SHOULD be in a supported format : PNG, GIF or MNG. + </para> + </sect1> + + <sect1 id="implementation"> + <title>Implementations notes</title> + <sect2 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 encounter) + </para> +</sect2> +</sect1> + +<sect1 id="example"> + <title>Example</title> + <para> + <programlisting> +<messaging-emoticon-map> + <emoticon file="smile.png"> + <string>:-)</string> + <string>:)</string> + <string>:o)</string> + </emoticon> + + <emoticon file="wink.png"> + <string>;-)</string> + <string>;)</string> + </emoticon> + + <emoticon file="unhappy.png"> + <string>:-(</string> + <string>:(</string> + </emoticon> +</messaging-emoticon-map> + + </programlisting> +</para> +</sect1> + +<sect1 id="todo"> + <title>TODO</title> + <para> + A DTD of the XML file + </para> +</sect1> +</appendix> + diff --git a/doc/index.docbook b/doc/index.docbook index b55fd88..5964528 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -25,6 +25,7 @@ <!ENTITY kopete-pipes SYSTEM "pipes.docbook"> <!ENTITY kopete-jabber SYSTEM "jabber.docbook"> <!ENTITY kopete-icq SYSTEM "icq.docbook"> + <!ENTITY kopete-emoticonspec SYSTEM "emoticonspec.docbook"> ]> <!-- Intro (1st draft, Will) @@ -1181,6 +1182,7 @@ Documentation copyright 2003,2004,2005 &Will.Stephenson; (lists at stevello free &kopete-pipes; &kopete-jabber; &kopete-icq; +&kopete-emoticonspec; &documentation.index; </book>
