diff options
Diffstat (limited to 'graphics/emo/emo.dtx')
-rw-r--r-- | graphics/emo/emo.dtx | 717 |
1 files changed, 717 insertions, 0 deletions
diff --git a/graphics/emo/emo.dtx b/graphics/emo/emo.dtx new file mode 100644 index 0000000000..05fa1b155f --- /dev/null +++ b/graphics/emo/emo.dtx @@ -0,0 +1,717 @@ +% \iffalse meta-comment +% +% emo: emoji for all (LaTeX engines) +% (C) Copyright 2023 by Robert Grimm +% Released under LPPL v1.3c or later +% <https://github.com/apparebit/emo> +% +% \fi +% ^^A ---------------------------------------------------------------------------------- +% \iffalse +% The option with date and version below applies to both \Provides<Something> +% declarations; see https://tug.org/TUGboat/tb29-2/tb92pakin.pdf. +%<*scaffold> +\ProvidesFile{emo.dtx} +%</scaffold> +%<package>\NeedsTeXFormat{LaTeX2e} +%<package>\ProvidesPackage{emo} +%<*package> + [2023/03/20 v0.1 emoji for all] +%</package> +% ====================================================================================== +%<*scaffold> +\iffalse +%</scaffold> +%<*readme> +# Emo: emoji for all (LaTeX engines) + +This package defines the `\emo{<emoji-name>}` macro for including color emoji in +a document no matter the input encoding or LaTeX engine. It uses the Noto color +emoji font if the engine supports doing so and falls back onto PDF graphics +otherwise. I wrote this package to use emoji in an academic paper subject to +[The ACM Publishing +System](https://authors.acm.org/proceedings/production-information/accepted-latex-packages), +which prohibits the use of most LaTeX packages but has only minimal support for +non-Latin scripts. ๐ + +When emo is used with the `extra` option, this package also defines the +`\lingchi` and `\YHWH` macros for ๅ้ฒ and ืืืื, respectively. Both macros +preserve a subsequent space as space, no backslash needed. When used with the +`index` option, this package also emits a raw index entry for each use of an +emoji into an emo index or `.edx` file. + +To **extract files** embedded in [emo.dtx](emo.dtx) and also rebuild the +[documentation](emo.pdf), run `pdflatex emo.dtx`. + +To **configure the emoji**, run `python3 config/emo.py` with appropriate +arguments. The [package documentation](emo.pdf) explains the configuration tool +in detail, but you may find the `-h` for help option sufficient to get started. + +To **install this package**, place `emo.def`, `emo.sty`, `lingchi.otf`, and the +contents of the `emo-graphics` directory somewhere where LaTeX can find them. In +a pinch, your project directory will do just fine. + + +## Supported Emoji + +By default, emo supports only a few emoji: + +1๏ธโฃ โฃ๏ธ โ๏ธ โ๏ธ ๐ช๐บ ๐ ๐ ๐๏ธ ๐๏ธ ๐๏ธ ๐ณ๏ธโ๐ ๐ท๏ธ ๐๏ธ ๐ฅ ๐ฑ ๐พ ๐ ๐ ๐ ๐ต๏ธ ๐๏ธ ๐ก ๐ ๐ค ๐ค ๐ฆ ๐งโโ๏ธ ๐งป ๐งพ + +Their names are keycap-one, biohazard, balance-scale, check-mark, eu, foggy, +globe-africa-europe, classical-building, desert-island, stadium, rainbow-flag, +label, eye, busts, currency-exchange, floppy-disk, triangular-ruler, pager, +loupe-left, detective, wastebasket, enraged-face, stop-sign, robot, handshake, +parrot, judge, roll-of-paper, and receipt. + +The [package's documentation](emo.pdf) explains the underlying naming scheme and +also how to reconfigure which emoji are supported. The [emo.py](config/emo.py) +script takes care of the heavy lifting during reconfiguration, converting SVG +into PDF files and generating an updated `emo.def` file. + + +## Copyright and Licensing + +This package combines code written in LaTeX and Python with Unicode data about +emoji as well as graphics and fonts derived from Google's Noto fonts. As a +result, a number of different licenses apply, all of which are [OSI +approved](https://opensource.org/licenses/) and non-copyleft: + + * This package's [LaTeX code](emo.dtx) is ยฉ Copyright 2023 by Robert Grimm and + has been released under the [LPPL + v1.3c](https://www.latex-project.org/lppl/lppl-1-3c/) or later. + * The [emo.py](config/emo.py) configuration script also is ยฉ Copyright 2023 by + Robert Grimm but has been released under the [Apache 2.0 + license](https://www.apache.org/licenses/LICENSE-2.0). + * The [emoji-test.txt](config/emoji-test.txt) configuration file is a data + file from [Unicode TR-51](https://unicode.org/reports/tr51/) and hence + subject to the [Unicode License](https://www.unicode.org/license.txt). + * The `lingchi.otf` font is a two-glyph subset of the serif traditional + Chinese version of Google's [Noto + fonts](https://github.com/notofonts/noto-cjk) and hence subject to the [SIL + Open Font License v1.1](https://scripts.sil.org/ofl). + * The PDF graphics in the `emo-graphics` directory are derived from the + sources for [Noto's color emoji](https://github.com/googlefonts/noto-emoji) + and hence subject to the Apache 2.0 license. + +%</readme> +% -------------------------------------------------------------------------------------- +%<*buildscript> +pdflatex emo.dtx +makeindex -s gind.ist -o emo.ind emo.idx +# makeindex -s gglo.ist -o emo.gls emo.glo # For tracking changes +pdflatex emo.dtx +%</buildscript> +%<*scaffold> +\fi +% ====================================================================================== +\begingroup +%</scaffold> +%<*install> +\input docstrip.tex +\keepsilent +\askforoverwritefalse +\preamble + +emo: emoji for all (LaTeX engines) +(C) Copyright 2023 by Robert Grimm +Released under LPPL v1.3c or later +<https://github.com/apparebit/emo> + +\endpreamble +\usedir{tex/latex/emo} +\generate{\file{\jobname.sty}{\from{\jobname.dtx}{package}}} +%</install> +% Don't stop processing the .dtx file; only stop processing the install file. +%<install>\endbatchfile +% -------------------------------------------------------------------------------------- +%<*scaffold> +\usedir{source/latex/emo} +\generate{\file{\jobname.ins}{\from{\jobname.dtx}{install}}} +\nopreamble\nopostamble +\usedir{source/latex/emo} +\generate{\file{build.sh}{\from{\jobname.dtx}{buildscript}}} +\usedir{doc/latex/emo} +\generate{\file{README.md}{\from{\jobname.dtx}{readme}}} +\endgroup +%</scaffold> +% ====================================================================================== +%<*driver> +\PassOptionsToPackage{utf8}{inputenc} +\documentclass{ltxdoc} +% Override the default \small, which looks odd with Inconsolata. +\renewcommand{\MacroFont}{\normalsize\ttfamily} +\usepackage[extra]{\jobname} +\usepackage{enumitem} +\usepackage{parskip} +\usepackage{inconsolata} + +% Use BlackFoundry's Inria fonts; see <https://tug.org/FontCatalogue/inriaserifregular/> +\usepackage[T1]{fontenc} +\usepackage[lining]{InriaSerif} +\renewcommand*\oldstylenums[1]{{\fontfamily{InriaSerif-OsF}\selectfont #1}} +\let\oldnormalfont\normalfont +\def\normalfont{\oldnormalfont\mdseries} + +\usepackage{hyperref} +\EnableCrossrefs +\CodelineIndex +\RecordChanges +\begin{document} + \DocInput{\jobname.dtx} +\end{document} +%</driver> +% \fi +% +% \newlist{inlinenum}{enumerate*}{1} +% \setlist[inlinenum]{label=(\alph{inlinenumi})} +% \newenvironment{verbaish}{% +% \ttfamily% +% \obeylines% +% \obeyspaces% +% \vspace{\the\parskip}% +% \setlength{\parskip}{0pt}% +% \setlength{\parindent}{2em}% +% }{} +% +% \GetFileInfo{\jobname.dtx} +% +% \DoNotIndex{\{,\}} +% \DoNotIndex{\begingroup,\char,\csname,\def} +% \DoNotIndex{\else,\endcsname,\endgroup,\expandafter} +% \DoNotIndex{\fi,\ifcsname,\ifluatex,\index} +% \DoNotIndex{\newcommand,\newif,\newindex} +% \DoNotIndex{\relax,\string,\textbackslash,\textsf,\texttt} +% +% \title{emo: emoji for all\\(LaTeX engines)} +% \author{\href{https://apparebit.com}{Robert Grimm}} +% \date{Version \fileversion\ (\filedate)} +% +% \maketitle +% +% \begin{abstract} +% \noindent{}Emo implements the |\emo|\marg{emoji-name} command for including +% color emoji such as \emo{desert-island} or \emo{parrot} in your documents +% independent of input encoding or LaTeX engine. The implementation uses the +% Noto color emoji font if the engine supports it and includes PDF graphics +% otherwise. The latter are automatically derived from Noto's SVG sources, so +% the visual appearance is very similar. The source repository is at +% \url{https://github.com/apparebit/emo}. Emo may come in particularly handy +% when dealing with academic publishers that provide only minimal support for +% non-Latin scripts (cough, +% \href{https://authors.acm.org/proceedings/production-information/accepted-latex-packages}{ACM}, +% cough). +% \end{abstract} +% +% \tableofcontents +% +% +% ^^A ================================================================================== +% \section{Installation} +% +% Installation of the emo package is fairly straightforward, though it does +% involve a lot more files than usual. +% +% \begin{enumerate} +% \item Start by extracting this package's files from |emo.dtx| by running: +% \begin{verbaish} +% \$ pdflatex emo.dtx +% \end{verbaish} +% +% \item Build the package documentation with indices by running: +% \begin{verbaish} +% \$ source build.sh +% \end{verbaish} +% +% \item If you want to reconfigure the supported emoji, see \S\ref{sec:config} +% below. +% +% \item Put the following files somewhere LaTeX can find them. While your current +% project's directory will do, emo's installation potentially comprises +% thousands of files. Hence it may be preferrable to adhere to the +% \href{https://en.wikibooks.org/wiki/LaTeX/Installing_Extra_Packages}{TeX +% Directory Structure}, with dedicated directories for the following files: +% \begin{enumerate} +% \item |emo.sty| with the package implementation; +% \item |emo.def| with the emoji table; +% \item |lingchi.otf| for |\lingchi|; +% \item \emph{all} PDF files in the |emo-graphics| directory. +% \end{enumerate} +% \end{enumerate} +% +% When running on the LuaLaTeX engine, the emo package also uses the Noto color +% emoji (|NotoColorEmoji.ttf|) and Linux Libertine (|LinLibertine_R.otf|) fonts, +% with the latter used for rendering |\YHWH| only. Neither file is included with +% emo's distribution, since both of them are distributed with major TeX +% distributions already. If they are not included with your LaTeX distribution, +% you can find them on CTAN. The |lingchi.otf| font distributed with emo is a +% two glyph subset of |NotoSerifTC-Regular.otf|, i.e., the serif traditional +% Chinese version of Noto. +% +% +% ^^A ================================================================================== +% \section{Usage} +% +% As usual, you declare your document's dependency on emo with +% |\usepackage{emo}|. In addition to the unadorned form, emo takes up to two +% options: +% \begin{description} +% \item[extra] Also define the |\lingchi| and |\YHWH| macros, which produce +% \lingchi and \YHWH, respectively, and are documented below. +% \item[index] Create an emoji index tagged |emo| with the |.edx| extension for +% the raw index and the |.end| extension for the processed index. This +% option relies on the |index| package, generates the raw |.edx| file, +% but does not build or use the processed index. +% \end{description} +% +% \DescribeMacro{\emo} +% An |\emo|\marg{emoji-name} invocation expands to the named emoji. For +% LuaLaTeX, it uses the Noto color emoji font. For all other engines, it uses +% PDF graphics. That way, |\emo{desert-island}| results in~\emo{desert-island} +% and |\emo{parrot}| results in~\emo{parrot}. +% +% Since LaTeX tends to produce a lot of command line noise about underfull boxes +% and loaded fonts, it's a easy to miss meaningful warnings. For that reason, +% |\emo| expands to an attention-seeking error message upon undefined emoji +% names. For example, |\emo{boo}| produces \emo{boo}. +% +% +% ^^A ---------------------------------------------------------------------------------- +% \subsection{Emoji Names} +% +% With some exceptions, emo's names for emoji are automatically derived from +% their Unicode names, with letters converted to lowercase, punctuation such as +% commas, colons, quotes, and parentheses stripped, and interword spaces +% replaced by dashes. Furthermore, instead of the rather verbose +% |dark-skin-tone|, |medium-dark-skin-tone|, etc modifiers, emo +% uses the more succinct |darkest|, |darker|, |medium|, |lighter|, and +% |lightest|. +% +% For some emoji names, emo goes further by hard-coding shorter names. Those +% names are listed in Table~\ref{tab:special-names}. +% +% \begin{table} +% \caption{Exceptional emoji names} +% \label{tab:special-names} +% \small\vspace{1em} +% \begin{tabular}{ll} +% \textbf{Transformed Unicode Name} & \textbf{Emo Replacement Name} \\ \hline +% |a-button-blood-type| & |a-button| \\ +% |ab-button-blood-type| & |ab-button| \\ +% |b-button-blood-type| & |b-button| \\ +% |o-button-blood-type| & |o-button| \\ +% |bust-in-silhouette| & |bust| \\ +% |busts-in-silhouette| & |busts| \\ +% |flag-european-union| & |eu| \\ +% |globe-showing-americas| & |globe-americas| \\ +% |globe-showing-asia-australia| & |globe-asia-australia| \\ +% |globe-showing-europe-africa| & |globe-africa-europe| \\ +% |hear-no-evil-monkey| & |hear-no-evil| \\ +% |index-pointing-at-the-viewer| & |index-pointing-at-viewer| \\ +% |index-pointing-at-the-viewer-darkest| & |index-pointing-at-viewer-darkest| \\ +% |index-pointing-at-the-viewer-darker| & |index-pointing-at-viewer-darker| \\ +% |index-pointing-at-the-viewer-medium| & |index-pointing-at-viewer-medium| \\ +% |index-pointing-at-the-viewer-lighter| & |index-pointing-at-viewer-lighter| \\ +% |index-pointing-at-the-viewer-lightest| & |index-pointing-at-viewer-lightest| \\ +% |keycap-*| & |keycap-star| \\ +% |keycap-#| & |keycap-hash| \\ +% |keycap-0| & |keycap-zero| \\ +% |keycap-1| & |keycap-one| \\ +% |keycap-2| & |keycap-two| \\ +% |keycap-3| & |keycap-three| \\ +% |keycap-4| & |keycap-four| \\ +% |keycap-5| & |keycap-five| \\ +% |keycap-6| & |keycap-six| \\ +% |keycap-7| & |keycap-seven| \\ +% |keycap-8| & |keycap-eight| \\ +% |keycap-9| & |keycap-nine| \\ +% |keycap-10| & |keycap-ten| \\ +% |magnifying-glass-tilted-left| & |loupe-left| \\ +% |magnifying-glass-tilted-right| & |loupe-right| \\ +% |palm-down-hand| & |palm-down| \\ +% |palm-down-hand-darkest| & |palm-down-darkest| \\ +% |palm-down-hand-darker| & |palm-down-darker| \\ +% |palm-down-hand-medium| & |palm-down-medium| \\ +% |palm-down-hand-lighter| & |palm-down-lighter| \\ +% |palm-down-hand-lightest| & |palm-down-lightest| \\ +% |palm-up-hand| & |palm-up| \\ +% |palm-up-hand-darkest| & |palm-up-darkest| \\ +% |palm-up-hand-darker| & |palm-up-darker| \\ +% |palm-up-hand-medium| & |palm-up-medium| \\ +% |palm-up-hand-lighter| & |palm-up-lighter| \\ +% |palm-up-hand-lightest| & |palm-up-lightest| \\ +% |rolling-on-the-floor-laughing| & |rofl| \\ +% |see-no-evil-monkey| & |see-no-evil| \\ +% |speak-no-evil-monkey| & |speak-no-evil| \\ +% \end{tabular} +% \end{table} +% +% Emo's |emo.def| contains the names and codepoints of all currently supported +% emoji. Its distribution also includes the |emoji-test.txt| file, which is part +% of \href{https://unicode.org/reports/tr51/}{Unicode TR-51} and contains the +% names and codepoints of all \emph{potentially} supported emoji, i.e., all +% emoji. It further organizes emoji into groups and subgroups, with the current +% (sub)group being the one named on the closest line above the emoji that starts +% with |# |(|sub|)|group:|. As described in the next section, the group and +% subgroup names can be used during configuration for concisely naming a large +% number of emoji. +% +% +% ^^A ---------------------------------------------------------------------------------- +% \subsection{Extras} +% +% \DescribeMacro{\lingchi} +% \DescribeMacro{\YHWH} +% The |\lingchi| and |\YHWH| macros take no arguments and produce \lingchi and +% \YHWH, respectively. They are only available if emo is used with the +% \textsf{extra} option. The former renders the Chinese term for ``death by a +% thousand cuts.'' While originally an execution method, the term applies to +% surprisingly many software systems as well. The latter produces the +% Tetragrammaton, the Hebrew name for God. Observant Jews never utter what's +% written, not even in their thoughts, substituting Adonai (``My Lord''), Elohim +% (``God''), or HaShem (``The Name'') instead. In my mind, that nicely mirrors +% the very incomprehensibility of \YHWH. Both macros preserve a subsequent space +% as space, no backslash needed. +% +% +% ^^A ================================================================================== +% \section{Configuration} +% \label{sec:config} +% +% Emo's implementation is split over two files, |emo.sty| and |emo.def|. The +% former file defines the substance of the package, its options, its helper +% macros, and the user-visible |\emo|, |\lingchi|, and |\YHWH| macros. The +% latter file defines the table of supported emoji. For each such emoji, the +% table contains a command |\emo@emoji@|\meta{emoji-name} with the emoji's +% codepoints as value. |emo.sty| includes the table during loading and +% thereafter relies on it for validating emoji names and rendering emoji in +% LuaLaTeX. It may be possible to combine the two files into one, but that +% avoids at most a few disc reads and hence doesn't seem worth the trouble. +% +% +% \subsection{Update Configuration} +% +% Invoke |config/emo.py| to automatically reconfigure emo's supported emoji: +% \begin{verbaish} +% \$ python3 config/emo.py \meta{selector} \meta{selector} $\ldots$ +% \end{verbaish} +% +% Each selector may be: +% \begin{itemize} +% \item The literal |ALL| (case-sensitive) for \emph{all} emoji. +% \item Name of a group in |emoji-test.txt| lowercased and with spaces replaced +% by dashes and ampersand |&| replaced by an |and|; e.g., +% |travel-and-places|. +% \item Name of a group, a double colon |::|, and name of a subgroup, again +% lowercased and with spaces replaced by dashes and |&| by an |and|; e.g., +% |travel-and-places::place-geographic|. +% \item The name of an emoji; e.g., |desert-island|. +% \end{itemize} +% For conjunctive group names, such as ``Smileys \& Emotion'' (|emoji-test.txt|) +% or ``smileys-and-emotion'' (|emo.py|), the configuration script also accepts +% either of the two nouns as a shortcut, e.g., ``smileys'' or ``emotion.'' +% +% For data safety, |emo.py| does not overwrite PDF graphics and hence can only +% add emoji to the configuration. To remove emoji, simply remove their PDF +% graphics from |emo-graphics| and then run |emo.py|, which updates the emoji +% table accordingly. +% +% |emo.py| effectively treats |emoji-test.txt| as registry of all emoji and the +% filenames of PDF graphics in |emo-graphics| as emo's current inventory. For +% all emoji named by selector arguments but not in the inventory, |emo.py| +% converts the SVG source graphic from the Noto color emoji sources to a PDF +% file and deletes the |/Page| |/Group| object from the the PDF again, since +% that object trips up |pdflatex|. And yeah, |emo.py| automatically downloads +% the Noto color emoji sources if necessary. +% +% +% ^^A ================================================================================== +% \section{Copyright and Licensing} +% +% Since emo's distribution includes not only LaTeX code but also a substantial +% Python script, Unicode data about emoji, as well as graphics and fonts derived +% from Google's Noto project, a number of different licenses apply. All of them +% are \href{https://opensource.org/licenses/}{OSI approved} and non-copyleft: +% \begin{itemize} +% \item This package's LaTeX code is ยฉ Copyright 2023 by Robert Grimm and has +% been released under the +% \href{https://www.latex-project.org/lppl/lppl-1-3c/}{LPPL v1.3c} or later. +% \item The |config/emo.py| script also is ยฉ Copyright 2023 by Robert Grimm but +% has been released under the +% \href{https://www.apache.org/licenses/LICENSE-2.0}{Apache 2.0 license}. +% \item The [config/emoji-test.txt] configuration file is a data file from +% \href{https://unicode.org/reports/tr51/}{Unicode TR-51} and hence subject +% to the \href{https://www.unicode.org/license.txt}{Unicode License}. +% \item The |lingchi.otf| font is a two-glyph subset of the serif traditional +% Chinese version of Google's +% \href{https://github.com/notofonts/noto-cjk}{Noto fonts} and hence subject +% to the \href{https://scripts.sil.org/ofl}{SIL Open Font License v1.1}. +% \item The PDF graphics in the |emo-graphics| directory are derived from the +% sources for \href{https://github.com/googlefonts/noto-emoji}{Noto's color +% emoji} and hence subject to the Apache 2.0 license. +% \end{itemize} +% +% +% \StopEventually{\PrintIndex} +% +% +% ^^A ================================================================================== +% \section{Implementation} +% +% Now that we understand how to configure emo, we are ready for exploring the +% implementation in detail. Let's get started: +% \begin{macrocode} +%<*package> +% \end{macrocode} +% +% Except, the package implementation started near the top of the |emo.dtx| file, +% so that version number and date are more visible and declared only once. But +% that's also well before the documentation preamble and hence cannot be +% included in the annotated implementation. Nonetheless, we can simulate the +% lines: +% +% \begingroup\obeylines +% |\NeedsTeXFormat{LaTeX2e}|\setlength{\parskip}{0pt} +% |\ProvidesPackage{emo}[|\texttt{\filedate}| |\texttt{\fileversion}| emo for all]| +% \endgroup +% +% And no, I didn't repeat the version number and date. Check |emo.dtx|. +% +% +% ^^A ---------------------------------------------------------------------------------- +% \subsection{Package Options} +% +% Emo's \textsf{extra} and \textsf{index} options are simple flags. So, we +% declare a |\newif| for each option and, if the package use includes an option, +% it just toggles the conditional's state: +% \begin{macrocode} +\newif\ifemo@extra\emo@extrafalse +\DeclareOption{extra}{\emo@extratrue} +\newif\ifemo@indexing\emo@indexingfalse +\DeclareOption{index}{\emo@indexingtrue} +\ProcessOptions\relax +% \end{macrocode} +% +% +% ^^A ---------------------------------------------------------------------------------- +% \subsection{Dependencies} +% +% The dependency on |inputenc| effectively declares this file's encoding to be +% UTF-8. The XeTeX and LuaTeX engines already expect files to be encoded that +% way and hence ignore the declaration. However, pdfTeX supports other (legacy) +% encodings and needs to be told. +% \begin{macrocode} +\RequirePackage[utf8]{inputenc} +% \end{macrocode} +% +% Depending on TeX engine, this package requires either |fontspec| or |graphicx| +% as the emoji-emitting backend. In turn, to tell the engines apart, it requires +% |iftex|. +% \begin{macrocode} +\RequirePackage{iftex} +\ifluatex +\RequirePackage{fontspec} +\else +\RequirePackage{graphicx} +\fi +% \end{macrocode} +% +% Emo requires |xcolor| for formatting highly visible error messages within the +% text. Always including another package that is only used when there are errors +% is not ideal. But when I tried calling |\RequirePackage| for |xcolor| from +% inside the error macro, it didn't work. Alternatively, I could make in-text +% errors optional. +% \begin{macrocode} +\RequirePackage{xcolor} +% \end{macrocode} +% +% Finally, emo's options also have dependencies, with \textsf{extra} requiring +% the |xspace| package and \textsf{index} requiring the |index| package: +% \begin{macrocode} +\ifemo@extra +\RequirePackage{xspace} +\fi +\ifemo@indexing +\RequirePackage{index} +\fi +% \end{macrocode} +% +% +% ^^A ---------------------------------------------------------------------------------- +% \subsection{The Emoji Table} +% +% For each emoji with a PDF graphic in the |emo-graphics| directory, a macro +% named |\emo@emoji@|\meta{emoji-name} expands to its Unicode sequence. With +% over 3,000 distinct emoji in Unicode 15, emo relies on a Python script for +% populating the graphics directory and writing the table to the +% \texttt{\jobname.def} file. Since the package code does not change after +% installation but the emoji table may very well change, they are kept separate +% for now. Alternatively, we could use DocStrip to assemble the package file +% from three parts, the code from the previous sections, then the contents of +% the emoji table in |emo.def|, and then all subsequent code. +% \begin{macrocode} +\input{emo.def} +% \end{macrocode} +% +% +% ^^A ---------------------------------------------------------------------------------- +% \subsection{Internal Macros} +% +% \begin{macro}{emo@error@fg} +% \begin{macro}{emo@error@bg} +% \begin{macro}{emo@error} +% Define two colors and a function that uses the two colors for formatting an +% attention-grabbing error message. If you use an invalid emoji name and +% overlook the warning in the console, you \emph{will} notice the error messsage +% in the document thusly formatted. +% \begin{macrocode} +\definecolor{emo@error@fg}{rgb}{1,1,1} +\definecolor{emo@error@bg}{rgb}{.6824,.0863,.0863} +\def\emo@error#1{% + \colorbox{emo@error@bg}{% + \textcolor{emo@error@fg}{% + \textsf{Bad} \texttt{\textbackslash emo\{#1\}}% + }% + }% +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{emo@ifdef} +% Validate the emoji name given as first argument. The macro expands to the +% second argument if the name is valid and an error message otherwise. Its +% implementation relies on the |emo@emoji| table. +% \begin{macrocode} +\def\emo@ifdef#1#2{% + \ifcsname emo@emoji@#1\endcsname#2\else% + \PackageWarning{emo}{Unknown emoji name in `\string\emo{#1}'}% + \emo@error{#1}% + \fi% +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{emo@index} +% If indexing is enabled, record the use of an emoji. Otherwise, do nothing. +% \begin{macrocode} +\ifemo@indexing +\newindex{emo}{edx}{end}{Emoji Index} +\def\emo@index#1{\index[emo]{#1}} +\else +\def\emo@index#1{} +\fi +% \end{macrocode} +% \end{macro} +% +% +% ^^A ---------------------------------------------------------------------------------- +% \subsection{User Macros} +% +% \begin{macro}{emo} +% Emit the named color emoji. Both the font-based version for LuaTeX and the +% graphics-based fallback validate the emoji name and then invoke the +% |\emo@index| macro. But they differ in how they actually display the emoji. +% The LuaTeX version turns the emoji name into its Unicode sequence and wraps +% that in a group that also uses the previously declared Noto color emoji font. +% The fallback version instead includes a suitably sized PDF graphic. +% \begin{macrocode} +\ifluatex +\newfontface\emo@font[Renderer=Harfbuzz]{NotoColorEmoji.ttf} +\newcommand\emo[1]{% + \emo@ifdef{#1}{% + \emo@index{#1}% + {\emo@font\csname emo@emoji@#1\endcsname}% + }% +} +\else +\newcommand\emo[1]{% + \emo@ifdef{#1}{% + \emo@index{#1}% + \raisebox{-0.2ex}{\includegraphics[height=1em]{./emo-graphics/#1}}% + }% +} +\fi +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{lingchi} +% \begin{macro}{YHWH} +% The definitions for the optional |\lingchi| and |\YHWH| macros follow from +% that of |\emo|, except that +% \begin{inlinenum} +% \item there are no arguments to validate and hence no equivalent to +% |\emo@ifdef|; +% \item Hebrew is written right-to-left and hence |\YHWH| requires a +% |\textdir TRT|; +% \item subsequent space should be preserved and hence both macros end +% with |\xspace|. +% \end{inlinenum} +% While it would be nice to use Unicode inside the groups for the LuaTeX macros, +% doing so breaks the package documentation. So |\char| it is. +% \begin{macrocode} +\ifemo@extra +\ifluatex +\newfontface\emo@chinese{lingchi.otf} +\newfontface\emo@hebrew{LinLibertine_R.otf} +\newcommand\lingchi{% + \emo@index{lingchi}% + \begingroup\emo@chinese \char"51CC\char"9072\endgroup% + \xspace} +\newcommand\YHWH{% + \emo@index{YHWH}% + \begingroup\textdir TRT\emo@hebrew \char"5D9\char"5D4\char"5D5\char"5D4\endgroup% + \xspace} +\else +\newcommand\lingchi{% + \emo@index{lingchi}% + \raisebox{-0.2ex}{\includegraphics[height=1em]{./emo-graphics/lingchi}}% + \xspace} +\newcommand\YHWH{% + \emo@index{YHWH}% + \raisebox{-0.2ex}{\includegraphics[height=1em]{./emo-graphics/YHWH}}% + \xspace} +\fi +\fi +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% Et voil\`a. That's it! +% +% \begin{macrocode} +%</package> +% \end{macrocode} +% +% \Finale +% +% ^^A ---------------------------------------------------------------------------------- +% \obeyspaces +% \typeout{} +% \typeout{โโโโโโโโโโโโโโโโโโโโโโemoโโโฐ} +% \typeout{โ} +% \typeout{โ To extract build.sh, emo.ins, emo.sty, and README.md, run:} +% \typeout{โ} +% \typeout{โ $ pdflatex emo.dtx} +% \typeout{โ} +% \typeout{โ} +% \typeout{โ To build emo's documentation with indices, run:} +% \typeout{โ} +% \typeout{โ $ source build.sh} +% \typeout{โ} +% \typeout{โ} +% \typeout{โ To reconfigure supported emoji, run:} +% \typeout{โ} +% \typeout{โ $ python3 config/emo.py -h} +% \typeout{โ} +% \typeout{โ} +% \typeout{โ To install emo, put these files somewhere LaTeX can find them:} +% \typeout{โ} +% \typeout{โ emo.def} +% \typeout{โ emo.sty} +% \typeout{โ NotoSerifTC-Regular.otf} +% \typeout{โ emo-graphics/*.pdf} +% \typeout{โ} +% \typeout{โโโโโโโโโโโโโโโโโโโโโโemoโโโฐ} +% \typeout{} |