% \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