summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/twemojis/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/twemojis/README.md')
-rw-r--r--macros/latex/contrib/twemojis/README.md140
1 files changed, 140 insertions, 0 deletions
diff --git a/macros/latex/contrib/twemojis/README.md b/macros/latex/contrib/twemojis/README.md
new file mode 100644
index 0000000000..dbc0de32fd
--- /dev/null
+++ b/macros/latex/contrib/twemojis/README.md
@@ -0,0 +1,140 @@
+# LaTeX Twemojis
+
+Simple wrapper that allows to use Twitter's emojis through LaTeX commands.
+As this package works with graphics and not with fonts to achieve its goal, it *should* work on every machine with any LaTeX version without problems.
+
+In comparison, the `emoji` package on CTAN <https://www.ctan.org/pkg/emoji> works on fonts and requires lualatex.
+It is lighter and probably compiles faster if you use thousands of emojis, but it also has stricter requirements and is not as flexible.
+
+## Usage
+
+This package in on [CTAN](https://www.ctan.org), so you should be able to use it like any other package, with
+
+```latex
+\usepackage{twemojis}
+```
+
+An emoji can be used via `\twemoji{...}`.
+There is the alternative `\texttwemoji{...}` command which scales and sets the emoji to fit the text line.
+
+## Emoji Names
+
+There are three ways to get the emoji you want:
+
+1. The unicode value
+ - in hexadezimal,
+ - with small letters,
+ - and without leading zeros.
+
+ If the emojis use combined values (e.g., for skin color) separate them via `-`.
+
+ The value can be found, for example, [here](https://unicode-table.com) (not ever unicode character is supported, only those you typically find on an โ€œEmoji Keyboardโ€).
+
+2. The official unicode CLDR names of the emoji.
+ These can also be found, for example, [here](https://unicode-table.com)
+ The information is taken from [here](https://www.unicode.org/Public/emoji/13.1/emoji-test.txt).
+
+3. The easiest names to remember (used by Signal, WhatsApp, Discord, etc) like `:smile:` can also be used, but only support a subset (e.g. no variations like skin colors).
+ These can be found, for example, [here](https://www.webfx.com/tools/emoji-cheat-sheet/) (without the `:`).
+ The information is taken from [here](https://github.com/github/gemoji/blob/master/db/emoji.json).
+
+### Examples
+
+| Emoji | Unicode Value | CLDR Name | Short Names |
+| ----- | -------------------------------------- | ------------------------------------------------ | ----------------------- |
+| ๐Ÿ’ƒ | `\twemoji{1f483}` | `\twemoji{woman dancing}` | |
+| ๐Ÿ˜„ | `\twemoji{1f604}` | `\twemoji{grinning face with smiling eyes}` | `\twemoji{smile}` |
+| ๐Ÿ’‡๐Ÿปโ€โ™‚๏ธ | `\twemoji{1f487-1f3fb-200d-2642-fe0f}` | `\twemoji{man getting haircut: light skin tone}` | |
+| ๐Ÿ˜ˆ | `\twemoji{1f608}` | `\twemoji{smiling face with horns}` | `\twemoji{smiling_imp}` |
+
+The emojis here are actual font emojis, so if something weird is displayed: that is exactly why this package works on graphics and not fonts.
+That also means the emojis might look different in the package.
+
+## Problems/TODOs
+
+- Currently the emojis are not text-selectable, that might change in future versions.
+
+# Development
+
+## Manual Installation
+
+If you don't use TeX Live or something similar you can install the package by downloading on of the releases and unzipping it.
+In the creaded folder are a `.ins`, a `.dtx` and a folder called `pdf-twemojis`.
+
+Run:
+```
+pdflatex twemojis.ins
+```
+
+which creates `twemoji.sty`.
+You can copy `twemoji.sty` and `pdf-twemojis` wherever you want, as long as both are in the same folder and LaTeX looks at that path for the package you can use it normally.
+
+## Building
+
+To build the package you need `python 3`, `inkscape`, and the official Twemoji Repo (init the submodule).
+Install the Python requirements and run `./generate.py`.
+Afterwards execute
+```
+pdflatex twemojis.ins
+pdflatex twemojis.dtx
+```
+in the latex-package folder.
+
+To create the `.sty` and the documentation PDF.
+
+## Releasing
+
+- Adapt the version number in `generate.py`.
+- Re-generate the `latex-package` folder.
+- Run `./package.sh`.
+- Upload `/dist/twemojis.zip` to CTAN.
+- Add the ZIP to the releases in GIT.
+
+# Implementation Notice
+
+As the emojis are PDF-based and use transparency, they include groups.
+I was not able to change the inkscape export so that that does not happen.
+Hence, pdflatex throws a warning about multiple groups on one PDF page.
+This package disables said warning: `\pdfsuppresswarningpagegroup=1` as it is of no concern for the inputted emojis.
+It **could** happen, that a PDF you input is faulty and you don't notice due to said suppression.
+You can enable the warning with `\pdfsuppresswarningpagegroup=0`.
+
+# License
+
+## LaTeX Package
+
+Copyright (c) 2021 Jost Rossel
+This file may be distributed and/or modified under the
+conditions of the LaTeX Project Public License, either
+version 1.3 of this license or (at your option) any later
+version. The latest version of this license is in:
+
+ http://www.latex-project.org/lppl.txt
+
+and version 1.3 or later is part of all distributions of
+LaTeX version 2005/12/01 or later.
+
+## Emojis
+
+Copyright 2019 Twitter, Inc and other contributors
+
+Graphics licensed under CC-BY 4.0: https://creativecommons.org/licenses/by/4.0/
+
+### Attribution
+
+**I'm no lawyer, so take this section with a grain of salt.**
+
+As the emojis themselves are licensed under CC-BY they require attribution but are open to be distributed and modified anyway you like.
+I'm not sure whether the attribution in this file is enough for a file (e.g. PDF) generated with this package to be covered as well.
+
+I see two different possibilities to attribute the emojis in a compiled document:
+
+1. Add attribution to the metadata of the document.
+ For example with <https://www.ctan.org/pkg/hyperxmp> in PDF files.
+2. Add attribution in the document directly (e.g. on the last page of a presentation).
+ For example:
+ ```
+ Emoji graphics licensed under CC-BY 4.0: https://creativecommons.org/licenses/by/4.0/
+ Copyright 2019 Twitter, Inc and other contributors
+ ```
+ I consider this option to be the safest.