path: root/Master/texmf-dist/source/latex/minipage-marginpar/mpgmpar.dtx

% \iffalse meta-comment
%
%%  (C) 2006 Paul Ebermann
%%
%%   Package mpgmpar - Randnotizen auch in Minipages
%%
%%   Die Datei mpgmpar.dtx sowie die dazugehörige
%%   mpgmpar.ins sowie die damit generierte
%%   mpgmpar.sty stehen unter der
%%   "LaTeX Project Public License" (LPPL, zu finden
%%   unter http://www.latex-project.org/lppl/, sowie
%%   auch in den meisten TeX-Distributionen in
%%   texmf/docs/latex/base/lppl*.txt), Version 1.3b oder
%%   später (nach Wahl des Verwenders).
%%
%%   Der 'maintenance-status' ist (zur Zeit) 'maintained'.
%%   
%%   Das heißt in etwa, die Dateien dürfen frei vertrieben
%%   werden, bei Änderungen (durch andere Personen als Paul Ebermann)
%%   ist aber der Name der Datei zu ändern.
%
% \fi
%
% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}[2003/12/01]
%<package>\ProvidesPackage{mpgmpar}
%<package> [2006/05/23 v0.2 Randnotizen auch in Minipages (PE)]
%
%<*driver>
\documentclass[draft,ngerman]{ltxdoc}
\usepackage{mpgmpar}
\usepackage{pauldoc}
\begin{document}
   \DocInput{mpgmpar.dtx}
\end{document}
%</driver>
% \fi
%
% \CheckSum{47}
%
% \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         \~}
%
%  \DoNotIndex{\relax,\end,\begin,\endinput,\global,\let,\newcommand}
%  \DoNotIndex{\newenvironment,\renewcommand,\RequirePackage,\undefined}
%  \DoNotIndex{\@tempa}
%
% \changes{v0.0}{2006/05/20}{Erste Fassung}
% \changes{v0.1}{2006/05/23}{Erste veröffentlichte Fassung}
%
% \GetFileInfo{mpgmpar.sty}
%
%
% \title{Das \pack{mpgmpar}-Package -- Randnotizen auch in Minipages\thanks{%
% Dieses Dokument gehört zu \pack{mpgmpar}~\fileversion,
% vom~\filedate.}}
% \author{Paul Ebermann\thanks{\texttt{Paul-Ebermann@gmx.de}}}
%
% \maketitle
%
%  \begin{abstract}
%    Innerhalb von Boxen wie etwa einer 'minipage'-Umgebung sind bekanntlich
%    '\marginpar'-Befehle nicht erlaubt -- dieses Package hat eine
%    (Teil"=)Lösung.
%  \end{abstract}
%
% \tableofcontents
%
% \section{Einleitung}
%
%    Innerhalb von Boxen wie etwa einer 'minipage'-Umgebung sind
%    '\marginpar'-Befehle nicht erlaubt, das heißt, sie bewirken
%    nichts außer einer Fehlermeldung ("`Float(s) lost"').
%
%   Das Paket \pack{marginnote}\footnote{auf CTAN unter
%   \texttt{macros/latex/contrib/marginnote/}} von Markus Kohm umgeht das,
%   indem nicht-gleitende Marginalien bereitgestellt werden.
%
%   Dieses Paket verfolgt einen anderen Ansatz:
%   Es wird ein Mechanismus bereitgestellt, mit dem die '\marginpar'-Befehle
%   abgefangen und dann außerhalb dieser Box ausgeführt werden können.
%
% \section{Benutzerdoku}
%
%   \indent\DescribeEnv{minipagewithmarginpars}
%   Diese Umgebung funktioniert wie die 'minipage'-Umgebung aus dem \LaTeX-Kernel,
%   mit dem Unterschied, dass in ihr vorkommende '\marginpar'-Befehle erst am
%   Ende der Umgebung, nach der Minipage selbst, ausgeführt werden.
%
%
%  Hier ein Beispiel:
%
%   \begin{minipagewithmarginpars}{4cm}
%     Text am Anfang\marginpar{Bla}.
%
%     \vspace{1.5cm}
%     Text am Ende\marginpar[links]{rechts}.
%   \end{minipagewithmarginpars}
%  \begin{minipage}[t]{7cm}\vspace{-1ex}
%\begin{verbatim}
%\begin{minipagewithmarginpars}{4cm}
%  Text am Anfang\marginpar{Bla}.
%
%  \vspace{1.5cm}
%  Text am Ende\marginpar[links]{rechts}.
%\end{minipagewithmarginpars}
% \end{verbatim}
%  \end{minipage}
%
%  Die Randnotizen werden in der durch die (hier zwei, der Code ist auch eine) Minipages
%  gebildeten Zeile abgesetzt -- dabei ist die Default-Ausrichtung hier '[t]' anstatt
%  '[c]'.
%
%  \subsection{Probleme/Nachteile}
%  \begin{itemize}
%    \item Die Marginalien werden alle ab der selben Zeile (jeweils etwas
%        nach unten verschoben) gesetzt, nicht entsprechend der Zeile (in
%        der Minipage), in der der '\marginpar'-Befehl vorkam.
%
%       Dies ist prinzipbedingt, ich habe keine Idee, was man dagegen
%       tun könnte. (Je nach Problem gibt \pack{marginnote} wohl bessere
%       Ergebnisse.)
%
%    \item Wird die 'minipagewithmarginpars' innerhalb einer weiteren Box
%        verwendet (z.B. um noch einen Rahmen zu setzen), funktioniert es
%        weiterhin nicht, da ja dort ebenfalls keine '\marginpar's erlaubt sind.
%
%       Hierfür gibt es eine Lösung -- die gesicherten '\marginpar's müssen
%       einfach erst nach der äußersten Box (die hoffentlich in einer
%       horizontalen Liste ist) ausgeführt werden. Dazu kann man sich analog
%       zu 'minipagewithmarginpars' eine entsprechende Umgebung definieren,
%       Details sind \ifReferenceExists{sec:minipagewithmarginpars}{in Abschnitt
%       \ref{sec:minipagewithmarginpars} im Implementations-Teil}{in der
%         Implementations"=Beschreibung des Paketes}  nachzulesen.
%
%     \item Befinden sich die '\marginpar'-Befehle innerhalb einer der 
%       AMS-Mathe-Umgebungen (wie etwa 'align', 'gather' und ihre '*'-Varianten),
%       so kann es vorkommen, dass die Marginalien doppelt auftauchen.
%       Dies liegt daran, dass diese Umgebungen ihren Inhalt mehrfach auswerten --
%       und jedesmal wird dann der Inhalt gespeichert.
%       Dieses Problem betrifft auch andere Makros, die ähnlich vorgehen.
%
%       Ich halte dies für einen Bug (in \pack{mpgmpar}), habe aber noch keine Idee,
%       was ich dagegen tun könnte.
%
%  \end{itemize}
%
% \StopEventually{\PrintChanges\PrintIndex}
%
% \section{Implementation}
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
%  \subsection{Vorbereitungen}
%  \changes{v0.2}{2006/07/27}{\pack{ifthen} wird nicht mehr benötigt.}
%
%  \begin{macro}{\mpgmpar@savedmargins}
%  Dieses Makro ist einfach nur ein "`Behälter"' für die aufgesparten
%  '\marginpar'-Befehle. Wir definieren es hier (leer) mittels '\newcommand',
%   um bei Konflikten eine Fehlermeldung zu erhalten.
%    \begin{macrocode}
\newcommand*{\mpgmpar@savedmargins}{}%
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\mpgmpar@dummy}
%   Diese Kontrollsequenz wird nur verwendet, um einen nicht vorhandenen
%   Parameter erkennen zu können. (Wir definieren es zunächst als Makro,
%   um Konflikte zu erkennen, lassen es nachher aber gleich '\relax' sein.)
%    \begin{macrocode}
\newcommand*{\mpgmpar@dummy}{}%
\let \mpgmpar@dummy = \relax
%    \end{macrocode}
%  \end{macro}
%
%
%  \subsection{Interne Kommandos}
%
%  Unsere beiden Makros '\mpgmpar@savemarginpars' (am Anfang eines Bereiches) und
%  '\mpgmpar@restoremarginpars' (am Ende)
%  machen die eigentliche Arbeit und können auch für die Definition eigener
%  \emph{Box-Making}-Umgebungen verwendet werden, für eine Anleitung dafür
%  siehe Abschnitt \ref{sec:minipagewithmarginpars}.
%
%  \begin{macro}{\mpgmpar@savemarginpars}
%    Dieses Makro leitet einen Bereich ein, in dem '\marginpar's aufgespart werden
%    (er geht bis zum Ende der aktuellen Gruppe).
%    \begin{macrocode}
\newcommand*{\mpgmpar@savemarginpars}{%
%    \end{macrocode}
%   Wir definieren '\marginpar' neu.
%  \begin{macro}{\marginpar}
%    Es hat wie das Original-'\marginpar' einen
%   optionalen und einen verpflichtenden Parameter. (Um den Fall, dass der optionale
%   Parameter angegeben wurde, von dem Fall der Nichtangabe zu unterscheiden,
%   nehmen wir als Default '\mpgmpar@dummy' und vergleichen nachher damit.)
%    \begin{macrocode}
   \renewcommand*{\marginpar}[2][\mpgmpar@dummy]%
   {%
%    \end{macrocode}
%    Das '\@bsphack' und das dazugehörige '\@esphack' am Ende
%    sind Kernel"=Kommandos, welche (zusammen) dafür sorgen, dass
%    an der Stelle der Verwendung keine Spur des
%    '\marginpar'-Aufrufs bleibt.
%    \begin{macrocode}
      \@bsphack
%    \end{macrocode}
%   \changes{v0.2}{2006/07/26}{Vergleich jetzt mit \cs{ifx} statt \cs{ifthenelse}.}
%   Jetzt der Vergleich \ldots{} bis zu Version 0.1 hatte ich
%   den mit
%\begin{verbatim}
%        \ifthenelse{\equal{\mpgmpar@dummy}{##1}}{...
%\end{verbatim}
%   aus \pack{ifthen} gemacht, aber das hatte Nebenwirkungen (da für
%   den Vergleich '##1' expandiert wurde). Daher direkt mit '\ifx'.
%    \begin{macrocode}
      \def\temp@a{##1}%
      \ifx\mpgmpar@dummy\temp@a%
%    \end{macrocode}
%   Dann kopieren wir (global) einfach den '\marginpar'-Aufruf an das Ende unseres
%   "`Speicher-Makros"' '\mpgmpar@savedmargins'.
%    \begin{macrocode}
         \g@addto@macro{\mpgmpar@savedmargins}{%
            \marginpar{##2}}%
      \else%
         \g@addto@macro{\mpgmpar@savedmargins}{%
            \marginpar[{##1}]{##2}}%
      \fi%
      \@ignorefalse
      \@esphack
   }%
}%
%    \end{macrocode}
%  Das '\@bsphack'-'\@esphack'-Paar ist hier vorhanden, damit sich unser
%  modifiziertes '\marginpar' bezüglich umrundender Leerzeichen o.ä.
%  genauso verhält wie das Original-'\marginpar'.
%  \end{macro}
%  \end{macro}
%
%  \begin{macro}{\mpgmpar@restoremarginpars}
%  Dieses Makro führt die gespeicherten '\marginpar'-Befehle
%  aus und leert dann die Liste.
%    \begin{macrocode}
\newcommand*{\mpgmpar@restoremarginpars}{%
%    \end{macrocode}
%  Zuerst merken wir uns die Liste im Makro '\@tempa' (das ist
%  für derartige Sachen gedacht), dann löschen wir (global) 
%  '\mpgmpar@savedmargins'.
%    \begin{macrocode}
   \let        \@tempa               = \mpgmpar@savedmargins
   \global\let \mpgmpar@savedmargins = \@empty
%    \end{macrocode}
%   Die eben kopierte Liste führen wir nun aus (falls wir
%   jetzt noch in einer äußeren Umgebung mit unserem
%   Spezial-'\marginpar' sind, wird die Liste dadurch neu angelegt,
%   andernfalls werden die Randnotizen ausgegeben), und
%   löschen dann die Kopie.
%    \begin{macrocode}
   \@tempa
   \let        \@tempa               = \undefined
}%
%    \end{macrocode}
%  \end{macro}
%
%  \subsection{Neue \texttt{minipage}-Umgebung}\label{sec:minipagewithmarginpars}
%
%  Diese Umgebung dient als Beispiel für die Erstellung derartiger
%  Umgebungen mit Hilfe von '\mpgmpar@savemarginpars' und '\mpgmpar@restoremarginpars'.
%  Das Wesentliche dabei ist: '\mpgmpar@savemarginpars' sollte innerhalb einer
%  Gruppe aufgerufen werden (meist nahe am Anfang), '\mpgmpar@restoremarginpars'
%  nach dem Ende dieser Gruppe (an der Stelle, wo die Randnotizen erscheinen sollen).
%
%  \begin{quotation}\small
%    Mit etwas Eigenarbeit dürfte es auch ohne eine (weitere) Gruppe klappen. Dafür
%    muss man am Anfang '\marginpar' mit '\let' sichern und am Ende wiederherstellen:
%\begin{verbatim}
%  \let \savedmarginpar = \marginpar
%  \mpgmpar@savemarginpars
%  ...
%  \let \marginpar = \savedmarginpar
%  \mpgmpar@restoremarginpars
%\end{verbatim}
%    Das ist aber nicht von mir getestet, also ohne Garantie. Und es ist eher nicht
%    robust gegenüber Verschachtelungen derartiger Konstrukte.
%  \end{quotation}
%
%  \begin{environment}{minipagewithmarginpars}
%  Hier nun unserer neue Minipage-Umgebung. Sie hat einen optionalen
%  (vertikale Ausrichtung~-- Default ist 't') und einen verpflichtenden (Breite) Parameter.
%    \begin{macrocode}
\newenvironment*{minipagewithmarginpars}[2][t]{%
%    \end{macrocode}
%  Die Implementation ist einfach: Wir beginnen zunächst
%  die Original-'minipage'-Umgebung (mit den selben Parametern)
%  und innerhalb davon rufen wir unser Makro '\mpgmpar@savemarginpars' auf.
%    \begin{macrocode}
   \begin{minipage}[#1]{#2}%
      \mpgmpar@savemarginpars
} {%
%    \end{macrocode}
%   Am Ende beenden wir zunächst die Minipage (wodurch '\marginpar' seine
%   Original-Bedeutung wiedererlangt), und rufen dann
%   '\mpgmpar@restoremarginpars' auf.
%    \begin{macrocode}
   \end{minipage}%
   \mpgmpar@restoremarginpars
}%
%    \end{macrocode}
%  \end{environment}
%
%  \subsection{Ende}
% ...
%  Das war es.
%    \begin{macrocode}
\endinput
%</package>
%    \end{macrocode}
%
% \Finale
%\endinput


%%% Folgendes ist nur für meinen Editor.
%%%
%%% Local Variables:
%%% mode: latex
%%% TeX-master: t
%%% End: