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

% \iffalse meta-comment
%
%%  (C) 2005 Paul Ebermann
%%
%%   Package extpfeil, mit einigen weiteren in der Länge
%%   wachsenden Pfeilen (à la \xrightarrow{} aus amsmath).
%%
%%   Die Datei extpfeil.dtx sowie die dazugehörige
%%   extpfeil.ins sowie die damit generierte
%%   extpfeil.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) 'author-maintained'.
%%   
%%   Das heißt u.a., 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{extpfeil}
%<package> [2009/10/31 v0.4 Extensible Pfeile (PE)]
%
%<*driver>
\documentclass[ngerman, draft]{ltxdoc}
\usepackage{pauldoc}
\usepackage{extpfeil}
\usepackage{array}

%\OnlyDescription
\begin{document}
   \DocInput{extpfeil.dtx}
\end{document}
%</driver>
% \fi
%
% \CheckSum{143}
%
% \changes{v0.0}{2006/01/18}{Anfang der Fassung als DTX}
%
% \GetFileInfo{extpfeil.sty}
%
% \DoNotIndex{\endinput,\newcommand,\RequirePackage}
%
% \title{Das \pack{extpfeil}-Package -- Weitere erweiterbare Pfeile\thanks{Diese
% Dokumentation gehört zu \pack{extpfeil}~\fileversion,
% vom~\filedate.}}
% \author{Paul Ebermann\footnote{\texttt{Paul-Ebermann@gmx.de}}}
%
% \maketitle
%
% \begin{abstract}
%  Dieses Paket definiert eine Reihe erweiterbare Pfeile,
%  sowie ein Kommando, um selbst weitere zu definieren.
% \end{abstract}
%
% \tableofcontents
%
% \section{Benutzerdoku}
%
%  Dieses Paket definiert einige erweiterbare Pfeile,
%  sowie ein Kommando, um selbst weitere zu definieren\ifReferenceExists{sec:newextarrow}
%  { (siehe Abschnitt \ref{sec:newextarrow}).}{. (Dieses ist nur
%   in der Implementations-Version der Doku beschrieben, denn die muss
%   man sowieso lesen, um es zu verstehen.)}
%
% \subsection{Generelle Benutzung der Pfeile}
%  
%  Die Pfeile funktionieren wie die Pfeile '\xleftarrow' und '\xrightarrow'
%  aus \AmS-\pack{Math} sowie diverse weitere Pfeile aus \pack{mathtools} bzw.
%  \pack{extarrows} (letzteres Paket habe ich erst später entdeckt -- es hat
%  auch keine Dokumentation).
%  Die generelle Syntax ist
%  \begin{quote}
%    \meta{pfeilname}\oarg{subscript}\marg{superscript}
%  \end{quote}
%  \meta{pfeilname} ist das entsprechend definierte Kommando (siehe Abschnitt \ref{pfeilliste})
%  \meta{subscript} eine Formel, die (falls vorhanden) unter den Pfeil gesetzt
%  wird, \meta{superscript} eine, die über den Pfeil gesetzt wird. Der Pfeil selbst
%  nimmt dann eine ausreichend hohe Länge an, um an beiden Seiten etwas über die
%  Formel hinauszuragen.
%
%  \subsection{Die einzelnen Pfeile}\label{pfeilliste}
%
% \changes{v0.2b}{2006/04/11}{Dokumentations-Update: \cs{xmapsto} jetzt auch beschrieben}
%
%  \DescribeMacro{\xtwoheadrightarrow}
%  \DescribeMacro{\xtwoheadleftarrow}
%  \DescribeMacro{\xmapsto}
%  \DescribeMacro{\xlongequal}
%  \DescribeMacro{\xtofrom}
%  \begin{tabular}[t]{lcp{5cm}}
%    '\xtwoheadrightarrow[a]{b}' &  $\xtwoheadrightarrow[a]{b}$  & ein einfacher Pfeil nach
%                                                                  rechts mit Doppelspitze \\
%    '\xtwoheadleftarrow[a]{b}' &  $\xtwoheadleftarrow[a]{b}$  & ein einfacher Pfeil nach
%                                                               links mit Doppelspitze \\
%    '\xmapsto[a]{b}' &  $\xmapsto[a]{b}$  & ein \emph{wird-abgebildet-auf}-Pfeil nach
%                                               rechts. \\
%  '\xlongequal[a]{b}' & $\xlongequal[a]{b}$ & kein Pfeil, sondern einfach nur ein
%                                               verlängerbares Gleichheitszeichen. \\
%  '\xtofrom[a]{b}' & $\xtofrom[a]{b}$ & Ein Doppelpfeil in beide Richtungen.
%  \end{tabular}
%
% 
% \StopEventually{\PrintChanges\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         \~}
%
%
% \section{Implementation}
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
%  \subsection{geladene Pakete}
%
%  Zunächst laden wir das \pack{amsmath}-Package, in welchem
%  die verwendeten Makros definiert sind, sowie \pack{amssymb},
%  in dem sich einige verwendete Symbole aufhalten.
%    \begin{macrocode}
\RequirePackage{amsmath}
\RequirePackage{amssymb}
%    \end{macrocode}
%
%  \pack{mathtools} definiert '\mathrlap' und '\mathllap', welche
%  in einigen meiner Befehle verwendet werden.
%    \begin{macrocode}
\RequirePackage{mathtools}
%    \end{macrocode}
%
%  \pack{stmaryrd} enthält viele Symbole, von denen wir nur
%   $\shortleftarrow$ und $\shortrightarrow$ brauchen.
%    \begin{macrocode}
\RequirePackage[only,shortleftarrow,shortrightarrow]{stmaryrd}
%    \end{macrocode}
%
%  \subsection{Die verwendeten \pack{amsmath}-Funktionen}
%
%  Leider ist die Dokumentation der \AmS-Math-Funktionen\footnote{in
%   Abschnitt 12 von 'amsmath.dvi', ab Seite 25 in der Version 2.13}
%  etwas dürftig -- ich musste mir selbst zusammenreimen, was
%  wie funktionieren könnte. Deswegen sind im folgenden die Ergebnisse meiner
%  Forschungen niedergelegt.
%
%  \DescribeMacro{\relbar}
%  \DescribeMacro{\Relbar}
%  Ich verwende für meine Pfeile '\relbar' -- das ist einfach nur
%  ein Minus-Zeichen ($\relbar$) (der Leerraum oben und unten etwas verkleinert, damit
%  Super- und Subskripte nicht so weit weg sind), als verlängerbares
%  Element. Genauso gibt es auch '\Relbar' ($\Relbar$) für Doppelpfeile.
%
%  \DescribeMacro{\arrowfill@}
%    \cmd{\arrowfill@}\marg{links}\marg{mitte}\marg{rechts}\marg{größe} wird benutzt, um
%    dehnbare Pfeile zu erstellen. Das Makro bekommt 4 Parameter:
%
%    \meta{links} ist das linke Ende des Pfeils, \meta{rechts} das rechte Ende.
%
%    \meta{mitte} ist das, was verlängerbar gemacht wird - also am besten
%    '\relbar' oder '\Relbar'.
%
%    \meta{größe} wird dem Makro von \cmd{\ext@arrow} (bzw. anderen Makros, die
%    mit '\arrowfill@' gebastelte Pfeile verwenden) übergeben, darum muss man sich
%    beim Erstellen von Pfeilen also nicht kümmern -- es ist ein Kommando, um die
%    Mathe-Schriftgröße einzustellen, (bei '\ext@arrow' ist es '\displaystyle').
%
%    Ein Beispiel der Anwendung\footnote{aus amsmath.dtx} ist
%\begin{verbatim}
%    \def\leftarrowfill@{\arrowfill@\leftarrow\relbar\relbar}
%\end{verbatim}
%    Das linke Ende ist also ein '\leftarrow' ($\leftarrow$), das
%    rechte Ende (genauso wie die Mitte) ein '\relbar' ($\relbar$).
%    Insgesamt führt  das (mit einer Übergabe von '\textstyle') zu
%    {\makeatletter{\leftarrowfill@{\textstyle}}\makeatother}  (hier
%    ziemlich lang, da es ja den Platz füllt).
%
%  \DescribeMacro{\ext@arrow}
%    \cmd{\ext@arrow}\marg{li 1}\marg{re 1}^^A
%    \marg{li 2}\marg{re 2}\marg{Pfeil}\marg{oben}\marg{unten}
%     ist nun das Kommando, welches einen (mit '\arrowfill@' erstellten)
%     Pfeil in der richtigen Länge mit etwas darüber und darunter ausgibt.
%
%     \meta{oben} ist eine Formel, die über
%     dem Pfeil ausgegeben wird, \meta{unten} eine Formel, die unter
%     dem Pfeil ausgegeben wird. Beides kann auch leergelassen werden,
%     dann wird eben nichts dort ausgegeben.
%
%     \meta{Pfeil} gibt den Pfeil an, der zu verwenden ist -- dies sollte
%     aus '\arrowfill@' mit den ersten drei Parametern gebildet sein
%     (entweder in '{}' -- so werden wir es nachher machen -- oder als
%      extra-Makro (wie '\leftarrowfill@').
%
%     \meta{li 1} und \meta{re 1} geben an, wieviel Platz
%     vor und nach \meta{oben} und \meta{unten} gelassen werden soll --
%     mittels '\mkern', die Einheit  dazu ist 'mu' (\emph{Math units}). Damit
%     kann man die Position der Formeln über/unter dem Pfeil etwas seitlich
%     anpassen.
%
%     \meta{li 2} und \meta{re 2} funktionieren ähnlich, werden allerdings
%     nur zum Berechnen der Länge des Pfeiles verwendet. Damit kann man
%     die Länge des Pfeiles noch etwas über die Breite der Formel hinaus
%     ausdehnen. Ich habe keine Ahnung, ob zwischen \meta{li 2} und \meta{re 2}
%     ein funktioneller Unterschied besteht, oder ob einfach nur die Summe
%     von beidem zählt.
%
%     Zum Definieren eines Pfeiles mit Sub- und Superskript geht man z.B. so
%     vor\footnote{aus 'amsmath.dtx', Zeilenumbruch von mir}:
%   \begin{verbatim}
%    \newcommand{\xleftarrow}[2][]{%
%       \ext@arrow 3095\leftarrowfill@{#1}{#2}}\end{verbatim}
%     Die ersten 4 Parameter werden also hier als einzelne Ziffern
%     übergeben (ohne '{}'), dann ('\leftarrowfill@') ein mit '\arrowfill@'
%     erstellter dehnbarer Pfeil, zum Schluss die beiden Parameter des
%     definierten Makros. Das Ergebnis ist z.B.
%     $$ \xleftarrow[unten]{oben}.$$
%
%  \subsection{Neue Pfeile}
%  \label{sec:newextarrow}
%  Wir kombinieren jetzt die beiden oben vorgestellten Kommandos,
%  um so einfacher eigene Pfeile erstellen zu können.
%
% \DescribeMacro{\newextarrow}
% \changes{v0.1}{2006/01/31}{Alle Pfeile verwenden nun newextarrow zur Definition.}
%  '\newextarrow'\marg{befehl}\marg{platz}\marg{pfeil}
%  definiert das Kommando \meta{befehl} als dehnbares Zeichen
%  (mit ober- und Unterscript), mit den Platz-Angaben in \meta{platz}
%  (dies sollte 4 Token enthalten) und den Pfeil-Teilen in \meta{pfeil}
% (das sollte drei Token enthalten).
%
% \begin{macro}{\newextarrow}
%  \changes{v0.1}{2006/01/31}{Neu hinzu}
%  Das damit definierte Makro ruft also '\ext@arrow' auf, mit den Parametern
%  \meta{platz}, dem aus '\arrowfill@' und \meta{pfeil} zusammengesetzten
%  Pfeil sowie seinen beiden eigenen Parametern (der erste davon ist optional) auf.
%    \begin{macrocode}
\newcommand*{\newextarrow}[3] {%
   \newcommand*{#1}[2][]{\ext@arrow #2{\arrowfill@#3}{##1}{##2}}
}
%    \end{macrocode}
%  \end{macro}
%
%  \subsection{Verschiedene Pfeile übereinander} \label{twoarrows}
%
%  In einigen Schriftsammlungen sind Pfeile wie $\rightleftarrows$
%  und $\rightrightarrows$ (\pack{\AmS symb}) vorhanden. Leider gibt
%  es damit einige Probleme, wenn man daraus erweiterbare Pfeile basteln
%  möchte:
%  \begin{itemize}
%    \item Der vertikale Abstand passt nicht zu $\Relbar$, wie
%       $\Relbar\mspace{-5mu}\rightrightarrows$ zeigt.
%    \item Es gibt keine $\twoarrowsleft\relbar\shortleftarrow$,
%        $\twoarrowsright\shortrightarrow\relbar$ etc., um
%      daraus einen verlängerbaren Pfeil wie $\xtofrom{\quad}$ zu basteln. 
%  \end{itemize}
%  Die folgenden Makros versuchen dies zu beheben.
%  
%  \begin{macro}{\twoarrowsleft}\noindent\marg{Pfeil1}\marg{Pfeil2}
%
%  \changes{v0.3}{2006/07/27}{Neu.}
%  Setzt zwei Pfeile (oder Striche etc.) so zusammen, dass der erste
%  zur oberen Linie, der zweite zur unteren Linie von $\Relbar$ ('\Relbar')
%  passt. Die beiden Symbole sind am linken Ende ausgerichtet.
%    \begin{macrocode}
\newcommand*{\twoarrowsleft}[2]{%
   \settoheight{\dimen@}{=}%
   \advance\dimen@ by 1pt\relax
   \mathrel{%
      \mathrlap{\raisebox{0.22\dimen@}[0pt][0pt]{$#1$}}%
      \mathrlap{\raisebox{-0.22\dimen@}[0pt][0pt]{$#2$}}%
      \hphantom{\vbox{\hbox{$#1$}\hbox{$#2$}}}%
   }%
}%
%    \end{macrocode}
%  \end{macro}
%  \begin{macro}{\twoarrowsright}
%  \changes{v0.3}{2006/07/27}{Neu.}
%   Das gleiche für die Rechtsausrichtung.
%    \begin{macrocode}
\newcommand*{\twoarrowsright}[2]{%
   \settoheight{\dimen@}{=}%
   \advance\dimen@ by 1pt\relax
   \mathrel{%
      \hphantom{\vbox{\hbox{$\m@th #1 $}\hbox{$\m@th #2 $}}}%
      \mathllap{\raisebox{0.22\dimen@}[0pt][0pt]{$\m@th #1 $}}%
      \mathllap{\raisebox{-0.22\dimen@}[0pt][0pt]{$\m@th #2 $}}%
   }%
}%
%    \end{macrocode}
%  \end{macro}
%
%  Da für einige Zwecke der durch '\Relbar' ($\Relbar$) vorgegebene Abstand
%  doch etwas gering ist, hier noch zwei Makros, die genauso funktionieren,
%  bei denen der Abstand größer (und mittels optionalem Argument
%  konfigurierbar) ist. Danach folgt ein dazu passendes '\bigRelbar'.
%
%
%  \begin{macro}{\bigtwoarrowsleft}\noindent\oarg{abstand}\marg{Pfeil1}\marg{Pfeil2}
%
%  ^^A \changes{v0.3}{2006/07/27}{Neu.}
%  Setzt zwei Pfeile (oder Striche etc.) so zusammen, dass der erste
%  zur oberen Linie, der zweite zur unteren Linie von $\bigRelbar$ ('\bigRelbar')
%  passt. Die beiden Symbole sind am linken Ende ausgerichtet.
%
%\newextarrow{\xsurjtoInjfrom}{9999} {%
%  {\bigtwoarrowsleft{\relbar}{\shortleftarrow}}%
%  \bigRelbar%
%  {\bigtwoarrowsright{\twoheadrightarrow}{\relbar\joinrel\rhook}}%
%}
%
% Zum Ausprobieren: $A \xsurjtoInjfrom[unten]{oben} B$.
%
%
%    \begin{macrocode}
\newcommand*{\bigtwoarrowsleft}[3][5pt]{%
   \setlength{\dimen@}{#1}%
   \mathrel{%
      \mathrlap{\raisebox{0.5\dimen@}{$\m@th #2 $}}%
      \mathrlap{\raisebox{-0.5\dimen@}{$\m@th #3 $}}%
      \hphantom{\vbox{\hbox{$\m@th #2 $}\hbox{$\m@th #3 $}}}%
   }%
}%
%    \end{macrocode}
%  \end{macro}
%  \begin{macro}{\bigtwoarrowsright}
%  \changes{v0.3}{2006/07/27}{Neu.}
%   Das gleiche für die Rechtsausrichtung.
%    \begin{macrocode}
\newcommand*{\bigtwoarrowsright}[3][5pt]{%
   \setlength{\dimen@}{#1}%
   \mathrel{%
      \hphantom{\vbox{\hbox{$\m@th #2 $}\hbox{$\m@th #3 $}}}%
      \mathllap{\raisebox{0.5\dimen@}{$\m@th #2 $}}%
      \mathllap{\raisebox{-0.5\dimen@}{$\m@th #3 $}}%
   }%
}%
%    \end{macrocode}
%  \end{macro}
%  \begin{macro}{\bigRelbar}\noindent\oarg{abstand}
%    \begin{macrocode}
\newcommand*{\bigRelbar}[1][5pt]{
   \setlength{\dimen@}{#1}%
   \mathrel{%
%     \vcenter{\offinterlineskip
%       \hbox{$\m@th \relbar$}%
%       \hbox{$\m@th \relbar$}%
%       }%
     \mathrlap{\raisebox{0.5\dimen@}{$\m@th \relbar $}}%
     \raisebox{-0.5\dimen@}{$\m@th \relbar$}%
   }%
}
%    \end{macrocode}
%  \end{macro}
%
%  \subsection{Weitere Pfeile}
%  Ich verwende jetzt '\newextarrow', um weitere Pfeile zu erstellen.
%
%  \begin{macro}{\xtwoheadrightarrow}
%    Unser Pfeil sollte ziemlich weit überstehen,
%    deswegen die '{40}'. '05' scheint zur
%    Justierung der Formeln ganz gut zu passen.
%    \begin{macrocode}
\newextarrow{\xtwoheadrightarrow}
       {05{40}0}
%    \end{macrocode}
%    Den Pfeil selbst setzen wir aus $\twoheadrightarrow$
%    (aus \pack{amssymb}) sowie den üblichen '\relbar' zusammen:
%    \begin{macrocode}
       {\relbar\relbar\twoheadrightarrow}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\xtwoheadleftarrow}
%   Das geht analog zu '\xtwoheadrightarrow' (die \meta{li}- und \meta{re}-Parameter
%   sind vertauscht, da der Pfeil ja genau gespiegelt ist).
%    \begin{macrocode}
\newextarrow{\xtwoheadleftarrow}
      {500{40}}
      {\twoheadleftarrow\relbar\relbar}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\xmapsto}
%   \changes{v0.2}{2006/03/19}{Neu.}
%    Hier noch eine verlängerbare Variante von $\mapsto$ und $\longmapsto$.
%    \pack{mathtools} hat bereits eine Implementation davon, aber diese
%    ist etwas länger und gefällt mir daher besser (das '\let' sorgt
%    dafür, dass sich '\newcommand' nicht beschwert).
%    \begin{macrocode}
\let\xmapsto\undefined
\newextarrow{\xmapsto}{0599}{{\mapstochar\relbar}\relbar\rightarrow}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\xlongequal}
%  \changes{v0.1}{2006/01/31}{Neu hinzu}
%  Alle drei Teile bestehen aus $\Relbar$, 
%    \begin{macrocode}
\newextarrow{\xlongequal}{5599}{\Relbar\Relbar\Relbar}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\xtofrom}
%  \changes{v0.3}{2006/07/27}{Neu}
%  Ein Doppelpfeil: $\xtofrom[\sin]{\cos}$.
%    \begin{macrocode}
\newextarrow
  {\xtofrom}%
  {55{40}0}%
  {%
    {\twoarrowsleft\relbar\shortleftarrow}%
    \Relbar%
    {\twoarrowsright\shortrightarrow\relbar}%
  }%
%    \end{macrocode}
%  \end{macro}

%  \section{Schluss}
%  Das war es fürs erste -- später kommen
%  bestimmt noch mehr Pfeile hinzu.
%
%    \begin{macrocode}
\endinput
%</package>
%    \end{macrocode}
%
% \Finale
%\endinput


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