diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/CMakeLists.txt | 1 | ||||
| -rw-r--r-- | doc/Doxyfile | 2 | ||||
| -rw-r--r-- | doc/commands.doc | 9 | ||||
| -rw-r--r-- | doc/doxygen_manual.tex | 1 | ||||
| -rw-r--r-- | doc/emojisup.doc | 166 | ||||
| -rw-r--r-- | doc/index.doc | 2 | ||||
| -rw-r--r-- | doc/xmlcmds.doc | 2 |
7 files changed, 181 insertions, 2 deletions
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index b95afd8..463d3d7 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -80,6 +80,7 @@ set(DOC_FILES starting.doc trouble.doc xmlcmds.doc + emojisup.doc language.tpl maintainers.txt translator.py diff --git a/doc/Doxyfile b/doc/Doxyfile index ceb6385..bdd1098 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -38,7 +38,7 @@ INPUT = index.doc install.doc starting.doc docblocks.doc markdown.do autolink.doc output.doc searching.doc extsearch.doc customize.doc custcmd.doc \ external.doc faq.doc trouble.doc features.doc \ doxygen_usage.doc doxywizard_usage.doc \ - config.doc commands.doc htmlcmds.doc xmlcmds.doc language.doc \ + config.doc commands.doc htmlcmds.doc xmlcmds.doc emojisup.doc language.doc \ perlmod.doc perlmod_tree.doc arch.doc changelog.doc FILE_PATTERNS = *.cpp *.h *.doc EXAMPLE_PATH = ../examples diff --git a/doc/commands.doc b/doc/commands.doc index 840c3b7..4930524 100644 --- a/doc/commands.doc +++ b/doc/commands.doc @@ -214,6 +214,7 @@ documentation: \refitem cmdperc \\\% \refitem cmdquot \\\" \refitem cmdchardot \\\. +\refitem cmdcolon \: \refitem cmddcolon \:: \refitem cmdpipe \\| \refitem cmdndash \\\-- @@ -3362,6 +3363,14 @@ class Receiver the start of a line. <hr> +\section cmdcolon \: + + \addindex \\: + This command writes a single colon (\c \:) to the output. This + character sequence has to be escaped in some cases, because it is used + to define `emoji` see also \ref emojisup "Emoji support". + +<hr> \section cmddcolon \\:: \addindex \\:: diff --git a/doc/doxygen_manual.tex b/doc/doxygen_manual.tex index 95e1ed6..e749560 100644 --- a/doc/doxygen_manual.tex +++ b/doc/doxygen_manual.tex @@ -121,6 +121,7 @@ Written by Dimitri van Heesch\\[2ex] \chapter{Special Commands}\label{commands}\hypertarget{commands}{}\input{commands} \chapter{HTML commands}\label{htmlcmds}\hypertarget{htmlcmds}{}\input{htmlcmds} \chapter{XML commands}\label{xmlcmds}\hypertarget{xmlcmds}{}\input{xmlcmds} +\chapter{Emoji support}\label{emojisup}\hypertarget{emojisup}{}\input{emojisup} \part{Developers Manual} \chapter{Doxygen's internals}\label{arch}\hypertarget{arch}{}\input{arch} \chapter{Perl Module Output format}\label{perlmod}\hypertarget{perlmod}{}\input{perlmod} diff --git a/doc/emojisup.doc b/doc/emojisup.doc new file mode 100644 index 0000000..75a90fb --- /dev/null +++ b/doc/emojisup.doc @@ -0,0 +1,166 @@ +/****************************************************************************** + * + * + * + * 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 and a so called "CLDR short name". The current version a v11.0 and can be found at +[Full Emoji List, v11.0](https://unicode.org/emoji/charts/full-emoji-list.html) furthermore there is the list with +[Full Emoji Modifier Sequences, v11.0](http://www.unicode.org/emoji/charts/full-emoji-modifiers.html). + +A common way to denote an emoji is by means of `:<text>:`, +doxygen supports the emoji as mentioned in the above mentioned unicode emoji lists in this way +by means of the "CLDR short name" with the exception that in case a colon (`:`) is in the +"CLDR short name" this colon has to be removed. +Furthermore doxygen supports the list of emoji as used by github (based on the list +https://api.github.com/emojis). In this list also a reference is given to the unicode codes (just the +first and last) and these unicodes are mapped onto the official unicode sequences. +In case the "CLDR short name" and the "github name" are the same the reference from the +"CLDR short name" has precedence. + +Implementation + +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 + - XML + - 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 + +\anchor emojiimage Emoji image retrieval + +In the lists +[Full Emoji List, v11.0](https://unicode.org/emoji/charts/full-emoji-list.html) and +[Full Emoji Modifier Sequences, v11.0](http://www.unicode.org/emoji/charts/full-emoji-modifiers.html). +define images for the different vendors. These images can be retrieved by means of the following procedure (based on the code from Henning Pohl, https://github.com/henningpohl/latex-emoji): +\code{.py} +from bs4 import BeautifulSoup +import base64 +import os +import requests + +# http://www.unicode.org/emoji/charts/index.html +# http://www.unicode.org/emoji/charts/full-emoji-list.html +PAGE_URL = 'http://www.unicode.org/emoji/charts/full-emoji-list.html' +PAGE_URL_SKIN = 'http://www.unicode.org/emoji/charts/full-emoji-modifiers.html' +PAGE = 'full-emoji-list.html' +PAGE_SKIN = 'full-emoji-modifiers.html' + + +def get_header_names(header): + cols = header.find_all('th') + cols = [c.get_text() for c in cols] + cols = [c.replace('*','') for c in cols] + cols = [c.lower() for c in cols] + return cols + +def extract_image(column): + if 'miss' in column['class']: + return None + + if 'miss7' in column['class']: + return None + + data = column.img['src'] + data_start = data.find("base64,") + if data_start == -1: + return None + + data = base64.b64decode(data[data_start + len("base64,"):]) + return data + +def save_image(folder, imgSrc, filename): + if os.path.exists(folder) is False: + os.mkdir(folder) + + filename = os.path.join(folder, filename) + if os.path.exists(filename): + return + + img = extract_image(imgSrc) + if img is not None: + with open(filename, 'wb') as out: + out.write(img) + +def scrape(page_url, page): + # Possibilities to obtain the basic data: + # - use request.get directly + soup = BeautifulSoup(requests.get(page_url).text, "html5lib") + # - download file (e.g. with wget http://www.unicode.org/emoji/charts/full-emoji-list.html) + # with open(page) as fp: + # soup = BeautifulSoup(fp,"html5lib") + + table = soup('table')[0] + + # for version 11.0 + # first row: smileys + # second row: face smileys + # third row: row with vendors, i.e. the one we want + header = table.find_all('tr')[2] + keys = get_header_names(header) + + for row in header.find_next_siblings('tr'): + fields = {k:c for k, c in zip(keys, row.find_all('td')) } + if 'code' not in fields: + continue + + codes = fields['code'].text.replace('U+', '').split(' ') + filename = "-".join(codes) + ".png" + + save_image('ios', fields['appl'], filename) + save_image('android', fields['goog'], filename) + save_image('twitter', fields['twtr'], filename) + save_image('windows', fields['wind'], filename) + save_image('one', fields['one'], filename) + save_image('facebook', fields['fb'], filename) + save_image('samsung', fields['sams'], filename) + #save_image('gmail', fields['gmail'], filename) + #save_image('softbank', fields['sb'], filename) + #save_image('docomo', fields['dcm'], filename) + #save_image('kddi', fields['kddi'], filename) + #save_image('bw', fields['chart'], filename) + +if __name__ == '__main__': + scrape(PAGE_URL, PAGE) + scrape(PAGE_URL_SKIN, PAGE_SKIN) +\endcode +This results in a number of directories with the supported images. By means of the doxygen configuration parameter +\ref cfg_latex_emoji_directory "LATEX_EMOJI_DIRECTORY" the requested directory can be selected. + +It is also possible to use images from other sources or mix images from different sources, the only requirement is that the filename represents the unicode of the emoji. e.g. if we have the emoji <tt>\:grinning face with big eyes\:</tt> (also known as <tt>\:smiley\:</tt>) the coresponding unicode is `U+1F603` and the name of the file is `1F603.png`.<br> +For a more complex emoji like <tt>\:keycap 1\:</tt> (also known as <tt>\:one\:</tt>) the coresponding unicode sequence is `U+0031U+FE0FU+20E3` and the name of the file is `0031-FE0F-20E3.png`. + + +Note that when you want to use a colon (`:`) in your text it might be necessary to escape the colon (see \ref cmdcolon "\\:") as it might conflict with a, possible, emoji sequence. + + +For a overview of the supported emoji one can issue the comand:<br> +`doxygen.exe -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 + +*/ + diff --git a/doc/index.doc b/doc/index.doc index b8f6e8e..9afe624 100644 --- a/doc/index.doc +++ b/doc/index.doc @@ -102,6 +102,8 @@ The second part forms a reference manual: can be used within the documentation. <li>Section \ref xmlcmds shows an overview of the C# style XML commands that can be used within the documentation. +<li>Section \ref emojisup shows an introduction how emoji can be used within + the documentation. </ul> The third part provides information for developers: diff --git a/doc/xmlcmds.doc b/doc/xmlcmds.doc index 848858d..b59095b 100644 --- a/doc/xmlcmds.doc +++ b/doc/xmlcmds.doc @@ -104,7 +104,7 @@ class Engine \htmlonly -Go to the <a href="langhowto.html">next</a> section or return to the +Go to the <a href="emojisup.html">next</a> section or return to the <a href="index.html">index</a>. \endhtmlonly |