Debian Codegraph @

texmf-dist/source/latex/emo/emo.dtx

raw
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