\makeatletter
\documentclass[
  use-a4-paper,
  use-10pt-font,
  final-version,
  use-UK-English,
  fancy-section-headings,
  frame-section-numbers,
  para-abstract-style,
  input-config-file,
  no-hyperref-messages,
  option-stack-limit=4,
  inputfile=true
]{amltxdoc}

\makeindex
\ifdefTF\newgeometry{}{%
  \let\newgeometry\@gobble
  \let\restoregeometry\relax
}

\begin{document}

\begin{frontmatter}
\title{The \texttt{\color{blue}xwatermark} Package\titleref{t1}}
\titlenote[t1]{The package is available at
  \iftogTF{pdf}{\url{\@titleurl}}{\url{\@shorttitleurl}}.
}
\version{1.5.1}
\titleurl{http://www.ctan.org/tex-archive/macros/latex/contrib/xwatermark/}
\shorttitleurl{http://www.ctan.org/}
\author{Ahmed Musa\Email{amusa22@gmail.com}\\Preston, Lancashire, UK}

\let\abstractname\relax
\begin{abstract}
\makecolorbox[framesep=4pt, framerule=1pt, innerframecolor=red!55,
  outerframecolor=ForestGreen, align=justified, fillcolor=white,
  width=\textwidth, boxalign=center, height=.25cm, depth=0cm,framebox]{%
  \centering\xwmcolorbox[align=center, fillcolor=white, innerframecolor=blue, outerframecolor=orange, width=.5\hsize, height=2.5mm]{\textbf{Abstract}} \\[\baselineskip]
  The \pkg{xwatermark} package puts user-supplied watermarks (graphics and/or arbitrary texts) on select pages of documents using user-friendly key-value interfaces. It has more functionality and dynamism than, for example, the packages \pkg'{draftcopy, draftwatermark, watermark, draftmark, wallpaper}. More than one (graphics and/or text) watermark can be placed jointly or independently on the same document page or on select pages. Watermarks can be placed in the page background or foreground, and watermarks can conveniently be placed on select pages as rectangular or square tiles, depending on the user's choice. Some utility macros, namely, \ffx'{\xwmminipage, \xwmcolorbox, \makecolobox, \fancypagenos} are also provided by the package for handy use in creating watermarks and for other uses. Watermarks (especially wallpapers) take their toll on computer resources, especially speed and save stack size. The packages in the \pkg{xwatermark} bundle (and beyond) have been optimized as much as currently possible. In many instances more than one run of the document will be needed to get the watermarks on the desired pages, especially if the user calls \fx{\lastdocpage} to get the last page of the document.
}
\end{abstract}
\end{frontmatter}

\vspace{4\baselineskip}

\newpage

\begin{xwmshade}[fillcolor=white,framecolor=orange,framerule=1pt,framesep=2pt,
  width=\hsize]\tableofcontents
\end{xwmshade}


\docsection(sec:intro){Introduction}

\lletter{T}{he \pkg'{xwatermark}} puts user-specified watermarks (graphics and/or arbitrary texts) on select pages of documents. It has more functionality and dynamism than, for example, the packages \pkg'{draftcopy, draftwatermark, watermark, draftmark}. The advantages of \pkg'{xwatermark} over these earlier packages include:

\begin{enum}
\item Both text and graphics watermarks are admissible within any watermark item or instance.
\item The user can dynamically customize the attributes (color, position, orientation, scale, the page(s)---first page, last page, all pages, odd pages, even pages, a particular page, and a range of pages---on which the watermark should appear) of each watermark.
\item Watermarks can be placed in the background and in the foreground of document pages by simple instructions.
\item Rectangular and square wallpapers can be produced from watermarks to suit user needs without effort.
\item All the command options/keys are passed directly via user-friendly key-value interfaces, instead of being defined in the source file by several macros. There are only two main user commands: \ffx'{\newwatermark, \newwallpaper}. The user is relieved of the need to remember and deploy several different macros, except, of course, that function keys are used. The list of keys and their default values for these functions are given in \amref{sec:packageoptions}.
\end{enum}

With the \pkg'{xcolor} (not loaded automatically by the \pkg'{xwatermark}), all colors (including \hx{white}, shades like \hx{-red!75!green!50}, and those defined within the user document) can be passed to this package. And, as mentioned above, both texts and pictures can be submitted and printed as watermarks on the same page, and on different positions.

There are global and local package options. These are listed and explained in
\amref{sec:packageoptions}.

Users who have since complained of not being able to conveniently place more than one watermark on the same page can now heave a sigh relieve: the current version of the package has enabled this functionality. You can now mix text and graphics watermarks and wallpapers and place as many of them as you like on the same page. This version of the package comes with an optimized looping macro and a key management system (the \pkg'{ltxkeys}) to enable several watermarks and wallpapers to be placed efficiently on the same document pages.


\docsection(sec:user-interface){User interfaces}

\docsubsection{Loading the package}

In style files the package may be loaded with \hx{\RequirePackage} and in document files with \hx{\usepackage} together with the package keys that can be passed as options.

\Note Some of the keys are \quoted{option keys}, \ie, they can appear only in \hx{\documentclass} or \hx{\usepackage} and not as, or in, arguments of other functions or macros. The \quoted{non-option keys} are those that can't appear in \hx{\documentclass} or \hx{\usepackage} but in the arguments of other macros. If a key is a non-option key and the user submits it to \hx{\documentclass} or \hx{\usepackage}, the package will alert the user. The same thing can be expected when a key is an option key and is submitted outside of \hx{\documentclass} or \hx{\usepackage}. The \quoted{need value} keys are keys that can't be called without a user-supplied value.

The package keys \ffx'{printwatermark, disablegeometry} are option keys, and hence can be called as follows:

\start'{example}[Package loading]
\RequirePackage[printwatermark,disablegeometry]{xwatermark}|label(mac:pkgload)
\usepackage[printwatermark,disablegeometry]{xwatermark}
\finish{example}

The other options may be submitted via user commands like \ffx'{\newwatermark, \newwallpaper}. Please see \amrefrange[tab:]{globaloptions,localoptions} for a full listing of all the available package and command options. By design, the boolean option \fx{printwatermark} should not appear in the macros \ffx'{\newwatermark, \newwallpaper} but as a package or \hx{\documentclass} option. It is disabled just before \hx{\begin{document}} and any attempt to pass it via \fx{\newwatermark} or \fx{\newwallpaper} thereafter will trigger an error.

When boolean options (\eg, \ffx'{printwatermark,allpages}) are passed without values, they are assumed implicitly \hx{true} by the package.

\Note When your watermark is not printed, first check that the option \fx{printwatermark} is \texttt{true}. This is one of the means to control the printing of watermarks. The others are through the following commands (more details are available in \amref{sec:dummywatermarks}):

\start+'{newmacro}[\dummywatermark, \DiscardAllWatermarks, etc]
\dummywatermark, \DiscardAllWatermarks, \UseDummyWatermarks,
\DiscardDummyWatermarks
\finish{newmacro}
\fxi*{\dummywatermark, \DiscardAllWatermarks,
  \UseDummyWatermarks, \DiscardDummyWatermarks}

The option \fx{textmark} implies text watermarks, for which all the font properties can be selected. It does not apply to graphics watermarks. For graphics watermarks you need the keys: \fx{picfile} (the graphics/picture filename, with its full path but without its extension), and \fx{picfileext} (the file extension). Admissible file extensions are \hhx'{ps,eps,pdf,png,mps,jpeg}; they should be submitted without the dot. The extensions \hhx'{ps,eps} are for \hx{dvi} files, while the rest are for \hx{pdf} runs. Additional information is needed (see \amref{sec:pic-watermark})\footnote{When the options \ffx'{align ,height, width, angle, scale, xpos, ypos, color} appear without prefixes such as \fx{pic} or \fx{text}, they refer to the text watermark and not the graphics watermark. The user can thus use these options in place of \ffx'{textalign,textheight,textwidth, textangle, textscale, textxpos, textypos, textcolor}, respectively. However, options referring to graphics watermarks must always be prefixed with \fx{pic} (\eg, picfile).}.

The following points should be noted about the values of the \fx{textmark}:

\begin{enum}
\item The value of the \fx{textmark} may be any arbitrary multi-line text, such as

\start{example}[textmark]
textmark=Hello world,\\[.25\baselineskip] We're here.
\finish{example}

\item The value of \fx{textmark} may be arbitrary (blocks of) texts or even kernel or package commands, but not filenames on their own (except when submitted as values of graphics keys). The package has a user-friendly interface for inserting graphics watermarks and wallpapers, which does not require the user to directly employ \hx{\includegraphics}.
\item The \ffx'{textwidth, picwidth} should be properly selected to match user's taste and the length of the \fx{textmark}. It may be set to \hx{\paperwidth} or \hx{\paperheight}, or any arbitrary length. Its default value is preset to \hx{\paperheight}. Sometimes it might also be necessary to suitably select the \fx{height}, whose default value is \hx{\paperwidth}.
\item If the longest line of a \fx{textmark} is longer than \hx{\paperwidth} and/or \hx{\paperheight} (depending on the orientation of the \fx{textmark}), then the \fx{fontsize} and the \fx{textscale} (or \fx{picscale}) options will have to be suitably chosen.
\end{enum}

The boolean options \ffx'{firstpage,lastpage,allpages, firstpage, oddpages, evenpages},
which specify the pages that should receive watermarks, may be replaced by any of the options \ffx{page=x, pages=x-y, pagex={x,y,z}}, where \quoted{\fx{x}}, \etcc, stand for any page number. If you enter, for example, \fx{pages=0-10}, all pages from 1~to 10 will receive the watermark. On the other hand, an entry like \fx{pages=10-0} will print watermark on page 10 only. If no page-specifying option is given and \fx{printwatermark} is true, watermark will appear only on the first page and a warning message will be entered in the transcript file. When passing \fx{page=x} or \fx{pages=x-y} as option to package, don't forget to include the equality sign (\fx{=}), otherwise the option will trigger an \quoted{unknown option/key} error. The key \fx{pages} expects a page range with the pages separated by a hyphen, while \fx{pagex} expects a comma-separated list of pages. For obvious reasons, the value of the key \fx{pagex} must always be given in balanced curly braces.

When specifying package options either in \hx{\usepackage} or \hx{\documentclass} (or indeed in the macros \ffx'{\newwatermark, \newwallpaper, \xwmminipage,\xwmcolorbox, \fancypagenos}), the following points should be noted:

\begin{enum}
\item Multiple lines are permitted but not blank lines.
\item Extra paces between options and words are ignored.
\item Active characters (those of catcode~13) may be allowed (but see \amref{sec:activechar} for further comments).
\item Options are mostly order-agnostic, except \fxi{graphicsoptions}, whose values take precedence over those supplied via other keys (see \amref{sec:graphicsoptions}).
\end{enum}


The global boolean option \fx{printwatermark}=\hx{true} (or \hx{=false}) should ideally be set when loading the package, \eg,

\start'{example}[Package option: printwatermark]
\usepackage[printwatermark]{xwatermark}
\finish{example}

or in the \hx{\documentclass} options list:

\start'{example}[Package option: printwatermark]
\documentclass[a4paper,12pt,printwatermark]{article}
\usepackage{xwatermark}.
\finish{example}

The remaining options should ideally be set dynamically using the macro \fx{\newwatermark} or \fx{\newwallpaper}. These other options can be set for each page, as on the pages of the accompanying example files.


\docsection(sec:newwatermarks){The \headfx{\newwatermark} macro}

The use syntax for the command \fx{\newwatermark} is as follows

\start{newmacro}[\newwatermark]
\newwatermark[|A(key-val)]{|A(mark)}
\newwatermark|R(*')[|A(key-val)]{|A(mark)}
\finish{newmacro}
\fxi*{\newwatermark}

where \ang{key-val} is the list of keys and their values (called the watermark attributes) and \ang{mark} is the text watermark. Graphics watermarks are to be specified with their file name, file extension, \etcc. The full lists of the available keys for the macro \fx{\newwatermark} and others are available in \amref{sec:packageoptions}.

The \stform of \fx{\newwatermark} puts the watermark in the foreground instead of the background, and the \pmform is ignored, \ie, no watermark is produced (see \amref{sec:dummywatermarks}).

The macro \fx{\newwatermark} can be used as in

\start{example}[\newwatermark]
\newwatermark[|R(pagex)={2,5,7},fontfamily=bch,color=gray!25,angle=45,scale=3,
  xpos=0,ypos=0]{DRAFT},
\finish{example}

where the \fx{textmark} has been enclosed in curly braces as the last argument of the macro. The options (called the watermark attributes) are expected in square brackets. The \fx{textmark} (which is \quoted{DRAFT} in the above example) can also be given within square brackets, in which case the curly braces will be empty:

\start{example}[\newwatermark]
\newwatermark|R(*)[page=10,fontfamily=bch,color=gray!25,angle=45,scale=3,xpos=0,
  ypos=0,textmark=DRAFT]{}.
\finish{example}

The option \fx{printwatermark} may appear in only \fx{\usepackage} or \hx{\documentclass} options list, since it is disabled at \hx{\begin{document}}. However, the options \ffx'{firstpage, lastpage, allpages, oddpages, evenpages}, \etcc, which specify watermark pages, can and should appear in the command \fx{\newwatermark}. This implies that the instructions that specify watermark pages may be issued and superseded dynamically (page by page or chapter by chapter). For small documents, this feature may be unnecessary, but it will be useful in large documents (such as a report or book), in which the watermark may change from chapter to chapter.

When you want the watermark on only one page of the document, you can conveniently use the \fx{\newwatermark} macro with the page option \mbox{\fx{page}=\ang{no}} in the preamble of your document after issuing

\start+{example}[\usepackage,printwatermark]
\usepackage[printwatermark]{xwatermark}
\finish{example}

In this way, you don't have to bother with locating in the source file the spot that corresponds to the page on which you want the watermark to appear. In fact, you can collect all the watermarks in the document preamble or in a configuration file with the command \fx{\newwatermark}.

\Note Each call to \fx{\newwatermark} must contain the page(s) that will receive the watermark(s), otherwise the user will be alerted. The page specifiers are:

\start'{example}[page specifiers]
page=x, pages=x-y, pagex={x,y,z}, firstpage, lastpage, allpages,
oddpages, evenpages
\finish{example}


\docsubsection{Options without values}

If you follow an option key with an equality sign but without a value, as in, \eg,

\start{example}[\newwatermark]
\newwatermark[firstpage,fontfamily=,color=gray!25,angle=45,scale=0.8,
  xpos=0,ypos=0,textmark=]{},
\finish{example}

then there will be no problem but the outcome may be unpredictable, depending on the key that has no value. In the above example, no watermark will be printed (not even the default mark, which is \fx{DRAFT}) because empty textmark is valid and implies that no watermark should be printed. The absence of \texttt{fontfamily} in \quoted{\fx{fontfamily=}} will compel \texorlatex to use an arbitrary \texttt{fontfamily} that isn't the default (the default \texttt{fontfamily} is \fx{phv} if the key \fx{fontfamily} is not passed, and \fx{cmr} otherwise).


\docsubsection{Emptying the watermarks of some pages or objects}

If you issue any of the statements

\start{example}[page specifiers]
page=x, pages=x-y, pagex={x,y,z}, firstpage, lastpage, allpages=true,
evenpages=true, oddpages=true
\finish{example}

together with \fx{printwatermark}=\hx{true} but you don't want the mark on any particular page, we can simply set \fx{\newwatermark[other keys,textmark=]{}} or, to the same effect, we may set \fx{\newwatermark[other keys]{}}, where \quoted{other keys} may include the page specifiers\footnote{In the case of graphics watermarks, setting \ftfx{\newwatermark[other keys,picfile=]{}} will prompt a \quoted{no file} error.}. These both imply that the text watermark for the given page is empty. This can be useful when transiting from one watermark type to another. Moreover, since both picture and text marks can be submitted via one and the same command \fx{\newwatermark} (see \amref{sec:pic-text-mark}), this technique may be used to empty the text watermark for the given page or range of pages. For example,

\start{example}[\newwatermark]
\newwatermark[allpages,fontfamily=put,color=white,fontsize=3cm,scale=1,
  picbb=112 619 242 751,picscale=3,picfile=./graphics/myfig,picfileext=eps,
  width=\paperheight,align=center,angle=0,xpos=0,ypos=0]{}
\finish{example}

will print only the picture watermark, since the \fx{textmark} is empty here.


\docsubsection(sec:pic-text-mark){Printing both picture and text watermarks on same page}

Both picture and text marks can be submitted and printed on the same page via one and the same \fx{\newwatermark}. For example,

\start{example}[\newwatermark]
\newwatermark[pages=1-2,fontfamily=put,color=white,fontsize=3cm,scale=1,
  picbb=112 619 242 751,picscale=3,picfile={./graphics/myfig},
  picfileext=eps,width=\paperheight,align=center,angle=0,xpos=0,
  ypos=0]{Hello World}
\finish{example}

However, both the picture and text marks will then share the same subset of the attributes (position, angle, align, \etcc). When text and graphics watermarks appear on the same page, the recommended approach is to submit the two types of watermark by two separate calls to \fx{\newwatermark}.


\docsubsection{The usefulness of the \headhx{white} color}

You can deploy the white color to great effect in designing text watermarks. Also, if you set \fx{allpages}=\hx{true} or \fx{evenpages}=\hx{true} or \fx{oddpages=true} together with \fx{printwatermark}=\hx{true} but you don't want the mark on any particular page, you can simply enter \fx{color=white} in the \fx{\newwatermark} on that page. This applies only to text watermarks, as such a declaration has no effect on picture watermarks. This may be convenient in circumstances where you may change your mind as to whether to place a watermark on a particular page or not. In this way you don't have to set \fx{\newwatermark[other keys,textmark=]{}} or remove (or comment out) the \fx{\newwatermark} command for that (or indeed any) page. See also \amref{sec:dummywatermarks}.


\docsubsection(sec:dummywatermarks){Dummy watermarks}

When you don't need a watermark printed, you can simply replace its \fx{\newwatermark} with \fx{\dummywatermark}, instead of commenting out the entire watermark or using \fx{color=white}. Both the macros \fx{\newwatermark} and \fx{\dummywatermark} have the same syntax and expect the same number and types of arguments:

\start{newmacro}[\dummywatermark]
\dummywatermark[pages=12-13,fontfamily=phv,fontsize=11pt,fontseries=m,
  align=center,height=\paperheight,width=\paperwidth,angle=90,scale=1,
  xpos=0,ypos=-1
]{Example}
\finish{newmacro}
\fxi*{\dummywatermark}

And when you don't want any of your watermarks printed, you could simply issue the option \fx{printwatermark}=\hx{false} or call the command \fxi{\DiscardAllWatermarks}. These will simply turn all instances of \fx{\newwatermark} command into \fx{\dummywatermark}. In any run, you may decide to use some or all of the dummy watermarks. To use all dummy watermarks, you issue the command \fxi{\UseDummyWatermarks} before instances of \fx{\dummywatermark}. To again disregard all subsequent dummy watermarks, which is the default state, simply call the command \fxi{\DiscardDummyWatermarks}. These commands provide a convenient scheme for deciding the watermarks to be printed with minimal typing. For wallpapers, there is the corresponding command \fxi{\dummywallpaper}. Also, putting a prime sign (\RedPrime) on \fx{\newwatermark} or \fx{\newwallpaper} turns the command into a dummy mark, but only for that single instance. Subsequent \fx{\newwatermark} and \fx{\newwallpaper} without primes will produce watermarks and wallpapers.


\docsection(sec:wallpapers){Wallpapers}

\docsubsection{The \headfx{\newwallpaper} macro}

The command \fx{\newwallpaper} can be used to produce rectangular and square tiles on document pages. The use syntax for the command \fx{\newwallpaper} is

\start{newmacro}[\newwallpaper]
\newwallpaper[|A(key-val)]{|A(mark)}
\newwallpaper|R(*')[|A(key-val)]{|A(mark)}
\finish{newmacro}
\fxi*{\newwallpaper}

where \ang{key-val} is the list of keys and their values (called the attributes) and \ang{mark} is the text (and not graphics) watermark. Graphics watermarks are again to be specified with their file name, file extension, \etcc. The full lists of the available keys for the macro \fx{\newwallpaper} are available in \amref{tab:localoptions}.

The \stform of \fx{\newwallpaper} puts the watermark in the foreground instead of the background, and the \pmform is ignored, \ie, no watermark is produced (see \amref{sec:dummywatermarks}).

When you get unexpected tiles, you should consider enabling or disabling the keys \fx{squaretiles} (default \texttt{true}) and/or \fx{boxalign} (default \texttt{center}). The key \fx{boxalign} may assume one of the values in the set \ffx{t-l,t-r,b-l,b-r,s} or \ffx{top-left, top-right, bottom-left, bottom-right, center, justified}.


\docsection(sec:pic-watermark){Graphics watermarks}

For graphics/picture watermarks, you need the \fx{picfile} (the graphics filename, with its full path but without its extension), \fx{picfileext} (the picture filename extension without the dot), \fx{picbb} (the picture bounding box), and \fx{picscale} (the picture scale)\footnote{These options have longer, easier to remember, names; see \amref{tab:localoptions}.}. Admissible file extensions are \fx{eps}, \fx{pdf}, \fx{png} and \fx{jpeg}; the latter three, but not the first, may be used in the case of \pdftex. The file extension should be passed without the dot. If the file extension is not passed to package, the package selects it automatically based on whether \pdftex mode is running or not (normal extensions are \fx{eps} for dvi mode and \fx{pdf} for \pdftex mode). In fact, the package does search hard on the given paths for other admissible file types with the base filename the user has specified. If you have the graphics file in both \fx{eps} and \pdf-compatible formats, then you don't have to bother about submitting the file extension to the package: it will automatically select the appropriate file extension, depending on the mode (\pdf or \texttt{dvi}) in which it is running.


\docsubsection(sec:graphicsoptions)
  [Passing key values to \headhx{\includegraphics} directly]
  {Passing key values to \headhx{\includegraphics} directly}
\fxim*{graphicsoptions}

The \pkg'{xwatermark} uses \pkg'{graphicx}'s \hxi{\includegraphics} to insert graphics watermarks.
Users can pass valid key values to the command \hx{\includegraphics} directly via the macros \ffx'{\newwatermark,\newwallpaper}. The key to use for this purpose is \fx{graphicsoptions}. The following points should be noted in respect of the key \fx{graphicsoptions}:

\begin{enum}
\item Values of the key \fx{graphicsoptions} must always be enclosed in curly braces, since they are expected to be more than one.
\item Only keys and values valid for the command \hx{\includegraphics} may appear in the command \fx{graphicsoptions}. Valid keys for \hx{\includegraphics} are

\start'{example}[\includegraphics keys]
bb, bbllx, bblly, hiresbb, viewport, trim, height, width, natheight,
natwidth, totalheight, angle, origin, keepaspectratio, scale, clip,
draft, type, ext, read, command
\finish{example}

\item Key values submitted via \fx{graphicsoptions} supersede those submitted outside it, even if those outside \fx{graphicsoptions} appear earlier than \fx{graphicsoptions} in the command \fx{\newwatermark} or \fx{\newwallpaper}.
\item Values submitted via \fx{graphicsoptions} have only local effect, in the sense that they become null and void outside of \fx{\newwatermark} or \fx{\newwallpaper}. If the user wants the key values submitted via \fx{graphicsoptions} to prevail for all subsequent watermarks and wallpapers, then he should use the command \fx{\GraphicsOptions}. Values passed via \fx{\GraphicsOptions} don't only have global effect, but they always override those submitted via \fx{graphicsoptions}.
\end{enum}

It should be noted that \fx{\GraphicsOptions} isn't a key but a stand-alone command with the following syntax:

\start{newmacro}[\GraphicsOptions]
\GraphicsOptions{|A(key-val)}
\finish{newmacro}
\fxi*{\GraphicsOptions}

where \ang{key-val} are admissible keys for the command \hx{\includegraphics} and their user-supplied values. The values so suggested by \fx{\GraphicsOptions} override those given via the keys of the \pkg{xwatermark}, including \fx{graphicsoptions}. Such values remain in force until they are changed later by another call to \fx{\GraphicsOptions}.

An example follows:

\start{example}[graphicsoptions]
\newwallpaper[%
  page=10,picangle=45,tilexoffset=0pt,tileyoffset=0pt,picontoptext=false,
  boxalign=top-left,picbb=116 428 477 718,picscale=2,picfile=tabu-test1,
  tileno=4,picfileext=pdf,|R(graphicsoptions)={clip,keepaspectratio,hiresbb}
]{mypicture}

|com(or globally as)
\GraphicsOptions{clip=true,keepaspectratio,hiresbb}
\finish{example}
\fxi*{\GraphicsOptions}

The commands \hhx'{\DeclareGraphicsExtensions, \DeclareGraphicsRule} of the \pkg'{graphics} can still be invoked before setting graphics watermarks.


\docsubsection{The graphics input paths}

Users can suggest the possible locations of the graphics watermarks to the package by using the command \fx{\watermarkpaths}, whose syntaxes are

\start{newmacro}[\watermarkpaths]
\watermarkpaths[|A(pre)]|(|A(post)|){{path-1}{path-2}...{path-n}}
\watermarkpaths|*[|A(pre)]|(|A(post)|){path-1,path-2,...,path-n}
\finish{newmacro}
\fxi*{\watermarkpaths}

Here, \ang{pre} and \ang{post} are optional arguments that apply to all the given paths. Caution should be exercised when using these optional arguments, since when used incorrectly they can yield the wrong path (see the example below). In the \unstform all the paths must be provided in surrounding curly braces and must have no commas, otherwise the package will raise an error. The \stform expects paths to be separated by commas. The package works hard to find your watermark on the suggested path.

\start+{example}[\watermarkpaths]
\watermarkpaths{{./}{./graphics/}{./graphics/recentfiles/}}
\watermarkpaths|*{./,./graphics/,./graphics/recentfiles/}
\watermarkpaths|(/|){{.}{./graphics}{./graphics/recentfiles}}
\watermarkpaths|*|(/|){.,./graphics,./graphics/recentfiles}
|com(Note the empty balanced braces below. Without them, the first entry)
|com(|(which is supposed to be {./}|) will be wrong:)
\watermarkpaths[.]|(/|){{}{/graphics}{/graphics/recentfiles}}
\watermarkpaths|*[.]|(/|){{},/graphics,/graphics/recentfiles}
\finish{example}

By default, the packages works hard to preserve outer curly braces, unless and until they are required to be removed.

The command \fx{\watermarkpaths} inherits the current contents of \latex's \hx{\input@path} command and \pkg'{graphics}'s \hx{\Ginput@path} (the latter takes argument from \hx{\graphicspath}).


\docsection{Other aspects of package architecture and use}

\docsubsection{\headhx{\documentclass} options}

The package is set to inherit the \hx{\documentclass} options, if the options apply to the package. Therefore, some of the package options can be passed to the package via the \hx{\documentclass} options list. This is perhaps most appropriate in the case of the option \fx{printwatermark}. However, package options supersede those passed via the \hx{\documentclass}. For example, the option \fx{printwatermark}=\hx{true} in the \hx{\documentclass} options list can normally be superseded by the option \fx{printwatermark}=\hx{false} in loading the \pkg'{xwatermark}, \eg, as in

\start{example}[package loading]
\usepackage[printwatermark=false]{xwatermark},
\finish{example}

and vice versa. It should, however, be noted that some package options and keys are restricted either to the \hhx'{\documentclass,\usepackage} (this applies to the so-called \quoted{option keys}) or to the various user macros (in the case of \quoted{non-option keys}). Normally, the package will alert the user to the wrong call of any of the options and keys.

If you don't need the watermark on any page of your document, simply replace the option \fx{printwatermark} (=\hx{true}) with \fx{printwatermark}=\hx{false} in \hx{\usepackage} or \hx{\documentclass}. If you have specified \fx{printwatermark} (=\hx{true}) in the \hx{\documentclass} options list but you still don't need the watermark on any page of your document, then you would have to use the tools of \amref{sec:dummywatermarks}.


\docsubsection<Size of the watermark>{The size of the watermark}

In the case of text watermarks, the size of the watermark is controlled by three parameters, namely, \fx{fontsize}, \fx{fontseries} and \fx{scale}. All can be set dynamically. Their default values are \fx{5cm}, \fx{b} and \fx{1}, respectively. For picture watermarks, the size is determined by \fx{picscale}.


\docsubsection{The coordinates of the watermark}

The watermark coordinates (specified by \fx{xpos} and \fx{ypos}) have their origin at the center of the page and are with respect to the geometric center of the watermark. The default unit is \hx{millimeter}, but this can be changed on any page by changing the value of \fx{coordunit}. For example,

\start+{example}[\newwatermark,coordunit]
\newwatermark[other attributes,coordunit=|R(unit of length)]{}.
\finish{example}

Acceptable units of length include \hx{mm} (millimeter), \hx{cm} (centimeter), \hx{in} (inch), \hx{pt}~(point), \hx{bp} (big point), \hx{dd} (didot), \hx{ex} (height of small \hx{x}), \hx{pc} (pica), \hx{cc}~(cicero), and \hx{em}~(width of capital \hx{M}).


\docsubsection{Wrong location of the watermark}

If you discover that the watermark is wrongly positioned on the page(s) of your document, as some users have had course to complain, the chances are that you have submitted wrong coordinates (values of \fx{xpos} and \fx{ypos}) to the package or the watermark's width (\fx{textwidth} or \fx{picwidth}) is not optimal or both reasons. The package does not take responsibility for this and will normally not warn you in this respect. Since the output file provides a direct and simple indication of the occurrence of the anomaly, no attempt has been made in the package to warn users in this regard. If you do not specify the keys \fx{xpos} and/or \fx{ypos} at all in the call to  \fx{\newwatermark}, their default values will be used by the package. Also, if you list these keys without their values in the call to \fx{\newwatermark}, their default values (\fx{xpos=0} and \fx{ypos=0}, which yield the center of paper) will be assumed by the package. The default value of the watermark's width is \hx{\paperheight}, and not \hx{\paperwidth} as might be expected.

When the \pkg'{geometry} is loaded together with the \pkg'{xwatermark}, page layout scale changes by the \pkg'{geometry} may result in the watermarks being positioned slightly away from the intended position. See \amref{sec:geometry} for further details.


\docsubsection{Wrong size of the watermark}

When you discover that your text or graphics watermark is not of the size you expect, then you should check the global and local scale and width of the watermark. It is most likely that the chosen combination is wrong or inconsistent. Global and local package options are described in \amref{sec:packageoptions}. For example, choosing \fx{scale=0.7} and \fx{width=\paperwidth} may yield something unexpected. So will mixing inconsistent global and local scales or width, or both.


\docsubsection{Breaking the watermark into lines}

It is possible to break text watermarks into lines, as in the following examples:

\start{example}
\newwatermark[evenpages,fontfamily=ptm,angle=45,scale=.7,
  align=center,color=green,xpos=0,ypos=0]{Directorate\\[.25ex]Only}

\newwatermark[allpages,fontfamily=ptm,angle=45,scale=.8,align=left,
  color=green,xpos=0,ypos=0]{Control\\[.25ex]Version}.
\finish{example}

More complex examples are available in the example source and \pdf files that shipped with this package.


\docsubsection{The alignment of the watermark}

The alignment of the watermark is controlled by the keys \ffx'{align, textalign, boxalign}. The first two are equivalent and may be set to \fx{center}, \fx{left}, \fx{right} or \fx{justified}.  The default is \fx{center}. This is particularly useful for putting arbitrary texts (that are not necessarily watermarks) on pages of documents. The admissible values for the key \fx{boxalign} are given in \amref{tab:localoptions}.


\docsubsection{Locating the page center}

In case you need to locate the paper/page center for placing the watermark or some other material at any position on the page, a two-line grid can be placed on the page background with the key \fx{showpagecenter}, which may be issued (dynamically for each page) with the \fx{\newwatermark} macro as follows:

\start{example}[showpagecenter]
\newwatermark[allpages,showpagecenter]{}
\newwatermark[page=1,showpagecenter=true]{}

\newwatermark[allpages,showpagecenter,fontfamily=ptm,angle=60,scale=.7,
  color=brown!25!yellow!75,coordunit=cc,xpos=0,ypos=0]{Confidential!}.
\finish{example}

If after issuing this command to get a centered grid on a page, you no longer require the grid on the following pages, you simply issue another

\start{example}
\newwatermark[pages=1-2,showpagecenter=false]{}

\newwatermark[page=10-\lastdocpage,showpagecenter=false,fontfamily=panr,
  angle=60,scale=.7,color=brown!25!yellow!75,coordunit=cc,xpos=0,ypos=0]
  {Confidential!}
\finish{example}


\docsubsection{The last page of the document}

You can easily obtain the last page of the document with the label \fx{xwmlastpage}, which is automatically provided by the package: the user doesn't have to insert it himself. In general, you can use the command \fx{\xwmgetpagenumber} to extract page numbers from \latex labels (even in expansion contexts). More than one run may be necessary in extracting page numbers from this command. The following example inserts the watermark from second to the last page to the last page. Note that in this example the starting page is necessarily enclosed in curly braces so as to distinguish the two hyphens that serve different purposes.

\start{example}[\xwmgetpagenumber,\lastdocpage]
\newwatermark[pages={\lastdocpage-2}-\lastdocpage,angle=90,
  scale=1,xpos=0,ypos=-1]{This is page \thepage~of~\pageref*{xwmlastpage}}
\finish{example}
\fxi*{\xwmgetpagenumber,\lastdocpage}

The command \fx{\lastdocpage} is equivalent to \fx{\xwmgetpagenumber{xwmlastpage}}.


\docsubsection(sec:activechar){Active characters}

Active characters (\ie, those of category 13) and expandable commands can normally be used as values of the \fx{textmark} key in the \fx{\newwatermark} macro. However, such values cannot be passed via the \hx{\documentclass} or the \hx{\usepackage{xwatermark}} command without first loading one of the packages: \pkg'{xkvltxp,kvoptions-patch,catoptions}. That is, the following should work:

\start{example}
\RequirePackage{catoptions}
\documentclass[myoption={My watermark,\\[2ex]
  designed~by \textsc{Mr.~J\"ohnson}}]{class-file}

\begin{document}
Blackberry lily ...
\end{document}
\finish{example}

In plain \tex the only active character is the tie character (\ie, \hx{\nobreakspace}). However, some packages do make some other characters active. For example, after issuing the command \hx{\MakeShortVerb{\x}}, the packages \pkg{doc} and \pkg{shortvrb} make the character \fx{x} active\footnote{The \pkg'{fancyvrb} has, \eg, \ftfx{\DefineShortVerb[key=value pairs]{\x}}.}. The user can use such active characters in values of the \fx{textmark} key without locally changing their catcode to~11 or~12. In the case of \hx{\MakeShortVerb{\x}}, you can issue \hx{\DeleteShortVerb{\x}} to revert to normal use of character \fx{x}. As another example, the option \hx{turkish} of the \pkg'{babel} uses the equal sign (\hx{=}) as active shorthand character.


\docsection(sec:making-boxes){Macros for creating boxes}

To make it easier for users to create paragraph boxes and color boxes of texts and watermarks, the \pkg'{xwatermark} provides the macros \fx{\xwmcolorbox} and \fx{\xwmminipage}. The macro \fx{\xwmcolorbox} calls the macro \fx{\xwmminipage}.


\docsubsection(sec:minipage){The \headfx{\xwmminipage} macro}

The \fx{\xwmminipage} macro is a \hx{minipage} environment that may be used for framing watermarks. It accepts verbatim material. Like the \fx{\newwatermark} macro, this macro is called with key-value pairs as follows (see \amref{tab:localoptions} for a full listing of the available keys):

\start{newmacro}[\xwmminipage]
\xwmminipage[key=value list]{balanced text}
\xwmcolorbox[key=value list]{balanced text}.
\finish{newmacro}
\fxi*{\xwmminipage}

The \fx{textcolor} key in \fx{\xwmminipage} is the color of the text. In the case of \fx{\xwmcolorbox}, four color values are expected: \ffx'{textcolor, fillcolor, outerframecolor, innerframecolor}. Texts with commas need to be enclosed in braces when submitted to these macros. The default values of the keys of these macros are described in \amref{sec:localoptions}.

The macros \ffx'{\xwmminipage,\xwmcolorbox} can be nested within and among themselves, \eg,

\start{example}[\xwmminipage]
\newwatermark[pagex={1,3,10},fontfamily=txtt,fontseries=m,color=red,
  align=center,scale=0.7,angle=0,xpos=0,ypos=0]{%
    \xwmminipage[width=\paperwidth]{%
      \xwmminipage[width=\paperwidth,align=left,textcolor=magenta]
        {\TeX\\[.1ex] \LaTeX}\\[1ex]
      \xwmminipage[width=\paperwidth,align=center,textcolor=green]
        {\TeX\\[.1ex] \LaTeX}\\[1ex]
      \xwmminipage[width=\paperwidth,align=right,textcolor=orange]
        {\TeX\\[.1ex] \LaTeX}%
    }%
}
\finish{example}

More complicated examples can be found in the example files. But some of the complications found in the example files are unnecessary since several simple watermarks can be placed on the same document page by specifying the same page number for those simple watermarks.


\docsubsection(sec:colorbox){The \headfx{\xwmcolorbox} macro}

The macro \fx{\xwmcolorbox} provides a key-value interface to \pkg'{xcolor}'s \hx{\fcolorbox}\footnote{The \pkg'{xwatermark} also comes with the macro \fx{\xwmshade} which is similar to \fx{\xwmcolorbox}, but which, unlike \fx{\xwmcolorbox}, can break neatly across pages (in the manner of the \pkg'{framed}). But since no watermark is expected to break across pages, the macro \fx{\xwmshade}  isn't described in this guide. Power users should still be able to use it.}.

\start{newmacro}[\xwmcolorbox]
\xwmcolorbox[key=value list]{balanced text}.
\finish{newmacro}
\fxi*{\xwmcolorbox}


\docsubsection(sec:makecolorbox){The \headfx{\makecolorbox} macro}

This macro has the same syntax and options as the \fx{\xwmcolorbox} macro except that the resulting \hx{colorbox} is centered by using the \hx{center} environment and the markup box \hx{\makebox[0pt][c]{}}. It is intended for producing \hx{colorbox}\unskip es such as the one for article abstracts. The user may experiment with the following settings, from which the abstract of this guide was produced:

\start{newmacro}[\makecolorbox]
\makecolorbox[framesep=4pt,framerule=1pt,innerframecolor=red!55,
  outerframecolor=ForestGreen,align=justified,
  fillcolor=gray!25,width=.95\hsize,boxalign=center,
  height=2.5mm,depth=0mm,framebox]{%
    \centering\xwmcolorbox[align=center,fillcolor=white,
    innerframecolor=blue,outerframecolor=orange,width=.5\hsize,
    height=2mm]{\textbf{Abstract}}\\[\baselineskip]
    The \pkg'{xwatermark} provides facilities for \ldots
}
\finish{newmacro}
\fxi*{\makecolorbox}

Notice here that the macro \fx{\makecolorbox} calls the macro \fx{\xwmcolorbox}.


\docsection(sec:fancypagenos){The \headfx{\fancypagenos} macro}

The macro \fx{\fancypagenos}, which has the following syntax, can be used to position and format page numbers in the desired fashion. Its keys and their default values are described in \amref{tab:localoptions}. Page numbers produced by \fx{\fancypagenos} will, by default, appear in the foreground, so that they can be seen on top of watermarks. If you want the page numbers to appear in the background, then set \fx{sendtoback}=\hx{true} as one of the key-value pairs in the call to \fx{\fancypagenos}.

\start{newmacro}[\fancypagenos]
\fancypagenos[key=value pairs]
\finish{newmacro}
\fxi*{\fancypagenos}

Even after issuing the command \fx{\fancypagenos}, you can still decide not to print the fancy page numbers by calling the command \fxi{\NoFancyPageNumbers}. The complement of the command \fxi{\NoFancyPageNumbers} is \fxi{\FancyPageNumbers}.


\docsection(sec:geometry)[\headpkg{xwatermark} and \headpkg{geometry} package]
  {Using \headpkg{xwatermark} with \headpkg{geometry} package}

Because the \pkg'{geometry} changes the scale, ratio, magnification, and other native dimensions of the paper to get the needed layout right all the time, the \pkg'{geometry} may interfere with the \pkg'{xwatermark}. The only layout parameter that the \pkg'{geometry} may retain is the paper center, which, unfortunately, does not always coincide with the text center. In fact, even the \hx{\paperwidth} and \hx{\paperheight} can be changed by the user of the \pkg'{geometry}.

Feasible solutions to this problem include setting the watermarks before loading the \pkg'{geometry}; using the \pkg'{geometry} with the option \fx{pass} in the preliminary runs, when setting the watermarks (see further details below); using \hx{true} dimensions (\eg, \fx{coordunit}=\hx{truept}); and using relative, rather than absolute, dimension units (\ie, \hhx'{em,ex}). The power-user can also experiment with the primitives \hhx'{\magnification, \mag, \magstep}.

The \hx{pass} option of the \pkg'{geometry} has been available from version~4.2 of the \pkg'{geometry} onwards. It disables auto-layout and all of the \pkg'{geometry} settings except \hx{verbose} and \hx{showframe}. It can be used to determine the page layout of the \hx{\documentclass} and layouts created by other packages and manual settings. The user can also employ the option \hx{showframe} of the \pkg'{geometry} to view how the scaling factors used by the \pkg'{geometry} might change native layout dimensions. The option \hx{reset} of the \pkg'{geometry} is also useful in this regard.

The \pkg'{geometry} saves native \texorlatex dimensions and switches in the macro \hx{\Gm@dorg} before processing \pkg'{geometry} options. This macro is called by \pkg{geometry} when the options \hx{pass} and \hx{reset} are passed to it. Reconciling the two packages (\pkg{xwatermark,geometry}) at a \quoted{high level} will involve simply calling this macro within the \pkg'{xwatermark} whenever \pkg{xwatermark} detects that the \pkg'{geometry} has been loaded by the user. This is what has been done in the \pkg'{xwatermark}: the package has a boolean option called \fx{disablegeometry}, which, if true, invokes the command \hx{\Gm@dorg} of the \pkg'{geometry} to disable \pkg'{geometry} settings and enforce native paper layout dimensions. First the \pkg'{xwatermark} detects at the very last moment of the document preamble (just before \hx{\begin{document}}) if the \pkg'{geometry} has been loaded by the user. If yes, and if the user has suggested \fx{disablegeometry}=\hx{true} in the call to \pkg{xwatermark}, then \pkg{xwatermark} issues the command \hx{\geometry{pass}}, which, as mentioned earlier, calls \hx{\Gm@dorg}.

After the effects of the \pkg'{geometry} are re-introduced (\ie, after setting the \pkg'{xwatermark} option \fx{disablegeometry}=\hx{false}), it might still be necessary, depending on the user need, to fine-tune the positions of the watermarks.

Because the \pkg'{geometry} stipulates that the command \hx{\Gm@dorg} can be issued only in the document preamble, the switch \fx{disablegeometry} can appear as option only in \hx{\documentclass} or  \hx{\usepackage{xwatermark}}. But it matters not which of the two packages (\pkg{geometry, xwatermark}) is loaded first. To call \hx{\Gm@dorg}, the \pkg'{xwatermark} uses the hook \hx{\BeforeStartOfDocument} from the \pkg'{catoptions}. \hx{\AtBeginDocument}, a native \latex hook, is inapplicable in this case.


\docsection{Support for \deadunexpandable{\acro{UNICODE}} and
  \deadunexpandable{\acro{UTF}} encodings}

The \pkg'{xwatermark} can be used with any font encoding, provided the \fx{fontfamily} is properly declared before use. For example, with the following declarations on \XeTeX, Rembrandt Wolpert (\url{wolpert@uark.edu}) obtained some \fx{.pdf} outputs that he is willing to share with other users:

\start{example}[\newfontfamily]
\newfontfamily{\chinese}{STFangsong} % SinoType FangSong

\newcommand{\chtext}[1]{{\chinese \XeTeXlinebreaklocale "jp"
  \XeTeXlinebreakskip=0pt plus 1pt #1}%
}

\newwatermark[allpages,fontsize=5cm,align=center,
  color=red!75!blue!25,angle=90,xpos=-65,ypos=-38,scale=.49]
  {=\fbox{\color{red!65}\chtext{|color(red)watermark in Chinese or Japanese script|color(blue)}}=}

\newfontfamily{\Gara}{Garamond Premier Pro}

\newwatermark[allpages,fontsize=5cm,scale=.46,align=center,
  angle=90,color=red!75!blue!25,xpos=-72,ypos=-38]
  {=\fbox{\color{red!65}\Gara The different ligature}=\\[.35ex]}.
\finish{example}
\hxi*{\newfontfamily}

It doesn't matter what the user declares as a \fx{fontfamily} provided he/she declares it before using it and provided the declaration is valid. It is thus possible to mix scripts in one watermark (\eg, Latin, Chinese, Korean, Japanese, Arabic, Russian scripts, you name it).

\docsection{Repeated graphics in a document}

For graphics watermarks, the watermark image, or any other image that is repeated in the document, has the potential to make the processed version of the document surprisingly large. The problem is that the default mechanisms of graphics usage add the image at every point it is to be used, and when processed, the image appears in the output file at each such point.

See the \acro{UKTUG FAG}, version~3.20 (2010), entry number~146, page~95, for the available solutions to this problem. As described by this reference, if the \texttt{PostScript} version of the file is destined for conversion to \pdf, either by a ghostscript-based mechanism such as \hx{ps2pdf} or by, for example, Acrobat Distiller, the issue is not as important, since the distillation mechanism will amalgamate graphics objects whether or not the \texttt{PostScript} has them amalgamated. \pdftex does the same job with graphics, automatically converting multiple insertions into pointers to graphics objects.


\docsection{Further examples of use of \headpkg{xwatermark} package}

The files \files'{xwatermark-examples1,xwatermark-examples2}, source files of examples of use of the \pkg'{xwatermark} together with their \pdf versions, are provided with this guide in the \pkg{xwatermark} bundle.


\docsection(sec:packageoptions){Package options and macro keys}

We categorize the package options and keys into global and local. Global options are those set either in \hx{\documentclass} or in \hx{\usepackage}, while local options are those set with the macros \ffx'{\newwatermark,\newwallpaper,\xwmminipage,\xwmcolorbox,\makecolorbox}.


\docsubsection(sec:globaloptions){Global options}

The global package options are listed and described in the following \amref{tab:globaloptions}.

\ifboolTF{amd@inputfile}{%
  \InputDocument{tab-globaloptions}
}{}


\docsubsection(sec:localoptions){Local options}

Local package options are those associated with the commands \ffx'{\newwatermark, \newwallpaper, \xwmminipage, \xwmcolorbox, \makecolorbox, \fancypagenos}. They are described in the following \amref{tab:localoptions}.

\ifboolTF{amd@inputfile}{%
  \InputDocument{tab-localoptions}
}{}


\docsection(sec:version-hist){Version history}

The following change history highlights significant changes that affect user utilities and interfaces; changes of technical nature are not documented in this section. The \stsign on the right-hand side of the following lists means the subject features in the package but is not reflected anywhere in this user guide.

\begin{versionhist}
  \begin{version}{1.5.1}{2011/07/20}
  \item Following user request, two new keys were introduced for the macro \fx{\fancypagenos}. \vsecref{sec:fancypagenos}
  \end{version}
  \begin{version}{1.5.0}{2011/07/10}
  \item Introduced the \pkg'{ltxkeys}, a highly robust and optimized module for general creation and management of keys. \vsecref*
  \item Provisions for placing more than one watermark on the same page. \vsecref{sec:newwatermarks}
  \item Introduced wallpaper functionalities. \vsecref{sec:wallpapers}
  \item Adaptable and flexible fancy page numbers. \vsecref{sec:fancypagenos}
  \end{version}
\end{versionhist}

\newpage
\indexpreamble{Index numbers refer to page numbers.}
\indexpreambleformat{\centering}
\indexcolumns\tw@
\printindex

\end{document}