============================================================
 REDUCING THE EMOJI FONT DOWNLOAD SIZE (SUBSETTING)
 (Google Noto Color Emoji mode)
============================================================
USE AT OWN RISK!!!
============================================================

WHAT THIS IS - AND WHETHER YOU NEED IT
------------------------------------------------------------
The extension already ships with the complete Google Noto
Color Emoji font (about 5.6 MB). It contains every emoji and
works straight away - a visitor downloads it once, and their
browser caches it after that.

"Subsetting" simply means making a smaller copy of that font
that contains ONLY the emoji your board actually uses,
bringing the file down from ~5.6 MB to a few tens of KB. The
result looks identical; it just downloads faster.

This is OPTIONAL. If you don't mind the one-time 5.6 MB
download, you can skip this guide entirely and change nothing.


IMPORTANT - PLEASE READ BEFORE YOU START
------------------------------------------------------------
A subset font only contains the emoji that were in your list
at the moment you built it.

If you later ADD new emoji in the ACP but do NOT rebuild the
subset, those new emoji are not in the slimmed font. What
happens then:

  - On Chrome, Edge and Firefox they still appear, but in the
    visitor's OWN system style (Windows, Android, etc.) - not
    Google's - so they look inconsistent with the rest.
  - On Safari / Apple devices they may not display correctly
    at all.

So if you subset, you take on a small ongoing job: every time
you change the emoji list, you must rebuild and re-upload the
subset. If you add emoji often, you may prefer to leave the
full font in place and skip subsetting.


WHAT YOU NEED
------------------------------------------------------------
  - A Windows PC (Mac and Linux work too - see the note at
    the end).
  - About 10 minutes.

You do everything on your own PC. Your forum server is not
touched until the final upload.


STEP 1 - INSTALL PYTHON
------------------------------------------------------------
Go to:   https://www.python.org/downloads/
Download Python for Windows and run the installer.

IMPORTANT: On the very FIRST screen of the installer, tick
the box that says "Add python.exe to PATH" before you click
Install. This box is easy to miss, and skipping it causes
most of the problems people run into later.

Finish the install, then close any open command windows.


STEP 2 - INSTALL THE FONT TOOLS
------------------------------------------------------------
Open the Start menu, type  cmd  , and open Command Prompt.
Paste this line in and press Enter:

    pip install --user fonttools brotli lxml

Wait until it finishes. All THREE names matter:
  - fonttools : does the actual work
  - brotli    : needed to create the compressed .woff2 file
  - lxml      : needed to keep the font working in Safari

Do not leave any of them out. If lxml is missing, the font
is built WITHOUT an error message but breaks in some
browsers, so it is the one people most often forget.


STEP 3 - DOWNLOAD THE SOURCE FONT
------------------------------------------------------------
Download the font ONLY from Google's official page:

    https://fonts.google.com/noto/specimen/Noto+Color+Emoji

Click "Get font" (top right), then "Download all". You will
get a ZIP file. Open it and find the file named:

    NotoColorEmoji-Regular.ttf

Save it somewhere easy to reach, such as your Desktop.

IMPORTANT: Use only this file, from this page. Do NOT
download "Noto Color Emoji" from GitHub or other font sites.
An older version of this same font exists elsewhere that
looks identical but does NOT work in web browsers, and it
fails silently - you would only find out when the emoji show
up broken on your live forum. The page above always gives
the correct version.


STEP 4 - LIST YOUR EMOJI
------------------------------------------------------------
Open Notepad. Type or paste EVERY emoji currently in your
ACP emoji list - the complete set your board uses, not just
ones you have recently added - all on one line, separated by
spaces. For example:

    [paste your emoji here, e.g.]   :)  <3  !  etc.

(The subset must contain every emoji on your board, so list
them all.)

Save the file as  myemoji.txt  in the SAME folder as the
font. When saving in Notepad, set "Encoding" to "UTF-8".


STEP 5 - BUILD THE SUBSET
------------------------------------------------------------
Open the folder that contains both files (the font and
myemoji.txt). Click the address bar at the top of the
window, type  cmd  , and press Enter. A black command
window opens, already pointing at that folder.

Paste this single line and press Enter:

    pyftsubset NotoColorEmoji-Regular.ttf --text-file=myemoji.txt --flavor=woff2 --layout-features=* --output-file=NotoColorEmoji.woff2

After a moment you will have a new file in the folder:

    NotoColorEmoji.woff2


STEP 6 - QUICK CHECK
------------------------------------------------------------
Look at the size of NotoColorEmoji.woff2. It should be
roughly 100 to 200 KB.

If it is under about 50 KB, something went wrong - almost
always a missing package from Step 2. Re-run Step 2, then
build again (Step 5).


STEP 7 - UPLOAD IT
------------------------------------------------------------
Using FTP or your hosting file manager, upload
NotoColorEmoji.woff2 into this folder on your forum,
replacing the file that is already there:

    ext/stoker/emoji/fonts/

Then, in the ACP, go to:

    General  ->  Purge the cache

Finally, hard-refresh your browser (Ctrl + F5) and open a
topic. Your emoji now load from the smaller font.


REMEMBER
------------------------------------------------------------
Every time you add or change emoji in the ACP afterwards,
repeat Steps 4 to 7 so the subset stays in sync with your
list. If you skip it, the new emoji will not appear in
Google's style (and may not appear at all on Apple devices).


IF SOMETHING GOES WRONG
------------------------------------------------------------
"python is not recognized"
    Python was installed without the PATH box ticked. Run
    the python.org installer again, choose Modify / Repair,
    and make sure "Add python.exe to PATH" is turned on.

Emoji show as plain black shapes or empty boxes
    The colour data did not make it into the font. This is
    almost always a missing package in Step 2 (usually
    lxml). Re-run Step 2 and build the subset again.


MAC AND LINUX
------------------------------------------------------------
The steps are the same. Install Python from python.org or
your package manager, then run the Step 2 and Step 5
commands in Terminal. To open a terminal in a folder on a
Mac, right-click the folder and choose "New Terminal at
Folder" (enable it once under System Settings > Keyboard >
Keyboard Shortcuts > Services if needed).


------------------------------------------------------------
The Noto Color Emoji font is free and open source under the
SIL Open Font License 1.1.
------------------------------------------------------------
