[kde-doc-english] [kopete] doc: Add emoticons guide to docbook.
Jeremy Whiting
jpwhiting at kde.org
Fri Oct 31 14:30:38 UTC 2014
Git commit 9588b02513390e59ccb1b47288f3fc42fb10a34e by Jeremy Whiting.
Committed on 29/10/2014 at 20:22.
Pushed by whiting into branch 'master'.
Add emoticons guide to docbook.
Patch by Burkhard Lück <lueck at hube-lueck.de>
REVIEW:120896
A +163 -0 doc/emoticonspec.docbook
M +2 -0 doc/index.docbook
http://commits.kde.org/kopete/9588b02513390e59ccb1b47288f3fc42fb10a34e
diff --git a/doc/emoticonspec.docbook b/doc/emoticonspec.docbook
new file mode 100644
index 0000000..3547004
--- /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 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>
+ </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 <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>
+ </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 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>
+ </sect2>
+ </sect1>
+
+ <sect1 id="img-format">
+ <title>Format of the image.</title>
+ <para>
+ All images 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 encountered)
+ </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 4b2ded2..ee45568 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)
@@ -1245,6 +1246,7 @@ Documentation copyright 2003,2004,2005 &Will.Stephenson; (lists at stevello free
&kopete-pipes;
&kopete-jabber;
&kopete-icq;
+&kopete-emoticonspec;
&documentation.index;
</book>
More information about the kde-doc-english
mailing list