diff options
Diffstat (limited to 'macros/latex/contrib/twemojis/README.md')
-rw-r--r-- | macros/latex/contrib/twemojis/README.md | 140 |
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. |