// Render with Asciidoctor

= What's happening here?
Philippe Proulx
5 April 2025

This README explains how to generate the assets of jome.

== Input

The input files are:

`pass:[cats/*.txt]`::
    Emoji categorization.
+
Each text file is a category, and a single emoji can be in more than one
category.
+
Each line of those text files is an emoji followed by space followed by
its name, although this specific name isn't used.

`cats.yml`::
    Maps category IDs (text file names without the `.txt` extension)
    to category names.
+
The order of the categories is important as it's the final order of
presentation of those categories in the eventual UI.

`pass:[emojis-*.txt]`::
    Emoji names and keywords for a given Emoji standard version.
+
The data in those files comes (manually) from
`emoji-list-16.0.txt`, which is a plain text version of the table
of Unicode's
https://www.unicode.org/emoji/charts/emoji-list.html[Emoji List,{nbsp}v16.0].
For some reason, the CLDR data doesn't contain all the keywords that
this table holds. If you know where to find the raw source of this,
please tell me!
+
The format of each block of `pass:[emojis-*.txt]` is:

[horizontal]
First line:::
    The emoji.

Second line:::
    The name of the emoji (capitalized).

Third line:::
    The `|`-separated keywords of the emoji (lowercase).

`with-skin-tone-support.txt`::
    Emojis with skin tone modifier support.
+
Same format as a category text file.

`twemoji-svg`::
    The SVG files of the
    https://github.com/jdecked/twemoji[Twemoji fork] project
    (see its license, `twemoji-LICENSE-GRAPHICS`).
+
Each file name is a dash-separated list of codepoints (hexadecimal) used
to create the emoji sequence followed by `.svg`.

== Output

The `create.py` script creates the required files for the UI in the
specified directory.

To run `create.py`, you need Pycairo, CairoSVG, and PyYAML.

From the category files in `cats`:

* It knows the supported emojis. It
  combines this with the data from the `pass:[emojis-*.txt]` and
  `with-skin-tone-support.txt` files to create `emojis.json`. This is a
  map (emoji to info) for each supported emoji.

* It also creates `cats.json` which has the same content as `cats.yml`,
  but each category entry also has its full list of emojis.

`create.py` converts the Twemoji SVG files to 16×16, 24×24, 32×32,
40×40, and 48×48 PNG files.

`create.py` also creates `emojis-16.png`, `emojis-24.png`,
`emojis-32.png`, `emojis-40.png`, and `emojis-48.png` which are single
PNG files containing all the supported emojis in their final form. The
purpose of this file is to accelerate the UI, not having to open
hundreds of individual PNG files. It also creates
`emojis-png-locations-16.json`, `emojis-png-locations-24.json`,
`emojis-png-locations-32.json`, `emojis-png-locations-40.json`, and
`emojis-png-locations-48.json` which map each emoji to its location
(top-left corner), in pixels, within the corresponding `emojis-*.png`
images.
