summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/schule/doc/devModule.tex
blob: ddd2c358c4163a9a9a914f397e6647abcad09845 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
\section{Modularität}
	\label{sec:devmodule}
	\subsection{Erläuterungen zum Modulsystem}
	Ein zentrales Problem des alten Schule-Pakets bis Version 0.6
	war, dass es sehr monolithisch aufgebaut und alles integrierte,
	was im Schulalltag und in der Lehrerausbildung nützlich sein
	könnte. So wurden die Weiterentwicklung und Übergabe an neue
	Maintainer schwierig, da stets eine Einarbeitung in alle Bereiche
	erforderlich war.

	Die grundlegende Entscheidung für das neue Schule-Paket ist es
	also, eine Modularisierung zu etablieren, die, zusätzlich zu
	einem stabilen Kern, verschiedene Funktionen und Fachspezifika
	entsprechend kapselt und von diesem Kern trennt.

	Ein eindeutiger Aufbau dieser Module soll dafür sorgen, dass es
	leichter wird, neue Funktionen zu ergänzen, ohne den gesamten
	Quelltext des Pakets kennen und verstehen zu müssen.

	Grundsätzlich gibt es drei verschiedene Arten von Modulen im
	Schule-Paket: \textbf{Module}, \textbf{Fachmodule} und
	\textbf{Zusatzpakete}, \vgl\space \prettyref{sec:begriffe}.

	Erweiterungen ohne direkten Bezug (also alles, das auch ohne das
	Schule-Paket sinnvoll genutzt werden kann) zum Paket sollten in
	Form unabhängiger Zusatzmodule implementiert werden.

	\subsection{Aufbau eines Moduls}

	\label{sec:devmoduleModul}

    Ein Modul für das Schule-Paket besteht aus mehreren Dateien, deren erster Teil des Namens \texttt{schule.mod.Modulname} identisch ist. Je nach Funktion werden dort drei Möglichkeiten angehangen, die als Abschnitte bezeichnet werden. Sobald eine der Dateien mit diesem Schema vorhanden ist, kann das Modul über seinen Namen eingebunden werden, \vgl\space\prettyref{sec:module}. Alle Dateien vorgegebenen Dateien liegen dazu im Verzeichnis \enquote{latex}.

    Der Modulmechanismus sorgt dafür, dass die entsprechenden Abschnitte des Moduls an den richtigen Stellen des Quelltextes eingebunden werden. Es sind die folgenden drei Abschnitte definiert:

    \begin{description}
        \item[\texttt{optionen.tex}] $\rightarrow$ Paketoptionen des Moduls, \vgl\space Paket \pkg{pgfopts}
        \item[\texttt{pakete.tex}] $\rightarrow$ Paketabhängigkeiten des Moduls
        \item[\texttt{code.tex}] $\rightarrow$ Implementierung des Moduls
    \end{description}

    All diese Abschnitte sind optional und werden geladen, wenn sie vorhanden sind. Ein Modul kann also beispielsweise nur aus einer \texttt{code.tex}-Datei bestehen, wenn es nur einige Makros definiert.

	\subsubsection{Beispiel}
	\label{sec:devmoduleModulBeispiel}
	\paragraph{schule.mod.HalloWelt.optionen.tex}
\begin{sourcecode}[gobble=0]
% ********************************************************************
% * Paketoptionen                                                    *
% ********************************************************************

% Boolesche Optionen
% ********************************************************************
\newboolean{schule@nutzeGoodbye}

% Standardwerte
% ********************************************************************
\newcommand{\schule@weltname}{Welt}

% Definition der Paketoptionen
% ********************************************************************
\pgfkeys{
  /schule/.cd,
  weltname/.store in=\schule@weltname,
  nutzeGoodbye/.value forbidden,
  nutzeGoodbye/.code=\setboolean{schule@datumAnzeigen}{true},
}
\end{sourcecode}

	\paragraph{schule.mod.HalloWelt.pakete.tex}
\begin{sourcecode}[gobble=0]
% ********************************************************************
% * Paketabhängigkeiten                                              *
% ********************************************************************

\RequirePackage{ifthenelse}
\end{sourcecode}

	\paragraph{schule.mod.HalloWelt.code.tex}
\begin{sourcecode}[gobble=0]
% ********************************************************************
% * Hallo Welt!                                                      *
% ********************************************************************

\newcommand{\halloWelt}{
  \ifthenelse{\boolean{schule@nutzeGoodbye}}{
    Goodbye \schule@weltname!
  }{
    Hallo \schule@weltname!
  }
}
\end{sourcecode}


    \subsection{Aufbau eines Fachmoduls}

    \label{sec:devmoduleFachmodul}

    Ein Fachmodul für das Schule-Paket wird analog zu einem normalen Modul erstellt, \vgl\space\prettyref{sec:devmoduleModul}. Hier steht nur im Dateinamen nach dem zweiten Punkt \texttt{fach} anstatt \texttt{mod}.

    Die Dateien für das Fach Geschichte sind dann beispielsweise folgende:
    \begin{itemize}
        \item \texttt{schule.fach.Geschichte.optionen.tex}
        \item \texttt{schule.fach.Geschichte.pakete.tex}
        \item \texttt{schule.fach.Geschichte.code.tex}
    \end{itemize}


    \subsection{Aufbau eines Dokumenttyps}

    \label{sec:devDokumenttyp}

    Auch ein Dokumenttyp für das Schule-Paket hat den gleichen Aufbau wie ein normales Modul, \vgl\space\prettyref{sec:devmoduleModul}. Hier steht nur im Dateinamen nach dem zweiten Punkt \texttt{typ} anstatt \texttt{mod}.

    Die Dateien für das Arbeitsblatt (Typ ab) sind dann beispielsweise folgende:
    \begin{itemize}
        \item \texttt{schule.typ.ab.optionen.tex}
        \item \texttt{schule.typ.ab.pakete.tex}
        \item \texttt{schule.typ.ab.code.tex}
    \end{itemize}