Debian Codegraph @

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

raw
1 % \iffalse
2 %<*copyright>
3 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
4 %% forms16be.sty package, %%
5 %% Copyright (C) 2017--2019 %%
6 %% [email protected] %%
7 %% %%
8 %% This program can redistributed and/or modified under %%
9 %% the terms of the LaTeX Project Public License %%
10 %% Distributed from CTAN archives in directory %%
11 %% macros/latex/base/lppl.txt; either version 1.2 of the%%
12 %% License, or (at your option) any later version. %%
13 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
14 %</copyright>
15 %<package>\NeedsTeXFormat{LaTeX2e}
16 %<package>\ProvidesPackage{forms16be}
17 %<package> [2019/03/20 v1.3 Provides UTF-16BE encoding for text strings (dps)]
18 %<*driver>
19 \documentclass{ltxdoc}
20 \usepackage[colorlinks,hyperindex=false]{hyperref}
21 \OnlyDescription % comment out for implementation details
22 \EnableCrossrefs
23 \CodelineIndex
24 \RecordChanges
25 \InputIfFileExists{aebdocfmt.def}{\PackageInfo{forms16be}{Inputting aebdocfmt.def}}
26 {\def\IndexOpt{\DescribeMacro}\def\IndexKey{\DescribeMacro}\let\setupFullwidth\relax
27 \PackageInfo{forms16be}{aebdocfmt.def cannot be found}}
28 \begin{document}
29 \def\CMD#1{\textbackslash#1}
30 \let\pkg\textsf
31 \let\opt\texttt
32 \let\env\texttt
33 \let\app\textsf
34 \def\darg#1{\texttt{\char123\relax#1\char125\relax}}
35 \def\ameta#1{\ensuremath{\langle\textit{\texttt{#1}}\rangle}}
36 \def\meta#1{\textsl{\texttt{#1}}}
37 \GetFileInfo{forms16be.sty}
38 \title{The \textsf{forms16be} Package}
39 \author{D. P. Story\\
40 Email: \texttt{[email protected]}}
41 \date{processed \today}
42 \maketitle
43 \tableofcontents
44 \let\Email\texttt
45 \DocInput{forms16be.dtx}
46 \IfFileExists{\jobname.ind}{\newpage\setupFullwidth\par\PrintIndex}{\paragraph*{Index} The index goes here.
47 Execute
48 \begin{quote}
49 \texttt{makeindex -s gind.ist -o forms16be.ind forms16be.idx}
50 \end{quote}
51 on the command line and recompile \texttt{forms16be.dtx}.}
52 \IfFileExists{\jobname.gls}{\PrintChanges}{\paragraph*{Change History} The list of changes goes here.
53 Execute
54 \begin{quote}
55 \texttt{makeindex -s gglo.ist -o forms16be.gls forms16be.glo}
56 \end{quote}
57 on the command line and recompile
58 \texttt{forms16be.dtx}.}
59 \end{document}
60 %</driver>
61 % \fi
62 % \MakeShortVerb{|}
63 % \InputIfFileExists{aebdonotindex.def}{\PackageInfo{forms16be}{Inputting aebdonotindex.def}}
64 % {\PackageInfo{forms16be}{cannot find aebdonotindex.def}}
65 %\changes{v1.3}{2019/03/20}{Changed when macros are expanded; changes in response to new features
66 % of \string\pkg{insdljs} and \string\pkg{eforms}}
67 % \begin{macrocode}
68 %<*package>
69 % \end{macrocode}
70 % \section{Introduction}
71 %
72 % The code in this package was extracted from \pkg{aeb\_pro}. The code itself did not depend on
73 % PostScript, it is useful, therefore, to remove it from \pkg{aeb\_pro} code base and make it available
74 % to {\LaTeX} users with different workflows (\app{pdflatex}, \app{lualatex}, and \app{xelatex}).
75 %
76 % This package provides support for UTF-16BE Unicode character encoding for the \emph{text string type}
77 % (PDF Reference, version 1.7, beginning on page 158). Text strings are used in ``text annotations, bookmark names,
78 % article threads, document information, and so forth'' (to partially quote page~158). The particular application
79 % is in setting the property values of form fields, at least those properties that take the text strings as its value.
80 % The package contains support for Basic Latin plus the ability to enter any unicode character using the
81 % notation \cs{uXXXX}.
82 %
83 % The code was originally designed to be used with the \pkg{eforms} package, but can be used with
84 % the form fields generated by \pkg{hyperref}, but requires some custom modification of the form field
85 % commands of \pkg{hyperref}.
86 % \section{Code for the \textsf{forms16be} package}
87 % We begin the definitions for this package with some utility commands, followed by some of
88 % the main support command, then followed by the two major commands of this package \cs{unicodeStr}
89 % and \cs{defUniStr}. The unicode lookup tables are listed last.
90 % \subsection{Utility commands}
91 % \begin{macrocode}
92 \def\U@csarg#1#2{\expandafter#1\csname#2\endcsname}
93 \providecommand\aeb@exiii{\expandafter\expandafter\expandafter}
94 % \end{macrocode}
95 % Sanitize selected characters
96 % \changes{v1.2}{2017/08/28}{Sanitize selected characters}
97 % \begin{macrocode}
98 \def\fbe@sanitize{\@makeother\"\@makeother\#\@makeother\$%
99 \@makeother\%\@makeother~%
100 \@for\x:=ABCDEFabcdef()\do{\@makeother\x}}
101 % \end{macrocode}
102 % \subsection{Main supporting commands}
103 % \begin{macro}{\convertChriiUnicode}\hskip-\marginparsep\darg{\ameta{char}}\darg{\ameta{unicode}}
104 % A simple command for mapping a character to its unicode. This command is used in the character-unicode tables
105 % below.
106 % \begin{macrocode}
107 \providecommand\convertChriiUnicode[2]{\U@csarg\gdef{uni@#1}{#2}}%
108 % \end{macrocode}
109 % \end{macro}
110 %\leavevmode\DescribeMacro{\aref}\hskip-\marginparsep\darg{\ameta{name}}
111 % Display the defined character string in UTF-16BE.
112 % \begin{macrocode}
113 \def\aref(#1){\csname aeb@aDescript@#1\endcsname}
114 % \end{macrocode}
115 %\leavevmode\DescribeMacro{\displayUnicode}\hskip-\marginparsep\darg{\ameta{char}}
116 % Display the Unicode encoding of a character.
117 % \begin{macrocode}
118 \providecommand{\displayUnicode}[1]{\csname uni@#1\endcsname}
119 % \end{macrocode}
120 %\leavevmode\DescribeMacro{\stringiiUnicode} is the command that begins building
121 % of a big-endian string (UTF-16BE). It sets the unicode marker (\texttt{FEFF}) and passes the flow
122 % to \cs{@stringiiUnicode}.
123 % \begin{macrocode}
124 \providecommand{\stringiiUnicode}{FEFF\expandafter\@stringiiUnicode}
125 % \end{macrocode}
126 % When \cs{u} is detected \cs{@stringiiUnicode}, the command that converts the string
127 % to all unicode hex, it calls \cs{getRawUnicode} to get the next four characters, which
128 % should be XXXX, place them in the stream, followed by \cs{@stringiiUnicode} so as to
129 % continue the processing of the next character in the description string. I've placed
130 % an \cs{expandafter} in the definition of \cs{getRawUnicode} to allow the commands below
131 % to be used. Thus, instead of using \cs{u20AC}, which might necessitate the user to
132 % look up the code, \verb!\u\EURO! can be used instead. Additional shortcut commands
133 % like these can be created. Except for \cs{EURO}, these are the ones \TeX{} has trouble
134 % processing.
135 % \begin{macrocode}
136 \providecommand{\@stringiiUnicode}[1]{\ifx#1\relax\else
137 \ifx#1\u\aeb@exiii\getRawUnicode@tp\else
138 \displayUnicode{#1}\aeb@exiii\@stringiiUnicode\fi\fi}
139 % \end{macrocode}
140 % Allow parentheses around the value \cs{u}, this allows us to abut neighboring
141 % characters without creating an unwanted space; eg., |\u(\BSLASH)LaTeX|. This is needed
142 % in the case of when the hex digits are expanded from a command, such as \cs{EURO},
143 % \cs{BSLASH}, \cs{LBRACE}, \cs{RBRACE}, and \cs{DQUOTE}.
144 % The \DescribeMacro{\getRawUnicode@tp}\cs{getRawUnicode@tp} tests whether there is
145 % a left parenthesis following \cs{u}.
146 % \changes{v1.1}{2017/08/28}{Allow parentheses around the value of \string\cs{u}}
147 % \begin{macrocode}
148 \def\getRawUnicode@tp#1{\ifx#1(\aeb@exiii\getRawUnicode@p\else
149 \aeb@exiii\@getRawUnicode\fi#1}
150 % \end{macrocode}
151 % We come into \DescribeMacro{\getRawUnicode@p}\cs{getRawUnicode@p} if there is a left
152 % parenthesis following \cs{u}. We extract the left and right parentheses and continue
153 % on to \cs{@getRawUnicode}.
154 % \begin{macrocode}
155 \def\getRawUnicode@p(#1){\expandafter\@getRawUnicode#1}
156 % \end{macrocode}
157 % When the \cs{u} is encountered by \cs{@stringiiUnicode} it is followed four hex digits
158 % or by macro (such as \cs{EURO}) that expands to four hex digits. \DescribeMacro{\getRawUnicode}\cs{getRawUnicode}
159 % grabs these four hex digits (adding them to the string built by \cs{@stringiiUnicode}). Flow continues
160 % to \cs{@stringiiUnicode}.
161 % \begin{macrocode}
162 \providecommand{\@getRawUnicode}[4]{#1#2#3#4\@stringiiUnicode}
163 % \end{macrocode}
164 % \subsection{The \texorpdfstring{\protect\cs{defUniStr}}{\CMD{defUniStr}} command}
165 % \leavevmode\DescribeMacro{\defUniStr}\hskip-\marginparsep\darg{\ameta{name}}\darg{\ameta{string}}
166 % The \cs{defUniStr} command is used to define a unicode string. The \ameta{name} should be an
167 % ASCII character string (used to retrieve the \ameta{string} later); \ameta{string} is a combination
168 % of Basic Latin characters and unicode literals (\cs{uXXXX}). When the \pkg{aeb\_pro} package is loaded
169 % with the \opt{linktoattachments} option, \cs{labelName} expanded outside the
170 % \env{attachmentNames} environment expands \cs{defUniStr}, this is so to support legacy document that
171 % use \cs{labelName} for the purpose of initializing form fields with unicode.
172 % \changes{v1.2}{2017/08/28}{Added parentheses to the \string\@for\space loop}
173 % \begin{macrocode}
174 \def\defUniStr#1{\def\U@uniStrName{#1}\bgroup\fbe@sanitize
175 \obeyspaces\getUniDescript}
176 {\obeyspaces\gdef\getUniDescript#1{\gdef\U@description{#1}%
177 \U@NameUniStr}}
178 \def\U@NameUniStr{\global\U@csarg\let
179 {aeb@aDescript@\U@uniStrName}\U@description\egroup
180 % \end{macrocode}
181 % Within \cs{U@NameUniStr}, we add the line below, which is an expanded
182 % version of the unicode string, built earlier by \cs{buildUnicodeStr}.
183 % \begin{macrocode}
184 \U@csarg\xdef{expanded@\U@uniStrName}%
185 {\U@buildUnicodeStr(\U@uniStrName)}}
186 % \end{macrocode}
187 % \leavevmode\DescribeMacro{\U@buildUnicodeStr}\hskip-\marginparsep\texttt{(\ameta{name})}
188 % If \ameta{name} has been used in a \cs{defUniStr} macro, we prepare to be expanded by
189 % \cs{U@NameUniStr}.
190 % \changes{v1.3}{2019/03/20}{Added \string\cs{buildUnicodeStr} to do some of the work
191 % \string\cs{unicodeStr} used to do}
192 % \begin{macrocode}
193 \def\U@buildUnicodeStr(#1){\expandafter
194 \ifx\csname aeb@aDescript@#1\endcsname\relax
195 \else\aeb@exiii\stringiiUnicode\aref(#1)\relax\fi}
196 % \end{macrocode}
197 %
198 % \subsection{The \texorpdfstring{\protect\cs{unicodeStr}}{\CMD{unicodeStr}} command}
199 %\leavevmode\DescribeMacro{\unicodeStr}\hskip-\marginparsep\texttt{(\ameta{name})}
200 % This command expands \ameta{name} to its big-endian character string. Its argument
201 % is delimited with \emph{parentheses}. Do not redefine this command as it is used by
202 % \pkg{eforms} for automatic detection of a unicode string.
203 % The new \cs{unicodeStr} command: if the argument is not already registered
204 % by \cs{defUniStr}, we pass it through; otherwise we expand the macro defined
205 % by \cs{U@NameUniStr}.
206 % \changes{v1.2}{2017/08/28}{Define a new \string\cs{unicodeStr} command}
207 % \begin{macrocode}
208 \def\unicodeStr(#1){\expandafter
209 \ifx\csname aeb@aDescript@#1\endcsname\relax
210 FEFF#1\else\csname expanded@#1\endcsname\fi}
211 %</package>
212 %<*encoding>
213 % \end{macrocode}
214 % \subsection{Unicode for Basic Latin definitions}
215 % \begin{macrocode}
216 \convertChriiUnicode\space{0020}
217 \convertChriiUnicode{!}{0021}
218 {\@makeother\"
219 \convertChriiUnicode{"}{0022}}
220 \convertChriiUnicode{#}{0023}
221 \convertChriiUnicode{$}{0024}
222 {\@makeother\%
223 \convertChriiUnicode{%}{0025}}
224 \convertChriiUnicode{&}{0026}
225 \convertChriiUnicode{'}{0027}
226 \convertChriiUnicode{(}{0028}
227 \convertChriiUnicode{)}{0029}
228 \convertChriiUnicode{*}{002A}
229 \convertChriiUnicode{+}{002B}
230 \convertChriiUnicode{,}{002C}
231 \convertChriiUnicode{-}{002D}
232 \convertChriiUnicode{.}{002E}
233 \convertChriiUnicode{/}{002F}
234 \convertChriiUnicode{0}{0030}
235 \convertChriiUnicode{1}{0031}
236 \convertChriiUnicode{2}{0032}
237 \convertChriiUnicode{3}{0033}
238 \convertChriiUnicode{4}{0034}
239 \convertChriiUnicode{5}{0035}
240 \convertChriiUnicode{6}{0036}
241 \convertChriiUnicode{7}{0037}
242 \convertChriiUnicode{8}{0038}
243 \convertChriiUnicode{9}{0039}
244 \convertChriiUnicode{:}{003A}
245 \convertChriiUnicode{;}{003B}
246 \convertChriiUnicode{<}{003C}
247 \convertChriiUnicode{=}{003D}
248 \convertChriiUnicode{>}{003E}
249 \convertChriiUnicode{?}{003F}
250 \convertChriiUnicode{@}{0040}
251 \convertChriiUnicode{A}{0041}
252 \convertChriiUnicode{B}{0042}
253 \convertChriiUnicode{C}{0043}
254 \convertChriiUnicode{D}{0044}
255 \convertChriiUnicode{E}{0045}
256 \convertChriiUnicode{F}{0046}
257 \convertChriiUnicode{G}{0047}
258 \convertChriiUnicode{H}{0048}
259 \convertChriiUnicode{I}{0049}
260 \convertChriiUnicode{J}{004A}
261 \convertChriiUnicode{K}{004B}
262 \convertChriiUnicode{L}{004C}
263 \convertChriiUnicode{M}{004D}
264 \convertChriiUnicode{N}{004E}
265 \convertChriiUnicode{O}{004F}
266 \convertChriiUnicode{P}{0050}
267 \convertChriiUnicode{Q}{0051}
268 \convertChriiUnicode{R}{0052}
269 \convertChriiUnicode{S}{0053}
270 \convertChriiUnicode{T}{0054}
271 \convertChriiUnicode{U}{0055}
272 \convertChriiUnicode{V}{0056}
273 \convertChriiUnicode{W}{0057}
274 \convertChriiUnicode{X}{0058}
275 \convertChriiUnicode{Y}{0059}
276 \convertChriiUnicode{Z}{005A}
277 \convertChriiUnicode{[}{005B}
278 \convertChriiUnicode{]}{005D}
279 \convertChriiUnicode{^}{005E}
280 \convertChriiUnicode{_}{005F}
281 \convertChriiUnicode{`}{0060}
282 \convertChriiUnicode{a}{0061}
283 \convertChriiUnicode{b}{0062}
284 \convertChriiUnicode{c}{0063}
285 \convertChriiUnicode{d}{0064}
286 \convertChriiUnicode{e}{0065}
287 \convertChriiUnicode{f}{0066}
288 \convertChriiUnicode{g}{0067}
289 \convertChriiUnicode{h}{0068}
290 \convertChriiUnicode{i}{0069}
291 \convertChriiUnicode{j}{006A}
292 \convertChriiUnicode{k}{006B}
293 \convertChriiUnicode{l}{006C}
294 \convertChriiUnicode{m}{006D}
295 \convertChriiUnicode{n}{006E}
296 \convertChriiUnicode{o}{006F}
297 \convertChriiUnicode{p}{0070}
298 \convertChriiUnicode{q}{0071}
299 \convertChriiUnicode{r}{0072}
300 \convertChriiUnicode{s}{0073}
301 \convertChriiUnicode{t}{0074}
302 \convertChriiUnicode{u}{0075}
303 \convertChriiUnicode{v}{0076}
304 \convertChriiUnicode{w}{0077}
305 \convertChriiUnicode{x}{0078}
306 \convertChriiUnicode{y}{0079}
307 \convertChriiUnicode{z}{007A}
308 \convertChriiUnicode{|}{007C}
309 {\@makeother~
310 \convertChriiUnicode{~}{007E}}
311 \def\EURO{20AC}
312 \def\BSLASH{005C}
313 \def\LBRACE{007B}
314 \def\RBRACE{007D}
315 \def\DQUOTE{0022}
316 \def\ucspace{\u0020}
317 %</encoding>
318 %<*package>
319 \InputIfFileExists{uni4basic-latin.def}{\PackageInfo{forms16be}
320 {Inputting uni4basic-latin.def\MessageBreak definitions}}
321 {\PackageError{forms16be}
322 {Cannot find the file uni4basic-latin.def}{}}
323 %</package>
324 % \end{macrocode}
325 % \Finale
326 \endinput