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