Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2011-2018 by Enrico Gregorio
4 % <Enrico dot Gregorio at univr dot it>
5 % -------------------------------------------------------
6 %
7 % This work may be distributed and/or modified under the
8 % conditions of the LaTeX Project Public License, either
9 % version 1.3c of this license or (at your option) any
10 % later version. The latest version of this license is in
11 % http://www.latex-project.org/lppl.txt
12 % and version 1.3 or later is part of all distributions
13 % of LaTeX version 2005/12/01 or later.
14 %
15 % This work has the LPPL maintenance status `maintained'.
16 %
17 % The Current Maintainer of this work is Enrico Gregorio.
18 %
19 % This work consists of the files
20 % newunicodechar.dtx
21 % newunicodechar.ins
22 % and the derived file newunicodechar.sty.
23 %
24 % \fi
25 %
26 % \iffalse
27 %<*driver>
28 \ProvidesFile{newunicodechar.dtx}
29 %</driver>
30 %<package>\NeedsTeXFormat{LaTeX2e}[2018/04/01]
31 %<package>\ProvidesPackage{newunicodechar}
32 %<*package>
33 [2018/04/08 v1.2 Defining Unicode characters]
34 %</package>
35 %
36 %<*driver>
37 \documentclass{ltxdoc}
38 \usepackage[T1]{fontenc}
39 \usepackage{metalogo,booktabs,lmodern,textcomp,wasysym}
40 \EnableCrossrefs
41 \CodelineIndex
42 \RecordChanges
43 \begin{document}
44 \DocInput{newunicodechar.dtx}
45 \PrintChanges
46 \PrintIndex
47 \end{document}
48 %</driver>
49 % \fi
50 %
51 % \CheckSum{201}
52 %
53 % \CharacterTable
54 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
55 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
56 % Digits \0\1\2\3\4\5\6\7\8\9
57 % Exclamation \! Double quote \" Hash (number) \#
58 % Dollar \$ Percent \% Ampersand \&
59 % Acute accent \' Left paren \( Right paren \)
60 % Asterisk \* Plus \+ Comma \,
61 % Minus \- Point \. Solidus \/
62 % Colon \: Semicolon \; Less than \<
63 % Equals \= Greater than \> Question mark \?
64 % Commercial at \@ Left bracket \[ Backslash \\
65 % Right bracket \] Circumflex \^ Underscore \_
66 % Grave accent \` Left brace \{ Vertical bar \|
67 % Right brace \} Tilde \~}
68 %
69 % \changes{v1.2}{2018/04/08}{Now utf8 is default}
70 % \changes{v1.1}{2012/11/12}{Added support for \mbox{\textsf{inputenx}}}
71 % \changes{v1.0}{2011/02/15}{Initial version}
72 %
73 % \GetFileInfo{newunicodechar.dtx}
74 %
75 % \DoNotIndex{\newcommand,\newenvironment,\!,\@empty,\@gobble,\@gobbletwo}
76 % \DoNotIndex{\@ifpackageloaded,\@ifpackagewith,\@ifundefined,\@namedef}
77 % \DoNotIndex{\@nil,\@onlypreamble,\@tempa,\@tempb,\@tempswafalse,\def}
78 % \DoNotIndex{\@tempswatrue,\^,\-,\active,\begingroup,\catcode,\@car,\@cdr}
79 % \DoNotIndex{\edef,\else,\endgroup,\endinput,\expandafter,\fi,\if}
80 % \DoNotIndex{\if@tempswa,\ifcase,\ifnum,\ifx,\lccode,\let,\lowercase}
81 % \DoNotIndex{\MessageBreak,\next,\number,\numexpr,\or,\PackageError}
82 % \DoNotIndex{\PackageWarning,\PackageWarningNoLine,\strip@prefix,\@@end}
83 % \DoNotIndex{\relax,\space,\string,\DeclareOption,\ProcessOptions}
84 % \DoNotIndex{\meaning,\ifdefined,\csname,\chardef,\endcsname,\protect}
85 %
86 % \title{The \textsf{newunicodechar} package\thanks{This document
87 % corresponds to \textsf{newunicodechar}~\fileversion, dated \filedate.}}
88 % \author{Enrico Gregorio \\ \texttt{Enrico dot Gregorio at univr dot it}}
89 %
90 % \maketitle
91 %
92 % \section{Introduction}
93 %
94 % When using Unicode input with \LaTeX{} it's not so uncommon to get an
95 % incomprehensible error message such as
96 %\begin{verbatim}
97 %Unicode char \u8:xxx not set up for use with LaTeX
98 %\end{verbatim}
99 % where |xxx| may be the actual character we input or a combination of
100 % strange characters. This happens because the \texttt{utf8} option
101 % given to \textsf{inputenc} or \textsf{inputenx} defines the \LaTeX{}
102 % meaning of many Unicode characters, but, of course, not all of them.
103 %
104 % For example, one might want to write some Latin words with prosodic
105 % marks, i.e., the diacritics that tell whether a vowel is long or
106 % short, in order to distinguish between `p\u{o}p\u{u}lus' (people)
107 % and `p\=op\u{u}lus' (poplar), but using the actual Unicode
108 % characters that make the \LaTeX{} document easier to read; look at
109 % the following table, where on the left the input is via the \LaTeX{}
110 % Internal Character Representation (LICR) and on the right it's via
111 % Unicode characters,
112 % \begin{center}
113 % \begin{tabular}{cc}
114 % \toprule
115 % LICR & Unicode \\
116 % \midrule
117 % \verb|p\u{o}p\u{u}lus| & \texttt{p\u{o}p\u{u}lus}\\
118 % \verb|p\={o}p\u{u}lus| & \texttt{p\={o}p\u{u}lus}\\
119 % \bottomrule
120 % \end{tabular}
121 % \end{center}
122 % and judge by yourselves which one is better. Unfortunately, the
123 % \texttt{utf8} option to \textsf{inputenc} doesn't define a meaning
124 % for \texttt{\u{o}}, \texttt{\={o}}, and \texttt{\u{u}}. As a matter
125 % of fact, only \texttt{\u{a}} and \texttt{\u{A}} are defined, as they
126 % are used in the Romanian language.
127 %
128 % One might resort to |\DeclareUnicodeCharacter| in the document's
129 % preamble, but this requires looking up at the (long) list of Unicode
130 % characters and jotting down the relevant numbers. For example,
131 % \texttt{\u{o}} is \texttt{U+014F}, so the declaration
132 %\begin{verbatim}
133 %\DeclareUnicodeCharacter{014F}{\u{o}}
134 %\end{verbatim}
135 % would do for \texttt{\u{o}}.
136 %
137 % The present package introduces a simpler interface that frees the
138 % user from the burden to look up in the tables: all it's needed is
139 % \begin{flushleft}
140 % |\newunicodechar{|\texttt{\u{o}}|}{\u{o}}|
141 % \end{flushleft}
142 % You are not restricted to definition like this: for example,
143 % \eighthnote{}~is Unicode \texttt{U+266A}, but you are not required
144 % to know it: if your editor can insert the character~\eighthnote, you
145 % may define its meaning by loading a package that provides it and say
146 % \begin{flushleft}
147 % |\usepackage{wasysym}|\\
148 % |\newunicodechar{|\eighthnote|}{\eighthnote}|
149 % \end{flushleft}
150 % Important note: the package will not work if the \textsf{inputenc} package
151 % is called with an option different from \texttt{utf8}. As of April 2018,
152 % this encoding is assumed by default in 8~bit \TeX{} engines when running
153 % \LaTeX. However one can still load \textsf{inputenc} or \textsf{inputenx}
154 % with the \texttt{utf8} option (not \texttt{utf8x}).
155 %
156 % A similar problem may arise even with \XeLaTeX{}. A frequently asked
157 % question on mailing lists or discussion groups is how to print some
158 % particular character in a different font than the main one of the
159 % document, say, for example, the Euro sign which, in some fonts, is
160 % horrible. The usual answer is to write something like
161 % \begin{flushleft}
162 % |\newfontfamily{\eurofont}{|\meta{some font}|}|\\
163 % |\catcode`|\texttt{\texteuro}|=\active|\\
164 % |\protected\def |\texttt{\texteuro}|{{\eurofont\char`\|^^A
165 % \texttt{\texteuro}|}}|
166 % \end{flushleft}
167 % which, for the average user, is somewhat scaring. With
168 % \textsf{newunicodechar} this may be simplified into
169 % \begin{flushleft}
170 % |\newfontfamily{\eurofont}{|\meta{some font}|}|\\
171 % |\newunicodechar{|\texttt{\texteuro}|}{{\eurofont\texteuro}}|
172 % \end{flushleft}
173 %
174 % \section{Usage}
175 %
176 % The package requires the use of a Unicode engine, i.e., \XeLaTeX{}
177 % or \LuaLaTeX{}, or, with (pdf)\LaTeX{}, the \textsf{inputenc} or
178 % \textsf{inputenx} package along with the \texttt{utf8} option. It
179 % won't work with the \texttt{utf8x} option that employs a completely
180 % different mechanism for parsing Unicode characters in
181 % (pdf)\LaTeX{}. It should be said that \texttt{utf8x} defines many
182 % more characters than \texttt{utf8}, so that the present package
183 % wouldn't be needed.
184 %
185 % Of course the \LaTeX{} document must be written using a Unicode
186 % savvy editor.
187 %
188 % \bigskip
189 %
190 % The package has only one option, \texttt{verbose}^^A
191 % \marginpar{\raggedleft\texttt{verbose}}^^A
192 % \index{verbose=\texttt{verbose} option|usage}, which is off by
193 % default. If the package is called by
194 % |\usepackage[verbose]{newunicodechar}|, then the informative message
195 % on the log file will show the old definition along with the warning
196 % about the redefinition. Unfortunately this definition usually has a
197 % rather cryptic format; for example, redefining \texttt{\u{a}} would
198 % print
199 %\begin{verbatim}
200 %Redefining Unicode character; it meant
201 %*** \IeC {\u a} ***
202 %before your redefinition on input line 22.
203 %\end{verbatim}
204 % Call the package with this option if you are worried about what you
205 % are redefining, but the meaning of the Unicode character should
206 % correspond easily to just one LICR entry. This option does nothing
207 % when a Unicode engine is used, because no character is active
208 % initially (except for~|~|), so there should be non risk to redefine
209 % anything.
210 %
211 % \DescribeMacro{\newunicodechar}
212 % The package provides only one command, |\newunicodechar|, which must
213 % be called with two arguments:
214 % \begin{flushleft}
215 % |\newunicodechar{|\meta{char}|}{|\meta{code}|}|
216 % \end{flushleft}
217 % where \meta{char} is the Unicode character to which we need to give
218 % a meaning and \meta{code} is that meaning, that is the \LaTeX{} code
219 % that will be substituted to the character. Here is what's needed for
220 % the prosodic marks in Latin:
221 % \begin{flushleft}
222 % |%\newunicodechar{|\texttt{\u{A}}|}{\u{A}}|
223 % |\newunicodechar{|\texttt{\u{a}}|}{\u{a}}|\\
224 % |\newunicodechar{|\texttt{\u{E}}|}{\u{E}}|
225 % |\newunicodechar{|\texttt{\u{e}}|}{\u{e}}|\\
226 % |\newunicodechar{|\texttt{\u{I}}|}{\u{I}}|
227 % |\newunicodechar{|\texttt{\u{\i}}|}{\u{\i}}|\\
228 % |\newunicodechar{|\texttt{\u{O}}|}{\u{O}}|
229 % |\newunicodechar{|\texttt{\u{o}}|}{\u{o}}|\\
230 % |\newunicodechar{|\texttt{\u{U}}|}{\u{U}}|
231 % |\newunicodechar{|\texttt{\u{u}}|}{\u{u}}|\\
232 % |\newunicodechar{|\texttt{\={A}}|}{\={A}}|
233 % |\newunicodechar{|\texttt{\={a}}|}{\={a}}|\\
234 % |\newunicodechar{|\texttt{\={E}}|}{\={E}}|
235 % |\newunicodechar{|\texttt{\={e}}|}{\={e}}|\\
236 % |\newunicodechar{|\texttt{\={I}}|}{\={I}}|
237 % |\newunicodechar{|\texttt{\={\i}}|}{\={\i}}|\\
238 % |\newunicodechar{|\texttt{\={O}}|}{\={O}}|
239 % |\newunicodechar{|\texttt{\={o}}|}{\={o}}|\\
240 % |\newunicodechar{|\texttt{\={U}}|}{\={U}}|
241 % |\newunicodechar{|\texttt{\={u}}|}{\={u}}|
242 % \end{flushleft}
243 % The first line is commented out, because those characters are
244 % already defined. It doesn't hurt to give again a definition,
245 % \LaTeX{} will just warn about it.
246 %
247 % Caution: when used with \XeLaTeX{} or \LuaLaTeX{}, there will be no
248 % warning, but the standard setup doesn't define any active character.
249 %
250 % The first argument \emph{must} consist of a single Unicode
251 % character, but the package checks for it and raises an error
252 % otherwise; it will raise an error also if the first argument
253 % consists of a plain ASCII character: defining them is not allowed in
254 % (pdf)\LaTeX{} and would break almost everything in \XeLaTeX{} or
255 % \LuaLaTeX{}.
256 %
257 % \section{An easier way?}
258 %
259 % One could dispense with this package, since the same effect may be
260 % obtained in the way we have already seen in \XeLaTeX{} or \LuaLaTeX{};
261 % with (pdf)\LaTeX{}, calling |\newunicodechar{|\texttt{\={u}}|}{\={u}}|
262 % is equivalent to say
263 % \begin{flushleft}
264 % |\makeatletter|\\
265 % |\@namedef{u8:\detokenize{|\texttt{\={u}}|}}{\={u}}|\\
266 % |\makeatother|
267 % \end{flushleft}
268 %
269 % \StopEventually{}
270 %
271 % \section{Implementation}
272 %
273 % The usual presentation, that we repeat here for completeness.
274 %\begin{verbatim}
275 %\ProvidesFile{newunicodechar.dtx}
276 %\NeedsTeXFormat{LaTeX2e}[2008/04/05]
277 %\ProvidesPackage{newunicodechar}
278 %\end{verbatim}
279 % The date for the format has been chosen to match the last version of
280 % the \texttt{utf8enc.dfu} file that provides definitions for Unicode
281 % characters.
282 %
283 % Now the real macros. First of all we check that the typesetting
284 % engine is sufficiently recent to include $\varepsilon$-\TeX{}
285 % extensions.
286 % \begin{macrocode}
287 \@ifundefined{eTeXversion}
288 {\PackageError{newunicodechar}{LaTeX engine too old, aborting}
289 {Please upgrade your TeX system}\@@end}{}
290 % \end{macrocode}
291 %
292 % \subsection{Options}
293 % There's only one option.
294 % \begin{macrocode}
295 \DeclareOption{verbose}{\let\nuc@verbose=T}
296 \ProcessOptions\relax
297 % \end{macrocode}
298 % \subsection{Error messages}
299 % \begin{macrocode}
300 \def\nuc@onebyteerr{\PackageError{newunicodechar}
301 {ASCII character requested}
302 {Only characters above U+007F may be defined; you asked
303 for\MessageBreak a plain ASCII character and your definition
304 has been ignored.}}
305 \def\nuc@emptyargerr{\PackageError{newunicodechar}
306 {Empty argument}
307 {You shouldn't write \protect\newunicodechar{}{...}}}
308 \def\nuc@invalidargerr{\PackageError{newunicodechar}
309 {Invalid argument}
310 {The first argument to \protect\newunicodechar\space is
311 either\MessageBreak too long or an invalid sequence of bytes}}
312 % \end{macrocode}
313 %
314 % \subsection{Unicode engines}
315 % In case we are running a Unicode engine (\texttt{xelatex} or
316 % \texttt{lualatex}), the definition of the main macro is easier: we
317 % check whether the character is above $127$ and, in this case, we
318 % make it active expanding to the second argument. This definition of
319 % the main macro will be seen only if the engine has the |^^^^|
320 % convention for inputting characters in hexadecimal format, so that
321 % |^^^^0021| is one token and |\@gobble| will eat it up, making
322 % |\next| equal to |\@empty|; with an eight bit engine (\texttt{latex}
323 % or \texttt{pdflatex}), |\@gobble| will swallow only |^^^|.
324 %
325 % In this case we define the main macro all in one swoop; first we
326 % check that the first argument is nonempty, then we act only if it
327 % consists of only one (character) token. Then if the charcode of this
328 % token is less than $127$ we emit an error message; otherwise we
329 % activate the character and define its (protected) expansion to be
330 % the second argument. The last action, in this case, is to allow
331 % |\newunicodechar| only in the preamble. Then we do |\endinput|. If
332 % the engine is not Unicode savvy, everything up to the closing |\fi|
333 % is swallowed up.
334 %
335 % \begin{macro}{\newunicodechar}
336 % Here is the code for defining the Unicode engine version of the main
337 % macro. Notice that we try being on the safe side by not assuming any
338 % particular category code for~|~|, because we restore it after giving
339 % the definition where we need it to be active.
340 % \begin{macrocode}
341 \begingroup
342 \catcode`\^=7 \catcode30=12 \catcode`\!=12 % for safety
343 \edef\next{\@gobble^^^^0021}
344 \expandafter\endgroup
345 \ifx\next\@empty % Start of code for Unicode engines
346 \chardef\nuc@atcode=\catcode`\~
347 \catcode`\~=\active
348 \def\newunicodechar#1#2{%
349 \if\relax\detokenize{#1}\relax
350 \nuc@emptyargerr
351 \else
352 \if\relax\detokenize\expandafter{\@cdr#1\@nil}\relax
353 \ifnum`#1>\string"7F
354 \catcode`#1=\active
355 \begingroup\lccode`\~=`#1
356 \lowercase{\endgroup\protected\def~}{#2}%
357 \else
358 \nuc@onebyteerr
359 \fi
360 \else
361 \nuc@invalidargerr
362 \fi
363 \fi}
364 \catcode`\~=\nuc@atcode
365 \@onlypreamble\newunicodechar
366 \expandafter\endinput
367 \fi % End of code for Unicode engines
368 % \end{macrocode}
369 % \end{macro}
370 %
371 % \subsection{Eight bit engines}
372 % From now on we can assume an eight bit engine is used; we check that
373 % \textsf{inputenc} or \textsf{inputenx} has been loaded with the
374 % right option, otherwise we define |\newunicodechar| to swallow its
375 % arguments, after a warning. We need to first check for
376 % \textsf{inputenx} because it loads \textsf{inputenc}.
377 % \changes{v1.2}{2018/04/08}{Now utf8 is default}
378 % \changes{v1.1}{2012/11/12}{Added support for \mbox{\textsf{inputenx}}}
379 % \begin{macrocode}
380 \def\nuc@stop{\PackageWarningNoLine{newunicodechar}
381 {This package only works if the document\MessageBreak
382 encoding is `utf8'}%
383 \let\newunicodechar\@gobbletwo\endinput}
384 \edef\@tempa{\detokenize{utf8}}
385 \edef\@tempb{\detokenize\expandafter{\inputencodingname}}
386 \ifx\@tempb\@tempa\else
387 \nuc@stop
388 \fi
389 % \end{macrocode}
390 % \begin{macro}{\newunicodechar}
391 % The main macro. We set the temporary switch to false and put in
392 % |\nuc@tempa| the first argument, but detokenized, since it consists of
393 % active characters. We check that it's not empty and access to its
394 % first token that we put into |\@tempb|. Then we call |\nuc@check|
395 % and if it sets the temporary switch to true, we execute the
396 % definition, since the first argument is a valid UTF-8 character, but
397 % we issue a warning if it already has a meaning. All we need to do is
398 % to define the macro |\csname u8:\nuc@tempa\endcsname|, because that's
399 % how \textsf{inputenc} acts. The part between |\ifdefined| and the
400 % corresponding |\fi| will be executed only with the \texttt{verbose}
401 % option.
402 % \begin{macrocode}
403 \def\newunicodechar#1#2{%
404 \@tempswafalse
405 \edef\nuc@tempa{\detokenize{#1}}%
406 \if\relax\nuc@tempa\relax
407 \nuc@emptyargerr
408 \else
409 \edef\@tempb{\expandafter\@car\nuc@tempa\@nil}%
410 \nuc@check
411 \if@tempswa
412 \@ifundefined{u8:\nuc@tempa}{}
413 {\PackageWarning{newunicodechar}
414 {Redefining Unicode character\ifdefined\nuc@verbose;
415 it meant\MessageBreak
416 ***\space\space\nuc@meaning\space\space***\MessageBreak
417 before your redefinition\fi}}%
418 \@namedef{u8:\nuc@tempa}{#2}%
419 \fi
420 \fi
421 }
422 % \end{macrocode}
423 % \end{macro}
424 % The first helper macro computes the number of bytes in the first
425 % argument, though it appears to the user as a single character. The
426 % third is used for the \texttt{verbose} option.
427 % \begin{macrocode}
428 \def\nuc@getlength#1{%
429 \ifx#1\@nil
430 \expandafter\relax
431 \else
432 +1\expandafter\nuc@getlength
433 \fi}
434 \ifdefined\nuc@verbose
435 \def\nuc@meaning{\expandafter\expandafter\expandafter
436 \strip@prefix\expandafter\meaning\csname u8:\nuc@tempa\endcsname}
437 \fi
438 % \end{macrocode}
439 % We select the action based on the length of the first argument; in
440 % case only one byte appears, the user is trying to define an ASCII
441 % character, which is not allowed; if the input is two, three, or four
442 % bytes long, we check whether the first byte has the correct form:
443 % its binary form must be, respectively, \texttt{110xxxxx},
444 % \texttt{1110xxxx}, or \texttt{11110xxx}, so not less than $192$,
445 % $224$, or $240$. The macro |\nuc@ch@ck| does precisely this, issuing
446 % an error message if the argument is invalid or else setting the
447 % temporary switch to true.
448 % \begin{macrocode}
449 \def\nuc@check{%
450 \ifcase\numexpr0\expandafter\nuc@getlength\nuc@tempa\@nil
451 \or %0
452 \nuc@onebyteerr\or %1
453 \nuc@ch@ck{192}\or %2
454 \nuc@ch@ck{224}\or %3
455 \nuc@ch@ck{240}\else %4
456 \nuc@invalidargerr
457 \fi}
458 \def\nuc@ch@ck#1{%
459 \expandafter\ifnum\expandafter`\@tempb<#1\relax
460 \nuc@invalidargerr
461 \else
462 \@tempswatrue
463 \fi
464 }
465 % \end{macrocode}
466 % Finally we disallow |\newunicodechar| outside the preamble.
467 % \begin{macrocode}
468 \@onlypreamble\newunicodechar
469 % \end{macrocode}
470 % \Finale
471 \endinput