summaryrefslogtreecommitdiff
path: root/graphics/emo/emo.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/emo/emo.dtx')
-rw-r--r--graphics/emo/emo.dtx502
1 files changed, 325 insertions, 177 deletions
diff --git a/graphics/emo/emo.dtx b/graphics/emo/emo.dtx
index 05fa1b155f..e6940d46c2 100644
--- a/graphics/emo/emo.dtx
+++ b/graphics/emo/emo.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% emo: emoji for all (LaTeX engines)
+% emoโ€ขji for all (LaTeX engines)
% (C) Copyright 2023 by Robert Grimm
% Released under LPPL v1.3c or later
% <https://github.com/apparebit/emo>
@@ -8,61 +8,67 @@
% \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)
+# emoโ€ขji 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. ๐ŸŽ‰
+a document no matter the LaTeX engine. It uses the Noto color emoji font if the
+engine supports doing so and falls back onto PDF graphics otherwise. In either
+case, `\emo{desert-island}` results in ๐Ÿ and `\emo{parrot}` results in ๐Ÿฆœ. Emo
+may come in particularly handy when dealing with academic publishers that
+provide only minimal support for non-Latin scripts (cough,
+[ACM](https://www.acm.org), cough).
+
+Emo's source repository is <https://github.com/apparebit/emo>. It also is
+available [through CTAN](https://ctan.org/pkg/emo). Emo supports conversion
+to HTML [with LaTeXML](https://github.com/brucemiller/LaTeXML).
+
+
+## Package Options
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.
+preserve a subsequent space as space, no backslash needed.
-To **extract files** embedded in [emo.dtx](emo.dtx) and also rebuild the
-[documentation](emo.pdf), run `pdflatex emo.dtx`.
+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.
+
+
+## Installation
+
+To **extract files** embedded in [emo.dtx](emo.dtx), run `pdftex emo.dtx`. Note
+that plain old `tex` won't do, since it mangles this README. `pdflatex` works,
+but also generates the package documentation. The embedded files are `build.sh`,
+`emo.ins`, `emo.sty`, `emo.sty.ltxml`, and `README.md`.
+
+To **build the documentation** embedded in `emo.dtx`, run `source build.sh`. The
+shell script invokes `pdflatex emo.dtx` thrice and `makeindex` once each for the
+change and the symbol indices, resulting in [emo.pdf](emo.pdf).
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.
+To **install this package**, place `emo.def`, `emo.sty`, `emo.sty.ltxml`,
+`emo-lingchi.ttf`, and the `emo-graphics` directory with the fallback PDF files
+somewhere where LaTeX can find them. In a pinch, your project directory will do.
## Supported Emoji
By default, emo supports only a few emoji:
-1๏ธโƒฃ โ˜ฃ๏ธ โš–๏ธ โœ”๏ธ ๐Ÿ‡ช๐Ÿ‡บ ๐ŸŒ ๐ŸŒ ๐Ÿ›๏ธ ๐Ÿ๏ธ ๐ŸŸ๏ธ ๐Ÿณ๏ธโ€๐ŸŒˆ ๐Ÿท๏ธ ๐Ÿ‘๏ธ ๐Ÿ‘ฅ ๐Ÿ’ฑ ๐Ÿ’พ ๐Ÿ“ ๐Ÿ“Ÿ ๐Ÿ” ๐Ÿ•ต๏ธ ๐Ÿ—‘๏ธ ๐Ÿ˜ก ๐Ÿ›‘ ๐Ÿค– ๐Ÿค ๐Ÿฆœ ๐Ÿง‘โ€โš–๏ธ ๐Ÿงป ๐Ÿงพ
+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.
+label, eye, busts, collision, currency-exchange, floppy-disk, triangular-ruler,
+pager, loupe-left, detective, wastebasket, enraged-face, stop-sign, robot,
+handshake, exploding-head, 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)
@@ -72,8 +78,8 @@ 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
+This package combines code written in LaTeX, Python, and Perl 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:
@@ -86,7 +92,7 @@ approved](https://opensource.org/licenses/) and non-copyleft:
* 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
+ * The `emo-lingchi.ttf` 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).
@@ -99,30 +105,38 @@ approved](https://opensource.org/licenses/) and non-copyleft:
%<*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
+makeindex -s gglo.ist -o emo.gls emo.glo
+pdflatex emo.dtx
pdflatex emo.dtx
%</buildscript>
+% ======================================================================================
%<*scaffold>
\fi
-% ======================================================================================
-\begingroup
+\def\nameofplainTeX{plain}
+\ifx\fmtname\nameofplainTeX\else
+ \expandafter\begingroup
+\fi
%</scaffold>
+% --------------------------------------------------------------------------------------
%<*install>
\input docstrip.tex
\keepsilent
\askforoverwritefalse
\preamble
-emo: emoji for all (LaTeX engines)
+emoโ€ขji 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}}}
+\generate{
+ \file{\jobname.sty}{\from{\jobname.dtx}{package}}}
+\generate{
+ \nopreamble\nopostamble
+ \file{\jobname.sty.ltxml}{\from{\jobname.dtx}{latexml-binding}}}
%</install>
-% Don't stop processing the .dtx file; only stop processing the install file.
%<install>\endbatchfile
% --------------------------------------------------------------------------------------
%<*scaffold>
@@ -133,27 +147,44 @@ Released under LPPL v1.3c or later
\generate{\file{build.sh}{\from{\jobname.dtx}{buildscript}}}
\usedir{doc/latex/emo}
\generate{\file{README.md}{\from{\jobname.dtx}{readme}}}
-\endgroup
+\ifx\fmtname\nameofplainTeX
+ \expandafter\endbatchfile
+\else
+ \expandafter\endgroup
+\fi
%</scaffold>
% ======================================================================================
+% See https://tug.org/TUGboat/tb29-2/tb92pakin.pdf.
+%<*scaffold>
+\ProvidesFile{emo.dtx}
+%</scaffold>
+%<package>\NeedsTeXFormat{LaTeX2e}
+%<package>\ProvidesPackage{emo}
+%<*scaffold,package>
+ [2023/04/01 v0.2 emoโ€ขji for all (LaTeX engines)]
+%</scaffold,package>
+% ======================================================================================
%<*driver>
\PassOptionsToPackage{utf8}{inputenc}
\documentclass{ltxdoc}
-% Override the default \small, which looks odd with Inconsolata.
+% Override the default \small, which looks odd typeset in 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/>
+% Use BlackFoundry's Inria <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{xcolor}
\usepackage{hyperref}
+\definecolor{spot}{HTML}{353598}
+\hypersetup{allcolors=spot}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
@@ -161,29 +192,34 @@ Released under LPPL v1.3c or later
\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}%
-% }{}
+% \changes{0.1}{}{Initial release}
+% \changes{0.2}{}{Prefix PDF and font files with ``emo-''}
+% \changes{0.2}{}{Support pdftex for extracting emo.dtx}
%
% \GetFileInfo{\jobname.dtx}
%
-% \DoNotIndex{\{,\}}
+% \DoNotIndex{\{,\},\x,\\}
% \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)}
+% \newlist{inlinenum}{enumerate*}{1}
+% \setlist[inlinenum]{label=(\alph{inlinenumi})}
+% \newenvironment{verbatimish}{%
+% \ttfamily%
+% \obeylines%
+% \obeyspaces%
+% \vspace{\the\parskip}%
+% \setlength{\parskip}{0pt}%
+% \setlength{\parindent}{1em}%
+% }{}
+%
+% \title{emoโ€ขji for all\\(LaTeX engines)}
% \author{\href{https://apparebit.com}{Robert Grimm}}
% \date{Version \fileversion\ (\filedate)}
%
@@ -191,14 +227,14 @@ Released under LPPL v1.3c or later
%
% \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,
+% color emoji such as |\emo{desert-island}| for \emo{desert-island} or
+% |\emo{parrot}| for \emo{parrot} in your documents independent of 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}
@@ -209,34 +245,52 @@ Released under LPPL v1.3c or later
% ^^A ==================================================================================
% \section{Installation}
%
-% Installation of the emo package is fairly straightforward, though it does
-% involve a lot more files than usual.
+% The emo package is available through its
+% \href{https://github.com/apparebit/emo}{source repository} or through
+% \href{https://ctan.org/pkg/emo}{CTAN}. Installation 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{verbatimish}
+% \$ pdftex emo.dtx
+% \end{verbatimish}
+% Do \emph{not} use |tex|; it mangles the embedded |README.md|. |pdflatex| also
+% extracts the files and then builds the documentation. Embedded files are
+% |build.sh|, |emo.ins|, |emo.sty|, |emo.sty.ltxml|, and |README.md|. Extraction
+% will overwrite existing files with the same name without asking.
+%
+% \item Build the package documentation with change and symbol indices by
+% running:
+% \begin{verbatimish}
+% \$ source build.sh
+% \end{verbatimish}
+% The shell script invokes |pdflatex emo.dtx| thrice and |makeindex| once each
+% for the change and symbol indices to produce |emo.pdf|.
+%
+% \item Get started reconfiguring supported emoji by running:
+% \begin{verbatimish}
+% \$ python config/emo.py -h
+% \end{verbatimish}
+% For more detailed instructions, see \S\ref{sec:config} below.
+%
+% \item Put the following files somewhere LaTeX can find them. In a pinch, your
+% current project's directory will do. However, emo's installation potentially
+% comprises thousands of files. So, you probably want to use a dedicated
+% directory and add that to the search path for LaTeX, e.g., by setting the
+% |TEXINPUTS| environment variable.
% \begin{enumerate}
% \item |emo.sty| with the package implementation;
+% \item |emo.sty.ltxml| with the binding for
+% \href{https://github.com/brucemiller/LaTeXML}{LaTeXML};
% \item |emo.def| with the emoji table;
-% \item |lingchi.otf| for |\lingchi|;
-% \item \emph{all} PDF files in the |emo-graphics| directory.
+% \item |emo-lingchi.ttf| with the two glyphs for |\lingchi|;
+% \item |emo-graphics| with the fallback PDF graphics.
% \end{enumerate}
+% TeX Live requires that each package's files have unique names. For that
+% reason, the PDF graphics in the |emo-graphics| directory start with the |emo-|
+% prefix as well.
+%
% \end{enumerate}
%
% When running on the LuaLaTeX engine, the emo package also uses the Noto color
@@ -244,9 +298,9 @@ Released under LPPL v1.3c or later
% 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.
+% you can find them on CTAN. The |emo-lingchi.ttf| font distributed with emo is
+% a two glyph subset of |NotoSerifTC-Regular.otf|, i.e., the traditional Chinese
+% version of Noto serif.
%
%
% ^^A ==================================================================================
@@ -378,23 +432,25 @@ Released under LPPL v1.3c or later
% \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.
+% Emo's implementation is actually split over two files: |emo.sty| is extracted
+% from |emo.dtx| and defines the substance of the package, its options, its
+% helper macros, and the user-visible |\emo|, |\lingchi|, and |\YHWH| macros.
+% Currently supported emoji are defined by the emoji table in the second file,
+% |emo.def|. For every supported emoji, the file contains a command
+% |\emo@emoji@|\meta{emoji-name} with the emoji's codepoints as value.
%
+% Configuration automates the regeneration of the emoji table for arbitrary
+% numbers of emoji. |config/emo.py| is the script and |config/emoji-test.txt| is
+% the list of all emoji from the Unicode standard.
%
-% \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}
+% ^^A ----------------------------------------------------------------------------------
+% \subsection{Running the Configuration Script}
+%
+% To update emo's configuration, invoke the |config/emo.py| script:
+% \begin{verbatimish}
+% \$ python3 config/emo.py \meta{selector} \meta{selector} $\ldots$
+% \end{verbatimish}
%
% Each selector may be:
% \begin{itemize}
@@ -412,9 +468,9 @@ Released under LPPL v1.3c or later
% 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.
+% \emph{add} emoji to the configuration. To remove emoji, simply remove their
+% PDF graphics from |emo-graphics| and then run |emo.py| without selector
+% arguments, 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
@@ -433,18 +489,19 @@ Released under LPPL v1.3c or later
% 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 This package's LaTeX and also Perl code extracted from |emo.dtx|
+% 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
+% \item The |emo-lingchi.ttf| font is a two-glyph subset of the traditional
% Chinese version of Google's
-% \href{https://github.com/notofonts/noto-cjk}{Noto fonts} and hence subject
+% \href{https://github.com/notofonts/noto-cjk}{Noto serif} 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
@@ -452,38 +509,42 @@ Released under LPPL v1.3c or later
% \end{itemize}
%
%
-% \StopEventually{\PrintIndex}
+% \StopEventually{^^A
+% \PrintChanges^^A
+% \setcounter{IndexColumns}{2}^^A
+% \columnsep = 20pt^^A
+% \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:
+% Let's get started with emo's implementation:
% \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:
+% before the documentation preamble. We repeat it here for completeness:
%
-% \begingroup\obeylines
-% |\NeedsTeXFormat{LaTeX2e}|\setlength{\parskip}{0pt}
-% |\ProvidesPackage{emo}[|\texttt{\filedate}| |\texttt{\fileversion}| emo for all]|
-% \endgroup
+% \begin{verbatimish}
+% |\NeedsTeXFormat{LaTeX2e}|
+% |\ProvidesPackage{emo}|
+% | |[\filedate\space\fileversion\space\fileinfo]
+% \end{verbatimish}
%
-% And no, I didn't repeat the version number and date. Check |emo.dtx|.
+% And no, I didn't repeat the version number, date, or package information.
+% 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{macro}{\ifemo@extra}
+% \begin{macro}{\ifemo@index}
+% Emo's \textsf{extra} and \textsf{index} options are simple flags. So we
+% declare a new conditional for each and, if |\usepackage| includes an option,
+% toggle the conditional's state.
% \begin{macrocode}
\newif\ifemo@extra\emo@extrafalse
\DeclareOption{extra}{\emo@extratrue}
@@ -491,10 +552,12 @@ Released under LPPL v1.3c or later
\DeclareOption{index}{\emo@indexingtrue}
\ProcessOptions\relax
% \end{macrocode}
+% \end{macro}
+% \end{macro}
%
%
% ^^A ----------------------------------------------------------------------------------
-% \subsection{Dependencies}
+% \subsection{Setup Including 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
@@ -504,12 +567,23 @@ Released under LPPL v1.3c or later
\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{macro}{\ifemo@usefont}
+% Define a third conditional for selecting the backend. Originally, I didn't
+% bother with this, simply required |iftex|, and used |\ifluatex| throughout the
+% package. But that unnecessarily complicates support for other LaTeX-like
+% engines.
+% \changes{0.2}{}{Abstract over backend selection}
% \begin{macrocode}
+\newif\ifemo@usefont\emo@usefontfalse
\RequirePackage{iftex}
-\ifluatex
+\ifluatex\emo@usefonttrue\fi
+% \end{macrocode}
+% \end{macro}
+%
+% By now |\ifemo@usefont| should be correctly set up. So we use it for loading
+% the right emoji-emitting backend, |fontspec| or |graphicx|:
+% \begin{macrocode}
+\ifemo@usefont
\RequirePackage{fontspec}
\else
\RequirePackage{graphicx}
@@ -540,6 +614,7 @@ Released under LPPL v1.3c or later
% ^^A ----------------------------------------------------------------------------------
% \subsection{The Emoji Table}
%
+% \begin{macro}{\emo@emoji@<name>}
% 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
@@ -552,14 +627,15 @@ Released under LPPL v1.3c or later
% \begin{macrocode}
\input{emo.def}
% \end{macrocode}
+% \end{macro}
%
%
% ^^A ----------------------------------------------------------------------------------
% \subsection{Internal Macros}
%
-% \begin{macro}{emo@error@fg}
-% \begin{macro}{emo@error@bg}
-% \begin{macro}{emo@error}
+% \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
@@ -579,7 +655,7 @@ Released under LPPL v1.3c or later
% \end{macro}
% \end{macro}
%
-% \begin{macro}{emo@ifdef}
+% \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.
@@ -593,7 +669,7 @@ Released under LPPL v1.3c or later
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{emo@index}
+% \begin{macro}{\emo@index}
% If indexing is enabled, record the use of an emoji. Otherwise, do nothing.
% \begin{macrocode}
\ifemo@indexing
@@ -609,7 +685,7 @@ Released under LPPL v1.3c or later
% ^^A ----------------------------------------------------------------------------------
% \subsection{User Macros}
%
-% \begin{macro}{emo}
+% \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.
@@ -617,7 +693,7 @@ Released under LPPL v1.3c or later
% 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
+\ifemo@usefont
\newfontface\emo@font[Renderer=Harfbuzz]{NotoColorEmoji.ttf}
\newcommand\emo[1]{%
\emo@ifdef{#1}{%
@@ -629,15 +705,16 @@ Released under LPPL v1.3c or later
\newcommand\emo[1]{%
\emo@ifdef{#1}{%
\emo@index{#1}%
- \raisebox{-0.2ex}{\includegraphics[height=1em]{./emo-graphics/#1}}%
+ \raisebox{-0.2ex}{%
+ \includegraphics[height=1em]{emo-graphics/emo-#1}}%
}%
}
\fi
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{lingchi}
-% \begin{macro}{YHWH}
+% \begin{macro}{\lingchi}
+% \begin{macro}{\YHWH}
% The definitions for the optional |\lingchi| and |\YHWH| macros follow from
% that of |\emo|, except that
% \begin{inlinenum}
@@ -648,12 +725,12 @@ Released under LPPL v1.3c or later
% \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.
+% While it would be nice to use Unicode inside the groups for font-using
+% versions, this version is more robust given TeX pre-Unicode heritage.
% \begin{macrocode}
\ifemo@extra
-\ifluatex
-\newfontface\emo@chinese{lingchi.otf}
+\ifemo@usefont
+\newfontface\emo@chinese{emo-lingchi.ttf}
\newfontface\emo@hebrew{LinLibertine_R.otf}
\newcommand\lingchi{%
\emo@index{lingchi}%
@@ -661,16 +738,21 @@ Released under LPPL v1.3c or later
\xspace}
\newcommand\YHWH{%
\emo@index{YHWH}%
- \begingroup\textdir TRT\emo@hebrew \char"5D9\char"5D4\char"5D5\char"5D4\endgroup%
+ \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}}%
+ \raisebox{-0.2ex}{%
+ \includegraphics[height=1em]{emo-graphics/emo-lingchi}}%
\xspace}
\newcommand\YHWH{%
\emo@index{YHWH}%
- \raisebox{-0.2ex}{\includegraphics[height=1em]{./emo-graphics/YHWH}}%
+ \raisebox{-0.2ex}{%
+ \includegraphics[height=1em]{emo-graphics/emo-YHWH}}%
\xspace}
\fi
\fi
@@ -684,34 +766,100 @@ Released under LPPL v1.3c or later
%</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{}
+% ^^A ==================================================================================
+% \section{LaTeXML Binding}
+% \changes{0.2}{}{Add LaTeXML binding}
+%
+% To support conversion from LaTeX to HTML, emo includes a so-called binding for
+% \href{https://github.com/brucemiller/LaTeXML}{LaTeXML}. It effectively is a
+% (much simplified) re-implementation of emo's core functionality, only written
+% in Perl against LaTeXML's API. The binding ignores the \textsf{index} option
+% and does not perform error checking on emoji names. If either is important to
+% you, please compile the document with LaTeX first. Furthermore, the binding
+% emits necessary Unicode codepoints only, without font annotations. If you want
+% to specify fonts, please use a CSS fontstack.
+%
+% Asking package authors to reimplement their packages for LaTeXML seems
+% unreasonable to me. It leads to code duplication and places the maintenance
+% burden on package authors. Yet, right after announcing emo, the question of
+% LaTeXML support came up. LaTeXML includes the |latexml.sty| package, which
+% defines |\iflatexml|. I would have used that command to make the three-line
+% change to |emo.sty| necessary for LaTeX support, except |latexml.sty| contains
+% lots of other stuff that isn't needed. Always loading that only to detect
+% LaTeXML seems like a bad idea. Since reimplementing |\iflatexml| would require
+% a binding anyways, I just wrote a minimal binding. As I said, LaTeXML's
+% approach is broken.
+%
+% With that out of the way, let's get started:
+% \begin{macrocode}
+%<*latexml-binding>
+% \end{macrocode}
+%
+% The binding starts with an explicit preamble because |docstrip| does not
+% alllow for a redefinition of the starting characters of a line comment. It is
+% followed by the Perl dependencies.
+% \begin{macrocode}
+## emo's LaTeXML binding.
+## (C) 2023 by Robert Grimm.
+## Released under LPPL v1.3c or later.
+use strict;
+use warnings;
+use LaTeXML::Package;
+% \end{macrocode}
+%
+% \begin{macro}{\ifemo@extra}
+% Next, we use raw TeX to declare the LaTeX package and define the |emo@extra|
+% conditional. There is no need to define the |emo@indexing| conditional, since
+% it corresponds to the unsupported \textsf{index} option.
+% \begin{macrocode}
+RawTeX(<<'EOTeX');
+\ProvidesPackage{emo}
+ [2023/03/21 v0.2a1 emoโ€ขji for all (LaTeX engines)]
+\newif\ifemo@extra\emo@extrafalse
+EOTeX
+% \end{macrocode}
+% \end{macro}
+%
+% Option prcessing is almost trivial:
+% \begin{macrocode}
+DeclareOption('extra', '\emo@extratrue');
+DeclareOption('index', '');
+ProcessOptions();
+% \end{macrocode}
+%
+% \begin{macro}{\emo@emoji@<name>}
+% \begin{macro}{\emo}
+% Just like the actual package implementation, the binding reads the emoji table
+% from |emo.def|. Similar to the actual implementation of the |\emo| macro when
+% running under LuaLaTeX, the binding expands the named entry from the emoji
+% table, producing the emoji's Unicode codepoints.
+% \begin{macrocode}
+InputDefinitions('emo', type => 'def', noltxml => 1);
+DefMacro('\emo{}', '\csname emo@emoji@#1\endcsname');
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\lingchi}
+% \begin{macro}{\YHWH}
+% If the |emo@extra| conditional is enabled, require the |xspace| package and then
+% provide minimal re-definitions of the |\lingchi| and |\YHWH| macros. Both simply
+% expand to the necessary Unicode codepoints.
+% \begin{macrocode}
+if (IfCondition(T_CS('\ifemo@extra'))) {
+ RequirePackage('xspace');
+ DefMacro('\lingchi', "\x{51cc}\x{9072}\\xspace");
+ DefMacro('\YHWH', "\x{05D9}\x{05D4}\x{05D5}\x{05D4}\\xspace");
+}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% That's it for the binding, too.
+% \begin{macrocode}
+%</latexml-binding>
+% \end{macrocode}
+%
+%
+% \Finale