summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/forms16be/doc/forms16be-man.tex
blob: c9179b213657f4c5c54524212cdcd8e2cfc4568a (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
327
\documentclass{article}
\usepackage[fleqn]{amsmath}
\usepackage[
    web={centertitlepage,designv,forcolorpaper,tight*,latextoc,pro},
    eforms,aebxmp
]{aeb_pro}
\usepackage{forms16be}
%\usepackage{graphicx,array,fancyvrb}
%\usepackage{aeb_mlink}
%\usepackage{myriadpro}
%\usepackage{calibri}
\usepackage[altbullet]{lucidbry}

\def\hardspace{{\fontfamily{cmtt}\selectfont\symbol{32}}}

\usepackage{acroman}
\usepackage[active]{srcltx}

\urlstyle{tt}

\def\STRUT{\rule{0pt}{14pt}}

\makeatletter
\newcount\hesheCnt \hesheCnt=-1
\def\heshe{\@ifstar{\heshei}{\global\advance\hesheCnt1\relax\heshei}}
\def\heshei{\ifodd\hesheCnt she\else he\fi}
\def\HeShe{\@ifstar{\HeShei}{\global\advance\hesheCnt1\relax\HeShei}}
\def\HeShei{\ifodd\hesheCnt She\else He\fi}
\def\hisher{\@ifstar{\hisheri}{\global\advance\hesheCnt1\relax\hisheri}}
\def\hisheri{\ifodd\hesheCnt her\else his\fi}
\def\himher{\@ifstar{\himheri}{\global\advance\hesheCnt1\relax\himheri}}
\def\himheri{\ifodd\hesheCnt her\else him\fi}
\makeatother

\DeclareDocInfo
{
    university={\AcroTeX.Net},
    title={The \textsf{forms16be} Package},
    author={D. P. Story},
    email={dpstory@acrotex.net},
    subject=Documentation for the forms16be package,
    talksite={\url{www.acrotex.net}},
    version={1.3, 2019/03/20},
    Keywords={LaTeX, form fields, UTF-16BE, AcroTeX},
    copyrightStatus=True,
    copyrightNotice={Copyright (C) \the\year, D. P. Story},
    copyrightInfoURL={http://www.acrotex.net}
}

\universityLayout{fontsize=Large}
\titleLayout{fontsize=LARGE}
\authorLayout{fontsize=Large}
\tocLayout{fontsize=Large,color=aeb}
\sectionLayout{indent=-62.5pt,fontsize=large,color=aeb}
\subsectionLayout{indent=-31.25pt,color=aeb}
\subsubsectionLayout{indent=0pt,color=aeb}
\subsubDefaultDing{\texorpdfstring{$\bullet$}{\textrm\textbullet}}

\chngDocObjectTo{\newDO}{doc}
\begin{docassembly}
var titleOfManual="The forms16be Package";
var manualfilename="Manual_BG_Print_forms16be.pdf";
var manualtemplate="Manual_BG_Brown.pdf"; // Blue, Green, Brown
var _pathToBlank="C:/Users/Public/Documents/ManualBGs/"+manualtemplate;
var doc;
var buildIt=false;
if ( buildIt ) {
    console.println("Creating new " + manualfilename + " file.");
    doc = \appopenDoc({cPath: _pathToBlank, bHidden: true});
    var _path=this.path;
    var pos=_path.lastIndexOf("/");
    _path=_path.substring(0,pos)+"/"+manualfilename;
    \docSaveAs\newDO ({ cPath: _path });
    doc.closeDoc();
    doc = \appopenDoc({cPath: manualfilename, oDoc:this, bHidden: true});
    f=doc.getField("ManualTitle");
    f.value=titleOfManual;
    doc.flattenPages();
    \docSaveAs\newDO({ cPath: manualfilename });
    doc.closeDoc();
} else {
    console.println("Using the current "+manualfilename+" file.");
}
var _path=this.path;
var pos=_path.lastIndexOf("/");
_path=_path.substring(0,pos)+"/"+manualfilename;
\addWatermarkFromFile({
    bOnTop:false,
    bOnPrint:false,
    cDIPath:_path
});
\executeSave();
\end{docassembly}


\begin{document}

\maketitle

\selectColors{linkColor=black}
\tableofcontents
\selectColors{linkColor=webgreen}


\section{Introduction}

The \pkg{forms16be} package\footnote{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}).} provides support for UTF-16BE Unicode
character encoding (called a big-endian character string) 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 to set 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} or \cs{u(XXXX)}, where `\texttt{XXXX}' are four hex
digits.

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{Using the package}

We use the example from \texttt{forms16be-ef.tex} to discuss how to use this package.

First define the unicode string to be used.
\bVerb\takeMeasure{\string\defUniStr\darg{\ameta{name}}\darg{\ameta{string}}}%
\setlength\aebscratch{\bxSize}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\defUniStr{!ameta(name)}{!ameta(string)}
\end{dCmd}
\eVerb Define a unicode string with \cs{defUniStr}. The \ameta{name} is the
name of the unicode string you are defining, it is used later to refer to
this string. The \ameta{string} argument is a combination of Basic Latin
characters and unicode characters (more specifically, expressions of the form
\cs{uXXXX} or \cs{u(XXXX)}, where `\texttt{XXXX}' are hex digits). In the example below, we
declare,
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\defUniStr{VDV}{\u03B1 cos(\u03B8)}
\defUniStr{TU}{Don \u\EURO Story "\u03B1 cos(\u03B8)"}
\end{Verbatim}
The definition file \texttt{uni4basic-latin.def} defines the encoding for the
Basic Latin character set plus a few more definitions, including \cs{EURO}.
See that file for more details.

\defUniStr{VDV}{\u03B1 cos(\u03B8)}%
\defUniStr{TU}{Don \u\EURO Story "\u03B1 cos(\u03B8)"}

After declaring and naming your unicode strings, use \cs{unicodeStr} to set the values
of selected field properties.
\bVerb\takeMeasure{\string\unicodeStr\darg{\ameta{name}}}%
\setlength\aebscratch{\bxSize}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\unicodeStr{!ameta(name)}
\end{dCmd}
\eVerb \cs{unicodeStr\darg{\ameta{name}}} expands to the \ameta{string}
argument associated with \ameta{name}, as declared by the \cs{defUniStr}
command above. For example, \cs{unicodeStr(VDV)}, declared above, expands to
\begin{quote}\ttfamily
\unicodeStr(VDV)
\end{quote}
Notice the first four hex digits, `\texttt{FEFF}', these are `marker digits'.
As the PDF Specification describes, the markers are used to signal the
beginning of a big-endian hex string.

For \pkg{eforms}, incorporating these ideas into field creation is easy:
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\textField[\TU{\unicodeStr(TU)}
  \DV{\unicodeStr(VDV)}\V{\unicodeStr(VDV)}]{tst16be}{1.5in}{11bp}
\end{Verbatim}
The result is \textField[\textSize{8}\TU{\unicodeStr(TU)}
  \DV{\unicodeStr(VDV)}\V{\unicodeStr(VDV)}]{tst16be}{1.5in}{11bp}\!\cgBdry. Pass your mouse over
  the field to see the tool tip as well.

Within the argument of \ameta{string}, backslash, left and right braces are
not defined in the \texttt{uni4basic-latin.def} file. They, therefore,
cannot appear as literals within \ameta{string}. Should you need these
characters, use the following:
\begin{itemize}
  \item \cs{u005C} or \cs{u\cs{BSLASH}} for backslash (\verb~\~).
  \item \cs{u007B} or \cs{u\cs{LBRACE}} for left brace (\texttt{\{});
  \item \cs{u007D} or \cs{u\cs{RBRACE}} for right brace (\texttt{\}});
\end{itemize}
(Other definitions within the \texttt{uni4basic-latin.def} file are
\cs{EURO} and \cs{DQUOTE}.) The introduction of the command versions of
unicode brings up another problem, that of obeying spaces.

Suppose you wanted to initialize a field property with `\cs{LaTeX}'. To obtain
this value we would type `\cs{u\string\BSLASH\space LaTeX}'. But, because \ameta{string} is under the
influence of \cs{obeyspaces}, the specified initialization appears as `\texttt{\string\ LaTeX}', that is,
there is a space that follows the backslash; of course, we cannot specify \cs{u\string\BSLASHLaTeX} as that would
get an undefined command error. The solution is to enclose \cs{BSLASH} in parentheses; if we type
\cs{u(\string\BSLASH)LaTeX} we obtain the desired result:
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\defUniStr{LaTeX}{\u(\BSLASH)LaTeX}
\textField[\V{\unicodeStr(LaTeX)}
  \DV{\unicodeStr(LaTeX)}]{tstLaTeX}{1in}{11bp}
\end{Verbatim}
The above code results in
\defUniStr{LaTeX}{\u(\BSLASH)LaTeX}\textField[\V{\unicodeStr(LaTeX)}\DV{\unicodeStr(LaTeX)}]{tstLaTeX}{1in}{11bp}\cgBdry\!.

\section{List of field properties that take a text string}

The property entries in a form field that support the text string type are
\psf{DV}, \psf{V}, \psf{TU}, \psf{CA}, \psf{RC}, and \psf{AC}. The
\pkg{eforms} key counterparts are \cs{DV}, \cs{V}, \cs{TU}, \cs{CA}, \cs{RC},
and \cs{AC}. When the argument of any of these begins with \cs{unicodeStr},
\pkg{eforms} detects this and passes its argument to the unicode keys
\cs{uDV}, \cs{uV}, \cs{uTU}, \cs{uCA}, \cs{uRC}, and \cs{uAC}. Normally, the
value of \psf{DV}, for example, is \texttt{DV\,(\ameta{text})}, its value is
enclosed in parentheses; when the value consists of hex digits, angle
brackets are required, like so \texttt{DV\,<\ameta{string}>}.

If you enter raw big-endian hex digits, use the special \cs{u\ameta{cmd}} version of the keys, for example,
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\pushButton[\CA{\unicodeStr(263A263C)}]{btn}{.5in}{11bp}
\pushButton[\uCA{FEFF263A263C}]{btn}{.5in}{11bp}
\end{Verbatim}
expands to \pushButton[\CA{\unicodeStr(263A263C)}]{btn}{.5in}{11bp} or
\pushButton[\uCA{FEFF263A263C}]{btn}{.5in}{11bp}\!\cgBdry. The first version
uses \cs{unicodeStr} with raw hex digits, because \cs{unicodeStr} is used,
the unicode is detected and \cs{uCA} is used (with angle brackets). In the
second example, \cs{unicodeStr} is not used, so \cs{uCA} must be explicitly
used; also, the unicode marker \texttt{FEFF} must explicitly appear as well.
(\cs{unicodeStr} automatically inserts the marker.) The results of the markup
forms is the same.

\section{Fonts}

When using unicode to reference glyphs, such as the dings presented above, it
is important that the fonts the PDF viewer uses contains the glyphs. If the
glyph does not exist in the font, the viewer might be successful at
substituting the font. The viewer is not always successful. For example,
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\defUniStr{subS}{x\u209B}
\textField[\V{\unicodeStr(subS)}
  \DV{\unicodeStr(subS)}]{tstsubS}{.5in}{11bp}
\end{Verbatim}
The result is
\defUniStr{subS}{x\u209B}\textField[\V{\unicodeStr(subS)}\DV{\unicodeStr(subS)}]{tstsubS}{.5in}{11bp}\!\cgBdry,
the default value of this field should be $x_S$, is it so? The default font
is \texttt{Helv}. Now, if we change to the \texttt{TiRo} font, we obtain
\textField[\textFont{TiRo}\V{\unicodeStr(subS)}\DV{\unicodeStr(subS)}]{tstsubS}{.5in}{11bp}\!\cgBdry.
A better result! The (newer) \cs{u209B} glyph is not supported for all fonts.
Generally, you'll have to find a font that works and is available to the end
user as well.

\section{A combobox example}

For combo boxes and list boxes, things are slightly more
complicated. In the example below, we define a combo box. First,
define the appearance values of the combo box (the string that is
seen listed in the combo box).
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\defUniStr{myEuro}{\u20AC (Euro)}
\defUniStr{myYen}{\u00A5 (Yen)}
\defUniStr{mySheqel}{\u20AA (Sheqel)}
\defUniStr{myPound}{\u00A3 (Pound)}
\defUniStr{myFranc}{\u20A3 (Franc)}
\end{Verbatim}

\defUniStr{myEuro}{\u20AC (Euro)}
\defUniStr{myYen}{\u00A5 (Yen)}
\defUniStr{mySheqel}{\u20AA (Sheqel)}
\defUniStr{myPound}{\u00A3 (Pound)}
\defUniStr{myFranc}{\u20A3 (Franc)}

Then we can define our combo box.  According to the PDF file format,
unicode strings should be enclosed in angle brackets
\verb!<XXXXXXXXXXXX>!. In initializing the combo box below, the
\cs{unicodeStr} command is used, but this time it is enclosed in
angle brackets. (That is all the ``u'' versions of the keys do above
is to automatically insert the angle brackets for you. Here we have
to do it ourselves. (I suppose one could have a helper command, but
you can handle it.)
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\comboBox[\Ff\FfEdit\DV{Euro}\V{Euro}\textFont{Arial}
\BG{0.98 0.92 0.73}\BC{0 .6 0}]{myCombo}{1in}{11bp}
{*{[(Euro)<\unicodeStr(myEuro)>]%
    [(Yen)<\unicodeStr(myYen)>]%
    [(Sheqel)<\unicodeStr(mySheqel)>]%
    [(Pound)<\unicodeStr(myPound)>]%
    [(Franc)<\unicodeStr(myFranc)>]}
}
\end{Verbatim}
where the \texttt{*} in the position shown above is a token that signals the
passing of a raw form of the value options of a combo or list box; it is
defined in \pkg{eforms}.

\newtopic\noindent
The result is
\comboBox[\Ff\FfEdit\DV{Euro}\V{Euro}\textFont{Arial}
\BG{0.98 0.92 0.73}\BC{0 .6 0}]{myCombo}{1in}{11bp}
{*{[(Euro)<\unicodeStr(myEuro)>]%
    [(Yen)<\unicodeStr(myYen)>]%
    [(Sheqel)<\unicodeStr(mySheqel)>]%
    [(Pound)<\unicodeStr(myPound)>]%
    [(Franc)<\unicodeStr(myFranc)>]}
}\!\cgBdry. Very swave!


\section{Demonstration files}

There are three sample files:
\begin{itemize}
\item \texttt{forms16be-ef.tex} uses the \pkg{eforms} package to create
    form fields and demonstrate how to initialize form fields using
    unicode.
\item \texttt{forms16be-hy.tex} uses form fields created by \pkg{hyperref}.
    \pkg{hyperref} does not support initializing the value of a field, for
    example, with big-endian, so a redefinition is needed.
\item \texttt{forms16be-ap.tex} demonstrates the \pkg{forms16be} with
    \pkg{aeb\_pro} (\app{dvips}/\app{Distiller} workflow required). For consistency with previously
    documented behavior of \pkg{aeb\_pro}, the \opt{linktoattachments} option is used to import \pkg{forms16be}.
    It is not necessary, however, to use \opt{linktoattachments}.
\end{itemize}

\section{My retirement}

Now, I simply must get back to it. \dps

\end{document}