Zusätzliches Material zur Lektion.

Ein guter Einstieg in Bedeutung und Verwendung der Datei Contents.m in Matlab liefert (wie so häufig) die Matlab-Hilfe, direkt über Matlab oder über die Seite von Mathworks erreichbar:

• http://www.mathworks.de/de/help/matlab/matlab_prog/create-a-help-summary-contents-m.html
• http://www.mathworks.de/de/help/matlab/creating-help.html

Für Toolboxen ist es in aller Regel erst einmal ausreichend, wenn diese Datei die zwei Zeilen beinhaltet, wie auf den Folien gezeigt. Nachfolgend noch einmal zur Verdeutlichung ein Beispiel:

Contents.m

% trEPR Toolbox
% Version 0.3.29 06-Feb-2014

Das ist gleichzeitig der einzige Ort, um die Versionsnummer einer Toolbox nebst dem Veröffentlichungsdatum dieser Version abzulegen. Matlab „versteht“ diese Angabe und liefert sie entsprechend beim Aufruf von ver zurück, darüber lässt sich dann auch in einer info-Routine auf die Versionsnummer und das Datum zurückgreifen.

Wichtig: Diese Datei besteht ausschließlich aus Kommentarzeilen.

Man kann diese Dateien per Hand schreiben, muss aber nicht - Matlab hilft hier beim Generieren. Das scheint allerdings nicht von der Kommandozeile aus zu funktionieren, sondern nur über die Matlab-GUI. Details dazu und zu weiteren Inhalten (u.a. eine einzeilige Beschreibung aller Dateien im jeweiligen Verzeichnis) in der oben verlinkten Matlab-Hilfe.

Die von Matlab im internen Hilfefenster (u.a. über den Befehl doc zu erreichen) angezeigte Hilfe ist im HTML-Format abgelegt. Matlab bietet dem Nutzer an, für eigene Toolboxen die Hilfe ebenfalls im HTML-Format abzulegen und Matlab „bekannt“ zu machen. U.a. dafür dienen die folgenden drei XML-Dateien:

• info.xml
• helptoc.xml
• demos.xml

Ausführliche Hilfestellung zur Verwendung und zum Schema dieser Dateien wie immer in der Matlab-Hilfe:

• http://www.mathworks.de/de/help/matlab/matlab_prog/display-custom-documentation.html

Die so abgelegte Hilfe kann auch noch indiziert und so entsprechend durchsuchbar gemacht werden. Dafür gibt es in Matlab den Befehl builddocsearchdb, der, wenn gewünscht, sinnvollerweise in der Installationsroutine einer Toolbox mit aufgerufen wird. Hilfe zur Funktion:

• http://www.mathworks.de/de/help/matlab/ref/builddocsearchdb.html

Im Falle einer GUI ist es hilfreich, die Hilfe innerhalb der GUI direkt erreichbar zu machen (in der Regel über ein eigenes Fenster). Da die Hilfe im HTML-Format vorliegt, ist die einfachste Lösung, über die Java-Fähigkeiten von Matlab das gleiche Objekt zu verwenden, das Matlab intern auch für seinen Hilfebrowser verwendet. Die entsprechenden Tricks finden sich (wie so häufig für Java-relevante Aspekte der Matlab-GUI-Programmierung) auf Yair Altmans Blog http://undocumentedmatlab.com/.

Nachfolgend ein Minimalbeispiel aus der eigenen Praxis:

% Use a Java Browser object to display HTML
jObject = com.mathworks.mlwidgets.html.HTMLBrowserPanel;
[browser,container] = javacomponent(jObject, [], hMainFigure);
set(container,...
    'Units','Pixels',...
    'Position',[10 10 430 230]...
    );

Die aktuell angezeigte HTML-Datei teilt man dem so erzeugten Browser-Objekt wie folgt mit:

browser.setCurrentLocation(<pathToFileContainingHelp>);

Die möglichen Aufgaben der Installationsroutine wurden auf den Folien vorgestellt. Ohne Anspruch auf Vollständigkeit:

• Matlab-Suchpfad aktualisieren
• Durchsuchbare Dokumentation aufbauen
• Kompilieren von Quellcode (Fortran/C/C++/…)
• Anlegen notwendiger Verzeichnisse
• Anlegen einer Konfiguration aus Konfigurationsvorlagen

Nachfolgend zu einzelnen Aspekten noch zusätzliche Anmerkungen.

Grundsätzlich speichert Matlab den Suchpfad in der Datei pathdef.m im Matlab-Installationsverzeichnis.¹⁾ Matlab erlaubt allerdings über die Kommandozeile und die Befehle path und addpath eine Anzeige und Modifikation des Pfades.

• http://www.mathworks.de/de/help/matlab/ref/addpath.html

Interessant ist vor allem die Möglichkeit, einen Pfad auch an das Ende des Suchpfades anzuhängen, da die Reihenfolge der Einträge bei mehreren Funktionen mit identischem Namen entscheidend ist (first come, first served):

addpath('<verzeichnis>','-end');

Da Matlab selbst nicht in der Lage zu sein scheint, ein generisches Verzeichnis im jeweilgen Nutzerheimatverzeichnis anzulegen und dort alle relevanten Informationen zu speichern, muss derlei für eigene Toolboxen selbst implementiert werden. Es gibt Möglichkeiten, über entsprechende Systemaufrufe das Heimatverzeichnis des gerade angemeldeten Nutzers herauszubekommen, und von da aus kann man dann z.B. in Unix-Manier (Die sich mittlerweile weiter durchzusetzen scheint) ein mit einem Punkt beginnendes Verzeichnis anlegen und dort alle relevante Konfiguration etc. ablegen.

Möglicherweise relevante Informationen für ein solches Verzeichnis:

• Konfiguration (aktuell genutze und ggf. vom Nutzer angepasste)
• Snapshots (Zustand einer GUI, vgl. Lektion 7)

Auch wenn der Ansatz des „Convention over configuration“ sehr wertvoll ist, sollte man nicht auf eine weitgehende Konfigurierbarkeit verzichten.

Es hat sich in der Praxis als hilfreich erwiesen, Konfigurationsdateien als Vorlagen mitzuliefern und am Anfang bei der Installation der Toolbox aus diesen Vorlagen eine gültige und genutzte Konfiguration zu erzeugen. Die Installationsroutine sollte dabei gleichzeitig noch überprüfen, dass vom Nutzer durchgeführte Änderungen vorheriger Versionen möglichst erhalten bleiben.