\documentclass[11pt,a4paper]{article}
\usepackage[margin=2.5cm]{geometry}
\usepackage{fontspec}
\usepackage{etoolbox}
\usepackage{longtable}
\usepackage{xltabular}
\usepackage{booktabs}
\usepackage{xcolor}
\usepackage{hyperref}
\usepackage{emojinames}

% Color emoji font setup (LuaLaTeX required)
% Using Twemoji Mozilla (COLR/CPAL vector format - works reliably with LuaLaTeX)
\renewfontfamily\EmojiFont{Twemoji Mozilla}[Renderer=HarfBuzz]
\renewcommand{\emoji}[1]{%
	\ifcsdef{emoji@#1}{{\EmojiFont\csname emoji@#1\endcsname}}{{\textcolor{red}{?#1}}}%
}

% Key color
\definecolor{keycolor}{RGB}{0,100,150}

\title{\Huge The \texttt{emojinames} Package\\[0.5em]\Large Complete Emoji Reference}
\author{Kai Günther}
\date{July 2026}

\begin{document}
	\maketitle
	\tableofcontents
	\newpage
	
	%===============================================================================
	\section{Overview}
	%===============================================================================
	
	The \texttt{emojinames} package provides semantic emoji commands for \LaTeX{} documents.
	Instead of inserting raw Unicode emoji characters, you use meaningful keys like
	\verb|\emoji{status-ok1}| or \verb|\emoji{gis-select1}|.
	
	This package contains \textbf{2403} emoji definitions organized into
	semantic categories.
	
	\subsection{Requirements}
	\begin{itemize}
		\item \textbf{LuaLaTeX} compiler (required for color emoji rendering)
		\item \textbf{Twemoji Mozilla} font installed (COLR/CPAL vector format works best with LuaLaTeX)
		\item Packages: \texttt{fontspec}, \texttt{etoolbox}
	\end{itemize}
	
	\subsection{Quick Start}
	\begin{verbatim}
		\documentclass{article}
		\usepackage{fontspec}
		\usepackage{emojinames}
		
		\newfontfamily\EmojiFont{Twemoji Mozilla}[Renderer=HarfBuzz]
		\renewcommand{\emoji}[1]{%
			\ifcsdef{emoji@#1}{{\EmojiFont\csname emoji@#1\endcsname}}{?}%
		}
		
		\begin{document}
			Status: \emoji{status-ok1} \emoji{status-error1}
			GIS: \emoji{gis-select1} \emoji{gis-buffer1}
			Mood: \emoji{emo-joy1} \emoji{emo-sad1}
		\end{document}
	\end{verbatim}
	
	Compile with: \texttt{lualatex yourdocument.tex}
	
	%===============================================================================
	\section{Complete Emoji Reference}
	
	Every key defined by the package is listed below, grouped by family and
	generated directly from \texttt{emoji-map.json} (rerun
	\texttt{generate\_doc\_tables.py} after any change). A few entries use
	Unicode 15/16 codepoints that Twemoji Mozilla v0.7.0 predates and render as
	boxes -- see Troubleshooting.
	
	\input{emojinames-doc-generated.tex}
	
	\section{Troubleshooting}
	%===============================================================================
	
	\subsection{Emoji not rendering (shows ?)}
	\begin{itemize}
		\item Verify the key exists in \texttt{emoji-map.json}
		\item Keys are case-sensitive: \verb|status-ok1| $\neq$ \verb|Status-OK1|
		\item Check that \texttt{emojinames-map.tex} is in your TeX path
	\end{itemize}
	
	\subsection{Black \& white instead of color}
	\begin{itemize}
		\item Ensure you're using \textbf{LuaLaTeX} (not XeLaTeX or pdfLaTeX)
		\item Verify \textbf{Twemoji Mozilla} font is installed
		\item Add \verb|[Renderer=HarfBuzz]| to font declaration
	\end{itemize}
	
	\subsection{Font not found}
	Install \textbf{Twemoji Mozilla} (canonical \texttt{mozilla/twemoji-colr} v0.7.0). The easiest route is a TeX-tree install:
	\begin{itemize}
		\item \textbf{TeX Live:} \verb|tlmgr install twemoji-colr|
		\item \textbf{MiKTeX:} \verb|mpm --install=twemoji-colr|
		\item \textbf{Windows (system font):} download \verb|twemoji-colr.zip| from CTAN, extract, install \verb|TwemojiMozilla.ttf|
		\item \textbf{Linux (Debian/Ubuntu):} \verb|sudo apt install fonts-twemoji-svginot|
		\item \textbf{Linux (Fedora):} \verb|sudo dnf install twitter-twemoji-fonts|
		\item \textbf{macOS:} \verb|brew install --cask font-twemoji|
	\end{itemize}
	
	\subsection{Compilation errors with special characters}
	Some emoji keys contain underscores or other special characters. The package handles
	escaping automatically, but if you're defining custom keys, avoid \verb|#|, \verb|%|,
	\verb|&|, \verb|$|, \verb|_|, \verb|{|, \verb|}| unless properly escaped.
	
	%===============================================================================
	\section{License}
	%===============================================================================
	
	MIT License. See the package repository for full details.
	
\end{document}