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

% \iffalse
% $Id: adjmulticol.dtx,v 2.8 2011-02-24 03:51:47 boris Exp $
%
%% Copyright 2011, Boris Veytsman <borisv@lk.net>
%% This work 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 the 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/06/01 or later.
%%
%% This work has the LPPL maintenance status `maintained'.
%%
%% The Current Maintainer of this work is Boris Veytsman
%%
%% This work consists of the file adjmulticol.dtx and the
%% derived file adjmulticol.sty,
%%
%%
%% Since this package is based on the multicol package, 
%% Copyright 1989-2005 Frank Mittelbach, the following additional 
%% condition is added to the licensing terms.  The term ``multicol''
%% here should be interpreted as ``multicol and/or adjmulticol'' 
%% package, as appropriate.
%%
%%  In addition to the terms of LPPL any distributed version
%%  (unchanged or modified) of multicol has to keep the statement
%%  about the moral obligation for using multicol. In case of major
%%  changes where this would not be appropriate the author of the
%%  changed version should contact the copyright holder.
%%
%%
%%  Moral obligation for using multicol:
%%  ------------------------------------
%%
%%  Users of multicol who wish to include or use multicol or a modified
%%  version in a proprietary and commercially market product are asked
%%  under certain conditions (see below) for the payment of a license
%%  fee.  The size of this fee is to be determined, in each instance,
%%  by the commercial user, depending on his/her judgment of the value of
%%  multicol for his/her product.
%%
%%
%%  The conditions for this are as follows:
%%
%%   The producer of a proprietary and commercially market product
%%   that involves typesetting using multicol is asked to determine
%%   the value of a license fee for using multicol if
%%
%%   - the product is a document and the producer has decided to
%%     include multicol to typeset (parts of) the document or has
%%     directed the author of the document to include multicol (for
%%     example, by providing a class file to be used by the author)
%%
%%   - the product is a LaTeX class or package that includes multicol
%%
%%
%%   There is no moral obligation in case
%%
%%   - the product is a document but producer has not directed
%%     the author to include multicol (in that case the moral obligation
%%     lies with the author of the document)
%%
%%   - the product does not involve typesetting, e.g., consists, for
%%     example, of distributing multicol and its documentation.
%%
%%   - the product is not proprietary, i.e., is made available as free
%%     software itself (which doesn't prohibit its commercial marketing)
%%
%%   - multicol is used for non-commercial purposes
%%
%%
%% Determinating a license fee might result in a license fee of zero
%% (i.e., no payment) in case a producer has determined that the use
%% of multicol has no enhancing effect on the product. This is a
%% plausible scenario, i.e., in the above two cases the producer is
%% only asked to evaluate the value of multicol for the product
%% not for the payment of a license fee per se (which might or might
%% not follow from this evaluation).
%%
%% The license fee, if any, can be payed either to the LaTeX3 fund
%% (see ltx3info.txt in the base LaTeX distribution) or to the author of
%% the program who can be contacted at
%%
%%     Frank.Mittelbach@latex-project.org
%%
%<*gobble> 
% \fi
% \CheckSum{149}
%
%
%% \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         \~} 
%
%\iffalse
%    \begin{macrocode}
\documentclass{ltxdoc}
\usepackage[breaklinks,colorlinks,linkcolor=black,citecolor=black,
            pagecolor=black,urlcolor=black]{hyperref}
\usepackage{breakurl,adjmulticol}
\PageIndex
\CodelineIndex
\RecordChanges
\EnableCrossrefs
\begin{document}
  \DocInput{adjmulticol.dtx}
\end{document}
%    \end{macrocode}
%</gobble> 
% \fi
% \MakeShortVerb{|}
% \GetFileInfo{adjmulticol.sty}
% 
% \title{Adjusting Margins for Multicolumn and Unicolumn
% Output\thanks{\copyright Boris Veytsman, 2011} \thanks{Note: This
% package is released under terms which affect its use in commercial
% applications. Please see the details at the top of the source file}} 
% \author{Boris Veytsman}
% \date{\filedate, \fileversion}
% \maketitle
%
% \begin{abstract}
%   This package provides an extension of the \textsf{multicol}
%   package~\cite{Mittelbach06:Multicol} with the option to change the
%   margins for multicolumn and unicolumn layout.  The package understands the
%   difference between the even and odd margins for two side printing.
% \end{abstract}
%
% \tableofcontents
%
% \clearpage
%
%\section{Introduction}
%\label{sec:intro}
%
%
% One of the common requests from the book designers is the
% possibility to change the margins of the text in the midddle of the
% page.  The standard \LaTeX{} |list| environment does exactly this.
% Thus it is not surprising that many packages creatively use this
% tool to change the layout.  An example is the \textsf{changepage}
% package~\cite{Wilson09:Changepage}. Unfortunately this approach has
% a seriour drawback:  a list sets the margins globally.  If the
% material is split between the pages, the margins on the first page
% are repeated on all the subsequent pages.  While this is fine for
% one-side printing, it leads to a catastrophe for the two-sided
% one, as can be seen from the following example (provided by Ivo
% Welch):
% \begin{verbatim}
% \documentclass{book}
% \usepackage{lipsum,multicol}
% \evensidemargin=1.5in
% \oddsidemargin=-3em
% \textwidth=5in
%
% \newenvironment{chmargin}[2]{%
%   \begin{list}{}{\topsep0pt\partopsep0pt\itemsep0pt\parsep\parskip%
%       \listparindent\parindent\itemindent\parindent
%       \leftmargin#1\rightmargin#2\relax}\item}%
%   {\end{list}}
%
% \begin{document}
%
% \chapter{Show}
% \section{Normal}
% \marginpar{I need a lot of outer margin space in the normal text.}
% \lipsum[1-10]
% \begin{chmargin}{0pt}{-160pt}
%   \section{End of Chapter Meterial}
%   \textbf{Now I want to use the outer margin because I need width.}
%   \lipsum[11-16]
%   \fbox{\textbf{\Large Darn---it extends into the inner spine margin now.}}
%   \lipsum[17-40]
% \end{chmargin}
%
% \end{document}
% \end{verbatim}
% 
%
%  To remedy this problem, we need a completely different approach: we
%  need to change the output routine.  This is done in this package.
%
%  Since the text with the special layout is often typeset in the
%  multicolumn mode, we load the \textsf{multicol}
%  package~\cite{Mittelbach06:Multicol} and patch it to provide two
%  changes:
%  \begin{enumerate}
%  \item Margins changes, persistent over the pages.
%  \item The possibility of an one-column ``multicolumn'' layout.  Of
%    course, this layout does not make sense in the context of the
%    original \textsf{multicol} package, but is useful when the
%    margins are changed.
%  \end{enumerate}
%  
%  Note that since this package uses the \textsf{multicol} package, it
%  inherits its special moral obligation for the commercial users.
%  Please see the source file for the details.
%
%  This file was commissioned for by Prof.~Ivo Welch,
%  \url{http://www.ivo-welch.info/}.   He also provided sample files
%  and patiently tested it.
%
%\section{User Interface}
%\label{sec:interface}
%
% The installation of the class follows the usual
% practice~\cite{TeXFAQ} for \LaTeX{} packages:
% \begin{enumerate}
% \item Run \textsf{latex} on |adjmulticol.ins|.  This will produce the file
% |adjmulticol.sty|.
% \item Put the file |adjmulticol.sty| to
% the place where \LaTeX{} can find them (see
% \cite{TeXFAQ} or the documentation for your \TeX{}
% system).\label{item:install} 
% \item Update the database of file names.  Again, see \cite{TeXFAQ}
% or the documentation for your \TeX{} system for the system-specific
% details.\label{item:update}
% \item The file |adjmulticol.pdf| provides the documentation for the
% package (this is the file you are probably reading now).
% \end{enumerate}
% As an alternative to items~\ref{item:install} and~\ref{item:update}
% you can just put the files in the working directory where your
% |.tex| file is.
% 
% 
%
% To use this package, add to the preamble of your document
% the line |\usepackage{adjmulticol}|.
% 
% The package provides two new environments for adjusted multicolumn
% layout. 
%
% \DescribeEnv{adjmulticols}
% The environment |adjmulticols| is similar to the environment
% |multicols|, but it has three mandatory arguments instead of one:
% \begin{quote}
%   |\begin{adjmulticols}|\marg{number}\marg{inner margin}\marg{outer
%   margin}\\
% \meta{text}\\
% |\end{adjmulticols}|
% \end{quote}
% For example,
% \begin{verbatim}
%  \begin{adjmulticols}{2}{12pt}{-1in}
%     Text Text Text
% \end{adjmulticols}
% \end{verbatim}
% Here \meta{number} is the number of columns.  Unlike |multicols|,
% |adjmulticols| environment allows this number to be 1.  
%
% The \meta{inner margin} and \meta{outer margin} are calculated from
% the current text area margins, so negative values mean the extension
% of the text area.  In one-sided printing \meta{inner margin} is the
% left margin, and \meta{outer margin} is the right margin.  You
% probably would not want to use this package for one-sided printing,
% since in this case \textsf{changepage}
% package~\cite{Wilson09:Changepage} works fine.  In two-sided
% printing \meta{inner margin} is the margin on the spine side of the
% page, and \meta{outer margin} is the margin on the other side.
%
% You can use the optional arguments of the |multicols| environment.
% Note that the argument of the first optional argument, the header text
% spread over all columns, is typeset with the \emph{normal} margins.
% If you want to change margins for the header too, you may want to
% use one-column |adjmulticols| environment instead.
%
% \DescribeEnv{adjmulticols*}
% The starred version of the environment, |adjmulticols*| is similar
% to the |multicols*| environment: it does not balance the columns on
% the last page.
%
%
% Since the package redefines output routines, it may behave strangely
% if used with the packages that also redefine it or rely on the
% |\pagegoal| and |\pagetotal| dimen registers.  The command
% |\Needspace| from \textsf{memoir} package~\cite{Wilson:Memoir}
% is known to lead to loss of the text in some rare cases, and
% therefore this command is disabled inside |adjmulticols|.  Usually
% one can get the same effect as this command by setting the
% |\premulticols| to the desired value~\cite{Mittelbach06:Multicol}. 
%
%\StopEventually{\clearpage
% \bibliography{adjmulticol}
% \bibliographystyle{unsrt}}
%
% \clearpage
% 
% \section{Implementation}
% \label{sec:implementation}
% 
%
%\subsection{Declarations}
%\label{sec:decl}
% 
%  We start with declaration, who we are:
%
%
%    \begin{macrocode}
%<style>\NeedsTeXFormat{LaTeX2e}
%<*gobble>
\ProvidesFile{adjmulticol.dtx}
%</gobble>
%<style>\ProvidesPackage{adjmulticol}
%<*style>
[2011/02/23 v1.0 Adjusted margins for multicolumn layout]
%    \end{macrocode}
%
%
%\subsection{Options}
%\label{sec:options}
%
% All options are sent to |multicols|:
%    \begin{macrocode}
\DeclareOption*{\PassOptionsToPackage{\CurrentOption}{multicol}}
\ProcessOptions\relax
%    \end{macrocode}
% 
%
%\subsection{Loading Packages}
%\label{sec:loading}
%
% We use |multicol| to get all the code from it:
%    \begin{macrocode}
\RequirePackage{multicol}
%    \end{macrocode}
%
%
%\subsection{Registers}
%\label{sec:registers}
%
% \begin{macro}{\adjmc@inner}
%   Inner margin delta:  left on odd pages, right on even pages for
%   two-sided typesetting, and left for one-sided typesetting.
%    \begin{macrocode}
\newdimen\adjmc@inner
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\adjmc@outer}
%   Outer margin delta: right on odd pages, left on even pages, and
%   right for two-sided typesetting
%    \begin{macrocode}
\newdimen\adjmc@outer
%    \end{macrocode}   
% \end{macro}
%
%
% \begin{macro}{\adjmc@saved@leftmargin}
%   We save the value of |\multicol@leftmargin| between the calls in
%   the register |\adjmc@savedleftmargin|:
%    \begin{macrocode}
\newdimen\adjmc@saved@leftmargin
%    \end{macrocode}
%   
% \end{macro}
%
%\subsection{Starting Environment}
%\label{sec:start}
%  
% \begin{macro}{\adjmulticols}
%   We have three mandatory arguments instead of one for |multicols|:
%   the number of columns, the left margin delta and the right margin
%   delta:
%    \begin{macrocode}
\def\adjmulticols#1#2#3{\col@number#1\relax
  \def\@tempa{#2}%
  \ifx\@tempa\@empty\adjmc@inner\z@\else\adjmc@inner#2\fi
  \def\@tempa{#3}%
  \ifx\@tempa\@empty\adjmc@outer\z@\else\adjmc@outer#3\fi
%    \end{macrocode}
%   The standard |multicols| have the minimum of two columns.  We, of
%   course, want to consider one column layout too:
%    \begin{macrocode}
  \ifnum\col@number<\@ne
     \PackageWarning{adjmulticol}%
      {Using `\number\col@number'
       columns doesn't seem a good idea.^^J
       I therefore use one columns instead}%
     \col@number\@ne\fi
  \ifnum\col@number>10
     \PackageError{adjmulticol}%
      {Too many columns}%
      {Current implementation doesn't
       support more than 10 columns.%
       \MessageBreak
       I therefore use 10 columns instead}%
     \col@number10 \fi
%    \end{macrocode}
%
%  We alse disable |\Needspace| from \textsf{memoir}
%  package~\cite{Wilson:Memoir}:
%    \begin{macrocode}
  \def\Needspace{\PackageWarning{adjmulticol}%
    {The command \noexpand\Needspace is disabled}%
    {The command \noexpand\Needspace is not compatible with our 
      output routine}}
%    \end{macrocode}
%  
%   As in the standard package we redefine the footnote making command:
%    \begin{macrocode}
     \ifx\@footnotetext\mult@footnotetext\else
       \let\orig@footnotetext\@footnotetext
       \let\@footnotetext\mult@footnotetext
     \fi
%    \end{macrocode}
%   And look for the optional arguments
%    \begin{macrocode}
  \@ifnextchar[\adjmult@cols{\adjmult@cols[]}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\adjmult@cols}
%   Looking for the second optional argument.  Note that we use
%   |\premulticols| for the default:
%    \begin{macrocode}
\def\adjmult@cols[#1]{\@ifnextchar[%
  {\adjmult@@cols{#1}}%
  {\adjmult@@cols{#1}[\premulticols]}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\adjmult@@cols}
%   And now we are gathered all arguments:
%    \begin{macrocode}
\def\adjmult@@cols#1[#2]{%
%    \end{macrocode}
%  The macro |\prepare@multicols| uses the current value of
%  |\linewidth|.  We do not change his, but rather change |\linewidth|:
%    \begin{macrocode}
    \advance\linewidth by -\adjmc@inner\relax
    \advance\linewidth by -\adjmc@outer\relax
%    \end{macrocode}
% Then we redefine the output routines:
%    \begin{macrocode}
\let\page@sofar=\adjmc@page@sofar
%    \end{macrocode}
% and start the standard multicols:
%    \begin{macrocode}
   \mult@@cols#1[#2]}
%    \end{macrocode}
% \end{macro}
% 
%
% 
%
%
%\subsection{Ending Environment}
%\label{sec:end}
%
% \begin{macro}{\endadjmulticols}
%   Here we use the standard environment end.  Note that it uses
%   |\@checkend|, so we need to redefine |\@currenvir| to fool the
%   check. 
%    \begin{macrocode}
\def\endadjmulticols{%
  \def\@currenvir{multicols}%
  \endmulticols}
%    \end{macrocode}   
% \end{macro}
%
%
%
%\subsection{Output Routines}
%\label{sec:output}
%
% \begin{macro}{\adjmc@page@sofar@orig}
%   First, we save the original declaration of |\page@sofar|:
%    \begin{macrocode}
\let\adjmc@page@sofar@orig=\page@sofar
%    \end{macrocode}
%   
% \end{macro}
%
%
% \begin{macro}{\adjmc@page@sofar}
%   We redefine |\page@sofar| to change the margins and allow for
%  one-column output:
%    \begin{macrocode}
\def\adjmc@page@sofar{%
%    \end{macrocode}
%  If we have one column, the standard mechanisms leave empty space
%  instead of the first column.  Ok, we use the fact that there is a
%  copy of the first column in |\mult@firstbox|\dots
%    \begin{macrocode}
  \ifnum\col@number=\@ne
  \setbox\mult@rightbox\box\mult@firstbox
  \fi
%    \end{macrocode}
% We redefine |\multicol@leftmargin| to introduce the shift of the
% box.  We save the old code in |\adjmc@saved@leftmargin|
%    \begin{macrocode}
   \adjmc@saved@leftmargin=\multicol@leftmargin
   \if@twoside
      \ifodd\c@page
        \advance\multicol@leftmargin by \adjmc@inner\relax
     \else
        \advance \multicol@leftmargin by \adjmc@outer\relax
    \fi
   \else
      \advance \multicol@leftmargin by \adjmc@inner\relax
  \fi
%    \end{macrocode}
% Then we invoke the original |\page@sofar| and restore the margin:
%    \begin{macrocode}
   \adjmc@page@sofar@orig
   \multicol@leftmargin=\adjmc@saved@leftmargin}
%    \end{macrocode}
%   
% \end{macro}
% 
%
%\subsection{Not Balancing Columns}
%\label{sec:not_balance}
%
% The starred versions do not balance the columns.
%
% \begin{macro}{\adjmulticols*}
%   This follows the code of the \textsf{multicols} package:
%    \begin{macrocode}
\newenvironment{adjmulticols*}{%
   \ifinner
     \PackageWarning{multicol}%
       {multicols* inside a box does
        not make sense.\MessageBreak
        Going to balance anyway}%
   \else
     \let\balance@columns@out
         \multi@column@out
   \fi
   \adjmulticols}{%
   \vfill
  \endadjmulticols}
%    \end{macrocode}
%   
% \end{macro}
%
%
%\subsection{Ending the Style}
%\label{sec:end}
%
%
%
%    \begin{macrocode}
%</style>
%    \end{macrocode}
%\Finale
%\clearpage
%
%\PrintChanges
%\clearpage
%\PrintIndex
%
\endinput