Die Filetools beinhalten Werkzuge zur Indizierung und Konvertierung von Matlab Hilfefiles im Umfeld des MLTutor. Hier eine Übersicht über die entwickelten Tools:

`MatlabFunctionFileSearch`	Erzeugt Files mit Funktionslisten, die von der MLTutor- (genauer Meditor)-Hilfe benötigt werden.
`MatlabHelpfileIndexer`	Durchforstet die Matlab-Hilfe und speichert Daten in einer Datenbank. Diese ist die Basis zur Erzeugung der Matlab-Hilfe für das Wiki.
`HelpFileWikiIndexGenerator`	Generiert aus den Informationen in der Datenbank Textfiles, deren Inhalt ins Wiki kopiert wird um die Wiki-Matlab-Hilfe zu erhalten.
`MatlabHelpfileConverter`	Ersetzt unbrauchbare Links in den Matlab-Hilfeseiten (html-Hilfe) durch brauchbare.

Die grundlegende Idee hinter diesen Tools ist, Klassen zur Verfügung zu stellen, die sowohl eigenständig (konkrete Klassen mit main(...) Methode) als auch von anderen Modulen aus verwendet werden können. Für letztere Variante wird in jedem Paket ein allgemeines Interface definiert, sodass die Klassen möglichst allgemein benutzt weden kann (z.B. in einer Strategy).

Package filesearchtools

Beinhaltet Klassen zum Durchsuchen von Verzeichnisstrukturen.

Interface

public interface IFileSearch {
    abstract public int searchDir(File searchDir); 
}

Einfache Basisklasse

public abstract class SimpleFileSearch implements IFileSearch {
    public SimpleFileSearch(File outputFile){}
    public int searchDir(File searchdir){}
    abstract protected boolean isDirToSearch(String dir);
    abstract protected boolean isSearchedFileName(String filename);
    abstract protected void processFile(File file);
}

Kapselt Funktionalität zum Durchsuchen einer Verzeichnisstruktur.

Konkrete Klassen müssen Funktionen überschreiben, in denen spezifiziert wird, welche Files in welchen Verzeichnissen gesucht werden. In processFile(File) wird definiert wie mit einem "gefundenen" File umgegangen wird.

Konkrete Klasse `MatlabfunctionFileSearch`

public class MatlabfunctionFileSearch extends SimpleFileSearch{
    public static void main(String[] args) {}
    public MatlabfunctionFileSearch(File outputFile, File syncFile, Vector<String> syncDirs, boolean syncMode){}
    ...
}

Sucht Files die Matlab-Funktionen beinhalten und speichert den Namen jedes Files (und somit der Funktion) in primitiven ASCII Files, wobei in jeder Zeile ein Name steht. Zeilentrennung erfolgt mit "\n". Die gefundenen Funktionen werden getrennt in Matlab- und Toolbox-Funktionen und entsprechend dieser Einteilung in zwei Ausgabefiles gespeichert. Es ist auch möglich eine Synchronisierung mit der Matlab-Hilfe durchzuführen, wobei in diesem Falle ein weiteres File gleicher Struktur erzeugt wird, in welchem alle Funktionen, für die ein (oder kein, je nach Einstellung) Hilfefile direkt gefunden wurde, aufgelistet sind.

Es werden .m Files gesucht, deren Name nicht mit einem Großbuchstaben anfängt. Dabei werden alle Verzeichnisse, die nicht mit "@" anfangen, durchsucht. Als Matlab-Funktionen werden jene erkannt, deren Pfad "toolbox/matlab" beinhaltet.

Verwendung als Anwendung

$ java filetools/filesearchtools/MatlabfunctionFileSearch -d <directory> 
       [-om <outputfile_matlab_functions>] [-ot <outputfile_toolbox_functions>] [-ds <sync_directory>] [-os <sync_outputfile>] [-sm <syncmode>]

`-d`	gibt ein Verzeichnis an, in welchem (rekursiv) gesucht werden soll. Es können beliebig viele Verzeichnisse angegeben werden (jedes mit `-d` vorher!)
`-om`	Name des Ausgabefiles für die Liste der Matlab-Funktionen. Wird keiner angegeben, so wird das File `matlab_funcs` verwendet.
`-ot`	Name des Ausgabefiles für die Liste der Toolbox-Funktionen. Wird keiner angegeben, so wird das File `toolbox_funcs` verwendet.
`-ds`	Verzeichnis in dem nach den Hilfefiles gesucht wird, jedoch nicht in dessen Unterverzeichnissen. Es können mehrere Verzeichnisse angegeben werden, um die Synchronisierung durchzuführen muss jedoch mindestens eines genannt werden.
`-os`	Name des Ausgabefiles für die Liste der Funktionen ohne Hilfefile. Wird keiner angegeben, so wird das File `matlab_funcs_sync` verwendet.
`-sm`	Modus für die Synchronisierung. Wenn '0' angegeben wird, dann werden jene Files, für die es ein Hifefile gibt, gespeichert, bei jedem anderen Wert (keine Angabe ist unzulässig!) jene, für die kein Hilfefile existiert, was auch der Fall ist wenn dieser Parameter nicht gesetzt wird,

Konkrete Klasse `MatlabHelpfileIndexer`

public class MatlabHelpfileIndexer extends SimpleFileSearch{
    public static void main(String[] args) {}
    public MatlabHelpfileIndexer(){}
    public static boolean writeDefaultProperties(String filename){}
    ...
}

Sucht Matlab Hilfefiles (.htm und .html), analysiert diese und speichert die Ergebnisse in einer mySQL Datenbank. Informationen werden gewonnen aus dem Dateinamen, aus den Informationen, die in den meisten Files als Kommentar im head enthalten sind, aus dem title und aus weiteren Tags im File (derzeit nur frameset).

Datenbankschema

+-------------+-------------------------------------------------------------+------+-----+---------+----------------+
| Field       | Type                                                        | Null | Key | Default | Extra          |
+-------------+-------------------------------------------------------------+------+-----+---------+----------------+
| ID          | int(11)                                                     |      | PRI | NULL    | auto_increment |
| filename    | tinytext                                                    |      |     |         |                |
| abspath     | text                                                        |      |     |         |                |
| docname     | text                                                        | YES  | MUL | NULL    |                |
| chunkname   | text                                                        | YES  |     | NULL    |                |
| chapname    | text                                                        | YES  |     | NULL    |                |
| pagetype    | enum('REGULAR','FRAMEPAGE','INDEXPAGE','NAVPAGE','TOCPAGE') |      |     | REGULAR |                |
| title       | text                                                        | YES  | MUL | NULL    |                |
| specialdata | text                                                        | YES  | MUL | NULL    |                |
+-------------+-------------------------------------------------------------+------+-----+---------+----------------+

Erzeugen der Tabelle

CREATE TABLE `helpfiletable` (
  `ID` int(11) NOT NULL auto_increment,
  `filename` tinytext NOT NULL,
  `abspath` text NOT NULL,
  `docname` text,
  `chunkname` text,
  `chapname` text,
  `pagetype` enum('REGULAR','FRAMEPAGE','INDEXPAGE','NAVPAGE','TOCPAGE') NOT NULL default 'REGULAR',
  `title` text,
  `specialdata` text,
  PRIMARY KEY  (`ID`),
  FULLTEXT KEY `title` (`title`),
  FULLTEXT KEY `docname` (`docname`,`chunkname`,`chapname`),
  FULLTEXT KEY `specialdata` (`specialdata`)
) TYPE=MyISAM AUTO_INCREMENT=1284 ;

Konfigurationsfile

Die Daten für die Datenbankverbindung können in einem Konfigurationsfile abgelegt werden. Derzeit ist dessen Name auf dbproperties.xml festgelegt (d.h. es muss im aktuellen Verzeichnis liegen). Es ist ein zur java.util.Properties Klasse kompatibles XML-File, dessen Struktur folgendermaßen aussieht:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<comment></comment>
<entry key="HOSTNAME">xyz</entry>
<entry key="USERPWD">xyz</entry>
<entry key="DBNAME">xyz</entry>
<entry key="USERNAME">xyz</entry>
</properties>

wobei xyz durch passende Parameter zu ersetzen sind.

Verwendung als Anwendung

$ java filetools/filesearchtools/MatlabHelpfileIndexer <directories> [--propertyfile]

wobei <directories> eine Liste von Verzeichnissen ist, die als Ausgangspunkt für die Suche verwendet werden. Die einzelnen Verzeichnisse werden durch Leerzeichen getrennt und es muss mindestens eines angegeben werden, sofern nicht der optionale Parameter verwendet wird. Wird dieser angegeben, so wird das File dbproperties.xml erzeugt, in welchem die Defaultwerte für die Verbindungseinstellungen zur Datenbank abgelegt werden.

Package filegenerators

Beinhaltet Klassen zum Erzeugen von Files.

Interface

public interface IFileGenerator {
    public boolean generateFile(String filename);
    public void setProperties(Properties properties);
}

Einfache Basisklasse

public abstract class HelpFileIndexDBCompendiumGenerator implements IFileGenerator {
    private Statement dbStatement = null;
    protected FileWriter outputFileWriter = null;
    protected Properties properties = null;
   
    public void setProperties(Properties properties){}
    public static Properties readPropertiesFromFile(String filename){}
    public boolean generateFile(String filename) {}
    protected boolean connectToDB(){}
    protected void sendAndProcessQuery(String query) 
            throws SQLException, IOException{}
    protected void includeFile(String filename) 
            throws IOException {}
    protected abstract void processTask();
    protected abstract void processRow(ResultSet row) 
            throws SQLException, IOException;
    protected void startProcessQuery(ResultSet resultSet) 
            throws SQLException, IOException{
    }
    protected void endProcessQuery(ResultSet resultSet) 
            throws SQLException, IOException{
    }
}

Stellt ein Rohgerüst zum Erzeugen von Files mit Daten aus der Matlab-Helpfile Datenbank zur Verfügung. Die Verbindung zur Datenbank ist hier gekapselt, weiters sind generelle Abläufe und Tools implementiert.

Konkrete Klassen müssen Funktionen überschreiben, in denen spezifiziert wird, welche Daten aus der DB geholt werden und wie diese ins File geschrieben werden.

Konkrete Klasse `HelpFileWikiIndexGenerator`

public class HelpFileWikiIndexGenerator extends HelpFileIndexDBCompendiumGenerator {
     public HelpFileWikiIndexGenerator(){}
     public void setSingleline(boolean singleline){}
     public static void main(String[] args) {}
    ...
}

Es werden alle Hilfefiles zu Matlab-Funktionen aus der Matlab-Reference in Wiki-Syntax in ein File geschrieben. Die Funktionen sind alphabetisch sortiert und werden nach Anfangsbuchstaben in Kapitel eingeteilt. Dabei sind zwei verschiedene Formate für die Auflistung der Funktionen möglich:

Eine Tabelle mit 4 (ist einstellbar, 4 passt aber sehr gut) Spalten, wobei in jeder Zelle der Name der Funktion als Link zur Hilfeseite angeführt wird.
Eine Tabelle wobei pro Zeile eine Funktion (gleich wie oben) angeführt wird. Zusätzlich wird zu jeder eine kurze Beschreibung angegeben. (singleline-mode)

Verwendung als Anwendung

$ java filetools/filegenerators/HelpFileWikiIndexGenerator <filename> [--singleline]

Dabei ist <filename> der Name des zu erzeugenden Files. Wird der optionale Parameter angegeben, so wird die zweite Ausgabe-Variante gewählt.

Datenbank und Konfiguration

Gleich wie bei MatlabHelpfileIndexer, allerdings wird hier für die DB lediglich Lesezugriff benötigt.

Package fileconverttools

Interface

public interface IFileConverter {
    abstract public int convertInDir(File inputRootDir, File outputDir); 
}

Einfache Basisklasse

public abstract class SimpleFileConverter implements IFileConverter {
    public SimpleFileConverter(){}
    public int convertInDir(File inputDir, File outputDir){}
    protected void copyFile(File inputFile, File outputFile);
    abstract protected void convertFile(File inputFile, File outputFile);
    abstract protected boolean isDirToConvert(String dir);
    abstract protected boolean isFileToConvert(String filename);
    abstract protected boolean isFileToCopy(String filename);
}

Kapselt Funktionalität zum Kopieren einer Verzeichnisstruktur, wobei gewisse Files konvertiert werden. Eine einfache Kopierfunktion wird zur Verfügung gestellt. In dieser wird ein File über Streams blockweise (1k) kopiert.

Von ihr müssen konkrete Klassen abgeleitet werden, welche die durchzuführenden Operationen implementieren.

Konkrete Klasse `MatlabHelpfileConverter`

public class MatlabHelpfileConverter extends SimpleFileConverter{
    public static void main(String[] args) {}
    ...
}

Mit dieser Klasse kann eine Kopie des Inhalts eines Verzeichnisses erstellt werden, wobei .htm und .html Files konvertiert werden. Die Konvertierung besteht darin, dass Links der Form <a href="file:xxxxxxxx durch <a href="xxxxxxxx ausgetauscht werden. Dies erfolgt indem jedes Vorkommen der regex 'href\s*=\s*"file:' ersetzt wird durch 'href="'.

Verwendung als Anwendung

$ java filetools/fileconverttools/MatlabHelpfileConverter -i <input-directory> [-o <output-directory>]

Wird kein output-directory angegeben, so wird innerhalb des input-directories konvertiert (und man erspart sich das Kopieren der restlichen Dateien).

Javadoc

Matlab Update

Hier werden jene Schritte beschrieben, die bei einem Matlab-Update notwendig sind, um den MLTutor und die Matlab-Hilfe im Wiki auf den neuesten Stand zu bringen.

Für die Konsolenbefehle wird davon ausgegangen, dass man sich im Stammverzeichnis der Filetools befindet. Weiters wird ein laufender MySQL Server (samt angelegter, verwendbarer Datenbank) vorausgesetzt.

Die hier angegebenen Pfade beziehen sich auf die Matlab Version R14 SP3 und müssen bei einem Matlab Update natürlich sinngemäß angepasst werden.

Wichtig: Dies ist nur eine Kurzanleitung, die die notwendigen Schritte angeben soll. Die meisten Tools besitzen noch weitere Einstellmöglichkeiten.

MLTutor aktualisieren

Der Befehl

$ java filetools/filesearchtools/MatlabfunctionFileSearch 
    -d /afs/itp.tugraz.at/opt/matlab/R14.sp3/toolbox/matlab 
    -ds /afs/itp.tugraz.at/opt/matlab/R14.sp3/help/techdoc

erzeugt die Files matlab_funcs und matlab_funcs_sync. Ersteres muss ins config Verzeichnis des Meditor Plugins kopiert werden, letzteres dient zur Information darüber, zu welchen Matlab-Funktionen keine Hilfefiles gefunden wurden.
Sollen auch alle Toolbox-Funktionen in die Funktionenliste aufgenommen werden, so ist folgender Befehl zu verwenden:

$ java filetools/filesearchtools/MatlabfunctionFileSearch 
    -d /afs/itp.tugraz.at/opt/matlab/R14.sp3/toolbox
    -ds /afs/itp.tugraz.at/opt/matlab/R14.sp3/help/techdoc
    -ds /afs/itp.tugraz.at/opt/matlab/R14.sp3/help/toolbox

Eventuell müssen noch folgende config-Files des Meditors angepasst werden:

helpproperties.xml (Beinhaltet die Basis-URLs zu den Hilfeseiten)
helpfileexceptions.xml (Ausnahmeregelungen für Hilfeseiten, z.B. wenn der Filename nicht gleich der Funktion ist, wie bei Operatoren)

Datenbank updaten

Falls noch nicht geschehen muss das File help.jar entpackt werden, da ansonsten keine Files zum Indizieren gefunden werden. Sollte die Tabelle für den Helpfileindex noch nicht in der Datenbank angelegt sein, so kann dies folgendermaßen (in einer MySQL-Console) geschehen:

CREATE TABLE `helpfiletable` (
  `ID` int(11) NOT NULL auto_increment,
  `filename` tinytext NOT NULL,
  `abspath` text NOT NULL,
  `docname` text,
  `chunkname` text,
  `chapname` text,
  `pagetype` enum('REGULAR','FRAMEPAGE','INDEXPAGE','NAVPAGE','TOCPAGE') NOT NULL default 'REGULAR',
  `title` text,
  `specialdata` text,
  PRIMARY KEY  (`ID`),
  FULLTEXT KEY `title` (`title`),
  FULLTEXT KEY `docname` (`docname`,`chunkname`,`chapname`),
  FULLTEXT KEY `specialdata` (`specialdata`)
) TYPE=MyISAM AUTO_INCREMENT=1284 ;

Weiters sollte ein Konfigurationsfile dbproperties.xml mit den Einstellungen zur DB-Verbindung vorhanden sein. Die Datenbank selbst befindet sich auf dem Rechner faeppc14.

Der Befehl zum Indizieren lautet dann:

$ java filetools/filesearchtools/MatlabHelpfileIndexer /afs/itp.tugraz.at/opt/matlab/R14.sp3/help/techdoc/ref

Sollte die library zum Verbinden mit der Datenbank nicht im Classpath sein, so ist diese noch hinzuzufügen:

$ java -cp ./:./mysql-connector-java-3.1.12-bin.jar filetools/.......

Wiki-Hilfe generieren

Dabei handelt es sich um den Inhalt der Seite Matlab_-_Reference

Mit

$ java filetools/filegenerators/HelpFileWikiIndexGenerator wikitext

wird das File wikitext erzeugt, dessen Inhalt als Seiteninhalt im Wiki verwendet wird.

Sollte die library zum Verbinden mit der Datenbank nicht im Classpath sein, so ist diese noch hinzuzufügen:

$ java -cp ./:./mysql-connector-java-3.1.12-bin.jar filetools/.......

Hilfeseiten konvertieren

Sollten die Hilfeseiten Links der Form <a href="file:xxxxxxxx enthalten, so können diese mit

$ java filetools/fileconverttools/MatlabHelpfileConverter -i <input-directory>

in ein für Webbrowsern brauchbares Format konvertiert werden.

Filetools

Inhaltsverzeichnis

Package filesearchtools

Interface

Einfache Basisklasse

Konkrete Klasse `MatlabfunctionFileSearch`

Verwendung als Anwendung

Konkrete Klasse `MatlabHelpfileIndexer`

Datenbankschema

Erzeugen der Tabelle

Konfigurationsfile

Verwendung als Anwendung

Package filegenerators

Interface

Einfache Basisklasse

Konkrete Klasse `HelpFileWikiIndexGenerator`

Verwendung als Anwendung

Datenbank und Konfiguration

Package fileconverttools

Interface

Einfache Basisklasse

Konkrete Klasse `MatlabHelpfileConverter`

Verwendung als Anwendung

Javadoc

Matlab Update

MLTutor aktualisieren

Datenbank updaten

Wiki-Hilfe generieren

Hilfeseiten konvertieren

Navigationsmenü

Meine Werkzeuge

Namensräume

Varianten

Ansichten

Mehr

Suche

Navigation

Werkzeuge

Filetools

Inhaltsverzeichnis

Package filesearchtools

Interface

Einfache Basisklasse

Konkrete Klasse MatlabfunctionFileSearch

Verwendung als Anwendung

Konkrete Klasse MatlabHelpfileIndexer

Datenbankschema

Erzeugen der Tabelle

Konfigurationsfile

Verwendung als Anwendung

Package filegenerators

Interface

Einfache Basisklasse

Konkrete Klasse HelpFileWikiIndexGenerator

Verwendung als Anwendung

Datenbank und Konfiguration

Package fileconverttools

Interface

Einfache Basisklasse

Konkrete Klasse MatlabHelpfileConverter

Verwendung als Anwendung

Javadoc

Matlab Update

MLTutor aktualisieren

Datenbank updaten

Wiki-Hilfe generieren

Hilfeseiten konvertieren

Navigationsmenü

Suche

Konkrete Klasse `MatlabfunctionFileSearch`

Konkrete Klasse `MatlabHelpfileIndexer`

Konkrete Klasse `HelpFileWikiIndexGenerator`

Konkrete Klasse `MatlabHelpfileConverter`