diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /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.pdf | bin | 0 -> 861001 bytes | |||
-rw-r--r-- | macros/latex/contrib/forms16be/doc/forms16be-man.tex | 327 |
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 Binary files differnew file mode 100644 index 0000000000..e611305136 --- /dev/null +++ b/macros/latex/contrib/forms16be/doc/forms16be-man.pdf 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} |