path: root/Master/texmf-dist/source/latex/draftwatermark/draftwatermark.dtx

% \iffalse meta-comment
%
% Copyright 2006, 2012
% Sergio Callegari <sergio.callegari@gmail.com>
%
% ---------------------------------------------
% This file is part of the draftwatermark package,
% a contribution to the LaTeX2e system.
% ---------------------------------------------
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License, either version 1.3 of this licence, or
% any later version. The latest version of this license is at
% http://www.latex-project.org/lppl.txt and version 1.3 is part
% of all distributions of LaTeX version 2003/06/01 or later.
%
% This work has the LPPL maintenance status "author-maintained".
%
% This program consists of the files listed in the README file
% included in the package.
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{mathptmx, helvet, courier}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\usepackage{url}
\EnableCrossrefs
\DoNotIndex{\def,\gdef,\let,\NeedsTeXFormat,\newcommand}
\DoNotIndex{\ProvidesPackage,\endinput}
\DoNotIndex{\box,\dp,\fontsize,\ifx,\else,\fi}
\DoNotIndex{\hbox,\hss,\makebox,\moveleft,\newif,\newlength}
\DoNotIndex{\ProcessOptions,\vbox,\vss,\z@}
\DoNotIndex{\AddEverypageHook,\AddThispageHook}
\DoNotIndex{\@tempboxa,\@tempdimb,\@tempdimc}
\DoNotIndex{\begin}
\DoNotIndex{\DeclareOption,\documentclass}
\DoNotIndex{\end,\expandafter}
\DoNotIndex{\maketitle}
\DoNotIndex{\paperheight,\paperwidth,\put}
\DoNotIndex{\RequirePackage,\rotatebox}
\DoNotIndex{\scalebox,\section,\selectfont,\setbox,\setlength}
\DoNotIndex{\strip@pt}
\DoNotIndex{\textcolor,\title}
\DoNotIndex{\usepackage}
\DoNotIndex{\vskip}   
\CodelineIndex
%\RecordChanges
\begin{document}
  \DocInput{draftwatermark.dtx}
\end{document}
%</driver>
%
% \fi
%
% \CheckSum{143}
%
% \def\filename{draftwatermark.dtx}
% \def\fileversion{1.2}
% \def\filedate{2015/02/19}
% \def\docdate{2015/02/19}
%
% \newcommand*{\Lpack}[1]{\textsf {#1}}           ^^A typeset a package
% \newcommand*{\Lopt}[1]{\textsf {#1}}            ^^A typeset an option
% \newcommand*{\file}[1]{\texttt {#1}}            ^^A typeset a file
% \newcommand*{\Lcount}[1]{\textsl {\small#1}}    ^^A typeset a counter
% \newcommand*{\pstyle}[1]{\textsl {#1}}          ^^A typeset a pagestyle
% \newcommand*{\Lenv}[1]{\texttt {#1}}            ^^A typeset an environment
%
% \title{The \Lpack{draftwatermark} package\thanks{This file
%     (\texttt{\filename}) has version number \fileversion, last
%     revised \filedate.}}
%
% \author{%
%   Sergio Callegari\thanks{Sergio Callegari can be reached at
%       \texttt{sergio.callegari at gmail dot com}}} 
%
% \date{\docdate}
%
% \maketitle
%
% \begin{abstract}
%   The \Lpack{draftwatermark} package extends \LaTeX\ providing a means
%   to add a textual (usually light gray, but possibly colored) watermark
%   on every page or on the first page of a document. Typical usage may
%   consist in writing words such as \emph{DRAFT} or \emph{CONFIDENTIAL}
%   across document pages. The package may remind in some sense
%   \Lpack{draftcopy} by Dr.~Juergen Vollmer, but its implementation is
%   much lighter (as the reduced code footprint shows) and does not rely
%   on postscript specials, making the package fully compatible with
%   pdf\LaTeX. The package depends on \Lpack{everypage} by the same
%   author.
% \end{abstract}
% 
% \section{Introduction}
% 
% This program extends \LaTeX\ providing a means to add a textual,
% (usually light gray, but possibly colored) watermark on every page or on
% the first page of a document. Typical usage may consist in writing words
% such as \emph{DRAFT} or \emph{CONFIDENTIAL} across document pages. The
% package may remind in some sense \Lpack{draftcopy} by Dr.~Juergen
% Vollmer, but its implementation differs by a few points:
% \begin{enumerate}
% \item Code footprint is much, much smaller (about one order of
%   magnitude smaller), although this does not mean much on modern
%   computers.
% \item There is no use of Postscript specials or other
%   driver-dependent tricks, so the package should be compatible with
%   any output driver and with pdf\LaTeX\ in particular. Lack of
%   compatibility with pdf\LaTeX\ in these days is the biggest pitfall
%   of \Lpack{draftcopy} and was the first motivation for writing
%   \Lpack{draftwatermark}.
% \item Reduced code footprint comes at some price with regards to
% features. Many features of \Lpack{draftcopy} are not supported here,
% most notably \Lpack{draftwatermark} has:
% \begin{itemize}
% \item No automatic selection of the watermark text to use, depending on
%   the language, using translations of the word ``DRAFT''. However,
%   this is no big loss, since there is a possibility to set the text
%   to use explicitly, and this leaves the freedom to chose whatever
%   text one happens to prefer, including things that have nothing to
%   do with the word ``DRAFT'' (e.g., ``CONFIDENTIAL'', ``FOR YOUR
%   EYES ONLY'', etc.).
% \item No possibility to watermark only the first \emph{two} pages of a
%   document. However, it is possible to watermark only the first.
% \end{itemize}
% Other features available as options in \Lpack{draftcopy} (e.g., the
% possibility of time-stamping the watermark text) can be obtained
% working on the watermark text itself.
% \item Dependence on the \Lpack{everypage} package by the same
% author.
% \end{enumerate}
% 
% \section{User interface}
% When loaded, \Lpack{draftwatermark} sets up a number of defaults
% (detailed later and modifiable by specific commands) and immediately
% becomes active.
% 
% \subsection{Package options}
% If loaded as
% \begin{quote}
% |\usepackage{draftwatermark}|
% \end{quote}
% the package sets up itself to put a background text on every
% page. Alternatively, if loaded as
% \begin{quote}
% |\usepackage[firstpage]{draftwatermark}|
% \end{quote}
% the package sets up itself to put a background text only on the
% first page.
%
% If loaded as
% \begin{quote}
% |\usepackage[nostamp]{draftwatermark}|
% \end{quote}
% the package does not print any watermark even if it is loaded and
% configured to do so. This is handy for quickly removing the ``draft''
% status from a document. Option \Lopt{final} is a synonym for
% \Lopt{nostamp}. This can be handy because \Lopt{final} is a commonly
% used global option that can be simultaneously obeyed by many packages
% (e.g., to include figures, remove marks, and so on). The option
% \Lopt{stamp} can be used to override a global \Lopt{final} option and to
% recover the watermarking.
%
% \subsection{Default behavior and commands to modify it}
% The package defaults are illustrated in table~\ref{tbl:defaults}.
%
% \begin{table}[ht]
%   \begin{center}
%     \DeleteShortVerb{\|}
%     \begin{tabular}{|p{0.6\linewidth}|c|}
%       \hline
%       \MakeShortVerb{\|}       
%       Behavior & Default value\\
%       \hline\hline
%       Angle at which the watermark text is drawn & 45°\\
%       Color of the watermark text & gray 80\%\\       
%       Font size of the watermark text & 5$\;$cm\\
%       Horizontal center of watermark text & .5pagewidth\\
%       Scaling of the watermark text & 1.2\\
%       Vertical center of watermark text & .5pageheight\\
%       Watermark text & DRAFT\\
%       \hline
%     \end{tabular}
%   \end{center}
%   \caption{Package defaults.}
%   \label{tbl:defaults}
% \end{table}
%
% With reference to the defaults, note that:
% \begin{enumerate}
% \item the watermark font size cannot exceed a maximum value that is
%   about 5$\;$cm.
% \item the watermark scale can be any value. Using the default, the
% word ``DRAFT'' at 45° uses up all the space on an A4 paper. To have
% a good looking large text, it is better to enlarge the font size as
% much as possibile, rather than using a small font size and pumping
% up the scale.
% \item the watermark horizontal and vertical centers define the
% center of the text. Origin is upper left corner of page and values
% are positive.
% \end{enumerate}
%
% \DescribeMacro{\SetWatermarkAngle}
% \DescribeMacro{\SetWatermarkColor}
% \DescribeMacro{\SetWatermarkFontSize}
% \DescribeMacro{\SetWatermarkScale}
% \DescribeMacro{\SetWatermarkHorCenter}
% \DescribeMacro{\SetWatermarkVerCenter}
% \DescribeMacro{\SetWatermarkText}
% Table~\ref{tbl:commands} illustrates the commands used to modify the
% package behaviour. 
%
% \begin{table}[ht]
%   \begin{center}
%     \DeleteShortVerb{\|}
%     \begin{tabular}{|p{0.4\linewidth}|l|}
%       \hline
%       \MakeShortVerb{\|}
%       Behavior & Command affecting it\\
%       \hline\hline
%       Angle at which the watermark text is drawn &
%       |\SetWatermarkAngle{|\meta{real}|}|\\
%       Color of the watermark &
%       |\SetWatermarkColor|$\;$\meta{col\_spec}\\
%       Lightness of the watermark text (1=white, 0=black) &
%       |\SetWatermarkLightness{|\meta{real}|}|\\
%       Font size of the watermark text &
%       |\SetWatermarkFontSize{|\meta{length}|}|\\
%       Scaling of the watermark text &
%       |\SetWatermarkScale{|\meta{real}|}|\\
%       Horizontal center of watermark text &
%       |\SetWatermarkHorCenter{|\meta{length}|}|\\
%       Vertical center of watermark text &
%       |\SetWatermarkVerCenter{|\meta{length}|}|\\
%       Watermark text &
%       |\SetWatermarkText{|\meta{text}|}|\\
%       \hline
%     \end{tabular}
%   \end{center}
%   \caption{Commands affecting the package behavior.}
%   \label{tbl:commands}
% \end{table}
%
% Note that \meta{col\_spec} can be either a named color such as
% |{|\meta{name}|}| or a color specification such as
% |[|\meta{model}|]{|\meta{specs}|}|. For instance
% \begin{quote}
%  |\SetWatermarkColor{red}|\\
%  |\SetWatermarkColor[rgb]{0,1,0}|
% \end{quote}
% \DescribeMacro{\SetWatermarkLightness}
% are both valid colors. Also note that the command
% \begin{quote}
%   |\SetWatermarkLightness{|\meta{real}|}|
% \end{quote}
% is provided as a conveniency (and for backward compatibility) to select
% gray watermarks (1=white, 0=black).
%
% Observe that the |\SetWatermarkFontSize|,
% |\SetWatermarkHorCenter| and |\SetWatermarkVerCenter|
% commands take a length rather than a simple number.
% Also observe that multiline textual
% watermarks can easily be obtained by the |\shortstack| command and
% that there is the possibility of using an image rather than a text
% (e.g., a ``caution, work in progress'' sign, etc.). 
%
% Note that once the package is loaded, there is no way to stop it.
% In order to have textual watermarks that appear only when
% specific conditions are met, conditionals must be included in the
% watermarks.
% 
% Eventually consider that no special assumption is made on the
% \LaTeX\ output driver, so \Lpack{draftwatermark} should work equally
% well with \LaTeX\ and pdf\LaTeX. Furthermore, the package should
% work equally well with the dvi, dvips, etc.\@ output drivers.
% Obviously, the final compatibility with the different output drivers
% depends on the actual code that is placed in the textual watermark.
% 
% \section{Example}
% 
% As an example, consider the following code snippet:
% \iffalse
%<*samplecode>
% \fi
%    \begin{macrocode}
\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{mathptmx}
\usepackage{draftwatermark}
\title{Sample document for the draftwatermark package}

\begin{document}
\maketitle

\section{One}
This text is here just to fill in some space. This text is here just to
fill in some space. This text is here just to fill in some space. This
text is here just to fill in some space. This text is here just to fill in
some space. This text is here just to fill in some space. This text is
here just to fill in some space. This text is here just to fill in some
space. This text is here just to fill in some space. This text is here
just to fill in some space. This text is here just to fill in some
space. This text is here just to fill in some space. This text is here
just to fill in some space. This text is here just to fill in some
space. This text is here just to fill in some space. This text is here
just to fill in some space. This text is here just to fill in some
space. This text is here just to fill in some space. This text is here
just to fill in some space. This text is here just to fill in some
space. This text is here just to fill in some space.

\section{Two}

Also this text is here just to fill in some space. Also this text is here
just to fill in some space. Also this text is here just to fill in some
space. Also this text is here just to fill in some space. Also this text
is here just to fill in some space. Also this text is here just to fill in
some space. Also this text is here just to fill in some space. Also this
text is here just to fill in some space. Also this text is here just to
fill in some space. Also this text is here just to fill in some
space. Also this text is here just to fill in some space. Also this text
is here just to fill in some space. Also this text is here just to fill in
some space. Also this text is here just to fill in some space. Also this
text is here just to fill in some space. Also this text is here just to
fill in some space. Also this text is here just to fill in some space.

\end{document}
%    \end{macrocode}
% \iffalse
%</samplecode>
% \fi
%
% \section{Development and support}
%
% The package is developed at \emph{github}:
% \begin{quote}
%   \url{https://github.com/callegar/LaTeX-draftwatermark}
% \end{quote}
% Please refer to that site for any bug report or development information.
%
% \section{Changelog}
% \begin{description}
% \item[1.0 - 2006/06/30] Initial version.
% \item[1.1 - 2012/01/06] Add support for colored watermarks; Options to
%   disable watermarking; Many small fixes in the documentation.
% \item[1.2 - 2015/02/19] Add support for watermark position.
% \end{description}
%
% \StopEventually {}
% 
% \section{Implementation}
%
% Announce the name and version of the package, which requires
% \LaTeXe.
% \iffalse
%<*draftwatermark>
% \fi
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{draftwatermark}%
  [2015/02/19 1.2 Put a gray textual watermark on document pages]
%    \end{macrocode}
%
% Require the needed packages. Note that if these are pre-loaded
% before loading \Lpack{draftwatermark}, using suitable options to
% preset behavior for a desired output driver, this is used also
% here.
%    \begin{macrocode}
\RequirePackage{everypage}[2007/06/20]
\RequirePackage{graphicx}
\RequirePackage{color}
%    \end{macrocode}
%
% \begin{macro}{\if@sc@wm@first}
% Set up the conditional to store whether a watermark is needed only
% on the first page or everywhere.
%    \begin{macrocode}
\newif\if@sc@wm@first
\@sc@wm@firstfalse
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\if@sc@wm@stamp}
%   Set up the conditional to store whether to stamp the watermark or not.
%    \begin{macrocode}
\newif\if@sc@wm@stamp
\@sc@wm@stamptrue
%    \end{macrocode}
% \end{macro}
% 
% Declare the package options.
%    \begin{macrocode}
\DeclareOption{firstpage}{%
  \@sc@wm@firsttrue}
\DeclareOption{nostamp}{%
  \@sc@wm@stampfalse}
\DeclareOption{final}{%
  \@sc@wm@stampfalse}
\DeclareOption{stamp}{%
  \@sc@wm@stamptrue}
\ProcessOptions
%    \end{macrocode}
% 
% \begin{macro}{\sc@wm@angle}
% \begin{macro}{\sc@wm@colormodel}
% \begin{macro}{\sc@wm@colorspecs}
% \begin{macro}{\sc@wm@scale}
% \begin{macro}{\sc@wm@hcenter}
% \begin{macro}{\sc@wm@vcenter}
% \begin{macro}{\sc@wm@fontsize}
% \begin{macro}{\sc@wm@text}
% Set up the package defaults.
%    \begin{macrocode}
\newlength\sc@wm@hcenter
\newlength\sc@wm@vcenter
\newlength\sc@wm@fontsize
%% defaults
\def\sc@wm@angle{45}
\def\sc@wm@colormodel{[gray]}
\def\sc@wm@colorspecs{0.8}
\def\sc@wm@scale{1}
\setlength\sc@wm@hcenter{.5\paperwidth}
\setlength\sc@wm@vcenter{.5\paperheight}
\setlength\sc@wm@fontsize{5cm}
\def\sc@wm@text{DRAFT}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\SetWatermarkAngle}
% \begin{macro}{\SetWatermarkColor}
% \begin{macro}{\SetWatermarkLightness}
% \begin{macro}{\SetWatermarkFontSize}
% \begin{macro}{\SetWatermarkScale}
% \begin{macro}{\SetWatermarkHorCenter}
% \begin{macro}{\SetWatermarkVerCenter}
% \begin{macro}{\SetWatermarkText}
% Set up the commands to modify the behavior.
%    \begin{macrocode}
\newcommand\SetWatermarkAngle[1]{%
  \def\sc@wm@angle{#1}}
\newcommand\SetWatermarkColor{}
\def\SetWatermarkColor#1#{\sc@setWatermarkColor{#1}}
\def\sc@setWatermarkColor#1#2{%
  \def\sc@wm@colormodel{#1}%
  \def\sc@wm@colorspecs{#2}}
\newcommand\SetWatermarkLightness[1]{%
  \SetWatermarkColor[gray]{#1}}
\newcommand\SetWatermarkFontSize[1]{%
  \setlength\sc@wm@fontsize{#1}}
\newcommand\SetWatermarkScale[1]{%
  \def\sc@wm@scale{#1}}
\newcommand\SetWatermarkHorCenter[1]{%
  \setlength\sc@wm@hcenter{#1}}
\newcommand\SetWatermarkVerCenter[1]{%
  \setlength\sc@wm@vcenter{#1}}
\newcommand\SetWatermarkText[1]{%
  \def\sc@wm@text{#1}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% 
%\begin{macro}{\sc@watermark}
% The command to draw the watermark\ldots This assumes an origin in
% the left top corner of the page (and also assumes that |\paperwidth|
% and |\paperheight| are set correctly if accepting the defaults).
% There is no need to worry
% about the horizontal and vertical size that is taken by the
% watermark object. Note that this is typically a text, but
% |\sc@wm@text| may well contain other material, e.g.\@ an
% |\includegraphics| directive.
%    \begin{macrocode}
\newcommand\sc@watermark{%
  \setlength{\@tempdimb}{\sc@wm@hcenter}%
  \setlength{\@tempdimc}{-\sc@wm@vcenter}%
  \put(\strip@pt\@tempdimb,\strip@pt\@tempdimc){%
    \makebox(0,0){\rotatebox{\sc@wm@angle}{%
        \scalebox{\sc@wm@scale}{%
          \expandafter\expandafter\expandafter\textcolor
          \expandafter\sc@wm@colormodel\expandafter{\sc@wm@colorspecs}{%
            \fontsize{\sc@wm@fontsize}{1.2\sc@wm@fontsize}
            \selectfont
            \sc@wm@text}}}}}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\sc@wm@print}
% The command to actually \emph{print} the watermark. It is assumed
% that this is called before any other material is shipped to the
% page. As such, the origin here is the page origin in Knuthian sense
% (1 inch down, 1 inch right from the top left corner of the
% page\ldots First of all, this is changed to the proper top left
% corner of the page. 
%    \begin{macrocode}
\newcommand\sc@wm@print[1]{%
  \if@sc@wm@stamp
  \setbox\@tempboxa\vbox to \z@{%
    \vskip -1in \moveleft 1in \vbox{%
      \hbox to \z@{%
        #1\hss}}\vss}
  \dp\@tempboxa\z@
  \box\@tempboxa
  \fi}
%    \end{macrocode}
% \end{macro}
%
% Eventually, set up the |\sc@wm@print| command to be called when
% needed, using the appropriate \Lpack{everypage} hook.
%    \begin{macrocode}
\if@sc@wm@first
\AddThispageHook{\sc@wm@print{\sc@watermark}}
\else
\AddEverypageHook{\sc@wm@print{\sc@watermark}}
\fi
\endinput
%    \end{macrocode}
% \iffalse
%</draftwatermark>
% \fi
%
% \Finale
% \PrintIndex
%
%% \CharacterTable
%%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
\endinput

%%% Local Variables: 
%%% mode: doctex
%%% TeX-master: t
%%% End: