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

% \iffalse meta-comment
%
%%  (C) 2006 Paul Ebermann
%%
%%   Package pauldoc - Anpassungen für doc für Pauls Package-Dokus.
%%   Die Datei pauldoc.dtx sowie die dazugehörige
%%   pauldoc.ins sowie die damit generierte
%%   pauldoc.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{pauldoc}
%<package> [2006/04/05 v0.4a Pauls Anpassungen fuer doc (PE)]
%
% \changes{v0.2a}{2006/02/23}{'ue' statt 'ü' im Identifikations-String - gibt schönere
%                             Ausgabe bei \cs{listfiles}.}
%
%<*driver>
\nonstopmode
\documentclass[draft,ngerman]{ltxdoc}
\usepackage{pauldoc}
\setlength{\IndexMin}{2\IndexMin}
\begin{document}
   \DocInput{pauldoc.dtx}
\end{document}
%</driver>
% \fi
%
% \CheckSum{127}
%
%
% \changes{v0.0}{2006/01/31}{Erste Fassung}
% \changes{v0.1}{2006/02/12}{Erste veröffentlichte Fassung}
%
% \GetFileInfo{pauldoc.sty}
%
%
% \title{Das \pack{pauldoc}-Package -- Anpassungen für \pack{doc} für Pauls Package-Dokus\thanks{%
% Dieses Dokument gehört zu \pack{pauldoc}~\fileversion,
% vom~\filedate.}}
% \author{Paul Ebermann\footnote{\texttt{Paul-Ebermann@gmx.de}}}
%
% \maketitle
% \begin{abstract}
%  Dieses Package enthält einige Befehle, welche
%  die Funktion von \pack{doc} an meine Wünsche
%  anpassen.
% 
%  Außerdem werden noch einige gewünschte Pakete
%  geladen sowie einige neue Befehle definiert.
% \end{abstract}
% \tableofcontents
%
%  \changes{v0.4a}{2006/04/05}{Kleinere Änderungen an der Dokumentation.}
%
% \section{Benutzerdoku}
%
%
%  \subsection{Package-Optionen}
%
%  \DescribeMacro{chapter}
%  Diese Option legt fest, dass Index und Liste der Änderungen
%  in einem eigenen Kapitel (anstatt in einem Abschnitt) beginnen.
%  Dies ist nur in einer Dokumentenklasse sinnvoll, welche
%  überhaupt '\chapter' definiert, etwa den 'book'-artigen Klassen.
%
%  \DescribeMacro{section}
%  Legt fest, dass Index und Änderungsliste in einem Abschnitt beginnen.
%  Dies ist der Vorgabewert.
%
% \subsection{Neue Makros}
%
%  \DescribeMacro{\ifReferenceExists}\marg{refName}\marg{then}\marg{else}
%
%  Mit diesem Makro kann man, abhängig davon, ob eine bestimmte Referenz mit
%  '\label{}' gesetzt wurde, bestimmten Text ausgeben.
%
%  Falls ein '\ref'\marg{refName} Erfolg hätte, wird \meta{then} ausgewertet,
%  ansonsten \meta{else}.
%  Dies ist nützlich, wenn man im Beschreibungsteil verschiedenen Text aufnehmen
%  will, abhängig davon, ob auch der Implementationsteil mitgesetzt wird -- man
%  kann dann etwa auf einen bestimmten Abschnitt darin verweisen, und andernfalls
%  den Text im Konjunktiv formulieren ("`Wenn der Implementationsteil mit enthalten
%  wäre, könnte man dort jetzt \dots finden."').
%
%  \noindent\DescribeMacro{\pack}\marg{name}
%
%  In Paketbeschreibungen werden häufiger Paketnamen (der des eigenen
%  Paketes, gelegentlich auch andere Pakete) verwendet. Wie in
%  "`How to Package Your \LaTeX{} Package"' (Scott Pakin, dtxtut.pdf),
%  Abschnitt 3.2, erläutert, setzt man Package-Namen (sofern es dafür
%  nicht ein eigenes Logo gibt) üblicherweise in '\textsf{}' (die
%  serifenlose Schrift der Klasse). Ich bevorzuge einen sprechenderen
%  Namen, daher gibt es jetzt '\pack{pauldoc}' für \pack{pauldoc}.
%
%  \DescribeMacro{\includeLicense}
%  '\includeLicense' bindet die eventuell im \TeX-Suchpfad zu findende
%  Lizenz ein. Dies ergibt -- je nach dem, ob 'section' oder 'chapter'
%  als Option gegeben wurde -- ein neues Kapitel oder einen neuen
%  Abschnitt. Durch Neudefinition von\DescribeMacro{\lpplfilename}
%  '\lpplfilename' kann festgelegt werden, welche Datei zu verwenden
%  ist -- als Vorbgabewert ist die bei \LaTeX{} mitgelieferte Datei
%  \texttt{\lpplfilename} im Package festgelegt.
%
%
%  \DescribeMacro{\cmd}\DescribeMacro{\cs}
%  \DescribeMacro{\marg}\DescribeMacro{\oarg}\DescribeMacro{\parg}
%  Diese fünf Makros habe ich aus \pack{ltxdoc} kopiert, damit man sie
%  auch verwenden kann, wenn eine Doku mit einer anderen Klasse formatiert
%  wird (wie bei meiner \pack{alg-script}-Klasse). (Sie sind so formatiert,
%  dass eine andere Definition immer vorgeht.)
%
% '\cmd'\marg{makro} formatiert einen Makronamen. '\cmd{\bla}' ergibt
%  \cmd{\bla}. (Sollte der erste Buchstabe kein '\' sein, wird er
%      damit ersetzt: '\cmd{abc}' ergibt \cmd{abc}.)
%  '\cs'\marg{makro} tut das gleiche -- hier wird allerdings der '\' noch
%  angefügt. Falls '\cmd' mal nicht geht, geht gelegentlich noch '\cs'.
%  '\cs{bla}' ergibt \cs{bla}.
%
%   '\marg{text}' gibt \marg{text} aus. Die Abkürzung steht für
%   "`mandatory argument"'.
%    '\oarg{text}' ergibt \oarg{text} ("`optional argument"').
%    '\parg{te,xt}' ergibt \parg{te,xt} ("`picture mode argument"').
%
%
% \StopEventually{\appendix\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{Package-Optionen}
%
%  \begin{macro}{chapter}
%  '\chapter' als Trenner.
%    \begin{macrocode}
\DeclareOption{chapter}{
   \let\pauldoc@indexsec=\chapter
}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{section}
%  '\section' als Trenner.
%    \begin{macrocode}
\DeclareOption{section}{
   \let\pauldoc@indexsec=\section
}
%    \end{macrocode}
%  \end{macro}
%
% \begin{macro}{\pauldoc@indexsec}
%  Wir definieren noch '\pauldoc@indexsec', rufen dann
%  die Vorgabeoption 'section' auf (welche das gleich neu definiert)
%  und verarbeiten die gegebenen Optionen.
%    \begin{macrocode}
\newcommand*{\pauldoc@indexsec}{}
\ExecuteOptions{section}
\ProcessOptions\relax
%    \end{macrocode}
% \end{macro}
%
%  \subsection{geladene Pakete}
%
%  Wir laden das Paket \pack{inputenc} mit Option 'latin1', um
%  Sonderzeichen auch so eingeben zu können. \pack{babel} sorgt
%  für vernünftige deutsche Bezeichnungen.
%    \begin{macrocode}
\RequirePackage[latin1]{inputenc}
\RequirePackage[ngerman]{babel}
%    \end{macrocode}
%
%  \changes{v0.3}{2006/03/23}{Jetzt mit \cs{usepackage}\protect\linebreak[0]'[T1]{fontenc}'}
%  \pack{fontenc} mit Option 'T1' lädt das T1-Fontencoding, in dem
%  etwa Umlaute direkt aus der Schriftart genommen werden können,
%  anstatt sie mit \"{ } und den Vokalen a, o und u zusammenzusetzen. Dies führt
%  auch zu einer verbesserten Silbentrennung.
%    \begin{macrocode}
\RequirePackage[T1]{fontenc}
%    \end{macrocode}
%
%  \subsection{Diverse Einstellungen}
%  
% Wir wollen natürlich in der Doku Querverweise haben,
% die Änderungen registrieren (für eine entsprechende Liste)
% und im Index mit Zeilennummern arbeiten. Codestellen
% wollen wir mit \verb|'| markieren.
%    \begin{macrocode}
\EnableCrossrefs
\RecordChanges
\CodelineIndex
\AtBeginDocument{\MakeShortVerb{\'}\selectlanguage{ngerman}}
%    \end{macrocode}
%  Außerdem sollten Index und Änderungsliste auf deutsch beschriftet werden.
% Wie benutzen hier '\@pauldoc@indexsec', was entweder '\section'
% oder '\chapter' ist.
%    \begin{macrocode}
\renewcommand{\generalname}{Allgemein}
\GlossaryPrologue{\pauldoc@indexsec{Liste der Änderungen}}
\IndexPrologue{\pauldoc@indexsec{Index}
   
   Schräggedruckte Nummern verweisen auf die Seite, auf der der
   Eintrag beschrieben ist, unterstrichene Nummern zeigen auf die
   Zeilennummer der Definition, sonstige Zahlen auf die Zeilennummer
   einer Verwendung.}
%    \end{macrocode}
% Der Index bekommt nur zwei Spalten (wir haben einige ziemlich lange
% Makronamen).
%    \begin{macrocode}
   \setcounter{IndexColumns}{2}
%    \end{macrocode}
%
%  \subsection{Neue oder geänderte Makros}
%
%  \subsubsection{Bedingte Anweisungen}
%  \begin{macro}{\ifReferenceExists}\marg{label}\marg{then}\marg{else}
%
%    '\ifReferenceExists' prüft einfach, ob das Makro '\r@'\meta{label}
%     (dort wird die Referenz auf das Label gespeichert), existiert, und
%     wertet entsprechend \meta{then} oder \meta{else} aus.
%    \begin{macrocode}
\newcommand*{\ifReferenceExists}[3]
{%
  \@ifundefined{r@#1}{#3}{#2}%
}
%    \end{macrocode}
%  \end{macro}
%  
%  \subsubsection{Packagenamen}
%  \begin{macro}{\pack}
%  Um Packagenamen wie \pack{pauldoc} vernünftig
%  auszeichnen zu können, dieser Befehl.
%    \begin{macrocode}
   \newcommand*{\pack}{\textsf}
%    \end{macrocode}
%  \end{macro}
%
% \subsubsection{Logos}
%
%  \begin{macro}{\eTeX}
%  \changes{v0.4}{2006/04/02}{Neu.}
%  Aus 'etex.sty' geklaut -- das \eTeX-Logo.
%    \begin{macrocode}
\newcommand*\eTeX{$\m@th\varepsilon$-\TeX}
%    \end{macrocode}
%  \end{macro}
%
% \subsubsection{Lizenz}
%
%  \begin{macro}{\includeLicense}
%   Die Lizenz wird nur eingelesen, wenn sie auch
%   gefunden wird. Dafür wird der Dateiname,
%   welcher in '\lpplfilename' steht, eingebunden.
%    \begin{macrocode}
   \newcommand*{\includeLicense} {
   \IfFileExists{\lpplfilename}{%
%    \end{macrocode}
%  Zunächst stellen wir die Sprache um (aber nur Silbentrennung etc.,
%  keine Namen), mit dem passenden \pack{babel}-Befehl.
%    \begin{macrocode}
     \begin{otherlanguage*}{english}
%    \end{macrocode}
%  \changes{v0.2}{2006/02/14}{Verwendung einer neuen Version der
%                             LPPL macht Workarounds unnötig.}
%  Um die Lizenz als '\chapter' einzubinden und dann Referenzen
%  darauf im Text verwenden zu können, waren mit der \LaTeX-Version
%  vom 13. Januar 2006 einige Verrenkungen notwendig -- siehe unten.
%
%  Am 10. Februar habe ich einen Vorschlag zur Verbesserung
%  an die LaTeX-Bug-Liste geschickt, das wurde positiv aufgenommen.
%  \footnote{Siehe \texttt{http://www.latex-project.org/cgi-bin/ltxbugs2html?pr=latex/3839}.}
%  Ich habe jetzt von eine verbesserte Version von Frank Mittelbach bekommen,
%  die hoffentlich demnächst auch veröffentlicht wird.
%
%  Wir wollen die Abschnitte der Lizenz auch nummeriert
%  (und im Inhaltsverzeichnis) haben, deswegen die Versionen
%   ohne '*'. Falls 'chapter'
%  als Package-Option angegeben wurde, schieben wir außerdem
%  alles eine Ebene höher.
%    \begin{macrocode}
\ifx\pauldoc@indexsec\chapter
  \providecommand*{\LPPLsection}{\chapter}
  \providecommand*{\LPPLsubsection}{\section}
  \providecommand*{\LPPLsubsubsection}{\subsection}
  \providecommand*{\LPPLparagraph}{\subsubsection}
\else
  \providecommand*{\LPPLsection}{\section}
  \providecommand*{\LPPLsubsection}{\subsection}
  \providecommand*{\LPPLsubsubsection}{\subsubsection}
  \providecommand*{\LPPLparagraph}{\paragraph}
\fi
%    \end{macrocode}
%
% Der folgende (auskommentierte) Code sowie die eingerückte
% Dokumentation dazu ist mit der neuen
% Version der Lizenz-Datei nicht mehr notwendig -- ich lasse
% ihn mal trotzdem hier drin, zu Dokumentationszwecken.
% \begin{quotation}\slshape
%  Die Lizenz-Datei (zumindest die mir vorliegende
%  Version) verwendet Unterteilungen ab '\section' --
%  falls in unserer Dokumentation '\chapter' verwendet
%  werden soll (d.h. die entsprechende Option gegeben
%  wurde), stellen wir einen Kapitelbeginn davor.
%\begin{verbatim}
%       \ifx\pauldoc@indexsec\chapter
%         \chapter{Lizenz}%
%       \fi
%\end{verbatim}
%  \begin{macro}{\section*}
%  \begin{macro}{\lizenz@oldsection@}
%  Damit wir aus dem Dokument auf die Lizenz referieren
%  können, definieren wir den Befehl '\section', welcher
%  zu Beginn der Lizenz verwendet wird, so um, dass er
%  ein Label setzt. (Weil wir uns in einer Gruppe
%  befinden (durch die 'otherlanguage'-Umgebung), bleibt
%  die Änderung lokal.)
%\begin{verbatim}
%      \newcommand{\lizenz@oldsection@}{}%
%      \let\lizenz@oldsection@\section\relax%
%      \def\section*{% 
%        \label{lppl-chapter}%
%        \lizenz@oldsection@*%{##1}%
%       }%
%\end{verbatim}
%  \end{macro}
%  \end{macro}
%  \begin{macro}{\emph}
%  Leider habe ich es nicht wirklich geschafft, den Befehl
%  so umzudefinieren, dass nach dem '\section*{}'-Befehl noch
%  ein Label kommt -- deswegen definiere ich stattdessen den
%  '\emph{}'-Befehl um, der zumindest in meiner Ausgabe der
%  LPPL direkt nach dem '\section*' kommt. Ein böser Hack,
%  ich weiß \dots
%\begin{verbatim}
%      \newcommand{\lizenz@oldemph}{}%
%      \let\lizenz@oldemph\emph%
%      \def\emph{%
%         \label{lppl-section}%
%         \let\emph\lizenz@oldemph%
%         \emph%
%         }%
%\end{verbatim}
%  \end{macro}
%  \end{quotation}
%   Einige Änderungen sind notwendig, um
%   die Lizenz einzulesen: '%' soll wieder
%   ein Kommentarzeichen sein, \verb|'| darf kein
%   Verbatim-Zeichen mehr sein, weil diese Zeichen
%   in der Lizenz-Datei natürlich nicht den
%   Doc-Konventionen entsprechend verwendet werden.
%   Dann lesen wir die Datei ein, und machen danach die Änderungen
%   wieder rückgängig.
%    \begin{macrocode}
       \DeleteShortVerb{\'}%
       \MakePercentComment\input{\lpplfilename}\MakePercentIgnore%
       \MakeShortVerb{\'}%
%    \end{macrocode}
%  ... und jetzt setzen wir die Sprache wieder zurück.
%    \begin{macrocode}
     \end{otherlanguage*}
%    \end{macrocode}
%  Falls die Lizenz-Datei nicht gefunden wurde, geben wir nur eine passende Meldung aus.
%    \begin{macrocode}
   }{%
       \typeout{^^J%
          ^^J%
          Die Datei \lpplfilename{} wurde nicht gefunden.^^J%
          Schade, da wird die Lizenz eben nicht eingebunden.^^J%
          ^^J%
          }%
     }%
   }
%    \end{macrocode}
%  \end{macro}
%  
%  \begin{macro}{\lpplfilename}
%  \changes{v0.2}{2006/02/14}{Dateiname von
%                 'lppl-1-3b.tex' nach 'lppl.tex' geändert.}
%  Ich definiere noch den Dateinamen der Lizenz, unter
%  der die meisten meiner Pakete stehen, zur Zeit ist
%  das die unter dem Namen \texttt{\lpplfilename}
%   verbreitete LPPL.
%    \begin{macrocode}
\AtBeginDocument{
   \providecommand{\lpplfilename}{lppl.tex}
}
%    \end{macrocode}
%  \end{macro}
%
%
%  \subsubsection{Kopiert aus \pack{ltxdoc}}
%
%  \changes{v0.1}{2006/02/04}{\cs{cs}, \cs{cmd}, \cs{marg}, \cs{oarg}, \cs{parg}
%                             hinzugefügt aus
%                             \pack{latxdoc}.}
%  Die folgenden vier Kommandos kopierte ich aus \pack{ltxdoc},
%  um sie auch verwenden zu können, wenn ich nicht diese Klasse
%  verwende. Durch die Verwendung von '\providecommand' gibt es
%  keine Konflikte, falls sie doch schon definiert sind.
%
% \begin{macro}{\cmd}
%   Formatiert einen Makronamen, '\cmd{\bla}' ergibt \cmd{\bla}.
%   (Sollte der erste Buchstabe kein '\' sein, wird er damit ersetzt.)
%    \begin{macrocode}
\@ifundefined{cs}
{%
  \providecommand*{\cmd}[1]{\cs{\expandafter\cmd@to@cs\string#1}}
  \def\cmd@to@cs#1#2{\char\number`#2\relax}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\cs}
%   Implementiert wurde '\cmd' mit '\cs' -- '\cs{bla}' ergibt \cs{bla}.
%   Dies funktioniert auch an einigen Stellen, wo '\cmd{\bla}' nicht
%   funktioniert.\footnote{Das steht jedenfalls in der \pack{ltxdoc}-Doku,
%     auch wenn ich das nicht ganz verstanden habe.}
%    \begin{macrocode}
  \DeclareRobustCommand*\cs[1]{\texttt{\char`\\#1}}%
}
{}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\marg}
%    |\marg{text}| gibt \marg{text} aus. Die Abkürzung steht für
%   "`mandatory argument"'.
%    \begin{macrocode}
\providecommand\marg[1]{%
  {\ttfamily\char`\{}\meta{#1}{\ttfamily\char`\}}}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\oarg}
%    |\oarg{text}| ergibt \oarg{text} ("`optional argument"').
%    \begin{macrocode}
\providecommand\oarg[1]{%
  {\ttfamily[}\meta{#1}{\ttfamily]}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\parg}
%    |\parg{te,xt}| ergibt \parg{te,xt} ("`picture mode argument"').
%    \begin{macrocode}
\providecommand\parg[1]{%
  {\ttfamily(}\meta{#1}{\ttfamily)}}
%    \end{macrocode}
% \end{macro}
%
% \subsubsection{Bugfixes}
%  Inzwischen\footnote{mit dem \LaTeX-Beta-Release vom 3.Februar 2006 -- \pack{doc} hat das Datum 2006/02/02} ist der folgende Bug korrigiert, daher hier auskommentiert.
% \begin{quote}
%  \begin{macro}{\SpecialEnvIndex}\slshape
%  \changes{v0.1}{2006/02/04}{Bugfix ist überflüssig}
%   Aufgrund eines Bugs in \pack{doc}\footnote{Siehe
%   \texttt{http://www.latex-project.org/cgi-bin/ltxbugs2html?pr=tools/3834} --
%   das ist (laut einer E-Mail, die ich als Antwort auf meinen Bug-Report
%   (am 2006/01/30) bekam) schon bekannt und im Code korrigiert, ein
%   Release steht bevor.} definiere ich hier
%   '\SpecialEnvIndex' neu, damit die environment-Verwendungen
%   genauso wie die environment-Definitionen einsortiert werden,
%   nicht als eigener Eintrag namens "`environments:\meta{name}"'.
%\begin{verbatim}
%\renewcommand*{\SpecialEnvIndex}[1]{\@bsphack
%    \index{#1\actualchar{\protect\ttfamily#1}
%           (environment)\encapchar usage}%
%    \index{environments:\levelchar#1\actualchar{%
%                \protect\ttfamily#1}\encapchar
%           usage}\@esphack}
%\end{verbatim}
%  \end{macro}
% \end{quote}
% 
% \subsection{Ende}
%  \ldots und Schluss.
%    \begin{macrocode}
\endinput
%</package>
%    \end{macrocode}
%
% \Finale
%\endinput


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