Debian Codegraph @

texmf-dist/doc/latex/emoji/emoji-doc.tex

raw
1 %%
2 %% Copyright (C) 2020, 2021 by Xiangdong Zeng <[email protected]>
3 %%
4 %% This work may be distributed and/or modified under the
5 %% conditions of the LaTeX Project Public License, either
6 %% version 1.3c of this license or (at your option) any later
7 %% version. The latest version of this license is in:
8 %%
9 %% http://www.latex-project.org/lppl.txt
10 %%
11 %% and version 1.3 or later is part of all distributions of
12 %% LaTeX version 2005/12/01 or later.
13 %%
14 %% This work has the LPPL maintenance status `maintained'.
15 %%
16 %% The Current Maintainer of this work is Xiangdong Zeng.
17 %%
18 \documentclass{l3doc}
19 \usepackage{array,booktabs,emoji,fontspec,geometry,graphicx,longtable,xcolor}
20
21 \geometry{left=3cm, right=1.6cm, vmargin=3.2cm}
22 \setmainfont{NotoSerif}[
23 Extension = .ttf,
24 UprightFont = *-Light,
25 BoldFont = *-Medium,
26 ItalicFont = *-LightItalic,
27 BoldItalicFont = *-MediumItalic,
28 ]
29 \setsansfont{NotoSans}[
30 Extension = .ttf,
31 UprightFont = *-SemiCondensed,
32 BoldFont = *-SemiCondensedBold,
33 ItalicFont = *-SemiCondensedItalic,
34 BoldItalicFont = *-SemiCondensedBoldItalic,
35 ]
36 \setmonofont{NotoSansMono}[
37 Ligatures = CommonOff,
38 Extension = .ttf,
39 UprightFont = *-CondensedLight,
40 BoldFont = *-CondensedMedium,
41 ]
42 % \setemojifont{Twemoji Mozilla}[BoldFont=*]
43 \setemojifont{TwemojiMozilla.ttf}[Path=fonts/twemoji-colr/, BoldFont=*]
44
45 \newfontface\fontja{Source Han Serif Light}
46 \newfontface\fontsymbol{Noto Sans Symbols Light}
47 \newfontface\ttcond{NotoSansMono-ExtraCondensedLight.ttf}[Ligatures=CommonOff]
48
49 \makeatletter
50 \ExplSyntaxOn
51
52 \cs_set:Npn \@pnumwidth { 1.8em }
53
54 \cs_set_protected:Npn \__codedoc_meta_original:n #1
55 {
56 {\fontsymbol\symbol{"2329}}
57 \kern.2pt
58 \group_begin:
59 \normalfont \rmfamily \itshape
60 \edef \meta@hyphen@restore
61 { \hyphenchar \the \font \the \hyphenchar \font }
62 \hyphenchar \font \m@ne
63 \language \l@nohyphenation
64 #1 \/
65 \meta@hyphen@restore
66 \group_end:
67 \kern-.2pt
68 {\fontsymbol\symbol{"232A}}
69 }
70
71 \DeclareRobustCommand{\LaTeX}{
72 L\kern-.34em
73 \raisebox{.36ex}{\scalebox{0.9}{\textsc{a}}}
74 \kern-.12em
75 \TeX}
76
77 \def\@fnsymbol#1{
78 \ensuremath{
79 \ifcase #1
80 \or \text{\emoji{globe-with-meridians}}
81 \or \text{\emoji{email}}
82 \fi}}
83
84 \bool_new:N \g__emoji_doc_after_group_bool
85 \bool_new:N \g__emoji_doc_first_group_bool
86 \int_new:N \g__emoji_doc_group_count_int
87 \int_new:N \g__emoji_doc_subgroup_count_int
88 \int_new:N \g__emoji_doc_total_count_int
89 \str_new:N \g__emoji_doc_group_str
90 \str_new:N \g__emoji_doc_subgroup_str
91
92 \cs_set:Npn \__emoji_def:nnnnn
93 {
94 \int_gincr:N \g__emoji_doc_group_count_int
95 \int_gincr:N \g__emoji_doc_subgroup_count_int
96 \int_gincr:N \g__emoji_doc_total_count_int
97 \char_set_catcode_other:N \^
98 \__emoji_def_aux:nnnnn
99 }
100 \cs_set:Npn \__emoji_def_aux:nnnnn #1#2#3#4#5
101 {
102 \emoji {#2}
103 & \ttcond \scriptsize #2
104 & \ttcond \scriptsize
105 \clist_use:nn {#3} { , ~ }
106 & \scriptsize #4
107 & \ttcond \scriptsize
108 \str_set:Nn \l_tmpa_str {#1}
109 \str_replace_all:Nnn \l_tmpa_str { ^ ^ ^ ^ ^ ^ 0 } { , }
110 \str_replace_all:Nnn \l_tmpa_str { ^ ^ ^ ^ } { , }
111 \exp_args:Nx \clist_use:nn
112 { \str_uppercase:f { \str_tail:N \l_tmpa_str } }
113 { ~ }
114 & \ttcond \scriptsize E#5
115 \char_set_catcode_math_superscript:N \^
116 \\
117 }
118
119 \newcolumntype {C} [1] { > { \centering \arraybackslash } m {#1} }
120 \newcolumntype {P} [1] { > { \raggedright \arraybackslash } m {#1} }
121
122 \cs_set:Npn \__emoji_group:n #1
123 {
124 \bool_if:NTF \g__emoji_doc_first_group_bool
125 { \bool_set_false:N \g__emoji_doc_first_group_bool }
126 { \__emoji_doc_end_group: }
127 \str_gset:Nn \g__emoji_doc_group_str {#1}
128 \str_gremove_all:Nn \g__emoji_doc_group_str { ~\&~ }
129 \exp_args:Nx \subsubsection
130 { #1 ~ ( \exp_not:N \ref* { count: emoji@ \g__emoji_doc_group_str } ) }
131 \newcounter { emoji@ \g__emoji_doc_group_str }
132 \int_gzero:N \g__emoji_doc_group_count_int
133 \bool_set_true:N \g__emoji_doc_after_group_bool
134 }
135
136 \cs_set:Npn \__emoji_subgroup:n #1
137 {
138 \bool_if:NF \g__emoji_doc_after_group_bool
139 { \__emoji_doc_end_longtable: }
140 \bool_set_false:N \g__emoji_doc_after_group_bool
141 \str_gset:Nn \g__emoji_doc_subgroup_str {#1}
142 \str_gremove_all:Nn \g__emoji_doc_subgroup_str { ~\&~ }
143 \newcounter { emoji@ \g__emoji_doc_subgroup_str }
144 \int_gzero:N \g__emoji_doc_subgroup_count_int
145 \__emoji_doc_begin_longtable:x
146 { #1 ~ ( \exp_not:N \ref* { count: emoji@ \g__emoji_doc_subgroup_str } ) }
147 }
148
149 \cs_set:Npn \__emoji_doc_begin_longtable:n #1
150 {
151 \begin{longtable} { C{1.1cm} P{3.6cm} P{2.4cm} P{3.6cm} C{1.8cm} C{1.2cm} }
152 \caption{#1} \\
153 \__emoji_doc_longtable_head:
154 \endfirsthead
155 \__emoji_doc_longtable_head:
156 \endhead
157 \bottomrule
158 \endfoot
159 }
160 \cs_generate_variant:Nn \__emoji_doc_begin_longtable:n { x }
161
162 \cs_set:Npn \__emoji_doc_longtable_head:
163 {
164 \toprule
165 \strong{\small Emoji}
166 & \strong{\small Fullname}
167 & \strong{\small Aliases}
168 & \strong{\small Description}
169 & \strong{\small Codepoints}
170 & \strong{\small Version} \\
171 \midrule
172 }
173
174 \cs_set:Npn \__emoji_doc_end_longtable:
175 {
176 \end{longtable}
177 \int_set:cn
178 { c@emoji@ \g__emoji_doc_subgroup_str }
179 { \g__emoji_doc_subgroup_count_int - 1 }
180 \refstepcounter { emoji@ \g__emoji_doc_subgroup_str }
181 \label { count: emoji@ \g__emoji_doc_subgroup_str }
182 }
183
184 \cs_set:Npn \__emoji_doc_end_group:
185 {
186 \__emoji_doc_end_longtable:
187 \int_set:cn
188 { c@emoji@ \g__emoji_doc_group_str }
189 { \g__emoji_doc_group_count_int - 1 }
190 \refstepcounter { emoji@ \g__emoji_doc_group_str }
191 \label { count: emoji@ \g__emoji_doc_group_str }
192 }
193
194 \cs_new_protected:Npn \EMOJITABLE
195 {
196 \bool_set_true:N \g__emoji_doc_first_group_bool
197 \input { emoji-table.def }
198 \__emoji_doc_end_group:
199 \newcounter { emoji }
200 \int_set:cn { c@emoji } { \g__emoji_doc_total_count_int - 1 }
201 \refstepcounter { emoji }
202 \label { count: emoji }
203 \ExplSyntaxOff
204 }
205
206 \ExplSyntaxOff
207 \makeatother
208
209 \hypersetup{citecolor=green!75!black}
210 \linespread{1.2}
211
212 \def\LuaLaTeX{Lua\LaTeX}
213 \def\LuaHBTeX{LuaHB\TeX}
214
215 \def\contentsname{\emoji{snowman} Contents}
216 \def\refname{\emoji{mortar-board} References}
217
218 \title{The \pkg{emoji} package \thanks{\url{https://github.com/stone-zeng/latex-emoji}} \\
219 Emoji support in (Lua)\LaTeX}
220 \author{Xiangdong Zeng \thanks{\url{[email protected]}}}
221 \date{\emoji{date} 2021/07/17\quad v0.2.2}
222
223 \begin{document}
224
225 \maketitle
226
227 \tableofcontents
228
229 \section{\emoji{hamburger} Introduction}
230
231 \strong{Emoji} (\emoji{jp}: {\fontja 絵文字}) are pictographs (pictorial symbols) that are
232 typically presented in a colorful cartoon form and used inline in text. They represent things
233 such as faces, weather, vehicles and buildings, food and drink, animals and plants, or icons
234 that represent emotions, feelings, or activities.\textsuperscript{\cite{utr51}}
235
236 In 2019, \href{https://github.com/luigiScarso}{Luigi Scarso} has integrated the
237 \href{https://github.com/harfbuzz/harfbuzz}{HarfBuzz} library into \LuaTeX.%
238 \footnote{\href{https://github.com/khaledhosny}{Khaled Hosny} has also created a similar project
239 \href{https://github.com/khaledhosny/harftex}{HarfTeX}.}
240 While the original purpose is to optimize the rendering of indic and arabic scripts, emoji are
241 also supported by this new extended version of \TeX{} at the same time.
242
243 The \pkg{emoji} package allows user to typeset emoji in a \LaTeX{} document. It requires
244 \LuaHBTeX{}, which is the backend of \texttt{lualatex} since \TeX{} Live 2020. In \TeX{} Live
245 2019, only \texttt{lualatex-dev} can be used to compile.
246
247 Emoji has been included in the Unicode Standard since 2009. The \pkg{emoji} package support
248 the latest version Emoji 13.1 (published on 2020-09-18).%
249 \footnote{Starting with version 11.0, the repertoire of emoji characters is synchronized with
250 the Unicode Standard, and has the same version numbering system.}
251
252 \section{\emoji{fire} Basic usage}
253
254 \subsection{\emoji{car} Load the package}
255
256 The package should be loaded in the usual way:
257
258 \begin{verbatim}
259 \usepackage{emoji}
260 \end{verbatim}
261
262 \subsection{\emoji{beer} Set emoji fonts}
263
264 On Windows, macOS or Linux systems, the \pkg{emoji} package will automatically select available
265 emoji fonts. If the package can't find any emoji fonts, or if you want to change the default font,
266 you can use the following command to set emoji font manually.
267
268 \begin{function}{\setemojifont}
269 \begin{syntax}
270 \cs{setemojifont}\marg{font}\oarg{font features}
271 \end{syntax}
272 This command is similar to \cs{setmainfont} provided by \pkg{fontspec}, but only works for
273 emoji. The optional \meta{font features} should be a key-value list, which is described in the
274 document of \pkg{fontspec} package in detail.
275
276 You can use this command in the preamble or in the document body. Only emoji afterwards will
277 be affected.
278 \end{function}
279
280 Examples:
281
282 \begin{verbatim}
283 % Font name
284 \setemojifont{Apple Color Emoji}
285
286 % File name with explicit path
287 \setemojifont{EmojiOneMozilla.ttf}[Path=./fonts/]
288 \end{verbatim}
289
290 \subsection{\emoji{art} Use emoji}
291
292 \begin{function}{\emoji}
293 \begin{syntax}
294 \cs{emoji}\marg{name}
295 \end{syntax}
296 This is the main command to use emoji. All valid \meta{name} can be found in
297 \autoref{subsec:emoji-list} (fullnames and aliases are both OK).
298 \end{function}
299
300 Examples:
301
302 \begin{verbatim}
303 \emoji{joy}
304 \emoji{+1}
305 \emoji{family-man-woman-girl-boy}
306 \emoji{woman-and-man-holding-hands-light-skin-tone-medium-dark-skin-tone}
307 \end{verbatim}
308
309 \emoji{joy} \emoji{+1} \emoji{family-man-woman-girl-boy}
310 \emoji{woman-and-man-holding-hands-light-skin-tone-medium-dark-skin-tone}
311
312 \section{\emoji{electric-plug} Technical details}
313
314 \subsection{\emoji{orange-book} Emoji list}
315 \label{subsec:emoji-list}
316
317 The emoji and their description are from Unicode's
318 \href{https://www.unicode.org/Public/emoji/latest/emoji-test.txt}{\file{emoji-test.txt}},
319 while the aliases are from GitHub's
320 \href{https://github.com/github/gemoji/blob/master/db/emoji.json}{\file{emoji.json}}.
321
322 There are totally \ref*{count:emoji} emoji listed here. This should equal to the number of
323 fully-qualified emoji and components in Unicode standard.
324
325 In the following list, emoji is shown with Twemoji font. The fullname is actually a sanitized
326 version of description, which is from the CLDR short name. The version field \texttt{Ex.x}
327 corresponds to the Emoji version when the emoji character or emoji sequence was first defined.
328
329 \EMOJITABLE
330
331 \subsection{\emoji{hammer-and-wrench} Fonts}
332
333 At present, \LuaHBTeX{} doesn's support OpenType \texttt{SVG} table, so not all color emoji fonts
334 can be used normally. Some typical fonts are listed in \autoref{tab:emoji-fonts}.
335
336 \begingroup
337
338 \def\y{\emoji{white-check-mark}}
339 \def\x{\emoji{negative-squared-cross-mark}}
340 \small
341
342 \begin{longtable}{cccccc}
343 \caption{Typical color emoji fonts}
344 \label{tab:emoji-fonts}
345 \endfirsthead
346 \toprule
347 \strong{Font name}
348 & \strong{OpenType table(s)}
349 & \strong{Bitmap?}
350 & \strong{Vector?}
351 & \strong{Support?}
352 & \strong{Reference} \\
353 \midrule
354 Apple Color Emoji & \texttt{sbix} & \y & & \y & \\
355 Segoe UI Emoji & \texttt{COLR}/\texttt{CPAL} & & \y & \y & \\
356 EmojiOne Mozilla & \texttt{COLR}/\texttt{CPAL} & & \y & \y & \cite{twemoji-colr} \\
357 Twemoji Mozilla & \texttt{COLR}/\texttt{CPAL} & & \y & \y & \cite{twemoji-colr} \\
358 Noto Color Emoji & \texttt{CBDT}/\texttt{CBLC} & \y & & \y & \cite{noto-emoji} \\
359 JoyPixels & \texttt{CBDT}/\texttt{CBLC} & \y & & \y & \cite{joypixels} \\
360 EmojiOne & \texttt{SVG} & & \y & \x & \cite{emojione} \\
361 Twitter Color Emoji & \texttt{SVG} & & \y & \x & \cite{twemoji} \\
362 \bottomrule
363 \end{longtable}
364
365 \endgroup
366
367 This document uses the following fonts:
368
369 \begin{itemize}
370 \item Noto Serif
371 \item Noto Sans
372 \item Noto Sans Mono
373 \item Noto Sans Symbols
374 \item Source Han Serif ({\fontja 源ノ明朝})
375 \item Twemoji Mozilla
376 \end{itemize}
377
378 \subsection{\emoji{construction} Known issues}
379
380 The \pkg{emoji} package is highly experimental and may have a lot of bugs inevitably. For example:
381
382 \begin{itemize}
383 \item Spacing around emoji may be abnormal
384 \item The emoji may not be copied from PDF
385 \end{itemize}
386
387 If you have any problems when using this package, please create an issue on GitHub or send
388 an email to the author.
389
390 \subsection{\emoji{pencil} Todo list}
391
392 The following features may be added in the future:
393
394 \begin{itemize}
395 \item Allow direct input of emoji
396 \item Add options including default skin tones, genders, etc.
397 \item Support more fonts
398 \item Automatically fallback
399 \end{itemize}
400
401 \begin{thebibliography}{9}
402 \def\newblock{\\}
403 \small
404
405 \bibitem{utr51}
406 Unicode\textregistered{} Technical Standard \#51: Unicode Emoji
407 \newblock \url{https://www.unicode.org/reports/tr51/}
408
409 \bibitem{emojipedia}
410 \emoji{orange-book} Emojipedia --- \emoji{smiley} Home of Emoji Meanings
411 \emoji{information-desk-person}\emoji{ok-hand}\emoji{bamboo}\emoji{heart-eyes}
412 \newblock \url{https://emojipedia.org/}
413
414 \bibitem{noto-emoji}
415 Noto Color Emoji --- Google Noto Fonts
416 \newblock \url{https://www.google.com/get/noto/help/emoji/}
417
418 \bibitem{twemoji}
419 Twemoji
420 \newblock \url{https://twemoji.twitter.com/}
421
422 \bibitem{twemoji-colr}
423 Twemoji font in COLR/CPAL layered format\footnote{Before v0.3, it was based on EmojiOne.}
424 \newblock \url{https://github.com/mozilla/twemoji-colr}
425
426 \bibitem{emojione}
427 OpenType-SVG font of EmojiOne 2.3
428 \newblock \url{https://github.com/adobe-fonts/emojione-color}
429
430 \bibitem{joypixels}
431 JoyPixels\texttrademark{} --- Emoji as a Service (formerly EmojiOne)
432 \newblock \url{https://www.joypixels.com/}
433 \end{thebibliography}
434
435 \end{document}