path: root/macros/latex/contrib/fullminipage/fullminipage.dtx

% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \iffalse meta-comment
%
% DocStrip file for fullminipage package
%
% Copyright 2012 Christian Schneider <software(at)chschneider(dot)eu>
%
% This file is part of fullminipage.
%
% fullminipage is free software: you can redistribute it and/or modify
% it under the terms of the GNU General Public License version 3 as
% published by the Free Software Foundation, not any later version.
%
% fullminipage is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with fullminipage.  If not, see <http://www.gnu.org/licenses/>.
%
% WARNING: THIS IS ALPHA SOFTWARE AND MAY CONTAIN SERIOUS BUGS!
%
% \fi
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{fullminipage}
%<package>  [2014/07/06 v0.1.1 fullpage minipage environment]
%<*driver>
\documentclass[a4paper]{ltxdoc}
\usepackage{fullminipage}
\usepackage{hyperref}
\usepackage{units}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
%
% modified description environment
\newcommand{\listmark}{$\bullet$}
\newcommand{\listlengths}{%
  \setlength{\parsep}{0pt}%
  \setlength{\itemsep}{0pt}%
  \setlength{\leftmargin}{10.5em}%
  \setlength{\rightmargin}{0pt}%
  \setlength{\labelsep}{1em}%
  \setlength{\labelwidth}{9.5em}}
\newenvironment{mydescription}{%
  \begin{list}{\listmark}{\listlengths}%
}{%
  \end{list}%
}
%
\begin{document}
  \DocInput{fullminipage.dtx}
\end{document}
%</driver>
% \fi
%
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% \changes{v0.1.0}{2014/06/22}{initial public version}
% \changes{v0.1.1}{2014/07/06}{corrected README file; no \LaTeX{} changes}
%
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% \CheckSum{151}
%
% \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        \~}
%
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% \GetFileInfo{fullminipage.sty}
%
% \DoNotIndex{\#,\$,\%,\&,\@,\\,\{,\},\^,\_,\~,\ }
% \DoNotIndex{\@ne}
% \DoNotIndex{\advance,\begingroup,\catcode,\closein}
% \DoNotIndex{\closeout,\day,\def,\edef,\else,\empty,\endgroup}
%
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% \title{The \textsf{fullminipage} package\thanks{This document corresponds
%   to \textsf{fullminipage}~\fileversion, dated~\filedate. Copyright
%   2012,2014 Christian Schneider
%   \texttt{<software(at)chschneider(dot)eu>}, \url{http://chschneider.eu}.}}
% \author{Christian Schneider\\ \texttt{<software(at)chschneider(dot)eu>}}
%
% \maketitle
%
% \tableofcontents
% \clearpage
%
% \begin{abstract}
%   This package provides the environment |fullminipage|, which generates a
%   |minipage| spanning a new, complete page with page style |empty|.
%   The environment provides options to set margins around the |minipage| and
%   configure the background.
% \end{abstract}
%
% \section{Usage}
%
% \subsection{The Environment}
%
% \DescribeEnv{fullminipage}
% The environment |fullminipage| generates a new page with page style |empty|,
% which is spanned by a |minipage|.
% The available horizontal and vertical sizes are |\hsize| and |\vsize|,
% respectively.
%
% Caveat: The clearing of the page before/after the |fullminipage| might not
% be done correctly in certain circumstances, in particular, multi-column
% documents.
% Please refer to the |pagebreak| option for details.
%
% \subsection{Options}
%
% The environment |fullminipage| has an optional argument, which accepts
% a comma-separated list of \meta{key}|=|\meta{value} pairs:
% \begin{mydescription}
%   \item[\textsf{left}] left margin (default: $\unit[0]{pt}$)
%   \item[\textsf{right}] right margin (default: $\unit[0]{pt}$)
%   \item[\textsf{top}] top margin (default: $\unit[0]{pt}$)
%   \item[\textsf{bottom}] bottom margin (default: $\unit[0]{pt}$).
%     Note that content exceeding the vertical size of the minipage will not be
%     ``stopped'' by the bottom margin.
%     The value is rather used to calculate the vertical size of the minipage.
%   \item[\textsf{alignment}] the vertical alignment inside the minipage (one
%     of |tcb|; default: |t|)
%   \item[\textsf{bgcolor}] color of the background (except for the
%     margins, empty by default).
%     Omitting the \meta{value} will lead to a black background.
%     A blue background can, for example, be generated with |bgcolor=blue|.
%   \item[\textsf{background}] arbitrary macro for the background (empty by
%     default).
%     This allows, for example, to put an image into the background with
%     |background=\includegraphics{<file>}|.
%     The image will be aligned in the lower left corner of the minipage.
%     Note that |background| is put on top of the background color defined by
%     |bgcolor|.
%   \item[\textsf{pagebreak}] macro for clearing page before and after inserting
%     the |fullminipage|.
%     By default, |\newpage| will be used in single-column documents and
%     |\clearpage|, if a multi-column style is detected.
%     This detection, however, might fail and the user might want to explicitly
%     set |pagebreak=\clearpage|.
%     Note that |\clearpage| has the side-effect of flushing all pending floats.
% \end{mydescription}
%
% \section{License}
%
% \textsf{fullminipage} is free software: you can redistribute it and/or
% modify it under the terms of the GNU General Public License version~3 as
% published by the Free Software Foundation, not any later version.
%
% \textsf{fullminipage} is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
% Public License for more details.
%
% You should have received a copy of the GNU General Public License along with
% fullminipage.  If not, see \texttt{<http://www.gnu.org/licenses/>}.
%
% \section{Bugs, problems, and suggestions}
%
% Please report bugs and problems or send suggestions for this package to
% Christian Schneider.
%
% \StopEventually{\PrintChanges\PrintIndex}
%
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% \section{Implementation}
%
% The implementation is briefly described in this section. First of all, we
% need the \textsf{keyval} package for \meta{key}|=|\meta{value} options.
% The \textsf{color} package will only be required, if the background color
% needs to be defined.
%    \begin{macrocode}
\RequirePackage{keyval}
\RequirePackage{color}
%    \end{macrocode}
%
% Next, the \meta{key}s are defined:
%    \begin{macrocode}
\define@key{fullminipage}{left}{\def\fullminipage@left{#1}}
\define@key{fullminipage}{right}{\def\fullminipage@right{#1}}
\define@key{fullminipage}{top}{\def\fullminipage@top{#1}}
\define@key{fullminipage}{bottom}{\def\fullminipage@bottom{#1}}
\define@key{fullminipage}{alignment}{\def\fullminipage@alignment{#1}}
\define@key{fullminipage}{bgcolor}[black]{\def\fullminipage@bgcolor{#1}}
\define@key{fullminipage}{background}{\def\fullminipage@background{#1}}
\define@key{fullminipage}{pagebreak}{\def\fullminipage@pagebreak{#1}}
%    \end{macrocode}
%
% Finally, the environment is defined:
%    \begin{macrocode}
\newenvironment{fullminipage}[1][]{%
  \begingroup
%    \end{macrocode}
%
% The \meta{key}|=|\meta{value} pairs are evaluated and a simple detection
% for two-column layout is performed.
%    \begin{macrocode}
    \setkeys{fullminipage}{left=\z@,right=\z@,top=\z@,bottom=\z@,%
                           alignment=t,background={},pagebreak=\newpage}%
    \@ifundefined{twocolumn@sw}{}%
      {\twocolumn@sw{\setkeys{fullminipage}{pagebreak=\clearpage}}{}}%
    \if@twocolumn\setkeys{fullminipage}{pagebreak=\clearpage}\fi%
    \setkeys{fullminipage}{#1}%
%    \end{macrocode}
%
% A new page is started with pagestyle |empty|.
%    \begin{macrocode}
    \fullminipage@pagebreak
    \thispagestyle{empty}%
%    \end{macrocode}
%
% The top position is calculated and the top (vertical) position adjusted
% with |\vspace*|.
%    \begin{macrocode}
    \@tempdima=-1in
    \advance\@tempdima by-\voffset
    \advance\@tempdima by-\topmargin
    \advance\@tempdima by-\headheight
    \advance\@tempdima by-\headsep
    \@tempdimb=\@tempdima
    \advance\@tempdima by-\parskip
    \advance\@tempdima by-\topskip
    \advance\@tempdima by\fullminipage@top
    \vspace*{\@tempdima}%
%    \end{macrocode}
%
% The bottom position is calculated and the current page size enlarged
% accordingly with |\enlargethispage|.
%    \begin{macrocode}
    \@tempdima=\paperheight
    \advance\@tempdima by\@tempdimb
    \advance\@tempdima by-\textheight
    \advance\@tempdima by-\fullminipage@bottom
    \enlargethispage{\@tempdima}%
%    \end{macrocode}
%
% The position corresponding to the left margin is calculated.
%    \begin{macrocode}
    \leftmargin=-1in
    \advance\leftmargin by-\hoffset
    \if@twoside
      \ifodd\value{page}%
        \advance\leftmargin by-\oddsidemargin
      \else
        \advance\leftmargin by-\evensidemargin
      \fi
    \else
      \advance\leftmargin by-\oddsidemargin
    \fi
    \advance\leftmargin by\fullminipage@left
%    \end{macrocode}
%
% The length of a line is calculated and the margins are set with
% |\parshape|.
%    \begin{macrocode}
    \linewidth=\paperwidth
    \advance\linewidth by-\fullminipage@left
    \advance\linewidth by-\fullminipage@right
    \parshape \@ne \leftmargin \linewidth
%    \end{macrocode}
%
% Prepare output without extra spaces.
%    \begin{macrocode}
    \nointerlineskip
    \noindent
%    \end{macrocode}
%
% The value of |\vsize| is calculated and set.  (If it is set before the
% |\noindent| above, it will be overwritten in some cases.)
%    \begin{macrocode}
    \vsize=\paperheight
    \advance\vsize by-\fullminipage@top
    \advance\vsize by-\fullminipage@bottom
%    \end{macrocode}
%
% A zero-sized |picture| environment containing the background is output and the
% |minipage| is started.
%    \begin{macrocode}
    \begin{picture}(0,0)
      \@ifundefined{fullminipage@bgcolor}{}{%
        \put(0,0){\makebox(0,0)[bl]%
          {\color{\fullminipage@bgcolor}{\rule{\linewidth}{\vsize}}}%
        }%
      }%
      \put(0,0){\makebox(0,0)[bl]%
        {\fullminipage@background}%
      }%
    \end{picture}%
    \begin{minipage}[b][\vsize][\fullminipage@alignment]{\linewidth}
}%
%    \end{macrocode}
%
% The |minipage| is closed and a new page is started.
%    \begin{macrocode}
{%
    \end{minipage}%
    \parfillskip=\z@
    \fullminipage@pagebreak
  \endgroup
}
%    \end{macrocode}
%
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% \Finale
%
\endinput