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

% \iffalse meta-comment
%
% Copyright (C) 2009 by Gonzalo Medina
%
% --------------------------------------------------------------------------
%
% This file may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
% of this license or (at your option) any later version.
% The latest version of this license is in:
%
% http://www.latex-project.org/lppl.txt
%
% and version 1.3 or later is part of all distributions of LaTeX
% version 2003/12/01 or later.
%
% This work has the LPPL maintenance status `maintained'.
% 
% The Current Maintainer of this work is Gonzalo Medina.
%
% This work consists of the files background.dtx and background.ins,
% and the derived files background.sty and background.pdf.
%
% \fi
%
% \iffalse
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{booktabs}
\usepackage{xcolor}
\usepackage{ragged2e}
\usepackage{amsthm}
\usepackage{ifpdf}
\ifpdf
  \usepackage[top]{background}
  \SetBgContents{-\thepage-}
  \SetBgAngle{0}
  \SetBgColor{black!40}
  \SetBgScale{4}
  \SetBgHshift{60}
  \SetBgVshift{-5}
  \usepackage{mathptmx,courier}
  \usepackage[scaled=.9]{helvet}
\fi
\usepackage{hypdoc}
\ifpdf
  \usepackage{hypdestopt}
\fi
\hypersetup{pdfkeywords={LaTeX, package, background},%
  pdfstartpage={},pdfstartview={},breaklinks=true,%
  linktocpage}

\newcommand\MarNote[1]{\marginpar{\RaggedLeft\textcolor{blue}{#1}}}
\newcommand*\package[1]{{\upshape\mdseries\sffamily #1}}

\theoremstyle{remark}
\newtheorem{exam}{Example}

\setlength\parindent{0pt}

\pagestyle{empty}
\makeatletter
  \let\ps@titlepage\ps@empty
\makeatother

\usepackage{titletoc}
\titlecontents*{section}[0pt]
  {\itshape}{}{}
  {, \thecontentspage}[\ --\ ][.]
\titlecontents*{subsection}[0pt]
  {\upshape\small}{}{}
  {, \thecontentspage}[ (][. ][)]
\setcounter{tocdepth}{2}
\EnableCrossrefs
\CodelineIndex
\RecordChanges

\begin{document}
\DocInput{background.dtx}
\end{document}
%</driver>
% \fi
%
% \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         \~}
%
% \CheckSum{127}
%
% \changes{v 1.0}{2009/11/07}{First version}
%
% \GetFileInfo{background.sty}
%
% \title{The \package{background} package\\
% {\footnotesize\fileversion , dated \filedate.}}
% \author{Gonzalo Medina\\%
%   Universidad Nacional de Colombia -- Sede Manizales\\%
%   Departamento de Matem\'aticas y Estad\'istica\\
%   \texttt{gmedinaar@unal.edu.co}}
%
% \maketitle
%
% \begin{abstract}
% \noindent This package allows the placement of background material on the pages of a 
% document. The user can control many aspects (i.e., contents, position, color, opacity) of the
% background material that will be displayed. 
% \end{abstract}
% \tableofcontents
% \section{Introduction}
% The \package{background} package relies on the \package{TikZ} and \package{everypar} 
% packages to provide a simple and flexible mechanism to include background material on all 
% (or on some of) the pages of a \LaTeX2e document.
% \par\medskip
% The implementation is quite simple and parallels the one of the \package{draftwatermark} 
% package by Sergio Callegari, but adds greater control over the background material attributes.
% \par\medskip
% The author will gladly receive suggestions, comments and bug reports.
%
% \section{User Interface}
%
% Loading this package (without any package options) in the preamble of a document in the 
% standard way:
% \begin{center}
% |\usepackage{background}|
% \end{center}
% activates a set of predefined options that will typeset the word "Draft" across every page of 
% your document (from the lower left corner to the upper right corner), using 
% \textcolor{red!45}{this color} and a huge font size.
% \par\medskip
% Of course, the package can be loaded using some of the options described in the next section;
% for example:
% \begin{center}
% |\usepackage[some,bottom]{background}|
% \end{center}
%
% \subsection{Package Options}
% Table~\ref{tab:options} shows the available package options\MarNote{By 
% default, the package loads the options |all| and |center|.} and their meaning. Obviously, the
%  options |all| and |some| are mutually exclusive; the same remark applies to the group of options
% |center|, |bottom|, and |top|.
% \par\medskip
% Take into account that using the |some| option will cause no background material to be displayed 
% at all and the user will have to issue the command |\BgThispage| for each page
% in which he/she desires the background material to appear (see example \ref{exa:bgthispage}).
%
% \begin{table}[!ht]
%   \centering
%   \begin{tabular}{rp{6cm}}\toprule
%   Option & Meaning\\\toprule
%   |all| & The background material will be displayed in all the pages.\\
%   |some| & The background material will be displayed only in the pages for which the 
%   |\BgThispage| command was used.\\
%   |center| & The background material will be displayed diagonally.\\
%   |bottom| & The background material will be displayed horizontally at the bottom of the page.\\
%   |top| & The background material will be displayed horizontally at the top of the page.
%   \\\bottomrule
%   \end{tabular}
%  \caption{The package options.}
%  \label{tab:options}
% \end{table}
% 
% \subsection{User Commands}
%  Since the commands used to modify attributes of the background material depend on the 
% |\node| construct offered by the \package{TikZ} package, we strongly encourage the reading 
% of Till Tantau's
%  \href{http://mirror.ctan.org/graphics/pgf/base/doc/generic/pgf/pgfmanual.pdf}%
%    {\emph{PGF/TikZ package manual}}.
% \par\medskip
% \DescribeMacro{\SetBgContents}
% This command allows the user to change the material that will be used as background. The usage 
% is
%  \begin{center}
%    |\SetBgContents{|\meta{material}|}|
 % \end{center}
% where \meta{material} can be any text or an image (via the |\includegraphics| command
% from the \package{graphicx} package) or even a graphic created, for example, with the
% \package{TikZ} package.
% \par\medskip
% \DescribeMacro{\SetBgColor}
% This command allows the user to change the color that will be used for the background material if % such material is text. The usage is
% \begin{center}
%   |\SetBgContents{|\meta{color}|}|
% \end{center}
% where \meta{color} can be any color set by the \package{xcolor} package.
% \par\medskip
% \DescribeMacro{\SetBgAngle}
% This command allows the user to change the angle that will be used for displaying the background % material. The usage is
% \begin{center}
%   |\SetBgContents{|\meta{degrees}|}|
% \end{center}
% where \meta{degrees} can be any value between $-360$ and $360$.
% \par\medskip
% \DescribeMacro{\SetBgOpacity}
% This command allows the user to change the transparency level for the background material. The % usage is
% \begin{center}
%   |\SetBgOpacity{|\meta{value}|}|
% \end{center}
% where \meta{value} can be any number between $0$ (full transparency) and $1$ (no 
% transparency at all).
% \par\medskip
% \DescribeMacro{\SetBgScale}
% This command allows the user to change the scaling factor that will be applied to the background
% material. The usage is
% \begin{center}
%   |\SetBgScale{|\meta{factor}|}|
% \end{center}
% where \meta{factor} can be any positive value.
% \par\medskip
% \par\medskip
% \DescribeMacro{\SetBgPosition}
% This command allows the user to define the position of the background
% material. The usage is
% \begin{center}
%   |\SetBgPosition{|\meta{position}|}|
% \end{center}
% where \meta{position} can be any valid\MarNote{Do not enclose \meta{position} inside
%  parentheses} position accepted by the |at| syntax for nodes placement (see the TikZ 
% manual). Some examples of valid positions are
% \begin{center}
%   |\SetBgPosition{0,0}|\\
%   |\SetBgPosition{current page.north}|\\
%   |\SetBgPosition{5cm,7cm}|
% \end{center}
% \par\medskip
% \DescribeMacro{\SetBgAnchor}
% This command allows the user to set the anchor for the node placement. The usage is
% \begin{center}
%   |\SetBgAnchor{|\meta{anchor name}|}|
% \end{center}
% Typical examples are:
% \begin{center}
%   |\SetBgAnchor{north east}|\\
%   |\SetBgAnchor{west}|\\
% \end{center}
% \par\medskip
% \DescribeMacro{\SetBgHshift}
% \DescribeMacro{\SetBgVshift}
% These two commands control the horizontal and vertical shifting of the node position.
% \begin{center}
%   |\SetBgHshift{|\meta{value}|}|\\
%   |\SetBgVshift{|\meta{value}|}|
% \end{center}
% \par\medskip
% The following two commands are designed to give the user control on whether the background
% material should or should not appear on specific pages of the document.
% \par\medskip 
% \DescribeMacro{\BgThispage}
% This command permits to select particular pages in which the background material will
% be displayed (see example \ref{exa:bgthispage}).
%
% \subsubsection{Experimental}
% \DescribeMacro{\NoBgThispage}
% This command will prevent the background material to be displayed in the page where it
% \MarNote{Do not use this command in two column mode.}
% was issued. Its implementation depends on the \package{afterpage} package,
% so the corresponding precautions must be taken into account (see example 
% \ref{exa:nobgthispage}) . 
%
% \section{Examples}
% In the following examples, the \package{lipsum} package was used only to automatically
% generate text.
% \begin{exam}
% This example shows how to display the background material only on the first two pages of
% the document: 
% \end{exam}
% |\documentclass{article}|\\
% |\usepackage{background}|\\
% |\usepackage{lipsum}|\\
%
% |\begin{document}|\\
% |\lipsum[1-10]|\\
% |\newpage\SetBgContents{}|\\
% |\lipsum[1-30]|\\
% |\end{document}|
% \begin{exam}
% This example imitates the page numbering format used in this document: 
% \end{exam} 
% |\documentclass{article}|\\
% |\usepackage[top]{background}|\\
% |\usepackage{lipsum}|\\
%
% |\SetBgContents{-\thepage-}|\\
% |\SetBgAngle{0}|\\
% |\SetBgColor{black!40}|\\
% |\SetBgScale{4}|\\
% |\SetBgHshift{60}|\\
% |\SetBgVshift{-5}|\\
%
% |\pagestyle{empty}|\\
%
% |\begin{document}|\\
% |\lipsum[1-30]|\\
% |\end{document}|
%
% \begin{exam}\label{exa:bgthispage}
% This example illustrates how to use of the |\BgThispage| command to add background material 
% on selected pages.
% \end{exam}
% |\documentclass{article}|\\
% |\usepackage[some,top]{background}|\\
% |\usepackage{lipsum}|\\
%
% |\begin{document}|\\
% |\lipsum[1-5]|\\
% |\newpage|\\
% |\SetBgContents{A}\SetBgColor{yellow}|\\
% |\BgThispage|\\
% |\lipsum[1-5]|\\
% |\newpage|\\
% |\SetBgContents{B}\SetBgColor{blue}|\\
% |\BgThispage|\\
% |\lipsum[1-5]|\\
% |\end{document}|
% 
% \begin{exam}
% This example shows how to proceed in order to obtain different background material for the 
% odd and even pages of a document.
% \end{exam}
% |\documentclass{article}|\\
% |\usepackage{background}|\\
% |\usepackage{lipsum}|\\
% |\usepackage{ifthen}|\\
%
% |\SetBgContents{}|\\
% |\SetBgOpacity{1}|\\
% |\SetBgScale{1.5}|\\
% |\makeatletter|\\
% |\AddEverypageHook{%|\\
% |  \ifthenelse{\isodd{\thepage}}%|\\
% |    {\SetBgAngle{90}%|\\
% |     \SetBgPosition{0,-.7\textheight}%|\\
% |     \SetBgColor{blue!90}%|\\
% |     \SetBgContents{The background package}}%|\\
% |    {\SetBgAngle{270}%|\\
% |     \SetBgPosition{1.35\textwidth,-.7\textheight}%|\\
% |     \SetBgContents{First version}}%|\\
% |  \bg@material}|\\
% |\makeatother|\\
%
% |\begin{document}|\\
% |\lipsum[1-30]|\\
% |\end{document}|
%
% \begin{exam}\label{exa:nobgthispage}
% This example\MarNote{Adding the |twocolumn| class option will produce compilation errors}
% illustrates the use of the |\NoBgThispage| command, to 
% suppress the background material on selected pages (page 2, in this case).
% \end{exam}
% |\documentclass{article}|\\
% |\usepackage{background}|\\
% |\usepackage{lipsum}|\\
%
% |\begin{document}|\\
% |\lipsum[1-5]|\\
% |\newpage\NoBgThispage|\\
% |\lipsum[1-5]|\\
% |\newpage|\\
% |\lipsum[1-20]|\\
% |\end{document}|
%
% \DoNotIndex{\#,\$,\%,\&,\@,\\,\{,\},\^,\_,\~,\ }
% \DoNotIndex{\advance,\begingroup,\begin,\catcode,\closein}
% \DoNotIndex{\closeout,\day,\def,\edef,\else,\end,\empty,\endgroup,\fi}
% \DoNotIndex{\let,\newcommand,\renewcommand}
% 
% \StopEventually{\PrintIndex}
%
% \section{Implementation}
% 
% Standard identification:
% \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{background}[2009/11/07 v1.0 bg material]
%    \end{macrocode}
%
% Now we load the packages that will be used:
%
% \begin{macrocode}

\RequirePackage{everypage}
\RequirePackage{tikz}
\RequirePackage{afterpage}
%    \end{macrocode}
%
% \begin{macro}{\bg@some}
% A boolean (initially set to |false|) to control whether the background material will be displayed in
% every page or not.
% \begin{macrocode}

\newif\ifbg@some
  \bg@somefalse
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\bg@contents}
% \begin{macro}{\bg@color}
% \begin{macro}{\bg@angle}
% \begin{macro}{\bg@opacity}
% \begin{macro}{\bg@scale}
% \begin{macro}{\bg@position}
% \begin{macro}{\bg@anchor}
% \begin{macro}{\bg@hshift}
% \begin{macro}{\bg@vshift}
% We define the internal control commands and set their default value:
% \begin{macrocode}

\def\bg@contents{Draft}
\def\bg@color{red!45}
\def\bg@angle{60}
\def\bg@opacity{.5}
\def\bg@scale{15}
\def\bg@position{current page.center}
\def\bg@anchor{}
\def\bg@hshift{0}
\def\bg@vshift{0}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% 
% Now we declare the package options:
% \begin{macrocode}

\DeclareOption{all}{\bg@somefalse}
\DeclareOption{some}{\bg@sometrue}
\DeclareOption{center}{%
  \def\bg@position{current page.center}%
  \def\bg@anchor{}%
  \def\bg@angle{60}}
\DeclareOption{bottom}{%
  \def\bg@position{current page.south}%
  \def\bg@anchor{above}%
  \def\bg@angle{0}%
  \def\bg@scale{8}}
\DeclareOption{top}{%
  \def\bg@position{current page.north}%
  \def\bg@anchor{below}%
  \def\bg@angle{0}%
  \def\bg@scale{8}}
%    \end{macrocode}
%
% We next execute and process options in the standard \LaTeX2e way:
% \begin{macrocode}

\ExecuteOptions{all,center}
\ProcessOptions
%    \end{macrocode}
%
% \begin{macro}{\SetBgContents}
% \begin{macro}{\SetBgColor}
% \begin{macro}{\SetBgAngle}
% \begin{macro}{\SetBgOpacity}
% \begin{macro}{\SetBgScale}
% \begin{macro}{\SetBgPosition}
% \begin{macro}{\SetBgAnchor}
% \begin{macro}{\SetBgHshift}
% \begin{macro}{\SetBgVshift}
% Now comes the definition of the user commands:
% \begin{macrocode}

\newcommand*\SetBgContents[1]{%
  \def\bg@contents{#1}}
\newcommand*\SetBgColor[1]{%
  \def\bg@color{#1}}
\newcommand*\SetBgAngle[1]{%
  \def\bg@angle{#1}}
\newcommand*\SetBgOpacity[1]{%
  \def\bg@opacity{#1}}
\newcommand*\SetBgScale[1]{%
  \def\bg@scale{#1}}
\newcommand*\SetBgPosition[1]{%
  \def\bg@position{#1}}
\newcommand*\SetBgAnchor[1]{%
  \def\bg@anchor{#1}}
\newcommand*\SetBgHshift[1]{%
  \def\bg@hshift{#1}}
\newcommand*\SetBgVshift[1]{%
  \def\bg@vshift{#1}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\bg@material}
% Our main command uses a simple |\node| construct to build the background material.
% \begin{macrocode}

\newcommand\bg@material{%
  \begin{tikzpicture}[remember picture,overlay]
  \node [rotate=\bg@angle,scale=\bg@scale,opacity=\bg@opacity,%
    xshift=\bg@hshift,yshift=\bg@vshift,color=\bg@color]
    at (\bg@position) [\bg@anchor]  {\bg@contents};
  \end{tikzpicture}}%
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\BgThispage}
% A simple application of the |AddThispageHook| command provided by the \package{everypage}
% package.
% \begin{macrocode}
\newcommand\BgThispage{\AddThispageHook{\bg@material}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\NoBgThispage}
% A hack that perhaps admits improvements. We make a copy of |\bg@material|, and redefine
% it to be empty on the current page. Then we use the |afterpage| command to restore the 
% original background material.
% \begin{macrocode}

\newcommand\NoBgThispage{%
  \let\oldbg@material\bg@material\renewcommand\bg@material{}%
  \afterpage{\AddEverypageHook{\oldbg@material}}}
%    \end{macrocode}
% \end{macro}
%
% Finally, we check for the boolean |bg@some|; if it is |true|, then no background material is
% added; otherwise, the material will be added using the |AddEverypageHook| command.
% \begin{macrocode}

\ifbg@some
  \AddThispageHook{}
\else
  \AddEverypageHook{\bg@material}
\fi
%    \end{macrocode}
%
% \Finale
\endinput