1 files changed, 120 insertions, 0 deletions
diff --git a/doc/emojisup.doc b/doc/emojisup.doc
new file mode 100644
index 0000000..4c861fe
--- /dev/null
+++ b/doc/emojisup.doc
@@ -0,0 +1,120 @@
+/******************************************************************************
+ *
+ * 
+ *
+ * Copyright (C) 1997-2018 by Dimitri van Heesch.
+ *
+ * Permission to use, copy, modify, and distribute this software and its
+ * documentation under the terms of the GNU General Public License is hereby 
+ * granted. No representations are made about the suitability of this software 
+ * for any purpose. It is provided "as is" without express or implied warranty.
+ * See the GNU General Public License for more details.
+ *
+ * Documents produced by Doxygen are derivative works derived from the
+ * input used in their production; they are not affected by this license.
+ *
+ */
+/*! \page emojisup Emoji support
+
+The [Unicode consortium](http://www.unicode.org/) has defined a set of
+[emoji](https://en.wikipedia.org/wiki/Emoji) with the corresponding unicode
+sequences. Doxygen supports the subset of emoji characters as used by GitHub (based on the list
+https://api.github.com/emojis).
+An emoji is created using the \ref cmdemoji "\\emoji" command.
+For example `\emoji smile` (or `\emoji :smile:`) both produce \emoji smile.
+
+\section emojirep Representation
+
+For the different doxygen output types there is an output defined:
+- Unicode code sequence, the actual representation is depending on the possibilities of the fonts loaded:
+  - HTML
+  - DocBook
+  - RTF, converted to UTF-16 representation.
+- Image
+  - \LaTeX, in case the image can be found (see \ref emojiimage "Emoji image retrieval") otherwise the plain emoji text (i.e. `:<text>:`) is displayed
+- plain emoji text (i.e. `:<text>:`)
+  - man
+  - perl
+- For XML there is a dedicated `<emoji>` tag with name and unicode attributes.
+
+\section emojiimage Emoji image retrieval
+
+In the list of images can be downloaded via the following Python script:
+\code{.py}
+# script to download the emoticons from GitHub and to produce a table for
+# inclusion in doxygen. Works with python 2.7+ and python 3.x
+import json
+import os
+import argparse
+import re
+try:
+    import urllib.request as urlrequest
+except ImportError:
+    import urllib as urlrequest
+
+unicode_re = re.compile(r'.*?/unicode/(.*?).png\?.*')
+
+def get_emojis():
+    response  = urlrequest.urlopen('https://api.github.com/emojis')
+    raw_data  = response.read()
+    return json.loads(raw_data)
+
+def download_images(dir_name):
+    json_data = get_emojis()
+    num_items = len(json_data)
+    cur_item=0
+    for image,url in sorted(json_data.items()):
+        image_name = image+'.png'
+        cur_item=cur_item+1
+        if url.find('/unicode/')==-1 or not os.path.isfile(dir_name+'/'+image_name):
+            with open(dir_name+'/'+image_name,'wb') as file:
+                print('%s/%s: fetching %s' % (cur_item,num_items,image_name))
+                file.write(urlrequest.urlopen(url).read())
+        else:
+            print('%s/%s: skipping %s' % (cur_item,num_items,image_name))
+
+def produce_table():
+    json_data = get_emojis()
+    lines = []
+    for image,url in sorted(json_data.items()):
+        match = unicode_re.match(url)
+        if match:
+            unicodes = match.group(1).split('-')
+            unicodes_html = ''.join(["&#x"+x+";" for x in unicodes])
+            image_str = "\":"+image+":\","
+            unicode_str = "\""+unicodes_html+"\""
+            lines.append('  { %-42s %-38s }' % (image_str,unicode_str))
+    out_str = ',\n'.join(lines)
+    print("{")
+    print(out_str)
+    print("};")
+
+if __name__=="__main__":
+    parser = argparse.ArgumentParser()
+    group = parser.add_mutually_exclusive_group()
+    group.add_argument('-d','--dir',help='directory to place images in')
+    group.add_argument('-t','--table',help='generate code fragment',action='store_true')
+    args = parser.parse_args()
+    if args.table:
+        produce_table()
+    else:
+        download_images(args.dir)
+
+\endcode
+When invoking it with the `-d image_dir` option the images will by downloaded in the `image_dir` directory.
+By means of the doxygen configuration parameter
+\ref cfg_latex_emoji_directory "LATEX_EMOJI_DIRECTORY" the requested directory can be selected.
+
+For convenience a zip with the result of running the script can also be downloaded from 
+http://www.doxygen.nl/dl/github_emojis.zip
+
+For a overview of the supported emoji one can issue the comand:<br>
+`doxygen -f emoji <outputFileName>`
+
+\htmlonly
+Go to the <a href="langhowto.html">next</a> section or return to the
+ <a href="index.html">index</a>.
+\endhtmlonly
+
+*/
+