| 1 |
% \iffalse meta-comment |
| 2 |
% |
| 3 |
% emo•ji for all (LaTeX engines) |
| 4 |
% (C) Copyright 2023 by Robert Grimm |
| 5 |
% Released under LPPL v1.3c or later |
| 6 |
% <https://github.com/apparebit/emo> |
| 7 |
% |
| 8 |
% \fi |
| 9 |
% ^^A ---------------------------------------------------------------------------------- |
| 10 |
% \iffalse |
| 11 |
%<*scaffold> |
| 12 |
\iffalse |
| 13 |
%</scaffold> |
| 14 |
% ====================================================================================== |
| 15 |
%<*readme> |
| 16 |
# emo•ji for all (LaTeX engines) |
| 17 |
|
| 18 |
This package defines the `\emo{<emoji-name>}` macro for including color emoji in |
| 19 |
a document no matter the LaTeX engine. It uses the Noto color emoji font if the |
| 20 |
engine supports doing so and falls back onto PDF graphics otherwise. In either |
| 21 |
case, `\emo{desert-island}` results in 🏝 and `\emo{parrot}` results in 🦜. Emo |
| 22 |
may come in particularly handy when dealing with academic publishers that |
| 23 |
provide only minimal support for non-Latin scripts (cough, |
| 24 |
[ACM](https://www.acm.org), cough). |
| 25 |
|
| 26 |
Emo's source repository is <https://github.com/apparebit/emo>. It also is |
| 27 |
available [through CTAN](https://ctan.org/pkg/emo). Emo supports conversion to |
| 28 |
HTML with [LaTeXML](https://github.com/brucemiller/LaTeXML) or |
| 29 |
[TeX4ht](https://tug.org/tex4ht/). When using the latter tool, please be sure to |
| 30 |
use |make4ht -l| as invocation. |
| 31 |
|
| 32 |
|
| 33 |
## Package Options |
| 34 |
|
| 35 |
When emo is used with the `extra` option, this package also defines the |
| 36 |
`\lingchi` and `\YHWH` macros for 凌遲 and יהוה, respectively. Both macros |
| 37 |
preserve a subsequent space as space, no backslash needed. |
| 38 |
|
| 39 |
When used with the `index` option, this package also emits a raw index entry for |
| 40 |
each use of an emoji into an emo index or `.edx` file. |
| 41 |
|
| 42 |
|
| 43 |
## Installation |
| 44 |
|
| 45 |
To **extract files** embedded in [emo.dtx](emo.dtx), run `pdftex emo.dtx`. Note |
| 46 |
that plain old `tex` won't do, since it mangles this README. `pdflatex` works, |
| 47 |
but also generates the package documentation. The embedded files are `build.sh`, |
| 48 |
`emo.ins`, `emo.sty`, `emo.sty.ltxml`, `canary.tex`, and `README.md`. |
| 49 |
|
| 50 |
To **build the documentation** embedded in `emo.dtx`, run `source build.sh`. The |
| 51 |
shell script invokes `pdflatex emo.dtx` thrice and `makeindex` once each for the |
| 52 |
change and the symbol indices, resulting in [emo.pdf](emo.pdf). |
| 53 |
|
| 54 |
To **configure the emoji**, run `python3 config/emo.py` with appropriate |
| 55 |
arguments. The [package documentation](emo.pdf) explains the configuration tool |
| 56 |
in detail, but you may find the `-h` for help option sufficient to get started. |
| 57 |
|
| 58 |
To **install this package**, place `emo.def`, `emo.sty`, `emo.sty.ltxml`, |
| 59 |
`emo-lingchi.ttf`, and the `emo-graphics` directory with the fallback PDF files |
| 60 |
somewhere where LaTeX can find them. In a pinch, your project directory will do. |
| 61 |
|
| 62 |
|
| 63 |
## Supported Emoji |
| 64 |
|
| 65 |
By default, emo supports only a few emoji, ordered by Unicode codepoints: |
| 66 |
|
| 67 |
1️⃣ ☣️ ⚖️ ✅ ✔️ ❌ ➕ 🇪🇺 🉐 🌁 🌍 🎉 🏛️ 🏝️ 🏟️ 🏳️🌈 🏷️ 🐤 👁️ 👥 💥 💱 💾 📈 📐 📟 🔍 |
| 68 |
🕵️ 🗑️ 😡 🛑 🤖 🤝 🤦 🤪 🤯 🥺 🦜 🧑⚖️ 🧻 🧾 |
| 69 |
|
| 70 |
Their names are keycap-one, biohazard, balance-scale, check-mark-button, |
| 71 |
check-mark, cross-mark, plus, eu, japanese-bargain-button, foggy, |
| 72 |
globe-africa-europe, party-popper, classical-building, desert-island, stadium, |
| 73 |
rainbow-flag, label, baby-chick, eye, busts, collision, currency-exchange, |
| 74 |
floppy-disk, chart-increasing, triangular-ruler, pager, loupe-left, detective, |
| 75 |
wastebasket, enraged-face, stop-sign, robot, handshake, person-facepalming, |
| 76 |
zany-face, exploding-head, pleading-face, parrot, judge, roll-of-paper, and |
| 77 |
receipt. |
| 78 |
|
| 79 |
The [package's documentation](emo.pdf) explains the underlying naming scheme and |
| 80 |
also how to reconfigure which emoji are supported. The [emo.py](config/emo.py) |
| 81 |
script takes care of the heavy lifting during reconfiguration, converting SVG |
| 82 |
into PDF files and generating an updated `emo.def` file. |
| 83 |
|
| 84 |
|
| 85 |
## Copyright and Licensing |
| 86 |
|
| 87 |
This package combines code written in LaTeX, Python, and Perl with Unicode data |
| 88 |
about emoji as well as graphics and fonts derived from Google's Noto fonts. As a |
| 89 |
result, a number of different licenses apply, all of which are [OSI |
| 90 |
approved](https://opensource.org/licenses/) and non-copyleft: |
| 91 |
|
| 92 |
* This package's [LaTeX code](emo.dtx) is © Copyright 2023 by Robert Grimm and |
| 93 |
has been released under the [LPPL |
| 94 |
v1.3c](https://www.latex-project.org/lppl/lppl-1-3c/) or later. |
| 95 |
* The [emo.py](config/emo.py) configuration script also is © Copyright 2023 by |
| 96 |
Robert Grimm but has been released under the [Apache 2.0 |
| 97 |
license](https://www.apache.org/licenses/LICENSE-2.0). |
| 98 |
* The [emoji-test.txt](config/emoji-test.txt) configuration file is a data |
| 99 |
file from [Unicode TR-51](https://unicode.org/reports/tr51/) and hence |
| 100 |
subject to the [Unicode License](https://www.unicode.org/license.txt). |
| 101 |
* The `emo-lingchi.ttf` font is a two-glyph subset of the serif traditional |
| 102 |
Chinese version of Google's [Noto |
| 103 |
fonts](https://github.com/notofonts/noto-cjk) and hence subject to the [SIL |
| 104 |
Open Font License v1.1](https://scripts.sil.org/ofl). |
| 105 |
* The PDF graphics in the `emo-graphics` directory are derived from the |
| 106 |
sources for [Noto's color emoji](https://github.com/googlefonts/noto-emoji) |
| 107 |
and hence subject to the Apache 2.0 license. |
| 108 |
|
| 109 |
%</readme> |
| 110 |
% -------------------------------------------------------------------------------------- |
| 111 |
%<*buildscript> |
| 112 |
# Test emo |
| 113 |
pdflatex -jobname=pdftex-canary canary |
| 114 |
xelatex -jobname=xetex-canary canary |
| 115 |
lualatex -jobname=luatex-canary canary |
| 116 |
pdfunite pdftex-canary.pdf xetex-canary.pdf luatex-canary.pdf canary.pdf |
| 117 |
|
| 118 |
# Document emo |
| 119 |
pdflatex emo.dtx |
| 120 |
makeindex -s gind.ist -o emo.ind emo.idx |
| 121 |
makeindex -s gglo.ist -o emo.gls emo.glo |
| 122 |
pdflatex emo.dtx |
| 123 |
pdflatex emo.dtx |
| 124 |
%</buildscript> |
| 125 |
% ====================================================================================== |
| 126 |
%<*scaffold> |
| 127 |
\fi |
| 128 |
\def\nameofplainTeX{plain} |
| 129 |
\ifx\fmtname\nameofplainTeX\else |
| 130 |
\expandafter\begingroup |
| 131 |
\fi |
| 132 |
%</scaffold> |
| 133 |
% -------------------------------------------------------------------------------------- |
| 134 |
%<*install> |
| 135 |
\input docstrip.tex |
| 136 |
\keepsilent |
| 137 |
\askforoverwritefalse |
| 138 |
\preamble |
| 139 |
|
| 140 |
emo•ji for all (LaTeX engines) |
| 141 |
(C) Copyright 2023 by Robert Grimm |
| 142 |
Released under LPPL v1.3c or later |
| 143 |
<https://github.com/apparebit/emo> |
| 144 |
|
| 145 |
\endpreamble |
| 146 |
\usedir{tex/latex/emo} |
| 147 |
\generate{ |
| 148 |
\file{\jobname.sty}{\from{\jobname.dtx}{package}}} |
| 149 |
\generate{ |
| 150 |
\nopreamble\nopostamble |
| 151 |
\file{\jobname.sty.ltxml}{\from{\jobname.dtx}{latexml-binding}}} |
| 152 |
%</install> |
| 153 |
%<install>\endbatchfile |
| 154 |
% -------------------------------------------------------------------------------------- |
| 155 |
%<*scaffold> |
| 156 |
\usedir{source/latex/emo} |
| 157 |
\generate{\file{\jobname.ins}{\from{\jobname.dtx}{install}}} |
| 158 |
\generate{\file{canary.tex}{\from{\jobname.dtx}{canary}}} |
| 159 |
\nopreamble\nopostamble |
| 160 |
\usedir{source/latex/emo} |
| 161 |
\generate{\file{build.sh}{\from{\jobname.dtx}{buildscript}}} |
| 162 |
\usedir{doc/latex/emo} |
| 163 |
\generate{\file{README.md}{\from{\jobname.dtx}{readme}}} |
| 164 |
\ifx\fmtname\nameofplainTeX |
| 165 |
\expandafter\endbatchfile |
| 166 |
\else |
| 167 |
\expandafter\endgroup |
| 168 |
\fi |
| 169 |
%</scaffold> |
| 170 |
% ====================================================================================== |
| 171 |
% See https://tug.org/TUGboat/tb29-2/tb92pakin.pdf. |
| 172 |
%<*scaffold> |
| 173 |
\ProvidesFile{emo.dtx} |
| 174 |
%</scaffold> |
| 175 |
%<package>\NeedsTeXFormat{LaTeX2e} |
| 176 |
%<package>\ProvidesPackage{emo} |
| 177 |
%<*scaffold,package> |
| 178 |
[2023/04/26 v0.4 emo•ji for all (LaTeX engines)] |
| 179 |
%</scaffold,package> |
| 180 |
% ====================================================================================== |
| 181 |
%<*driver> |
| 182 |
\PassOptionsToPackage{utf8}{inputenc} |
| 183 |
\documentclass{ltxdoc} |
| 184 |
% Override the default \small, which looks odd typeset in Inconsolata. |
| 185 |
\renewcommand{\MacroFont}{\normalsize\ttfamily} |
| 186 |
\usepackage[extra]{\jobname} |
| 187 |
\usepackage{enumitem} |
| 188 |
\usepackage{parskip} |
| 189 |
\usepackage{inconsolata} |
| 190 |
|
| 191 |
% Use BlackFoundry's Inria <https://tug.org/FontCatalogue/inriaserifregular/> |
| 192 |
\usepackage[T1]{fontenc} |
| 193 |
\usepackage[lining]{InriaSerif} |
| 194 |
\renewcommand*\oldstylenums[1]{{\fontfamily{InriaSerif-OsF}\selectfont #1}} |
| 195 |
\let\oldnormalfont\normalfont |
| 196 |
\def\normalfont{\oldnormalfont\mdseries} |
| 197 |
|
| 198 |
\usepackage{xcolor} |
| 199 |
\usepackage{hyperref} |
| 200 |
\definecolor{spot}{HTML}{353598} |
| 201 |
\hypersetup{allcolors=spot} |
| 202 |
\EnableCrossrefs |
| 203 |
\CodelineIndex |
| 204 |
\RecordChanges |
| 205 |
\begin{document} |
| 206 |
\DocInput{\jobname.dtx} |
| 207 |
\end{document} |
| 208 |
%</driver> |
| 209 |
% ====================================================================================== |
| 210 |
% \fi |
| 211 |
% |
| 212 |
% \changes{0.1}{}{Make initial release} |
| 213 |
% \changes{0.2}{}{Prefix font and graphic files with ``{\tt emo-}''} |
| 214 |
% \changes{0.2}{}{Support {\tt pdftex} for extracting {\tt emo.dtx}} |
| 215 |
% \changes{0.3}{}{Support TeX4ht for conversion to HTML} |
| 216 |
% \changes{0.4}{}{Automate testing across engines with {\tt canary.tex}} |
| 217 |
% |
| 218 |
% \GetFileInfo{\jobname.dtx} |
| 219 |
% |
| 220 |
% \DoNotIndex{\{,\},\x,\\} |
| 221 |
% \DoNotIndex{\begingroup,\char,\csname,\def} |
| 222 |
% \DoNotIndex{\else,\endcsname,\endgroup,\expandafter} |
| 223 |
% \DoNotIndex{\fi,\ifcsname,\ifluatex,\index} |
| 224 |
% \DoNotIndex{\newcommand,\newif,\newindex} |
| 225 |
% \DoNotIndex{\relax,\string,\textbackslash,\textsf,\texttt} |
| 226 |
% |
| 227 |
% \newlist{inlinenum}{enumerate*}{1} |
| 228 |
% \setlist[inlinenum]{label=(\alph{inlinenumi})} |
| 229 |
% \newenvironment{verbatimish}{% |
| 230 |
% \ttfamily% |
| 231 |
% \obeylines% |
| 232 |
% \obeyspaces% |
| 233 |
% \vspace{\the\parskip}% |
| 234 |
% \setlength{\parskip}{0pt}% |
| 235 |
% \setlength{\parindent}{1em}% |
| 236 |
% }{} |
| 237 |
% |
| 238 |
% \title{emo•ji for all\\(LaTeX engines)} |
| 239 |
% \author{\href{https://apparebit.com}{Robert Grimm}} |
| 240 |
% \date{Version \fileversion\ (\filedate)} |
| 241 |
% |
| 242 |
% \maketitle |
| 243 |
% |
| 244 |
% \begin{abstract} |
| 245 |
% \noindent{}Emo implements the |\emo|\marg{emoji-name} command for including |
| 246 |
% color emoji such as |\emo{desert-island}| for \emo{desert-island} or |
| 247 |
% |\emo{parrot}| for \emo{parrot} in your documents independent of LaTeX engine. |
| 248 |
% The implementation uses the Noto color emoji font if the engine supports it |
| 249 |
% and includes PDF graphics otherwise. It also supports conversion to HTML with |
| 250 |
% either LaTeXML or TeX4ht. Next, PDF graphics are automatically derived from |
| 251 |
% Noto's SVG sources, so the visual appearance is very similar. The source |
| 252 |
% repository is at \url{https://github.com/apparebit/emo}. Emo may come in |
| 253 |
% particularly handy when dealing with academic publishers that provide only |
| 254 |
% minimal support for non-Latin scripts (cough, |
| 255 |
% \href{https://authors.acm.org/proceedings/production-information/accepted-latex-packages}{ACM}, |
| 256 |
% cough). |
| 257 |
% \end{abstract} |
| 258 |
% |
| 259 |
% \tableofcontents |
| 260 |
% |
| 261 |
% |
| 262 |
% ^^A ================================================================================== |
| 263 |
% \section{Installation} |
| 264 |
% |
| 265 |
% The emo package is available through its |
| 266 |
% \href{https://github.com/apparebit/emo}{source repository} or through |
| 267 |
% \href{https://ctan.org/pkg/emo}{CTAN}. Installation is fairly |
| 268 |
% straightforward, though it does involve a lot more files than usual. |
| 269 |
% |
| 270 |
% \begin{enumerate} |
| 271 |
% \item Start by extracting this package's files from |emo.dtx| by running: |
| 272 |
% \begin{verbatimish} |
| 273 |
% \$ pdftex emo.dtx |
| 274 |
% \end{verbatimish} |
| 275 |
% Do \emph{not} use |tex|; it mangles the embedded |README.md|. |pdflatex| also |
| 276 |
% extracts the files and then builds the documentation. Embedded files are |
| 277 |
% |build.sh|, |emo.ins|, |emo.sty|, |emo.sty.ltxml|, |canary.tex|, and |
| 278 |
% |README.md|. Extraction will overwrite existing files with the same name |
| 279 |
% without asking. |
| 280 |
% |
| 281 |
% \item Build the package documentation with change and symbol indices by |
| 282 |
% running: |
| 283 |
% \begin{verbatimish} |
| 284 |
% \$ source build.sh |
| 285 |
% \end{verbatimish} |
| 286 |
% The shell script processes the tests in |canary.tex| with |pdflatex|, |
| 287 |
% |xelatex|, and |lualatex|, combining test results into |canary.pdf|. It also |
| 288 |
% processes |emo.dtx| with |pdflatex| and |makeindex| to produce documentation |
| 289 |
% in |emo.pdf|. |
| 290 |
% |
| 291 |
% \item Get started reconfiguring supported emoji by running: |
| 292 |
% \begin{verbatimish} |
| 293 |
% \$ python config/emo.py -h |
| 294 |
% \end{verbatimish} |
| 295 |
% For more detailed instructions, see \S\ref{sec:config} below. |
| 296 |
% |
| 297 |
% \item Put the following files somewhere LaTeX can find them. In a pinch, your |
| 298 |
% current project's directory will do. However, emo's installation potentially |
| 299 |
% comprises thousands of files. So, you probably want to use a dedicated |
| 300 |
% directory and add that to the search path for LaTeX, e.g., by setting the |
| 301 |
% |TEXINPUTS| environment variable. |
| 302 |
% \begin{enumerate} |
| 303 |
% \item |emo.sty| with the package implementation; |
| 304 |
% \item |emo.sty.ltxml| with the binding for |
| 305 |
% \href{https://github.com/brucemiller/LaTeXML}{LaTeXML}; |
| 306 |
% \item |emo.def| with the emoji table; |
| 307 |
% \item |emo-lingchi.ttf| with the two glyphs for |\lingchi|; |
| 308 |
% \item |emo-graphics| with the fallback PDF graphics. |
| 309 |
% \end{enumerate} |
| 310 |
% TeX Live requires that each package's files have unique names. For that |
| 311 |
% reason, the PDF graphics in the |emo-graphics| directory start with the |emo-| |
| 312 |
% prefix as well. |
| 313 |
% |
| 314 |
% \end{enumerate} |
| 315 |
% |
| 316 |
% When running on the LuaLaTeX engine, the emo package also uses the Noto color |
| 317 |
% emoji (|NotoColorEmoji.ttf|) and Linux Libertine (|LinLibertine_R.otf|) fonts, |
| 318 |
% with the latter used for rendering |\YHWH| only. Neither file is included with |
| 319 |
% emo's distribution, since both of them are distributed with major TeX |
| 320 |
% distributions already. If they are not included with your LaTeX distribution, |
| 321 |
% you can find them on CTAN. The |emo-lingchi.ttf| font distributed with emo is |
| 322 |
% a two glyph subset of |NotoSerifTC-Regular.otf|, i.e., the traditional Chinese |
| 323 |
% version of Noto serif. |
| 324 |
% |
| 325 |
% |
| 326 |
% ^^A ================================================================================== |
| 327 |
% \section{Usage} |
| 328 |
% |
| 329 |
% As usual, you declare your document's dependency on emo with |
| 330 |
% |\usepackage{emo}|. In addition to the unadorned form, emo takes up to two |
| 331 |
% options: |
| 332 |
% \begin{description} |
| 333 |
% \item[extra] Also define the |\lingchi| and |\YHWH| macros, which produce |
| 334 |
% \lingchi and \YHWH. |
| 335 |
% \item[index] Create an emoji index tagged |emo| with the |.edx| extension for |
| 336 |
% the raw index and the |.end| extension for the processed index. This |
| 337 |
% option relies on the |index| package, generates the raw |.edx| file, |
| 338 |
% but does not build or use the processed index. |
| 339 |
% \end{description} |
| 340 |
% |
| 341 |
% |
| 342 |
% ^^A ---------------------------------------------------------------------------------- |
| 343 |
% \subsection{One Main Macro} |
| 344 |
% \DescribeMacro{\emo} |
| 345 |
% An |\emo|\marg{emoji-name} invocation expands to the named emoji. For |
| 346 |
% LuaLaTeX, it uses the Noto color emoji font. For all other engines, it uses |
| 347 |
% PDF graphics. That way, |\emo{desert-island}| results in~\emo{desert-island} |
| 348 |
% and |\emo{parrot}| results in~\emo{parrot}. |
| 349 |
% |
| 350 |
% Since LaTeX tends to produce a lot of command line noise about underfull boxes |
| 351 |
% and loaded fonts, it's a easy to miss meaningful warnings. For that reason, |
| 352 |
% |\emo| expands to an attention-seeking error message upon undefined emoji |
| 353 |
% names. For example, |\emo{boo}| produces \emo{boo}. |
| 354 |
% |
| 355 |
% |
| 356 |
% ^^A ---------------------------------------------------------------------------------- |
| 357 |
% \subsubsection{Emoji Names} |
| 358 |
% |
| 359 |
% With some exceptions, emo's names for emoji are automatically derived from |
| 360 |
% their Unicode names, with letters converted to lowercase, punctuation such as |
| 361 |
% commas, colons, quotes, and parentheses stripped, and interword spaces |
| 362 |
% replaced by dashes. Furthermore, instead of the rather verbose |
| 363 |
% |dark-skin-tone|, |medium-dark-skin-tone|, etc modifiers, emo |
| 364 |
% uses the more succinct |darkest|, |darker|, |medium|, |lighter|, and |
| 365 |
% |lightest|. |
| 366 |
% |
| 367 |
% For some emoji names, emo goes further by hard-coding shorter names. Those |
| 368 |
% names are listed in Table~\ref{tab:special-names}. |
| 369 |
% |
| 370 |
% \begin{table} |
| 371 |
% \caption{Exceptional emoji names} |
| 372 |
% \label{tab:special-names} |
| 373 |
% \small\vspace{1em} |
| 374 |
% \begin{tabular}{ll} |
| 375 |
% \textbf{Transformed Unicode Name} & \textbf{Emo Replacement Name} \\ \hline |
| 376 |
% |a-button-blood-type| & |a-button| \\ |
| 377 |
% |ab-button-blood-type| & |ab-button| \\ |
| 378 |
% |b-button-blood-type| & |b-button| \\ |
| 379 |
% |o-button-blood-type| & |o-button| \\ |
| 380 |
% |bust-in-silhouette| & |bust| \\ |
| 381 |
% |busts-in-silhouette| & |busts| \\ |
| 382 |
% |flag-european-union| & |eu| \\ |
| 383 |
% |globe-showing-americas| & |globe-americas| \\ |
| 384 |
% |globe-showing-asia-australia| & |globe-asia-australia| \\ |
| 385 |
% |globe-showing-europe-africa| & |globe-africa-europe| \\ |
| 386 |
% |hear-no-evil-monkey| & |hear-no-evil| \\ |
| 387 |
% |index-pointing-at-the-viewer| & |index-pointing-at-viewer| \\ |
| 388 |
% |index-pointing-at-the-viewer-darkest| & |index-pointing-at-viewer-darkest| \\ |
| 389 |
% |index-pointing-at-the-viewer-darker| & |index-pointing-at-viewer-darker| \\ |
| 390 |
% |index-pointing-at-the-viewer-medium| & |index-pointing-at-viewer-medium| \\ |
| 391 |
% |index-pointing-at-the-viewer-lighter| & |index-pointing-at-viewer-lighter| \\ |
| 392 |
% |index-pointing-at-the-viewer-lightest| & |index-pointing-at-viewer-lightest| \\ |
| 393 |
% |keycap-*| & |keycap-star| \\ |
| 394 |
% |keycap-#| & |keycap-hash| \\ |
| 395 |
% |keycap-0| & |keycap-zero| \\ |
| 396 |
% |keycap-1| & |keycap-one| \\ |
| 397 |
% |keycap-2| & |keycap-two| \\ |
| 398 |
% |keycap-3| & |keycap-three| \\ |
| 399 |
% |keycap-4| & |keycap-four| \\ |
| 400 |
% |keycap-5| & |keycap-five| \\ |
| 401 |
% |keycap-6| & |keycap-six| \\ |
| 402 |
% |keycap-7| & |keycap-seven| \\ |
| 403 |
% |keycap-8| & |keycap-eight| \\ |
| 404 |
% |keycap-9| & |keycap-nine| \\ |
| 405 |
% |keycap-10| & |keycap-ten| \\ |
| 406 |
% |magnifying-glass-tilted-left| & |loupe-left| \\ |
| 407 |
% |magnifying-glass-tilted-right| & |loupe-right| \\ |
| 408 |
% |palm-down-hand| & |palm-down| \\ |
| 409 |
% |palm-down-hand-darkest| & |palm-down-darkest| \\ |
| 410 |
% |palm-down-hand-darker| & |palm-down-darker| \\ |
| 411 |
% |palm-down-hand-medium| & |palm-down-medium| \\ |
| 412 |
% |palm-down-hand-lighter| & |palm-down-lighter| \\ |
| 413 |
% |palm-down-hand-lightest| & |palm-down-lightest| \\ |
| 414 |
% |palm-up-hand| & |palm-up| \\ |
| 415 |
% |palm-up-hand-darkest| & |palm-up-darkest| \\ |
| 416 |
% |palm-up-hand-darker| & |palm-up-darker| \\ |
| 417 |
% |palm-up-hand-medium| & |palm-up-medium| \\ |
| 418 |
% |palm-up-hand-lighter| & |palm-up-lighter| \\ |
| 419 |
% |palm-up-hand-lightest| & |palm-up-lightest| \\ |
| 420 |
% |rolling-on-the-floor-laughing| & |rofl| \\ |
| 421 |
% |see-no-evil-monkey| & |see-no-evil| \\ |
| 422 |
% |speak-no-evil-monkey| & |speak-no-evil| \\ |
| 423 |
% \end{tabular} |
| 424 |
% \end{table} |
| 425 |
% |
| 426 |
% Emo's |emo.def| contains the names and codepoints of all currently supported |
| 427 |
% emoji. Emo's distribution also includes the |emoji-test.txt| file, which is |
| 428 |
% part of \href{https://unicode.org/reports/tr51/}{Unicode TR-51} and contains |
| 429 |
% the names and codepoints of all \emph{potentially} supported emoji, i.e., all |
| 430 |
% emoji. It further organizes emoji into groups and subgroups, with the current |
| 431 |
% (sub)group being the one named on the closest line above the emoji that starts |
| 432 |
% with |# |(|sub|)|group:|. As described in the next section, the group and |
| 433 |
% subgroup names can be used during configuration for concisely naming a large |
| 434 |
% number of emoji. |
| 435 |
% |
| 436 |
% |
| 437 |
% ^^A ---------------------------------------------------------------------------------- |
| 438 |
% \subsection{Two Extra Macros} |
| 439 |
% |
| 440 |
% \DescribeMacro{\lingchi} |
| 441 |
% \DescribeMacro{\YHWH} |
| 442 |
% The |\lingchi| and |\YHWH| macros take no arguments and produce \lingchi and |
| 443 |
% \YHWH. They are only available if emo is used with the \textsf{extra} option. |
| 444 |
% The former renders the Chinese term for ``death by a thousand cuts.'' While |
| 445 |
% originally an execution method, the term applies to surprisingly many software |
| 446 |
% systems as well. The latter produces the Tetragrammaton, the Hebrew name for |
| 447 |
% God. Observant Jews never utter what's written, not even in their thoughts, |
| 448 |
% substituting Adonai (``My Lord''), Elohim (``God''), or HaShem (``The Name'') |
| 449 |
% instead. In my mind, that nicely mirrors the very incomprehensibility of |
| 450 |
% \YHWH. Both macros preserve a subsequent space as space, no backslash needed. |
| 451 |
% |
| 452 |
% |
| 453 |
% ^^A ---------------------------------------------------------------------------------- |
| 454 |
% \subsection{Conversion to HTML} |
| 455 |
% |
| 456 |
% Emo supports conversion to HTML with either |
| 457 |
% \href{https://github.com/brucemiller/LaTeXML}{LaTeXML} or |
| 458 |
% \href{https://tug.org/tex4ht/}{TeX4ht}. LaTeXML support is implemented by a |
| 459 |
% separate ``binding'' against LaTeXML's Perl API. I chronicled my exploration |
| 460 |
% of suitable options leading to that less than ideal choice in a |
| 461 |
% \href{https://github.com/brucemiller/LaTeXML/issues/2063}{GitHub issue}. |
| 462 |
% TeX4ht support is implemented by the emo package itself. It requires |
| 463 |
% processing with LuaLaTeX e.g., by passing |-l| to the |make4ht| tool. |
| 464 |
% |
| 465 |
% |
| 466 |
% ^^A ================================================================================== |
| 467 |
% \section{Configuration} |
| 468 |
% \label{sec:config} |
| 469 |
% |
| 470 |
% Emo's implementation is actually split over two files: |emo.sty| is extracted |
| 471 |
% from |emo.dtx| and defines the substance of the package, its options, its |
| 472 |
% helper macros, and the user-visible |\emo|, |\lingchi|, and |\YHWH| macros. |
| 473 |
% Currently supported emoji are defined by the emoji table in the second file, |
| 474 |
% |emo.def|. For every supported emoji, the file contains a command |
| 475 |
% |\emo@emoji@|\meta{emoji-name} with the emoji's codepoints as value. |
| 476 |
% |
| 477 |
% Configuration automates the regeneration of the emoji table for arbitrary |
| 478 |
% numbers of emoji. |config/emo.py| is the script and |config/emoji-test.txt| is |
| 479 |
% the list of all emoji from the Unicode standard. |
| 480 |
% |
| 481 |
% |
| 482 |
% ^^A ---------------------------------------------------------------------------------- |
| 483 |
% \subsection{Running the Configuration Script} |
| 484 |
% |
| 485 |
% To update emo's configuration, invoke the |config/emo.py| script: |
| 486 |
% \begin{verbatimish} |
| 487 |
% \$ python3 config/emo.py \meta{selector} \meta{selector} $\ldots$ |
| 488 |
% \end{verbatimish} |
| 489 |
% |
| 490 |
% Each selector may be: |
| 491 |
% \begin{itemize} |
| 492 |
% \item The literal |ALL| (case-sensitive) for \emph{all} emoji. |
| 493 |
% \item Name of a group in |emoji-test.txt| lowercased and with spaces replaced |
| 494 |
% by dashes and ampersand |&| replaced by an |and|; e.g., |
| 495 |
% |travel-and-places|. |
| 496 |
% \item Name of a group, a double colon |::|, and name of a subgroup, again |
| 497 |
% lowercased and with spaces replaced by dashes and |&| by an |and|; e.g., |
| 498 |
% |travel-and-places::place-geographic|. |
| 499 |
% \item The name of an emoji; e.g., |desert-island|. |
| 500 |
% \end{itemize} |
| 501 |
% For conjunctive group names, such as ``Smileys \& Emotion'' (|emoji-test.txt|) |
| 502 |
% or ``smileys-and-emotion'' (|emo.py|), the configuration script also accepts |
| 503 |
% either of the two nouns as a shortcut, e.g., ``smileys'' or ``emotion.'' |
| 504 |
% |
| 505 |
% For data safety, |emo.py| does not overwrite PDF graphics and hence can only |
| 506 |
% \emph{add} emoji to the configuration. To remove emoji, simply remove their |
| 507 |
% PDF graphics from |emo-graphics| and then run |emo.py| without selector |
| 508 |
% arguments, which updates the emoji table accordingly. |
| 509 |
% |
| 510 |
% |emo.py| effectively treats |emoji-test.txt| as registry of all emoji and the |
| 511 |
% filenames of PDF graphics in |emo-graphics| as emo's current inventory. For |
| 512 |
% all emoji named by selector arguments but not in the inventory, |emo.py| |
| 513 |
% converts the SVG source graphic from the Noto color emoji sources to a PDF |
| 514 |
% file and deletes the |/Page| |/Group| object from the the PDF again, since |
| 515 |
% that object trips up |pdflatex|. And yeah, |emo.py| automatically downloads |
| 516 |
% the Noto color emoji sources if necessary. |
| 517 |
% |
| 518 |
% |
| 519 |
% ^^A ================================================================================== |
| 520 |
% \section{Copyright and Licensing} |
| 521 |
% |
| 522 |
% Since emo's distribution includes not only LaTeX code but also a substantial |
| 523 |
% Python script, Unicode data about emoji, as well as graphics and fonts derived |
| 524 |
% from Google's Noto project, a number of different licenses apply. All of them |
| 525 |
% are \href{https://opensource.org/licenses/}{OSI approved} and non-copyleft: |
| 526 |
% \begin{itemize} |
| 527 |
% \item This package's LaTeX and also Perl code extracted from |emo.dtx| |
| 528 |
% is © Copyright 2023 by Robert Grimm and has been released |
| 529 |
% under the \href{https://www.latex-project.org/lppl/lppl-1-3c/}{LPPL v1.3c} |
| 530 |
% or later. |
| 531 |
% \item The |config/emo.py| script also is © Copyright 2023 by Robert Grimm but |
| 532 |
% has been released under the |
| 533 |
% \href{https://www.apache.org/licenses/LICENSE-2.0}{Apache 2.0 license}. |
| 534 |
% \item The [config/emoji-test.txt] configuration file is a data file from |
| 535 |
% \href{https://unicode.org/reports/tr51/}{Unicode TR-51} and hence subject |
| 536 |
% to the \href{https://www.unicode.org/license.txt}{Unicode License}. |
| 537 |
% \item The |emo-lingchi.ttf| font is a two-glyph subset of the traditional |
| 538 |
% Chinese version of Google's |
| 539 |
% \href{https://github.com/notofonts/noto-cjk}{Noto serif} and hence subject |
| 540 |
% to the \href{https://scripts.sil.org/ofl}{SIL Open Font License v1.1}. |
| 541 |
% \item The PDF graphics in the |emo-graphics| directory are derived from the |
| 542 |
% sources for \href{https://github.com/googlefonts/noto-emoji}{Noto's color |
| 543 |
% emoji} and hence subject to the Apache 2.0 license. |
| 544 |
% \end{itemize} |
| 545 |
% |
| 546 |
% |
| 547 |
% \StopEventually{^^A |
| 548 |
% \PrintChanges^^A |
| 549 |
% \setcounter{IndexColumns}{2}^^A |
| 550 |
% \columnsep = 20pt^^A |
| 551 |
% \PrintIndex} |
| 552 |
% |
| 553 |
% |
| 554 |
% ^^A ================================================================================== |
| 555 |
% \section{Implementation} |
| 556 |
% |
| 557 |
% Let's get started with emo's implementation: |
| 558 |
% \begin{macrocode} |
| 559 |
%<*package> |
| 560 |
% \end{macrocode} |
| 561 |
% |
| 562 |
% Except, the package implementation started near the top of the |emo.dtx| file, |
| 563 |
% before the documentation preamble. We repeat it here for completeness: |
| 564 |
% |
| 565 |
% \begin{verbatimish} |
| 566 |
% |\NeedsTeXFormat{LaTeX2e}| |
| 567 |
% |\ProvidesPackage{emo}| |
| 568 |
% | |[\filedate\space\fileversion\space\fileinfo] |
| 569 |
% \end{verbatimish} |
| 570 |
% |
| 571 |
% And no, I didn't repeat the version number, date, or package information. |
| 572 |
% Check |emo.dtx|. |
| 573 |
% |
| 574 |
% |
| 575 |
% ^^A ---------------------------------------------------------------------------------- |
| 576 |
% \subsection{Package Options} |
| 577 |
% |
| 578 |
% \begin{macro}{\ifemo@extra} |
| 579 |
% \begin{macro}{\ifemo@index} |
| 580 |
% \begin{macro}{\ifemo@debug} |
| 581 |
% \changes{0.4}{}{Add \textsf{debug} option for drawing boundary boxes} |
| 582 |
% Emo's \textsf{extra} and \textsf{index} options are simple flags. So is the |
| 583 |
% only incompletely documented \textsf{debug} option. We declare a new |
| 584 |
% conditional for each and, if |\usepackage| includes an option, toggle the |
| 585 |
% conditional's state. |
| 586 |
% \begin{macrocode} |
| 587 |
\newif\ifemo@extra\emo@extrafalse |
| 588 |
\DeclareOption{extra}{\emo@extratrue} |
| 589 |
\newif\ifemo@indexing\emo@indexingfalse |
| 590 |
\DeclareOption{index}{\emo@indexingtrue} |
| 591 |
\newif\ifemo@debug\emo@debugfalse |
| 592 |
\DeclareOption{debug}{\emo@debugtrue} |
| 593 |
\ProcessOptions\relax |
| 594 |
% \end{macrocode} |
| 595 |
% \end{macro} |
| 596 |
% \end{macro} |
| 597 |
% \end{macro} |
| 598 |
% |
| 599 |
% |
| 600 |
% ^^A ---------------------------------------------------------------------------------- |
| 601 |
% \subsection{Setup Including Dependencies} |
| 602 |
% |
| 603 |
% The dependency on |inputenc| effectively declares this file's encoding to be |
| 604 |
% UTF-8. The XeTeX and LuaTeX engines already expect files to be encoded that |
| 605 |
% way and hence ignore the declaration. However, pdfTeX supports other (legacy) |
| 606 |
% encodings and needs to be told. |
| 607 |
% \begin{macrocode} |
| 608 |
\RequirePackage[utf8]{inputenc} |
| 609 |
% \end{macrocode} |
| 610 |
% |
| 611 |
% \begin{macro}{\emo@use@unicode} |
| 612 |
% \begin{macro}{\emo@use@font} |
| 613 |
% \begin{macro}{\emo@use@pdf} |
| 614 |
% \begin{macro}{\emo@backend} |
| 615 |
% \changes{0.3}{}{Make backend support scalable through symbolic names} |
| 616 |
% Emo currently supports three different backends for actually rendering emoji, |
| 617 |
% namely the backend named |\emo@use@unicode| emits Unicode codepoints in a |
| 618 |
% group, the one named |\emo@use@font| emits font selection before those same |
| 619 |
% Unicode codepoints in the group, and the one named |\emo@use@pdf| emits PDF |
| 620 |
% graphics. Once we know to name the backends, we can set |\emo@backend| to the |
| 621 |
% currently active backend, determined by interrogating the runtime environment. |
| 622 |
% Alas, we still need to implement the three backends; but |\emo@content| is |
| 623 |
% defined closer to the end of the package implementation. |
| 624 |
% \begin{macrocode} |
| 625 |
\def\emo@use@unicode{backend:unicode} |
| 626 |
\def\emo@use@font{backend:font+unicode} |
| 627 |
\def\emo@use@pdf{backend:pdf} |
| 628 |
\RequirePackage{iftex} |
| 629 |
\ifdefined\HCode |
| 630 |
\let\emo@backend=\emo@use@unicode |
| 631 |
\else |
| 632 |
\ifluatex |
| 633 |
\let\emo@backend=\emo@use@font |
| 634 |
\else |
| 635 |
\let\emo@backend=\emo@use@pdf |
| 636 |
\fi |
| 637 |
\fi |
| 638 |
% \end{macrocode} |
| 639 |
% \end{macro} |
| 640 |
% \end{macro} |
| 641 |
% \end{macro} |
| 642 |
% \end{macro} |
| 643 |
% |
| 644 |
% With the backend selected, we can now require backend-specific packages, |
| 645 |
% namely |fontspec| for selecting fonts in the |\emo@use@font| backend and |
| 646 |
% |graphicx| for including PDF graphics in the |\emo@use@pdf| backend. The |
| 647 |
% |\emo@use@unicode| backend has no similar requirements. |
| 648 |
% \begin{macrocode} |
| 649 |
\ifx\emo@backend\emo@use@font |
| 650 |
\RequirePackage{fontspec} |
| 651 |
\fi |
| 652 |
\ifx\emo@backend\emo@use@pdf |
| 653 |
\RequirePackage{graphicx} |
| 654 |
\fi |
| 655 |
% \end{macrocode} |
| 656 |
% |
| 657 |
% Next, emo requires |xcolor| for formatting highly visible error messages |
| 658 |
% within the text. Always including another package that is only used when there |
| 659 |
% are errors is not ideal. But when I tried calling |\RequirePackage| for |
| 660 |
% |xcolor| from inside the error macro, it didn't work. Alternatively, I could |
| 661 |
% make in-text errors optional. |
| 662 |
% \begin{macrocode} |
| 663 |
\RequirePackage{xcolor} |
| 664 |
% \end{macrocode} |
| 665 |
% |
| 666 |
% Finally, emo's options also have dependencies, with \textsf{extra} requiring |
| 667 |
% the |xspace| package and \textsf{index} requiring the |index| package: |
| 668 |
% \begin{macrocode} |
| 669 |
\ifemo@extra |
| 670 |
\RequirePackage{xspace} |
| 671 |
\fi |
| 672 |
\ifemo@indexing |
| 673 |
\RequirePackage{index} |
| 674 |
\fi |
| 675 |
% \end{macrocode} |
| 676 |
% |
| 677 |
% |
| 678 |
% ^^A ---------------------------------------------------------------------------------- |
| 679 |
% \subsection{The Emoji Table} |
| 680 |
% |
| 681 |
% \begin{macro}{\emo@emoji@name} |
| 682 |
% \changes{0.3}{}{Include {\tt\textbackslash lingchi} and {\tt\textbackslash YWHW} |
| 683 |
% as necessary} |
| 684 |
% For each emoji with a PDF graphic in the |emo-graphics| directory and, if |
| 685 |
% enabled, the two extra macros, the corresponding |
| 686 |
% |\emo@emoji@|\meta{emoji-name} macro expands to its Unicode sequence. With |
| 687 |
% over 3,000 distinct emoji in Unicode 15, emo relies on a Python script for |
| 688 |
% populating the graphics directory and writing the table to the |
| 689 |
% \texttt{\jobname.def} file. Since the package code does not change after |
| 690 |
% installation but the emoji table may very well change, they are kept separate. |
| 691 |
% Alternatively, we could use DocStrip to assemble the package file from three |
| 692 |
% parts, the code from the previous sections, then the contents of the emoji |
| 693 |
% table in |emo.def|, and then all subsequent code. Alas, that seems a bit much |
| 694 |
% for turning two files into one. |
| 695 |
% \begin{macrocode} |
| 696 |
\input{emo.def} |
| 697 |
% \end{macrocode} |
| 698 |
% \end{macro} |
| 699 |
% |
| 700 |
% |
| 701 |
% ^^A ---------------------------------------------------------------------------------- |
| 702 |
% \subsection{Internal Macros} |
| 703 |
% |
| 704 |
% \begin{macro}{\emo@error@fg} |
| 705 |
% \begin{macro}{\emo@error@bg} |
| 706 |
% \begin{macro}{\emo@error} |
| 707 |
% Define two colors and a function that uses the two colors for formatting an |
| 708 |
% attention-grabbing error message. If you use an invalid emoji name and |
| 709 |
% overlook the warning in the console, you \emph{will} notice the error messsage |
| 710 |
% in the document thusly formatted. |
| 711 |
% \begin{macrocode} |
| 712 |
\definecolor{emo@error@fg}{rgb}{1,1,1} |
| 713 |
\definecolor{emo@error@bg}{rgb}{.6824,.0863,.0863} |
| 714 |
\def\emo@error#1{% |
| 715 |
\colorbox{emo@error@bg}{% |
| 716 |
\textcolor{emo@error@fg}{% |
| 717 |
\textsf{Bad} \texttt{\textbackslash emo\{#1\}}% |
| 718 |
}% |
| 719 |
}% |
| 720 |
} |
| 721 |
% \end{macrocode} |
| 722 |
% \end{macro} |
| 723 |
% \end{macro} |
| 724 |
% \end{macro} |
| 725 |
% |
| 726 |
% \begin{macro}{\emo@ifdef} |
| 727 |
% Validate the emoji name given as first argument. The macro expands to the |
| 728 |
% second argument if the name is valid and an error message otherwise. Its |
| 729 |
% implementation relies on the |emo@emoji| table. |
| 730 |
% \begin{macrocode} |
| 731 |
\def\emo@ifdef#1#2{% |
| 732 |
\ifcsname emo@emoji@#1\endcsname#2\else% |
| 733 |
\PackageWarning{emo}{Unknown emoji name in `\string\emo{#1}'}% |
| 734 |
\emo@error{#1}% |
| 735 |
\fi% |
| 736 |
} |
| 737 |
% \end{macrocode} |
| 738 |
% \end{macro} |
| 739 |
% |
| 740 |
% \begin{macro}{\emo@index} |
| 741 |
% If indexing is enabled, record the use of an emoji. Otherwise, do nothing. |
| 742 |
% \begin{macrocode} |
| 743 |
\ifemo@indexing |
| 744 |
\newindex{emo}{edx}{end}{Emoji Index} |
| 745 |
\def\emo@index#1{\index[emo]{#1}} |
| 746 |
\else |
| 747 |
\def\emo@index#1{} |
| 748 |
\fi |
| 749 |
% \end{macrocode} |
| 750 |
% \end{macro} |
| 751 |
% |
| 752 |
% \begin{macro}{\emo@content} |
| 753 |
% \changes{0.4}{}{Remove extra space from PDF renderer} |
| 754 |
% Render the emoji content. This macro interfaces with the backend and thus |
| 755 |
% needs to be defined as many times as there are backends: The Unicode backend |
| 756 |
% just expands the entry from the emoji table. The font backend does the same, |
| 757 |
% but sets the font to Noto Color Emoji first. The PDF backend instead includes |
| 758 |
% the corresponding PDF graphic. |
| 759 |
% \begin{macrocode} |
| 760 |
\ifx\emo@backend\emo@use@unicode |
| 761 |
\def\emo@content#1{% |
| 762 |
\begingroup\csname emo@emoji@#1\endcsname\endgroup% |
| 763 |
} |
| 764 |
\else |
| 765 |
\ifx\emo@backend\emo@use@font |
| 766 |
\newfontface\emo@font[Renderer=Harfbuzz]{NotoColorEmoji.ttf} |
| 767 |
\def\emo@content#1{% |
| 768 |
\begingroup\emo@font\csname emo@emoji@#1\endcsname\endgroup% |
| 769 |
} |
| 770 |
\else |
| 771 |
\def\emo@content#1{% |
| 772 |
\raisebox{-0.2ex}{% |
| 773 |
\includegraphics[height=1em]{emo-graphics/emo-#1}}% |
| 774 |
} |
| 775 |
\fi |
| 776 |
\fi |
| 777 |
% \end{macrocode} |
| 778 |
% |
| 779 |
% In debug mode, emo draws a box around the content of |\emo|. That may help |
| 780 |
% when tracking down spurious whitespace. |
| 781 |
% \begin{macrocode} |
| 782 |
\ifemo@debug |
| 783 |
\let\emo@realcontent=\emo@content |
| 784 |
\def\emo@content#1{\fbox{\emo@realcontent{#1}}} |
| 785 |
\fi |
| 786 |
% \end{macrocode} |
| 787 |
% \end{macro} |
| 788 |
% |
| 789 |
% |
| 790 |
% ^^A ---------------------------------------------------------------------------------- |
| 791 |
% \subsection{User Macros} |
| 792 |
% |
| 793 |
% \begin{macro}{\emo} |
| 794 |
% Thanks to carefully defined internal macros, the implementation of the main |
| 795 |
% |\emo| macro is almost trivial. If the emoji name passes muster, emit an index |
| 796 |
% entry and render the emoji content: |
| 797 |
% \begin{macrocode} |
| 798 |
\newcommand\emo[1]{% |
| 799 |
\emo@ifdef{#1}{% |
| 800 |
\emo@index{#1}% |
| 801 |
\emo@content{#1}% |
| 802 |
}% |
| 803 |
} |
| 804 |
% \end{macrocode} |
| 805 |
% \end{macro} |
| 806 |
% |
| 807 |
% \begin{macro}{\lingchi} |
| 808 |
% \changes{0.3}{}{Build on {\tt\textbackslash emo} by default} |
| 809 |
% \begin{macro}{\YHWH} |
| 810 |
% \changes{0.3}{}{Build on {\tt\textbackslash emo} by default} |
| 811 |
% |
| 812 |
% Since the emoji table in |emo.def| includes macros with the Unicode codepoints |
| 813 |
% for ``lingchi'' and ``YHWH,'' the implementation of |\lingchi| and |\YHWH| |
| 814 |
% just delegates to |\emo|. |
| 815 |
% \begin{macrocode} |
| 816 |
\ifemo@extra |
| 817 |
\ifx\emo@backend\emo@use@font\else |
| 818 |
\newcommand\lingchi{\emo{lingchi}\xspace} |
| 819 |
\newcommand\YHWH{\emo{YHWH}\xspace} |
| 820 |
\fi |
| 821 |
% \end{macrocode} |
| 822 |
% |
| 823 |
% Except, as hinted at by the backend test, delegating to |\emo| won't work when |
| 824 |
% using fonts, since |\emo| uses Noto color emoji whereas the two extra macros |
| 825 |
% do not. In that case, we define alternative versions that, similar to |\emo| |
| 826 |
% rely on their own specialized |\emo@content| macros and also wrap them when |
| 827 |
% the \textsf{debug} package option is enabled. |
| 828 |
% \begin{macrocode} |
| 829 |
\ifx\emo@backend\emo@use@font |
| 830 |
\newfontface\emo@chinese{emo-lingchi.ttf} |
| 831 |
\newfontface\emo@hebrew{LinLibertine_R.otf} |
| 832 |
\def\emo@lingchi@content{\begingroup\emo@chinese\emo@emoji@lingchi\endgroup} |
| 833 |
\def\emo@YHWH@content{\begingroup\emo@hebrew\emo@emoji@YHWH\endgroup} |
| 834 |
|
| 835 |
\ifemo@debug |
| 836 |
\let\emo@lingchi@realcontent=\emo@lingchi@content |
| 837 |
\let\emo@YHWH@content=\emo@YHWH@content |
| 838 |
\def\emo@lingchi@content{\fbox{\emo@lingchi@realcontent}} |
| 839 |
\def\emo@YHWH@content{\fbox{\emo@YHWH@realcontent}} |
| 840 |
\fi |
| 841 |
|
| 842 |
\newcommand\lingchi{\emo@index{lingchi}\emo@lingchi@content\xspace} |
| 843 |
\newcommand\YHWH{\emo@index{YHWH}\emo@YHWH@content\xspace} |
| 844 |
\fi |
| 845 |
\fi |
| 846 |
% \end{macrocode} |
| 847 |
% \end{macro} |
| 848 |
% \end{macro} |
| 849 |
% |
| 850 |
% Et voil\`a. That's it! |
| 851 |
% |
| 852 |
% \begin{macrocode} |
| 853 |
%</package> |
| 854 |
% \end{macrocode} |
| 855 |
% |
| 856 |
% |
| 857 |
% ^^A ================================================================================== |
| 858 |
% \section{LaTeXML Binding} |
| 859 |
% \changes{0.2}{}{Add LaTeXML binding for conversion to HTML} |
| 860 |
% |
| 861 |
% ^^A Reset line number counter |
| 862 |
% \makeatletter |
| 863 |
% \c@CodelineNo 0 |
| 864 |
% \makeatother |
| 865 |
% |
| 866 |
% To support conversion from LaTeX to HTML, emo includes a so-called binding for |
| 867 |
% \href{https://github.com/brucemiller/LaTeXML}{LaTeXML}. It effectively is a |
| 868 |
% (much simplified) re-implementation of emo's core functionality, only written |
| 869 |
% in Perl against LaTeXML's API. The binding ignores the \textsf{index} option |
| 870 |
% and does not perform error checking on emoji names. If either is important to |
| 871 |
% you, please compile the document with LaTeX first. Furthermore, the binding |
| 872 |
% emits necessary Unicode codepoints only, without font annotations. If you want |
| 873 |
% to specify fonts, please use a CSS fontstack. |
| 874 |
% |
| 875 |
% Asking package authors to reimplement their packages for LaTeXML seems |
| 876 |
% unreasonable to me. It leads to code duplication and places the maintenance |
| 877 |
% burden on package authors. Yet, right after announcing emo, the question of |
| 878 |
% LaTeXML support came up. LaTeXML includes the |latexml.sty| package, which |
| 879 |
% defines |\iflatexml|. I would have used that command to make the three-line |
| 880 |
% change to |emo.sty| necessary to support LaTeXML, except |latexml.sty| |
| 881 |
% contains lots of other stuff that isn't needed. Always loading lots of macros |
| 882 |
% only to detect LaTeXML slows down compilation and wastes memory. Since |
| 883 |
% reimplementing |\iflatexml| would require a binding anyways, I just wrote a |
| 884 |
% minimal binding. As I said, LaTeXML's approach is broken. |
| 885 |
% |
| 886 |
% With that out of the way, let's get started: |
| 887 |
% \begin{macrocode} |
| 888 |
%<*latexml-binding> |
| 889 |
% \end{macrocode} |
| 890 |
% |
| 891 |
% The binding starts with an explicit preamble because |docstrip| does not |
| 892 |
% alllow for a redefinition of the starting characters of a line comment. It is |
| 893 |
% followed by the Perl dependencies. |
| 894 |
% \begin{macrocode} |
| 895 |
## emo's LaTeXML binding. |
| 896 |
## (C) 2023 by Robert Grimm. |
| 897 |
## Released under LPPL v1.3c or later. |
| 898 |
use strict; |
| 899 |
use warnings; |
| 900 |
use LaTeXML::Package; |
| 901 |
% \end{macrocode} |
| 902 |
% |
| 903 |
% \begin{macro}{\ifemo@extra} |
| 904 |
% Next, we use raw TeX to declare the LaTeX package and define the |emo@extra| |
| 905 |
% conditional. There is no need to define the |emo@indexing| conditional, since |
| 906 |
% it corresponds to the unsupported \textsf{index} option. |
| 907 |
% \begin{macrocode} |
| 908 |
RawTeX(<<'EOTeX'); |
| 909 |
\ProvidesPackage{emo} |
| 910 |
[2023/04/26 v0.4 emo•ji for all (LaTeX engines)] |
| 911 |
\newif\ifemo@extra\emo@extrafalse |
| 912 |
EOTeX |
| 913 |
% \end{macrocode} |
| 914 |
% \end{macro} |
| 915 |
% |
| 916 |
% Option prcessing is almost trivial: |
| 917 |
% \begin{macrocode} |
| 918 |
DeclareOption('extra', '\emo@extratrue'); |
| 919 |
DeclareOption('index', ''); |
| 920 |
DeclareOption('debug', ''); |
| 921 |
ProcessOptions(); |
| 922 |
% \end{macrocode} |
| 923 |
% |
| 924 |
% \begin{macro}{\emo@emoji@name} |
| 925 |
% \begin{macro}{\emo} |
| 926 |
% Just like the actual package implementation, the LaTeXML binding reads the |
| 927 |
% emoji table from |emo.def|. Similar to the actual implementation of the |\emo| |
| 928 |
% macro when running under LuaLaTeX, the binding expands the named entry from |
| 929 |
% the emoji table, producing the emoji's Unicode codepoints. |
| 930 |
% \begin{macrocode} |
| 931 |
InputDefinitions('emo', type => 'def', noltxml => 1); |
| 932 |
DefMacro('\emo{}', '\csname emo@emoji@#1\endcsname'); |
| 933 |
% \end{macrocode} |
| 934 |
% \end{macro} |
| 935 |
% \end{macro} |
| 936 |
% |
| 937 |
% \begin{macro}{\lingchi} |
| 938 |
% \begin{macro}{\YHWH} |
| 939 |
% If the |emo@extra| conditional is enabled, require the |xspace| package and then |
| 940 |
% provide minimal re-definitions of the |\lingchi| and |\YHWH| macros. Both simply |
| 941 |
% expand to the necessary Unicode codepoints. |
| 942 |
% \begin{macrocode} |
| 943 |
if (IfCondition(T_CS('\ifemo@extra'))) { |
| 944 |
RequirePackage('xspace'); |
| 945 |
DefMacro('\lingchi', "\x{51cc}\x{9072}\\xspace"); |
| 946 |
DefMacro('\YHWH', "\x{05D9}\x{05D4}\x{05D5}\x{05D4}\\xspace"); |
| 947 |
} |
| 948 |
% \end{macrocode} |
| 949 |
% \end{macro} |
| 950 |
% \end{macro} |
| 951 |
% |
| 952 |
% That's it for the binding, too. |
| 953 |
% \begin{macrocode} |
| 954 |
%</latexml-binding> |
| 955 |
% \end{macrocode} |
| 956 |
% |
| 957 |
% |
| 958 |
% ^^A ================================================================================== |
| 959 |
% \section{Emo's Test Document} |
| 960 |
% \changes{0.4}{}{Introduce a simple unit testing framework} |
| 961 |
% |
| 962 |
% ^^A Reset line number counter |
| 963 |
% \makeatletter |
| 964 |
% \c@CodelineNo 0 |
| 965 |
% \makeatother |
| 966 |
% |
| 967 |
% As emo's tagline so loudly pronounces, the package is intended to enable emoji |
| 968 |
% across all major LaTeX engines. This document provides the basis for testing |
| 969 |
% that this is indeed the case. It results in a concise card, or ``canary,'' |
| 970 |
% that (1) identifies the engine, (2) lists the macro names |\emo|, |\lingchi|, |
| 971 |
% and |\YHWH| adorned with \emo{check-mark-button} or \emo{cross-mark} to |
| 972 |
% indicate whether the macro produced output of the expected width, and (3) |
| 973 |
% shows the same line of text using the three macros, with visible bounding |
| 974 |
% boxes for line and words as well as line only. |
| 975 |
% |
| 976 |
% |
| 977 |
% \subsection{Test Preamble} |
| 978 |
% |
| 979 |
% As usual, we start the test document by declaring its class and requiring |
| 980 |
% necessary packages. Notably, |standalone| and |varwidth| help generate a PDF |
| 981 |
% card that is sized to the test output. |iftex| is necessary for dynamically |
| 982 |
% detecting the LaTeX engine, and |emo| is about to be tested. The rest are |
| 983 |
% mostly indulgences for appearance. We also wrap the entire test document in an |
| 984 |
% |\iffalse| |\fi| block so that it doesn't interfere with documentation |
| 985 |
% generation. |
| 986 |
% \begin{macrocode} |
| 987 |
%<*scaffold> |
| 988 |
\iffalse |
| 989 |
%</scaffold> |
| 990 |
%<*canary> |
| 991 |
\documentclass[border=10pt]{standalone} |
| 992 |
\usepackage[extra]{emo} |
| 993 |
\usepackage{iftex} |
| 994 |
\usepackage{xcolor} |
| 995 |
\usepackage{varwidth} |
| 996 |
|
| 997 |
\iftutex |
| 998 |
\usepackage{fontspec} |
| 999 |
\usepackage{libertinus} |
| 1000 |
\setmonofont{inconsolata} |
| 1001 |
\else |
| 1002 |
\usepackage{libertinus} |
| 1003 |
\usepackage{inconsolata} |
| 1004 |
\fi |
| 1005 |
% \end{macrocode} |
| 1006 |
% |
| 1007 |
% \begin{macro}{\enginename} |
| 1008 |
% I couldn't find an existing macro that provides the engine name. Hence, we |
| 1009 |
% gotta round up the usual suspects: |
| 1010 |
% \begin{macrocode} |
| 1011 |
\ifxetex |
| 1012 |
\def\enginename{XeTeX} |
| 1013 |
\else |
| 1014 |
\ifluatex |
| 1015 |
\def\enginename{LuaTeX} |
| 1016 |
\else |
| 1017 |
\ifpdftex |
| 1018 |
\def\enginename{pdfTeX} |
| 1019 |
\else |
| 1020 |
\def\enginename{unknown engine} |
| 1021 |
\fi |
| 1022 |
\fi |
| 1023 |
\fi |
| 1024 |
% \end{macrocode} |
| 1025 |
% \end{macro} |
| 1026 |
% |
| 1027 |
% \begin{macro}{\nobx} |
| 1028 |
% \begin{macro}{\wbx} |
| 1029 |
% \begin{macro}{\lbx} |
| 1030 |
% To display text with bounding boxes, we define some (very neutral) colors and |
| 1031 |
% boxes. In particular, |\nobx| and |\wbx|, respectively, do not or do draw a |
| 1032 |
% box around a word or emoji. |\lbx| draws a box around the line of text. |
| 1033 |
% \begin{macrocode} |
| 1034 |
\definecolor{wordboxframe}{HTML}{636366} |
| 1035 |
\definecolor{lineboxframe}{HTML}{48484A} |
| 1036 |
\definecolor{lineboxbg}{HTML}{E5E5EA} |
| 1037 |
|
| 1038 |
\setlength{\fboxrule}{0.5pt} |
| 1039 |
\setlength{\fboxsep}{0pt} |
| 1040 |
|
| 1041 |
\newcommand\nobx[1]{#1} |
| 1042 |
\newcommand\wbx[1]{\fcolorbox{wordboxframe}{white}{#1}} |
| 1043 |
\newcommand\lbx[1]{\fcolorbox{lineboxframe}{lineboxbg}{#1}} |
| 1044 |
% \end{macrocode} |
| 1045 |
% \end{macro} |
| 1046 |
% \end{macro} |
| 1047 |
% \end{macro} |
| 1048 |
% |
| 1049 |
% \begin{macro}{\boundedtext} |
| 1050 |
% Drawing bounding boxes around ``building blocks,'' i.e., emoji and words |
| 1051 |
% appearing in a line of text, can help identify buggy font metrics, spurious |
| 1052 |
% spaces, and so on. But it also is an awfully cluttered presentation. Hence we |
| 1053 |
% display the same line a second time, this time without the word-level boxes. |
| 1054 |
% That seems like a good use case for LaTeX's star-form of a command. |
| 1055 |
% \begin{macrocode} |
| 1056 |
\makeatletter |
| 1057 |
\def\@boundedtext#1{% |
| 1058 |
\lbx{% |
| 1059 |
#1{It's} #1{\lingchi}: |
| 1060 |
#1{Please}, #1{\YHWH}, #1{have} #1{mercy} |
| 1061 |
#1{\emo{pleading-face}}!% |
| 1062 |
}% |
| 1063 |
} |
| 1064 |
\newcommand*\boundedtext{% |
| 1065 |
\@ifstar{\@boundedtext{\wbx}}{\@boundedtext{\nobx}}% |
| 1066 |
} |
| 1067 |
\makeatother |
| 1068 |
% \end{macrocode} |
| 1069 |
% \end{macro} |
| 1070 |
% |
| 1071 |
% \begin{macro}{\checkwidth} |
| 1072 |
% Validating the output of emo's macros turned out to be a bit trickier than I |
| 1073 |
% had expected. The obvious approach, expanding macros to primitives and then |
| 1074 |
% comparing to expected results, simply doesn't work---even though LaTeX does |
| 1075 |
% have builtin support for eager expansion via, for example, |\expandafter| and |
| 1076 |
% |\edef|. The reason is that unlike C, where the preprocessor runs strictly |
| 1077 |
% before the rest of the compiler, macro expansion in TeX and LaTeX is |
| 1078 |
% ubiquitous, delayed, repeated, interleaved, and so on. |
| 1079 |
% |
| 1080 |
% ^^A https://tex.stackexchange.com/questions/67192/using-qstest-to-implement-unit-tests |
| 1081 |
% |
| 1082 |
% Instead, we need to take a sneakier approach: Generate a box with the macro |
| 1083 |
% application and another box with the expected result and then compare the |
| 1084 |
% widths of the two boxes. While that cannot detect all bugs, it can detect one |
| 1085 |
% critical class of bugs: spurious whitespace! Alas, there is an additional |
| 1086 |
% complication: |\lingchi| and |\YHWH| use |xspace| to avoid ugly trailing |
| 1087 |
% backslash characters. But that also makes their results context-sensitive, |
| 1088 |
% which might become a problem in a unit test without context. It is for just |
| 1089 |
% that reason that the text arguments to |\sbox\actual| or |\sbox\expected| |
| 1090 |
% below end with a period. |
| 1091 |
% |
| 1092 |
% Even though |\checkwidth| only tests three macros and two of them take no |
| 1093 |
% arguments, it still requires five arguments to cover all variability: |
| 1094 |
% \begin{enumerate} |
| 1095 |
% \item name of macro being tested; |
| 1096 |
% \item macro invocation being tested; |
| 1097 |
% \item name of font variable used in LuaLaTeX's output; |
| 1098 |
% \item Unicode code sequence in LuaLaTeX's output; |
| 1099 |
% \item file name for fallback PDF graphic without ``|emo-|'' prefix. |
| 1100 |
% \end{enumerate} |
| 1101 |
% The third and fourth arguments are separate because the font variable only |
| 1102 |
% exists when running under LuaLaTeX. |
| 1103 |
% \begin{macrocode} |
| 1104 |
\newsavebox{\actual} |
| 1105 |
\newsavebox{\expected} |
| 1106 |
|
| 1107 |
\newcommand\checkwidth[5]{% |
| 1108 |
\sbox\actual{#2.}% |
| 1109 |
\ifluatex% |
| 1110 |
\sbox\expected{% |
| 1111 |
\begingroup\csname#3\endcsname #4\endgroup.}% |
| 1112 |
\else% |
| 1113 |
\sbox\expected{% |
| 1114 |
\raisebox{-0.2ex}{% |
| 1115 |
\includegraphics[height=1em]{emo-graphics/emo-#5}}.}% |
| 1116 |
\fi% |
| 1117 |
\def\macroname{\texttt{\char`\\#1}}% |
| 1118 |
\ifdim\wd\actual=\wd\expected% |
| 1119 |
\mbox{\macroname{} \emo{check-mark-button}}% |
| 1120 |
\else% |
| 1121 |
\edef\actualwidth{\the\wd\actual}% |
| 1122 |
\edef\expectedwidth{\the\wd\expected}% |
| 1123 |
\mbox{\macroname{} \emo{cross-mark} \actualwidth{} \expectedwidth}% |
| 1124 |
\fi% |
| 1125 |
} |
| 1126 |
% \end{macrocode} |
| 1127 |
% \end{macro} |
| 1128 |
% |
| 1129 |
% |
| 1130 |
% \subsection{Test Body} |
| 1131 |
% |
| 1132 |
% All test macros have been defined and we can finally get to actually testing |
| 1133 |
% emo. We put all output in a |varwidth| environment to ensure that the PDF is |
| 1134 |
% content-sized. Since the output includes text with bounding boxes, we use a |
| 1135 |
% really large font size. |
| 1136 |
% \begin{macrocode} |
| 1137 |
\begin{document} |
| 1138 |
\begin{varwidth}{6in} |
| 1139 |
\Huge |
| 1140 |
|
| 1141 |
% \end{macrocode} |
| 1142 |
% |
| 1143 |
% At the top of the card are the engine name and the width tests, one for each |
| 1144 |
% macro. |
| 1145 |
% \begin{macrocode} |
| 1146 |
\noindent\enginename: |
| 1147 |
\Large Width of |
| 1148 |
\checkwidth{emo}{\emo{robot}}{emo@font}{\char"1F916}{robot}, |
| 1149 |
\checkwidth{lingchi}{\lingchi}{emo@chinese}{\char"51CC\char"9072}{lingchi}, |
| 1150 |
\checkwidth{YHWH}{\YHWH}{emo@hebrew}{\char"5D9\char"5D4\char"5D5\char"5D4}{YHWH} |
| 1151 |
\vspace{1ex}\Huge |
| 1152 |
|
| 1153 |
% \end{macrocode} |
| 1154 |
% |
| 1155 |
% At the bottom of the card are the two lines of text with bounding boxes, |
| 1156 |
% \emph{with} word-level boxes and then without. |
| 1157 |
% \begin{macrocode} |
| 1158 |
\boundedtext*{} |
| 1159 |
\vspace{1ex}\newline |
| 1160 |
\boundedtext{} |
| 1161 |
|
| 1162 |
% \end{macrocode} |
| 1163 |
% |
| 1164 |
% That's it as far as tests are concerned. Clearly, writing the test macros was |
| 1165 |
% more involved than using them. That effort also is the reason I decided to |
| 1166 |
% include the annotated test document in |emo.dtx|. All that's left at this |
| 1167 |
% point is wrapping up the test document, wrapping up the enclosing conditional, |
| 1168 |
% and wrapping up emo's documentation. It's a wrap \emo{zany-face} |
| 1169 |
% \begin{macrocode} |
| 1170 |
\end{varwidth} |
| 1171 |
\end{document} |
| 1172 |
%</canary> |
| 1173 |
%<*scaffold> |
| 1174 |
\fi |
| 1175 |
%</scaffold> |
| 1176 |
% \end{macrocode} |
| 1177 |
% |
| 1178 |
% |
| 1179 |
% \Finale |