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/aeb_tilebg/doc/aebbgtile_man.tex |
Initial commit
Diffstat (limited to 'macros/latex/contrib/aeb_tilebg/doc/aebbgtile_man.tex')
-rw-r--r-- | macros/latex/contrib/aeb_tilebg/doc/aebbgtile_man.tex | 519 |
1 files changed, 519 insertions, 0 deletions
diff --git a/macros/latex/contrib/aeb_tilebg/doc/aebbgtile_man.tex b/macros/latex/contrib/aeb_tilebg/doc/aebbgtile_man.tex new file mode 100644 index 0000000000..166711eb86 --- /dev/null +++ b/macros/latex/contrib/aeb_tilebg/doc/aebbgtile_man.tex @@ -0,0 +1,519 @@ +% makeindex < aebpro_man.idx > aebpro_man.ind +\documentclass{article} +\usepackage[fleqn]{amsmath} +\usepackage[ + web={centertitlepage,designv,forcolorpaper,tight*,latextoc,pro}, + eforms, + linktoattachments, +% attachments={../aeb_pro.dtx}, +% uselayers, + aebxmp +]{aeb_pro} +\usepackage{graphicx,array,fancyvrb} +\usepackage[altbullet]{lucidbry} +%\usepackage{myriadpro} +%\usepackage{calibri} + +%\usepackage{makeidx} +%\makeindex +\usepackage{acroman} + +\def\meta#1{$\langle\textit{\texttt{#1}}\rangle$} +\let\ameta\meta + +\usepackage[active]{srcltx} + +\urlstyle{tt} + +%\def\tutpath{doc/tutorial} +%\def\tutpathi{tutorial} +\def\expath{../examples} + +\DeclareDocInfo +{ + university={\AcroTeX.Net}, + title={The \textsf{aeb\_tilebg} Package\texorpdfstring{\\}{: }Creating Tiled Backgrounds}, + author={D. P. Story}, + email={dpstory@acrotex.net}, + subject=Documentation for the aeb\_tilebg package, + talksite={\url{www.acrotex.net}}, + version={1.2, 2018/04/26}, + keywords={LaTeX, Web package, tiled backgrounds, Adobe Acrobat}, + copyrightStatus=True, + copyrightNotice={Copyright (C) \the\year, D. P. Story}, + copyrightInfoURL={http://www.acrotex.net} +} + +\def\dps{$\hbox{$\mathfrak D$\kern-.3em\hbox{$\mathfrak P$}% + \kern-.6em \hbox{$\mathcal S$}}$} + +%\def\anglemeta#1{$\langle\textit{\texttt{#1}}\rangle$} +%\def\meta#1{\textit{\texttt{#1}}} +\def\darg#1{\texttt{\{#1\}}} +\def\takeMeasure{\bgroup\obeyspaces\takeMeasurei} +\def\takeMeasurei#1{\global\setbox\webtempboxi\hbox{\ttfamily#1}\egroup} +\def\bxSize{\wd\webtempboxi+2\fboxsep+2\fboxrule} +\let\pkg\textsf +\let\env\texttt +\let\opt\texttt +\let\app\textsf + +\let\amtIndent\parindent %\leftmargini +\def\SUB#1{${}_{\text{#1}}$} + +\newdimen\aebdimen \aebdimen 0pt %\advance\aebdimen\partopsep +\newcommand\bVerb[1][]{\begingroup#1\vskip\aebdimen\parindent0pt}% +\def\eVerb{\vskip\aebdimen\endgroup\noindent} + +\makeatletter +\renewcommand{\paragraph} + {\@startsection{paragraph}{4}{0pt}{6pt}{-3pt}{\bfseries}} +\renewcommand*\l@subsection{\@dottedtocline{2}{1.5em}{2.5em}} +\renewcommand*\descriptionlabel[1]{\hspace\labelsep + \normalfont #1} +\newcommand{\aebDescriptionlabel}[1]{% + \setlength\dimen@{\amtIndent+\labelsep}% + {\hspace*{\dimen@}#1}} +\makeatother +\newenvironment{aebDescript} + {\begin{list}{}{\setlength{\labelwidth}{0pt}% + \setlength{\leftmargin}{\leftmargin}% + \setlength{\leftmargin}{\leftmargin+\amtIndent}% + \setlength\itemindent{-\leftmargin}% + \let\makelabel\aebDescriptionlabel + }}{\end{list}} + +\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}} + +%\pagestyle{empty} +%\parindent0pt\parskip\medskipamount + + +\chngDocObjectTo{\newDO}{doc} +\begin{docassembly} +var titleOfManual="The aeb_tilebg MANUAL"; +var manualfilename="Manual_BG_Print_tilebg.pdf"; +var manualtemplate="Manual_BG_Brown.pdf"; // Blue, Green, Brown +var _pathToBlank="C:/Users/Public/Documents/ManualBGs/"+manualtemplate; +var doc; +var buildIt=true; +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} + +%\setTileBgGraphic[scale=.5]{brewtile1} +%\setTileBgGraphic[scale=.5]{math-bkgrd} +%\setTileBgGraphic[scale=.25]{bike_10} +%\setTileBgGraphic[scale=.2]{tile/tmfpurple_50} +%\setTileBgGraphic[scale=1]{g8pat26} +%\setTileBgGraphic[scale=.5]{th11an12_20} +% n_rows, n_columns, left,right,top, bottom +%\autosetScreensizeWithMargins{4}{3}{.25in}{.25in}{24pt}{.25in} +%\autosetScreensizeWithMargins{7}{5}{.25in}{.25in}{24pt}{.25in} + +%\textBgColor{cornsilk} + +%\setTileBgGraphic[scale=.75]{tile/brewtile1} + +\section{Introduction} + +This package, \texttt{aeb\_tilebg}, is a simple application +of established packages \textsf{graphicx}, \textsf{multido} and +\pkg{web}. + +Download your favorite tiled background swatch from the Internet or create one yourself, +convert it to an \texttt{.eps} or a \texttt{.pdf} format (depending +if you use \textsf{distiller} or \textsf{pdftex}), place that image +in the same folder as your source document. Anywhere in your +document, use the command \verb!\setTileBgGraphic! to bring in your +tiled background using the \textsf{graphicx} package; for example, +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +\setTileBgGraphic[scale=.5]{!meta(graphics_file)} +\end{Verbatim} +The \textsf{multido} package places these images in the background, +starting from the upper-left corner (the lower left corner if the +\texttt{uselltiling} option is taken) going across and down +(respectively, going across and up), one row at a time. The \pkg{web} +package is used to manage the graphical template created. + +During the development of this package, I Googled ``backgrounds'', +``tiled backgrounds'' and ``math tiled backgrounds'' and found, +amongst many, the following links +\begin{quote} +\url{http://www.patswebgraphics.com/tiled.html}\\ +\url{http://www.rhiossampler.com/Backgrounds/TBGIndex.htm}\\ +\url{http://www.backgroundcity.com/}\\ +\url{http://www.wou.edu/~burtonl/mathart/mathart.html} +\end{quote} +I downloaded a few of the swatches and used them during the testing +phase. The mathematical tiles of last the URL listed above are +particularly interesting. + +\section{Alternate package name: \texorpdfstring{\protect\pkg{aeb-tilebg}}{aeb-tilebg}} + +This package is listed on CTAN as \pkg{aeb-tilebg}, there is now a `dummy' package by +that name that loads \pkg{aeb\_tilebg} with the specified options. + +\section{The Preamble and Package Options} + +In the preamble, place the \textsf{aeb\_tilebg} package like so +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +\usepackage[!meta(options)]{aeb_tilebg} +\end{Verbatim} +This must be placed after the introduction of the web package. A +typical preamble might be +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +\documentclass{article} +\usepackage[!meta(driver),tight,designiv,usetemplates]{web} +\usepackage[!meta(options)]{aeb_tilebg} +\end{Verbatim} +where \meta{driver} can be \texttt{dvipsone}, \texttt{dvips} or +\texttt{pdftex} (which include the \textsf{lualatex} application) and +\texttt{xetex}. Only the \texttt{usetemplates} option and the driver type +are required options here, the others are optional.\footnote{The \textsf{web} package +automatically detects \textsf{pdftex} and \textsf{xetex} so they need not be specified.} + +The options of the \textsf{aeb\_tilebg} package are as follows: +\begin{enumerate} +\item \texttt{uselltiling}: When the package tiles a background, it +begins in the upper left corner, goes across the row from left to +right, then moves downward to the next row. This is the default +behavior. The algorithm uses the multido command and floating point +arithmetic; there may be some round off that leaves the tiles not +quite contiguous, though I haven't observed this myself. If the +upper-left starting point does not give satisfactory results, try +using \texttt{uselltiling}, this option causes \textsf{aeb\_tilebg} +to begin tiling in the lower-left corner; tiling moves left-to-right +and upward. This uses a faster, more accurate algorithm of multido +and should be superior and give the contiguous tiling you want. +\item \texttt{draft}: Tiling slows down {\LaTeX} compilation and +obscures the text content as viewed in the previewer; therefore, use +the \texttt{draft} to suppress tiling during the content development +phase of the document. Remove the option to build the final +document. +\item \texttt{ignoreforpaper}: The default behavior of +\textsf{aeb\_tilebg} is to automatically remove the tiling when the +\texttt{forpaper} option of the \pkg{web} package is selected. To +ignore this default ``forpaper'' behavior, select the +\texttt{ignoreforpaper} option; then, even if the \texttt{forpaper} +option is used, tiling of the document will occur. +\end{enumerate} + +\section{The Commands} + +There are only a few commands of this package, which we list and +discuss in this section. + +To specify the graphics file that is to be tiled, use the +\cs{setTileBgGraphic}, the central command of this package: +\bVerb\takeMeasure{\string\setTileBgGraphic[\meta{key\_values}]\darg{\meta{filename}}}% +\begin{dCmd}[commandchars=!()]{\bxSize} +\setTileBgGraphic[!meta(key_values)]{!meta(filename)} +\end{dCmd} +\endgroup +\PD The two parameters are passed to the \cs{includegraphics} +command of the \textsf{graphicx} package, consequently, their descriptions are +the same: the \texttt{\ameta{filename}} is the base name of the graphics +file and \texttt{\ameta{key\_values}} are any options of the +\cs{includegraphics} command desired. The package automatically +inserts the \texttt{hiresbb} option of \cs{includegraphics} to get a +better fit of the tiles; specifying this option, therefore, is not +needed. + +\CmdLoc This command can be placed in the preamble to tile beginning +at the first page, or anywhere in the body of the document to tile +the current page, and all pages thereafter. The tile graphic can be +changed freely, just by specifying a new graphics file in the +\cs{setTileBgGraphic} command. + +Below is an example of usage: +\bVerb\takeMeasure{\string\setTileBgGraphic[scale=.5]\darg{IndianBlanket}}% +\begin{dCmd*}[commandchars=!()]{\bxSize} +\setTileBgGraphic[scale=.5]{IndianBlanket} +\end{dCmd*} +\eVerb +The \texttt{scale} option re-scales the graphics by a factor given +as its value. This option is often used to set the size of the +tile, appropriate to the screen size. Other useful options are +\texttt{width} and \texttt{height}. + +You can disable and enable tiling using the following two commands:% +\bVerb\takeMeasure{\string\disableTiling\quad\string\enableTiling}% +\begin{dCmd}[commandchars=!()]{\bxSize} +\disableTiling!quad\enableTiling +\end{dCmd} +\eVerb +When you execute \cs{enableTiling}, the graphic tile currently +defined will be used. You can change the tiling as well + +You can disable tiling by using the \verb!\disableTiling! command then\dots +\bVerb\takeMeasure{\string\setTileBgGraphic[scale=.2]\darg{tmfpurple\_50}}% +\begin{dCmd*}[commandchars=!()]{\bxSize} +\disableTiling +... +\enableTiling +\setTileBgGraphic[scale=.2]{tmfpurple_50} +\end{dCmd*} +\eVerb +For \texttt{multido}, the number of iterations must be specified in +advance. The \textsf{aeb\_tilebg} package uses \cs{multidostop} to +break out of a \texttt{multido} loop early. By default it is set at +10, but can be changed through the \cs{maxiterations} +command,\footnote{It may become necessary to increase this number if +you decide to have a lot of tiles per page (increasing the size of +your file, I might add) or if you use the \texttt{ignoreforpaper} +command, where you are now trying to tile a larger area than +typically is done for the screen.}% +\bVerb\takeMeasure{\string\maxiterations\darg{\meta{number}}}% +\begin{dCmd}[commandchars=!()]{\bxSize} +\maxiterations{!meta(number)} +\end{dCmd} +\eVerb +here, the parameter \meta{number} is the maximum number of iterations to +be performed by the (nested) \texttt{multido}'s that tile the background. +The default is \verb!\maxiterations{10}!. + +\exSrc{tilebg_tst} The file \texttt{tilebg\_tst.tex} is the demo file +for the above series of commands. + +\newtopic The tiling algorithm automatically determines how many +rows and columns you need to completely cover the background. This, +of course, leads to partial tiles appearing in the background. In +most cases this is not a problem; however, if you are particularly +picky, you want only complete tiles to appear, no partials please. +To accomplish this wonder feat of magic, use the +\cs{autosetScreensizeWithMargins} command.% +\bVerb\takeMeasure{\small\string\autosetScreensizeWithMargins\darg{\meta{n\_rows}}% +\darg{\meta{n\_cols}}\darg{\meta{lm}}\darg{\meta{rm}}\darg{\meta{tm}}\darg{\meta{bm}}}% +\begin{dCmd}[fontsize=\small,commandchars={!()}]{\bxSize} +\autosetScreensizeWithMargins{!meta(n_rows)}{!meta(n_cols)}{!meta(lm)}{!meta(rm)}{!meta(tm)}{!meta(bm)} +\end{dCmd} +\endgroup +\PD The command has six parameters, as listed below and described +briefly. +\begin{enumerate} +\item \meta{n\_rows}: number of rows +\item \meta{n\_cols}: number of columns +\item \meta{lm}: length of left margin +\item \meta{rm}: length of right margin +\item \meta{tm}: length of top margin +\item \meta{bm}: length of bottom margin +\end{enumerate} +\Important This command, which sets the screen dimensions of the +document, can be used only in the preamble. When using this command, +do not specify a design argument for the \pkg{web} package,\footnote{This is +referring to the \pkg{web} options of +\texttt{designi}--\texttt{designvii}.} and don't use either the +\cs{margins} or \cs{screensize} commands of \pkg{web} as these two +commands are used by \cs{autosetScreensizeWithMargins}. + +An example of usage is\setbox\webtempboxi\hbox{\ttfamily\string\autosetScreensizeWithMargins\{7\}\{5\}\{.25in\}\{.25in\}\{24pt\}\{.25in\}}% +\begin{dCmd*}{\wd\webtempboxi+2\fboxsep} +\setTileBgGraphic[scale=.25]{bike_10} +\autosetScreensizeWithMargins{7}{5}{.25in}{.25in}{24pt}{.25in} +\end{dCmd*} +The last four parameters are typical margin settings for the \pkg{web} +package. + +\exSrc{tilebg_tst_auto} \texttt{tilebg\_tst\_auto.tex} is the demo file +for the \cs{autosetScreensizeWithMargins} command. + +\section{Reducing the file size} + +Tiling the background increases the file size of the document. I believe +pdftex and xetex can reuse a graphics file to reduce the file size, and +does a decent job. + +\subsection{Tiling using the \textsf{graphicxsp} package} + +One approach to reducing file size is to embed your tile graphic once and +use and reuse it without significantly increasing file size. How is this +done? Using the \textsf{graphicxsp} package. + +We outline the method through example. In the preamble, we have, +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +\usepackage[tight,designiv,usetemplates]{web} +\usepackage{graphicxsp} +\usepackage{aeb_tilebg} + +\embedEPS[transparencyGroup]{bike}{tile/bike_10} +\setTileBgGraphic[name=bike, + transparency={/ca .3},scale=.25]{tile/bike_10} +%\autosetScreensizeWithMargins{7}{5}{.25in}{.25in}{24pt}{.25in} +\end{Verbatim} +You can optionally set the dimensions of the page to exactly 7 rows and 5 +columns. With \textsf{graphicxsp}, you embed the graphic using +\cs{embedEPS} and give it a name, \texttt{bike} in this example. In the +optional argument of \cs{setTileBgGraphic} we pass that name using the +\meta{name} key and pass some transparency settings as well. See the +documentation of \texttt{graphicxsp} for more information. + +\exSrc{tilebg_tst_sp} \texttt{tilebg\_test\_sp.tex} is the test file for +demonstrating this method. Acrobat Distiller is required as the PDF +creator. + +\subsection{Tiling using \textsf{graphicxsp} and layers} + +One criticism of a background or tiled background is that it is really not +desired when the document is printed. However, if you put the background +in layers and set the layers never to print, the problem is solved. To use +layers, the \texttt{uselayers} option of the \textsf{aeb\_pro} package +must be used (with Distiller as the PDF creator). To get the tiles to +appear in their a layer (all in the same layer), use the +\textsf{aeb\_tilebg} \cs{placeTilesinLayers} command. +\bVerb\takeMeasure{\string\placeTilesinLayers[\meta{name}]\darg{\meta{KV-pairs}}}% +\begin{dCmd}[commandchars={!()}]{\bxSize} +\placeTilesinLayers[!meta(name)]{!meta(KV-pairs)} +\end{dCmd} +\eVerb +The \meta{name} argument is the name of the layer, the default is +\texttt{tileBG}. The \meta{KV-pairs} argument consists of key-value pairs +that are recognized by the \cs{xBld} command of {\AEBP}, refer to the +documentation of \cs{xBld} in the {\AEBP} manual. + +We outline the method through example. In the preamble, we have, +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +\usepackage[ + graphicxsp,uselayers, + web={tight,designiv,usetemplates} +]{aeb_pro} +\usepackage{aeb_tilebg} +\embedEPS[transparencyGroup]{bike}{tile/bike_10} +\placeTilesinLayers{initState=on,print=never} +\setTileBgGraphic[name=bike, + transparency={/ca .3},scale=.25]{tile/bike_10} +\end{Verbatim} +This is pretty much the same as the previous example, except \textsf{aeb\_pro} +is used with the \texttt{uselayers} option. + +\exSrc{tilebg_tst_layers}\texttt{tilebg\_tst\_layers.tex} is the test file for +demonstrating this method. Acrobat Distiller is required as the PDF +creator, the \texttt{Standard\_transparency.joboptions}, which ships with \pkg{aeb\_pro}, +is required to distill this file so it has a transparent background. + +\begin{comment} +\subsection{Using Acrobat Pro} + +The key to this technique is to use the +\texttt{addWatermarkFromFile()} JavaScript method for Acrobat. For +convenience, it is suggested that the \texttt{aeb\_pro} package be +used to make this technique straightforward. The preamble might look +like the following: +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small] +\documentclass{article} +\usepackage[ + web={tight,usetemplates} +]{aeb_pro} +\usepackage{aeb_tilebg} +\end{Verbatim} + +The steps are as follows: +\begin{enumerate} + \item Open the file \texttt{tilebg\_blank.tex}. This is a simple + file that produces one (or more) page(s). Set the design + parameter of \Web, as desired, or, remove the design option, set + your own screen size, or let \cs{autosetScreensizeWithMargins} + set the size by using, as described above (using a graphic tile + of your choice). + \item Compile the file, distill, and save the \texttt{.pdf} with a name + of your choice. + \item Now, in your document, the one that uses + \texttt{aeb\_pro}, insert the \texttt{docassembly} environment + in the preamble: +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small] +\begin{docassembly} +\addWatermarkFromFile({ + bOnTop:false, + cDIPath:"/C/acrotex/aeb_tilebg/bike_bg.pdf" +}); +\executeSave(); +\end{docassembly} +\end{Verbatim} + \item If you are not using \cs{autosetScreensizeWithMargins}, + in the preamble, set up the file without any tiling by executing + \cs{disableTiling}. If you are using the command + \cs{autosetScreensizeWithMargins}, the screen size must be set + up to match the screen size of your background template; + in this case, your preamble should read something like this +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small] +\setTileBgGraphic[scale=.25]{tile/bike_10} +\autosetScreensizeWithMargins{7}{5}{.25in}{.25in}{24pt}{.25in} +\disableTiling +\end{Verbatim} +\item Compile and distill, the Acrobat JavaScript retrieves your +background template embeds it in the PDF document, and uses and +reuses the graphic on each of the specified pages. +\end{enumerate} +\exSrc{tilebg_tst_pro} See the files \texttt{tilebg\_blank.tex} and +\texttt{tilebg\_tst\_pro.tex} for an example. +\end{comment} + +\subsection{Comparison of file sizes} + +We build and noted the file size of one of the test files under various +conditions. +\begin{flushleft} +\hspace*{\amtIndent}\begin{tabular}{llll} +\textbf{Driver}&\textbf{graphicx}&\textbf{graphicxsp}&\textbf{Reduced Size PDF}\\ +\texttt{dvips}&797KB&42KB&23KB\\ +\texttt{pdftex}&62KB&--&--\\ +\texttt{xetex}&27KB&--&-- +\end{tabular} +\end{flushleft} +Using the standard graphics package \texttt{graphicx}, \texttt{dvips} does +the worst with \texttt{xetex} doing best. For \texttt{dvips}, with the +test file uses \texttt{graphicxsp}, the file size is reduced to +\texttt{43KB}, and reduced further when the Reduced Size PDF operation is +performed by Acrobat, accessed through the menu +\texttt{File\;>\;Save\;As\;Other\;>\;Reduced\;Size\;PDF}.\footnote{The user-interface is often redesigned, this is the location +for Acrobat~11.} + +% 797KB (no sp) +% 42KB (sp) 23KB (reduced) +% 51KB, 26KB reduced (sp in layers) + +% 62KB (pdftex) +% 27KB (xetex) + +\newtopic\noindent +Now, I simply must get back to my retirement. \dps + +\end{document} |