From 4ac795a4cbc17927bd3bc444849a5144d23ba43f Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Fri, 14 May 2021 06:36:17 +0900
Subject: acrotex (May14)

---
 texmf-dist/doc/latex/acrotex/eformman.tex | 386 ++++++++++++++++++++----------
 1 file changed, 261 insertions(+), 125 deletions(-)

(limited to 'texmf-dist/doc/latex/acrotex/eformman.tex')

diff --git a/texmf-dist/doc/latex/acrotex/eformman.tex b/texmf-dist/doc/latex/acrotex/eformman.tex
index 82bea44f..c56e1beb 100644
--- a/texmf-dist/doc/latex/acrotex/eformman.tex
+++ b/texmf-dist/doc/latex/acrotex/eformman.tex
@@ -12,6 +12,7 @@
 
 \setlength{\marginparpush}{3pt}
 \setlength{\mathindent}{\the\parindent}
+
 %\previewOn\pmpvOn
 
 \usepackage{graphicx,array,longtable}
@@ -21,7 +22,6 @@
 \DeclareInitView{layoutmag={navitab:UseOutlines}}
 \xbmksetup{colors={int=red},styles={intbf}}
 
-
 \def\STRUT{\rule{0pt}{14pt}}
 \def\negSTRUT{\rule[-8pt]{0pt}{0pt}}
 \def\mSTRUT{\makebox[0pt][l]{\phantom{$\frac00$}}}
@@ -72,16 +72,17 @@
 \def\tutpathi{tutorial}
 \def\expath{../examples}
 
+\let\tops\texorpdfstring
 \DeclareDocInfo
 {
     university={\AcroTeX.Net\protect\\[1ex]eforms and insdljs Documentation},
-    title={Support for AcroForms and Links, and for\texorpdfstring{\protect\\[2ex]}{ }Document JavaScript and Open Page Events},
+    title={Support for AcroForms and Links, and for\tops{\protect\\[2ex]}{ }Document JavaScript and Open Page Events},
     author={D. P. Story},
     email={dpstory@acrotex.net},
     subject={Documentation for the eforms and insdljs packages},
     talksite={\url{www.acrotex.net}},
     version={2.0},
-    prepared={2021/02/17},
+    prepared={2021/05/10},
     preparedLabel={Distribution Dated:},
     keywords={LaTeX, hyperref, PDF, exercises, quizzes},
     copyrightStatus=True,
@@ -103,7 +104,7 @@
 \sectionLayout{indent=-62.5pt,fontsize=large,color=aeb,fontfamily=sffamily}
 \subsectionLayout{indent=-31.25pt,color=aeb,fontfamily=sffamily}
 \subsubsectionLayout{indent=0pt,color=aeb,fontfamily=sffamily}
-\subsubDefaultDing{\texorpdfstring{$\bullet$}{\textrm\textbullet}}
+\subsubDefaultDing{\tops{$\bullet$}{\textrm\textbullet}}
 
 \def\verygoodbreak{%
 \vskip0pt plus1in\goodbreak\vskip0pt plus-1in}
@@ -118,7 +119,7 @@
 
 
 \makeatletter
-\let\bslash=\@backslashchar
+\let\bslash\@backslashchar
 \renewcommand{\paragraph}{\@startsection{paragraph}{4}{0pt}{6pt}{-3pt}{\bfseries}}
 
 % Begin definition of \appendixsubsection
@@ -630,11 +631,12 @@ The push button is a button field that has no
 value, it is neither on nor off. Generally, push buttons are used
 to initiate some action, such as JavaScript action.
 
-\settowidth{\aebdimen}{\cs{pushButton[\#1]\darg{\#2}\darg{\#3}\darg{\#4}}}
-\begin{dCmd}[commandchars=!()]{\aebdimen+2\fboxsep+2\fboxrule}
+%\settowidth{\aebdimen}{\cs{pushButton[\#1]\darg{\#2}\darg{\#3}\darg{\#4}}}
+\bVerb\takeMeasure{\string\cs{pushButton[\#1]\darg{\#2}\darg{\#3}\darg{\#4}}}%
+\begin{dCmd}[commandchars=!()]{\bxSize}
 \pushButton[#1]{#2}{#3}{#4}
 \end{dCmd}
-
+\endgroup
 \PD
 \begin{enumerate}
 \item[\texttt{\#1}:] optional, used to enter any modification of appearance/actions
@@ -690,11 +692,12 @@ A check box is a type of button that has one of two values,
 ``off'' is \texttt{Off}; the value of the ``on'' state can be
 defined by the user.
 
-\settowidth{\aebdimen}{\cs{checkBox[\#1]\darg{\#2}\darg{\#3}\darg{\#4}\darg{\#5}}}
-\begin{dCmd}{\aebdimen+2\fboxsep+2\fboxrule}
+%\settowidth{\aebdimen}{\cs{checkBox[\#1]\darg{\#2}\darg{\#3}\darg{\#4}\darg{\#5}}}
+\bVerb\takeMeasure{\cs{checkBox[\#1]\darg{\#2}\darg{\#3}\darg{\#4}\darg{\#5}}}
+\begin{dCmd}{\bxSize}
 \checkBox[#1]{#2}{#3}{#4}{#5}
 \end{dCmd}
-
+\endgroup
 \PD
 \begin{enumerate}
 \item[\texttt{\#1}:] optional, used to enter any modification of appearance/actions
@@ -745,11 +748,12 @@ the \pkg{eforms} package.
 A radio button field is similar to a check box, but is meant to be
 used in unison with one or more additional radio buttons.
 
-\settowidth{\aebdimen}{\cs{radioButton[\#1]\darg{\#2}\darg{\#3}\darg{\#4}\darg{\#5}}}
-\begin{dCmd}{\aebdimen+2\fboxsep+2\fboxrule}
+%\settowidth{\aebdimen}{\cs{radioButton[\#1]\darg{\#2}\darg{\#3}\darg{\#4}\darg{\#5}}}
+\bVerb\takeMeasure{\cs{radioButton[\#1]\darg{\#2}\darg{\#3}\darg{\#4}\darg{\#5}}}
+\begin{dCmd}{{\bxSize}}
 \radioButton[#1]{#2}{#3}{#4}{#5}
 \end{dCmd}
-
+\endgroup
 \PD
 \begin{enumerate}
 \item[\texttt{\#1}:] optional, used to enter any modification of appearance/actions
@@ -824,11 +828,12 @@ of the choices are visible in a rectangle.  A scroll bar becomes
 available if any of the items in the list are not visible in the
 rectangle provided.
 
-\settowidth{\aebdimen}{\cs{listBox[\#1]\darg{\#2}\darg{\#3}\darg{\#4}\darg{\#5}}}
-\begin{dCmd}{\aebdimen+2\fboxsep+2\fboxrule}
+%\settowidth{\aebdimen}{\cs{listBox[\#1]\darg{\#2}\darg{\#3}\darg{\#4}\darg{\#5}}}
+\bVerb\takeMeasure{\cs{listBox[\#1]\darg{\#2}\darg{\#3}\darg{\#4}\darg{\#5}}}%
+\begin{dCmd}{\bxSize}
 \listBox[#1]{#2}{#3}{#4}{#5}
 \end{dCmd}
-
+\endgroup
 \PD
 \begin{enumerate}
 \item[\texttt{\#1}:] optional, used to enter any modification of appearance/actions
@@ -916,11 +921,12 @@ A combo box is a drop down list of items that can optionally have
 an editable text box for the user to type in a value other than
 the predefined choices.
 
-\settowidth{\aebdimen}{\cs{comboBox[\#1]\darg{\#2}\darg{\#3}\darg{\#4}\darg{\#5}}}
+%\settowidth{\aebdimen}{\cs{comboBox[\#1]\darg{\#2}\darg{\#3}\darg{\#4}\darg{\#5}}}
+\bVerb\takeMeasure{\cs{comboBox[\#1]\darg{\#2}\darg{\#3}\darg{\#4}\darg{\#5}}}%
 \begin{dCmd}{\aebdimen+2\fboxsep+2\fboxrule}
 \comboBox[#1]{#2}{#3}{#4}{#5}
 \end{dCmd}
-
+\endgroup
 \PD
 \begin{enumerate}
 \item[\texttt{\#1}:] optional, used to enter any modification of appearance/actions
@@ -1014,11 +1020,12 @@ else
 
 A text field is the way a user can enter text into a form.
 
-\settowidth{\aebdimen}{\cs{textField[\#1]\darg{\#2}\darg{\#3}\darg{\#4}}}
-\begin{dCmd}{\aebdimen+2\fboxsep+2\fboxrule}
+%\settowidth{\aebdimen}{\cs{textField[\#1]\darg{\#2}\darg{\#3}\darg{\#4}}}
+\bVerb\takeMeasure{\cs{textField[\#1]\darg{\#2}\darg{\#3}\darg{\#4}}}%
+\begin{dCmd}{\bxSize}
 \textField[#1]{#2}{#3}{#4}
 \end{dCmd}
-
+\endgroup
 \PD
 \begin{enumerate}
 \item[\texttt{\#1}:] optional, used to enter any modification of appearance/actions
@@ -1112,11 +1119,12 @@ Total:    & \textField[\AA{%
 
 A signature field is a field that can be digitally signed.
 
-\settowidth{\aebdimen}{\cs{sigField[\#1]\darg{\#2}\darg{\#3}\darg{\#4}}}
-\begin{dCmd}{\aebdimen+2\fboxsep+2\fboxrule}
+%\settowidth{\aebdimen}{\cs{sigField[\#1]\darg{\#2}\darg{\#3}\darg{\#4}}}
+\bVerb\takeMeasure{\cs{sigField[\#1]\darg{\#2}\darg{\#3}\darg{\#4}}}%
+\begin{dCmd}{\bxSize}
 \sigField[#1]{#2}{#3}{#4}
 \end{dCmd}
-
+\endgroup
 \PD
 \begin{enumerate}
 \item[\texttt{\#1}:] optional, used to enter any modification of appearance/actions
@@ -1224,6 +1232,145 @@ is signed.
 \end{itemize}
 
 
+\subsection{Obtaining a uniform look across all workflows}\label{s:efuniformWF}
+
+In this section, several commands are
+presented that help you layout {\PDF} forms, as created by \pkg{eforms}, in a
+way that is consistent across all workflows (\app{dvips}/\penalty0
+\app{Distiller}, \app{pdflatex}, \app{lualatex}, and \app{xelatex}).
+
+\bVerb\takeMeasure{\string\makeXasPDOn\qquad\string\vcgBdry[\ameta{length}]}%
+\settowidth{\aebdimen}{\cs{makeXasPDOn}}%
+\def\1{\rlap{\ttfamily\hskip\aebdimen\qquad\string\cgBdry*[\ameta{length}]}}%
+\def\2{\rlap{\ttfamily\hskip\aebdimen\qquad\string\vcgBdry[\ameta{length}]}}%
+\def\3{\rlap{\hskip\linewidth\ding{182}}}
+\def\4{\rlap{\hskip\linewidth\ding{183}}}
+\def\5{\rlap{\hskip\linewidth\ding{184}}}
+\def\6{\rlap{\hskip\linewidth\ding{185}}}
+\def\7{\rlap{\hskip\linewidth\ding{186}}}
+\xdef\panelWidth{\the\linewidth}%
+\begin{dCmd}[commandchars=!()]{\bxSize}
+!3\makeXasPDOn!qquad\makeXasPDOff
+!4\makePDasXOn!qquad\makePDasXOff
+!5!1\olBdry
+!6!2\volBdry
+!7\efKern{!ameta(length!SUB1)}{!ameta(length!SUB2)}
+\end{dCmd}
+\endgroup
+
+\paragraph*{Matching dimensions of form fields.}
+The form fields created by \app{xelatex} are smaller than the ones with the
+same dimensions created the other {\PDF} creators (\app{pdflatex},
+\app{lualatex}, or \app{dvips}/\penalty0\app{Distiller}). To obtain a uniform
+look across all workflows, you can either increase the size of the
+\app{xelatex} form fields, or decrease the size of the form fields created by
+non-\app{xelatex} workflows. The first two lines of the display (\ding{182}
+and \ding{183}) address the issue that different workflows produce different
+sized form fields even though their dimensions are the same.
+\begin{itemize}
+
+    \item Expanding the command \cs{makeXasPDOn} increases the size of the
+        form fields created by \app{xelatex} to make them the same size as
+        those created by the other applications\app{pdflatex} or; while
+        \cs{makeXasPDOff} turns off this feature, the fields created by
+        \app{xelatex} are smaller than the ones otherwise created by the
+        other workflows.
+
+        The \pkg{eforms} package expands \cs{makeXasPDOn} as the default behavior.
+
+    \item Expanding the command \cs{makePDasXOn} decreases the size of the
+        created by non-\app{xelatex} workflows to make them the same size
+        as those created by \app{xelatex}; while \cs{makeXasPDOff} turns
+        off this feature, the fields created by non-\app{xelatex} workflows
+        are larger than the ones created by \app{xelatex}.
+\end{itemize}
+
+\paragraph*{Setting the horizontal relationship between fields.} When one form field follows another
+on the same line, the space between them becomes an issue. There are three
+problems addressed in this paragraph:
+\begin{itemize}
+    \item You\FmtMP{\cs{olBdry} described, illustrated} want the two fields, which have the same border thickness
+        (usually 1\,bp), to overlap borders, like so,
+    \begin{quote} %\previewtrue
+    \textField{txt1}{30bp}{10bp}\olBdry\textField{txt2}{30bp}{10bp}\\[3pt]
+    \footnotesize\cs{textField\darg{txt1}\darg{30bp}\darg{10bp}}\textbf{\cs{olBdry}}\\
+    \cs{textField\darg{txt2}\darg{30bp}\darg{10bp}}
+    \end{quote}
+    use the \cs{olBdry} command (\textbf{o}ver\textbf{l}ay
+    \textbf{b}oun\textbf{d}a\textbf{ry}), as listed in line~\ding{184} in
+    the display above. Overlapping the border lines is only useful if the
+    border colors are the same.
+
+%\promoteNewPage[\baselineskip]
+
+    \item When\FmtMP{\cs{cgBdry} described, illustrated} the border colors
+        are different, you can place neighboring fields contiguously. To
+        make the field have contiguous border lines, use the \cs{cgBdry}
+        command (\textbf{c}onti\textbf{g}uous
+        \textbf{b}oun\textbf{d}a\textbf{ry}), as listed in line \ding{184}
+        in the above display.
+    \begin{aebQuote}
+    \def\ci{red}\def\cii{blue}
+    \textField[\BC{\ci}]{txt3}{30bp}{10bp}\cgBdry\textField[\BC{\cii}]{txt4}{30bp}{10bp}\\[3pt]
+    \footnotesize\cs{textField[\string\BC\darg{\ci}]\darg{txt3}\darg{30bp}\darg{10bp}}\textbf{\cs{cgBdry}}\\
+    \cs{textField[\string\BC\darg{\cii}]\darg{txt4}\darg{30bp}\darg{10bp}}
+    \end{aebQuote}
+
+    \item The\FmtMP{\cs{olBdry} continued} third case is where you want the field to be separated by a
+        nonzero length, in this case, the optional first argument
+        \cs{cgBdry[\ameta{length}]} is used; \cs{cgBdry} positions the two neighboring
+        field contiguously, then moves the right-field \ameta{length} to the right.
+    \begin{quote}
+    \textField{txt5}{30bp}{10bp}\cgBdry[1in]\textField{txt6}{30bp}{10bp}\\[3pt]
+    \footnotesize\cs{textField\darg{txt5}\darg{30bp}\darg{10bp}}\textbf{\cs{cgBdry[1in]}}\\
+    \cs{textField\darg{txt6}\darg{30bp}\darg{10bp}}
+    \end{quote}
+    The two fields are separated by 1\,inch.
+\end{itemize}
+
+\paragraph*{Setting the vertical relationship between fields.} In a similar
+manner, the space between two fields on consecutive lines may be precisely
+controlled. Both \cs{volBdry} and \cs{vcgBdry} (line~\ding{185} in the
+display) start a new paragraph. The \cs{volBdry}\FmtMP{\cs{volBdry}
+described} command positions the two fields so that their borders exactly
+overlap (assuming the same border width), while the \cs{vcgBdry} command
+positions them so the borders are contiguous. The optional argument for
+\cs{vcgBdry[\ameta{length}]}\FmtMP{\cs{vcgBdry} described} allows for a
+separation of exactly \ameta{length}, assuming \cs{parskip} is 0\,pt.
+\begin{quote}\def\ci{red}\def\cii{blue}
+\settowidth\aebdimen{\footnotesize\ttfamily\ameta{field\SUB1}\cs{vcgBdry[6pt]}\ameta{field\SUB2}}\edef\widthi{\the\aebdimen}%
+\def\1{\makebox[0pt][l]{\footnotesize\hskip\widthi\quad\vrbnormal(overlay borders)}}%
+\def\2{\makebox[0pt][l]{\footnotesize\hskip\widthi\quad\vrbnormal(contiguous borders)}}%
+\def\3{\makebox[0pt][l]{\footnotesize\hskip\widthi\quad\vrbnormal(6pt separation)}}%
+\parbox{36pt}{\textField{txt7}{30bp}{10bp}\volBdry\textField{txt8}{30bp}{10bp}}\quad
+\1\footnotesize\ameta{field\SUB1}\textbf{\cs{volBdry}}\ameta{field\SUB2}\\[6pt]
+\parbox{36pt}{\textField[\BC{\ci}]{txt8}{30bp}{10bp}\vcgBdry
+\textField[\BC{\cii}]{txt9}{30bp}{10bp}}\quad
+\2\footnotesize\ameta{field\SUB1}\textbf{\cs{vcgBdry}}\ameta{field\SUB2}\\[6pt]
+\parbox{36pt}{\textField{txt10}{30bp}{10bp}\vcgBdry[6pt]
+\textField{txt11}{30bp}{10bp}}\quad
+\3\footnotesize\ameta{field\SUB1}\textbf{\cs{vcgBdry[6pt]}}\ameta{field\SUB2}
+\end{quote}
+If \cs{parskip} is not 0\,pt, use the star form,
+\cs{vcgBdry*[\ameta{length}]}\FmtMP{\cs{vcgBdry*} described}, on the last line of form fields; when the star
+argument is present, \cs{vcgBdry} performs the subtraction
+\texttt{\ameta{length}-\cs{parskip}}, in that way, there is exactly
+\ameta{length} of vertical space between the last form field and the next paragraph.
+
+%\begin{example}%\recordExample{eforms/positioning-fields.pdf}
+%The commands of this section are illustrated in the sample file associated with the
+%example.\noexskip\eqfititin{\exrtnlabelformat}
+%\end{example}
+
+\paragraph*{On the \cs{efKern} command.} The \cs{efKern}
+command listed in above display, line~\ding{186}, is a general command that
+can be used to induce driver-dependent spacing. It is designed to provide
+spacing between fields and gives finer control over the ``intelligent'' and
+automatic spacing provided by \cs{olBdry} and \cs{cgBdry}. When \emph{not
+compiled} with the \texttt{xetex} option, \cs{efKern} expands to
+\cs{kern\ameta{length\SUB1}}, and when \emph{compiled with} the
+\texttt{xetex} option, \cs{efKern} expands to \cs{kern\ameta{length\SUB2}}.
+
 \verygoodbreak
 
 
@@ -1245,7 +1392,7 @@ is a named color. \cs{defaultlinkcolor} has a definition of
 \begin{Verbatim}[xleftmargin=\amtIndent]
 \newcommand{\defaultlinkcolor}{\@linkcolor}
 \end{Verbatim}
-\noindent where \cs{@linkcolor} is a command defined in
+where \cs{@linkcolor} is a command defined in
 \textsf{hyperref}, and is defined to be \texttt{red}. This can be
 redefined as desired.\footnote{The {\Web} package redefines
 \cs{@linkcolor} to be a flavor of green.}
@@ -1254,12 +1401,14 @@ The first link command is a general link for text, or any
 {\LaTeX} content. It is used, for example, by the \textsf{aeb\_mlink}
 package to create multiple-line links.
 
-\settowidth{\aebdimen}{\cs{setLinkText[\meta{options}]\darg{\meta{link\_text}}}}
-\begin{dCmd}[commandchars=!()]{\aebdimen+2\fboxsep+2\fboxrule}
+%\settowidth{\aebdimen}{\cs{setLinkText[\meta{options}]\darg{\meta{link\_text}}}}
+\bVerb\takeMeasure{\cs{setLinkText[\meta{options}]\darg{\meta{link\_text}}}}%
+\begin{dCmd}[commandchars=!()]{\bxSize}
 \setLink[!meta(options)]{!meta(link_text)}
 !grayV(\setLinkText[!meta(options)]{!meta(link_text)})
 \end{dCmd}
-\newtopic Both link commands are the same, the use of the second one, \cs{setLinkText} (grayed out), is
+\eVerb
+Both link commands are the same, the use of the second one, \cs{setLinkText} (grayed out), is
 discouraged in favor of the use of \cs{setLink}.
 
 \PD The command has two arguments, the first is optional. The first
@@ -1273,12 +1422,10 @@ anything that takes up space, such as a graphic or \cs{parbox}.
 
 \Example \setLink[\A{\JS{app.alert("AcroTeX rocks!")}}
     \linktxtcolor{blue}\Color{0 0 1}\W1\S{U}\H{P}]{Push me!}
-\begingroup\obeyspaces\settowidth{\aebdimen}{\ttfamily%
-    \string\linktxtcolor\darg{blue}\string\Color\darg{0 0 1}\string\W1\string\S\darg{U}\string\H\darg{P}]\darg{Push me!}%
-}%
-\begin{dCmd*}{\aebdimen+2\fboxsep+2\fboxrule}
+\bVerb\def\rB{]}\takeMeasure{\quad\string\linktxtcolor\darg{blue}\string\Color\darg{0 0 1}\string\W1\string\S\darg{U}\string\H\darg{P}\rB\darg{Push me!}}%
+\begin{dCmd*}[commandchars={~@$}]{\bxSize}
 \setLink[\A{\JS{app.alert("AcroTeX rocks!")}}
-    \linktxtcolor{blue}\Color{0 0 1}\W1\S{U}\H{P}]{Push me!}
+~quad\linktxtcolor{blue}\Color{0 0 1}\W1\S{U}\H{P}]{Push me!}
 \end{dCmd*}
 \endgroup
 
@@ -1290,11 +1437,13 @@ rather comprehensive article \textit{Support for Links in AeB/eForms},
 \newtopic\indent The next link command is a convenience command to put the link content into a parbox,
 the parameters enable you to set the width, height and position of material in the box.
 
-\settowidth{\aebdimen}{\cs{setLinkBbox[\meta{options}]\darg{\meta{width}}\darg{\meta{height}}}}
-\begin{dCmd}[commandchars=!()]{\aebdimen+2\fboxsep+2\fboxrule}
+%\settowidth{\aebdimen}{\cs{setLinkBbox[\meta{options}]\darg{\meta{width}}\darg{\meta{height}}}}
+\bVerb\takeMeasure{\cs{setLinkBbox[\meta{options}]\darg{\meta{width}}\darg{\meta{height}}}}%
+\begin{dCmd}[commandchars=!()]{\bxSize}
 \setLinkBbox[!meta(options)]{!meta(width)}{!meta(height)}
-    [!meta(position)]{!meta(link_content)}
+!quad[!meta(position)]{!meta(link_content)}
 \end{dCmd}
+\endgroup
 \PD The command has five arguments, the first is optional.
 \begin{aebDescript}
 \item [\meta{options}] are optional key-value pairs to change the appearance or action
@@ -1306,13 +1455,10 @@ the parameters enable you to set the width, height and position of material in t
 \end{aebDescript}
 
 \Example \setLinkBbox[\W{1}\Color{1 0 0}\A{\JS{app.alert("Thank you for using AcroTeX!")}}]{50bp}{30bp}[c]{\centering Press Me!}
-\begingroup\obeyspaces%
-\settowidth{\aebdimen}{\ttfamily%
-    \string\A\darg{\string\JS\darg{app.alert("Thank you for using AcroTeX!")}}%
-}%
-\begin{dCmd*}{\aebdimen+2\fboxsep+2\fboxrule}
+\bVerb\takeMeasure{\quad\string\A\darg{\string\JS\darg{app.alert("Thank you for using AcroTeX!")}}}%
+\begin{dCmd*}[commandchars={~@$}]{\bxSize}
 \setLinkBbox[\W{1}\Color{1 0 0}
-    \A{\JS{app.alert("Thank you for using AcroTeX!")}}
+~quad\A{\JS{app.alert("Thank you for using AcroTeX!")}}
 ]{50bp}{30bp}[c]{\centering Press Me!}
 \end{dCmd*}
 \endgroup
@@ -1795,7 +1941,7 @@ documentation in the \textsf{insdljs} package, which is distributed with
 the {\cAcroB}.
 
 \subsubsection{The Convenience Command
-    \texorpdfstring{\protect\cs{JS}}{\CMD{JS}}}\label{convienceJS}
+    \tops{\protect\cs{JS}}{\CMD{JS}}}\label{convienceJS}
 
 The syntax for writing JavaScript actions is
 \begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!~@]
@@ -1948,23 +2094,39 @@ is found on the {\AcroBlog} website.
 
 
 \subsection{Defining JavaScript Strings with
-    \texorpdfstring{\protect\cs{defineJSStr}}{\CMD{defineJSStr}}}
-
-The command \Com{defineJSStr} is used to define JavaScript strings, such as in dialog boxes.
-The syntax for this command is
-\settowidth{\aebdimen}{\cs{defineJSStr\darg{\cs{\anglemeta{CMD}}}\darg{\anglemeta{JS\_string}}}}
-\begin{dCmd}[commandchars=!()]{\aebdimen+2\fboxsep+2\fboxrule}
-\defineJSStr{\!anglemeta(CMD)}{!anglemeta(JS_string)}
+    \tops{\protect\cs}{\CMD}{flJSStr} and \tops{\protect\cs}{\CMD}{dlJSStr}}
+
+The \pkg{insdljs} package defines \cs{flJSStr} and \cs{dlJSStr} to
+help create JavaScript strings that contain Latin~1 glyphs (or for the
+general purpose of defining JavaScript strings).
+\bVerb\takeMeasure{\string\flJSStr*[\ameta{options}]\darg{\cs{\ameta{cmd}}}\darg{\ameta{JS\_string}}}%
+\def\1{\rlap{\hskip\linewidth\sffamily(Field level)}}%
+\def\2{\rlap{\hskip\linewidth\sffamily(Document level)}}%
+\begin{dCmd}[commandchars=!()]{\bxSize}
+!1\flJSStr*[!ameta(options)]{\!ameta(cmd)}{!ameta(JS_string)}
+!2\dlJSStr*[!ameta(options)]{\!ameta(cmd)}{!ameta(JS_string)}
 \end{dCmd}
-\PD Where \cs{\anglemeta{CMD}} is a command to be defined by
-\cs{defineJSStr}, for example, \cs{myMessage}, and \anglemeta{JS\_string} is
-the JavaScript string to be defined as the expansion of the
-\cs{\anglemeta{CMD}}.
-
-\CmdDescription \cs{defineJSStr} executes \verb!\xdef#1{"#2"}!, so
-the JavaScript is expanded at the time of definition. (Note the
-enclosing double quotes) Before the expansion occurs, however, there
-are a number of definitions that occur locally:
+\eVerb The previously documented \cs{defineJSStr} command is now an alias for
+\cs{flJSStr}. Each command defines a new command \cs{\ameta{cmd}} with body
+\meta{JS\_string}. The command \cs{flJSStr} is designed to define JavaScript
+strings that are passed through the optional argument of a form field or link
+annotation, whereas \cs{dlJSStr} is used for a Document JavaScript string,
+that is, one that is inserted into a \env{insDLJS} environment of the
+\pkg{insdljs} package. Document JavaScript is implemented differently
+depending on the driver used, as a result, \cs{dlJSStr} is more driver
+dependent than is \cs{flJSStr}.
+
+\paragraph*{Options discussed.} When the optional star (\texttt{*}) is present, the
+\meta{JS\_string} argument is passed to \cs{pdfstringdef} before the
+definition of \cs{\ameta{cmd}}. The \meta{options} argument may consist of
+one or more of the keywords \texttt{quotes}, \texttt{noquotes},
+\texttt{parens}, \texttt{noparens}. By default, \ameta{JS\_String} is enclosed
+in double quotes, unless the option \opt{noquotes} is taken.
+The \texttt{parens} option causes \pkg{insdljs} to enclose \meta{JS\_string} in parentheses; while
+\texttt{noparens} specifies not to enclose the string in parentheses. The default is \opt{noparens}.
+
+\CmdDescription Prior to defining \cs{\ameta{cmd}}, there are a number of
+definitions that occur locally:
 \begin{itemize}
   \item \cs{uXXXX} is recognized as a unicode escape sequence. So, within the JavaScript string,
   unicode can be entered directly, for example, \cs{u00FC} is the u-umlaut.
@@ -1984,68 +2146,20 @@ are a number of definitions that occur locally:
   a literal double quote, use \verb!\\"! to get a literal double quote
   to appear in a JavaScript string. For example,
 \begin{Verbatim}[xleftmargin=\amtIndent]
-\defineJSStr{\myMessage}
+\flJSStr{\myMessage}
     {My name is \\"Stan\\" and I'm \\"the man.\\"}
 \end{Verbatim}
 
   \item The command \cs{jslit} is recognized within the JavaScript string. Using \cs{jslit}
   (short for JavaScript literal), you can insert, for example, unbalanced braces:
 \begin{Verbatim}[xleftmargin=\amtIndent]
-\defineJSStr{\myMessage}
+\flJSStr{\myMessage}
     {You forgot the left brace \\"\jslit\{\\",
      please insert it.}
 \end{Verbatim}
 The definition of \cs{jslit} is \verb!\let\jslit\string!.
-
-
 \end{itemize}
 
-\newtopic The design decision to automatically insert the double
-quotes in the definition of the string has its faults. When you want
-to break the string to insert dynamic content, you must always be
-aware of the definition \verb!\xdef#1{"#2"}! contained with the
-definition of \cs{defineJSStr}. To illustrate, we return to an
-earlier example presented in \nameref{lengthyJS}, on
-page~\pageref*{lengthyJS}.
-
-We begin by defining some JavaScript strings. Note that in each of
-these two definitions, the leading and trailing double quote
-(\texttt{"}) is missing (these are the ones inserted automatically).
-The definitions look a bit strange because we break the string to
-insert dynamic content (\texttt{f.value}, \texttt{f.getItemAt(a,
-false)}, etc.), then continue on with the string from there.
-
-\begin{Verbatim}[xleftmargin=\amtIndent]
-\defineJSStr\myAlerti{You've typed in \\"" + f.value +"\\".}
-\defineJSStr\myAlertii{Selection: " + f.getItemAt(a, false)
-   + " (export value: " + f.getItemAt(a, true)+").}
-\end{Verbatim}
-
-\newtopic We use the \texttt{defineJS} environment, after setting the escape code to \texttt{@}. The \texttt{defineJS}
-is a fully verbatim environment, the escape character cannot be changed to \verb!\!, but it
-may be changed to another character, such as \texttt{@}.
-
-\begin{Verbatim}[xleftmargin=\amtIndent]
-\begin{defineJS}[\catcode`\@=0\relax]{\getComboJS}
-var f = this.getField("myCombo");
-var a = f.currentValueIndices;
-if ( a == -1 )
-    app.alert(@myAlerti);
-else
-    app.alert(@myAlertii);
-\end{defineJS}
-\end{Verbatim}
-
-\newtopic Then again, the use of \cs{defineJSStr} is not required, it is a convenience for creating
-JavaScript strings, especially ones with embedded Unicode. The previous example could have been
-done by defining \cs{myAlerti} and \cs{myAlertii} by
-\begin{Verbatim}[xleftmargin=\amtIndent]
-\newcommand\myAlerti{"You've typed in \\"" + f.value +"\\"."}
-\newcommand\myAlertii{"Selection: " + f.getItemAt(a, false)
-   + " (export value: " + f.getItemAt(a, true)+")."}
-\end{Verbatim}
-\noindent Note the \emph{presence} of the leading and trailing double quotes.
-
 \section{The \texttt{useui} option: A User-Friendly Interface}\label{useui}
 
 \def\myFavFive{%
@@ -2056,17 +2170,16 @@ uptxt={Push Me}}
 
 To use the ``user-friendly'' interface, the \texttt{useui} option must be taken. The key-value pairs
 described below are enclosed as the argument of the special \cs{ui} key.  For example,
-\bgroup\obeyspaces\ttfamily%
-\settowidth{\aebdimen}{    bordercolor=\darg{1 0 0},bgcolor=\darg{0 1 0},}%
-\begin{dCmd*}{\aebdimen+2\fboxsep+2\fboxrule}
+\bVerb\takeMeasure{{\quad}bordercolor=\darg{1 0 0},bgcolor=\darg{0 1 0},}%
+\begin{dCmd*}[commandchars={!@^}]{\bxSize}
 \pushButton[\ui{%
-    bordercolor={1 0 0},bgcolor={0 1 0},
-    textcolor={1 0 0},align={right},
-    uptxt={Push Me},
-    js={app.alert("AcroTeX rocks!")}
+@!quad^bordercolor={1 0 0},bgcolor={0 1 0},
+@!quad^textcolor={1 0 0},align={right},
+@!quad^uptxt={Push Me},
+@!quad^js={app.alert("AcroTeX rocks!")}
 }]{pb1}{}{11bp}
 \end{dCmd*}
-\egroup\newtopic You can develop your own set of appearances and use the \texttt{presets} key to conveniently set these.
+\endgroup\newtopic You can develop your own set of appearances and use the \texttt{presets} key to conveniently set these.
 For example,
 \begin{Verbatim}[xleftmargin=\amtIndent]
 \def\myFavFive{%
@@ -2094,10 +2207,12 @@ displayed in the margin. Some of the user-friendly are a combination of
 We present these key-value pairs to model the user-interface of \app{Acrobat}.
 
 
-\settowidth{\aebdimen}{\ttfamily border=visible|invisible}
-\begin{dCmd}[commandchars=!()]{\aebdimen+2\fboxsep+2\fboxrule}
+%\settowidth{\aebdimen}{\ttfamily border=visible|invisible}
+\bVerb\takeMeasure{border=visible|invisible}%
+\begin{dCmd}[commandchars=!()]{\bxSize}
 border=visible|invisible
 \end{dCmd}
+\endgroup
 \CmdDescription Used with link annotations and determines whether the border
 surrounding the bounding box of the link is visible. In the case of a link,
 this is the Link Type: \textsf{Visible Rectangle} or \textsf{Invisible
@@ -2759,7 +2874,7 @@ The \cs{setTabOrder} command is available for users of pdftex and dvipdfm, as we
 \setTabOrderByNumber
 \end{dCmd}
 
-\subsection{Using \texorpdfstring{\protect\cs{setTabOrderByList}}{\CMD{setTabOrderByList}}}
+\subsection{Using \tops{\protect\cs{setTabOrderByList}}{\CMD{setTabOrderByList}}}
 
 We illustrate with a simple example, followed by a verbatim listing of the code, and a discussion
 afterward. We begin by placing two text fields in a row; normally,we would tab from the first one created
@@ -2824,7 +2939,7 @@ b\hspace{9.5pt}}}}}}\texttt{\href{\urlAcroTeXBlog/?p=320}{settaborder.pdf}} for
 including tabbing using structure, has its source file attached to the PDF file.
 The file is posted one the \href{\urlAcroTeXBlog}{AeB Blog}.
 
-\subsection{Using \texorpdfstring{\protect\cs{setTabOrderByNumber}}{\CMD{setTabOrderByNumber}}}
+\subsection{Using \tops{\protect\cs{setTabOrderByNumber}}{\CMD{setTabOrderByNumber}}}
 
 An alternate method for setting tab order by structure is to directly enter the tab order into the
 optional argument of the field, link, or comment annotation.
@@ -2916,16 +3031,37 @@ embedding of the JavaScripts.
 
 \newtopic Other options are discussed in the following paragraphs.
 \begin{description}\def\NH{\hspace{-\labelsep}}
-\item\NH\texttt{nodljs} turns off the embedding of the document level
+\item\NH\opt{nodljs} turns off the embedding of the document level
     JavaScript. This might be useful, for creating a paper document that is
     not interactive. For a non-interactive paper document, no JS is needed.
 
-\item\NH\texttt{execJS} is a very useful option/feature if you know  how to use
+\item\NH\opt{execJS} is a very useful option/feature if you know  how to use
     it.  Any JavaScript that is written in an \env{execJS} environment is
     executed once when the document is first opened in \app{Acrobat}, then
     discarded. AeB uses this for post-distillation document processing. The
     default is that the JavaScript in an \texttt{execJS} environment is not
     executed; using this option turns on this feature.
+
+\item\NH\opt{usealtadobe} imports alternate naming for most of Adobe's
+    built in functions. All of Adobe built in functions begin with `AF',
+    when this option is taken, the same functions are defined, but prefixed
+    with `EF'. For example, \texttt{AFNumber\_Keystroke()} has an alias of
+    \texttt{EFNumber\_Keystroke()}, when the \opt{usealtadobe} option is
+    specified.
+
+    \textbf{Developer's Note.} Use this option when developing new code
+    that use the Adobe built-in functions. For developers that have
+    \app{Acrobat}, it is useful to specify this option and to refer to the
+    built-in function using the special syntax,
+    \[\cs{dl@EForAF4\ameta{no-AF-function-name}}\]
+    For example, \cs{dl@EForAF4Number\_Keystroke(0,0,0,0,"",true)} expands to
+    \[\texttt{EFNumber\_Keystroke(0,0,0,0,"",true)}\] if \opt{usealtadobe} is taken,
+    and \[\texttt{AFNumber\_Keystroke(0,0,0,0,"",true)}\] otherwise.
+
+\item\NH\opt{debug} causes the document JavaScript created by the
+    {\AcroTeX} Bundle to generate more debugging messages to the JavaScript
+    console.
+
 \end{description}
 
 \section{The \texttt{insDLJS} and \texttt{insDLJS*} Environments}
@@ -3463,7 +3599,7 @@ Use \env{defineJS*} in the body of the document; the command argument \cs{\ameta
 used and redefined in a later \env{defineJS*} environment.
 The \env{@defineJS} environment is for package authors.
 
-\paragraph*{The \texorpdfstring{{\protect\env{defineJS}}}{defineJS}-type environments with arguments.}\label{para:defineJSwArgs}
+\paragraph*{The \tops{{\protect\env{defineJS}}}{defineJS}-type environments with arguments.}\label{para:defineJSwArgs}
 %\index{defineJS with arguments@\env{defineJS} with arguments}
 The \env{defineJS}-type environments do not have parameters/arguments as
 normal environments (or commands) do. To enable the ability to  modify the
-- 
cgit v1.2.3

