summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/twemojis/README.md
blob: 0b29b9efec26a0a6feceac39799af96265d5f686 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
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 hexadecimal,
   - 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.