summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/forms16be/doc
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/forms16be/doc
Initial commit
Diffstat (limited to 'macros/latex/contrib/forms16be/doc')
-rw-r--r--macros/latex/contrib/forms16be/doc/forms16be-man.pdfbin0 -> 861001 bytes
-rw-r--r--macros/latex/contrib/forms16be/doc/forms16be-man.tex327
2 files changed, 327 insertions, 0 deletions
diff --git a/macros/latex/contrib/forms16be/doc/forms16be-man.pdf b/macros/latex/contrib/forms16be/doc/forms16be-man.pdf
new file mode 100644
index 0000000000..e611305136
--- /dev/null
+++ b/macros/latex/contrib/forms16be/doc/forms16be-man.pdf
Binary files differ
diff --git a/macros/latex/contrib/forms16be/doc/forms16be-man.tex b/macros/latex/contrib/forms16be/doc/forms16be-man.tex
new file mode 100644
index 0000000000..c9179b2136
--- /dev/null
+++ b/macros/latex/contrib/forms16be/doc/forms16be-man.tex
@@ -0,0 +1,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}