Anleitung zum Übersetzen von Correctoren

Für diese Anleitung ist MIAU erforderlich, wo die weiteren Arbeiten in der Checkin Tree-Ansicht ("View") getätigt werden.

Correctoren befinden sich im Allgemeinen im correctors-Ordner unterhalb des problems-Ordners in einem Inhaltspaket (also z.B. unterhalb content/tub/linear_algebra/problems für die Lineare Algebra). Unterhalb dieses Ordners liegt meistens eine weitere, mathematisch-motivierte Struktur. Das Übersetzen kann am einfachsten mit dem Mumie Java Editor getätigt werden. Dieser wird standardmäßig geöffnet wenn man einen Corrector im Checkin Tree doppelt-klickt (zu erkennen am Icon mit einem "J").

Prinzip

Im Quellcode gibt es mitunter Texte, die direkt innerhalb von Programmieranweisungen stehen, also z.B.:

subNode.getAnswerNode().addParagraphNode("Berechne die Norm des Vektors");

Diese Texte müssen vom Programmiercode gelöst und in eine externe Datei geschrieben werden, wobei der ursprüngliche Text im Quellcode durch einen Text-Schlüssel (einen sogenannten LSP-Key) ausgetauscht wird. Damit wird der Text durch diesen Schlüssel identifiziert.

Es gibt 2 verschiedene Techniken, die Textschlüssel im Quellcode anzugeben.
  1. Austauschen von Java-Methoden: Methoden A durch Methode B tauschen, ggf. weitere Anpassungen nötig; abhängig von der Komplexität der Aufgabentexte kann dies recht kompliziert werden
  2. Benutzung eines TeX-Kommandos: statt des Textes wird das TeX-Kommando "\lsp{..}" benutzt, dessen Inhalt der Textschlüssel ist; der Text darf keine Parameter enthalten, darf aber überall verwendet werden, wo jetzt schon Text steht

Beiden Techniken gemein ist, dass innerhalb der Übersetzungen keine TeX-Kommandos benutzt werden dürfen. Dies ist bei jenen Correctoren recht schwierig, die von TeX-Kommandos extensiv Gebrauch machen oder Texte und Formeln stark vermischen. Hier bietet sich letztere Technik an, da das "\lsp{..}"-Kommando direkt im Text benutzt werden kann.

Austauschen von Java-Methoden

Die addParagraphNode(..)-Anweisung muss durch eine geeignete addText(..)-Anweisung ausgetauscht werden.

Der Quellcode müsste dann wie folgt aussehen:

subNode.getAnswerNode().addText("text_1");

Benutzung des TeX-Kommandos

Die addParagraphNode(..)-Anweisung bleibt stehen, der Text muss lediglich durch eine \lsp{..}-Anweisung ausgetauscht werden.

Der Quellcode müsste dann wie folgt aussehen:

subNode.getAnswerNode().addParagraphNode("\\lsp{text_1}");

Der doppelte Backslash ist nötig, da er in Java ein Sonderzeichen ist.

LSP-Sheets erstellen

LSP Sheets liegen in einem Verzeichnis "i18n" parallel zur TeX-Quelle der Aufgabe und zum "correctors"-Verzeichnis, d.h.:


|- correctors
|    |- Corrector 1
|    |- Corrector 2
|- i18n
|    |- LSP 1
|    |- LSP 2
|- Aufgabe 1
|- Aufgabe 2

Um ein neues Verzeichnis "i18n" zu erstellen das Verzeichnis darüber im Checkin Tree anklicken, Rechtsklick, New -> Section und als Namen "i18n" eintippen.

Nun das Verzeichnis "i18n" anklicken, Rechtsklick, New -> Document und als Kategorie Other Mumie Documents → Language Sensitive Phrases auswählen. Als Namen kann der des Correctors gewählt werden. Nun auf Next drücken, das einzige Layout-Template auswählen und Finish drücken. Das neue LSP-Sheet wird nun im Editor geöffnet.

Als nächstes muss das LSP-Sheet dem Corrector zugeordnet werden. Hierzu muss der Corrector geöffnet werden (Doppelklick im Checkin Tree). Oben in der Corrector-Quelle beginnt ein Absatz mit einem %/%* Zeichen, in dem die Anweisungen in blauen Schrift stehen. Hier muss eine weitere Information hinzugefügt werden, die mit "* * @mm.requireLSP **" beginnt und den Pfad zum LSP-Sheet enthält, zum Beispiel:

<fc blue>
%/**%\\ * @author ...\\ * ...\\ * @mm.section content/tub/linear_algebra/problems/1_no_geometric_structure/1_1_vector_spaces_and_the_Kn/correctors\\
  •  @mm.requireLSP content/tub/linear_algebra/problems/1_no_geometric_structure/1_1_vector_spaces_and_the_Kn/i18n/g_lsp_basis_in_r3.meta.xml\\ * ...
    </fc>

Achtung: jede Zeile muss mit einem Stern (*) beginnen. Wenn dies im obigen Beispiel nicht der Fall ist liegt das am automatischen Zeilenumbruch dieses Wikis ;-)

Zur besseren Übersicht sollte die neue Zeile unter jener stehen, die mit "* * @mm.section *" beginnt. Schließlich muss der Corrector noch kompiliert werden (Corrector im Checkin Tree auswählen und den Compile-Knopf drücken).

Siehe auch [[doc:manuals:miau:docs:i18n|Internationalization of documents]] im MIAU-Manual.

Workflow

Am Anfang sollte der Corrector gestartet werden, um für später einen Vorher-Nachher-Vergleich machen zu können. Dazu muss das zugehörige Aufgaben-TeX-Dokument im Checkin Tree angeklickt werden, wodurch der "Correction"-Button oben in der Toolbar aktiviert wird. Durch diesen wird der Corrector gestartet und die Korrektur im Browser angezeigt.

  1. Text im Corrector-Quellcode suchen
  2. Text markieren (ohne Anführungszeichen!) und Ausschneiden (Tastaturkombination Strg+x)
  3. in den LSP-Editor wechseln
  4. Add Phrase klicken, einen neuen Schlüsselnamen ausdenken und diesen in die erste Spalte der neuen Zeile schreiben
  5. in die nächste Spalte den Text einfügen (Strg+v)
  6. den Schlüsselnamen klicken, markieren und kopieren (Strg+c)
  7. zum Corrector-Quellcode wechseln
  8. die Anweisungen austauschen (siehe weiter unten für Beispiele)
  9. den kopierten Schlüsselnamen in die Anführungszeichen einfügen (Strg+v); der Schlüsselname sollte nun umgeben von Anführungszeichen sein

Zum Schluss sollte der Corrector kompiliert und gestartet werden (Qualitätssicherung!). Sollten Fehler in der MIAU-eigenen Konsole angezeigt oder sonstirgendwie gemeldet werden war das Übersetzen wohl nicht erfolgreich...

Beispiele

In der oberen Zeile steht der Vorher-Version, darunter folgt die Nachher-Version. Der Term "subNode" kann ein anderer sein (oft ist es auch "n"). Statt "getAnswerNode()" kann auch "getSolutionNode()" oder "getExplanationNode()" stehen. Die Anweisung "addParagraphNode()" fügt einen neuen Absatz hinzu, d.h. der Inhalt einer jeder solchen Anweisung steht in einer neuen Zeile.

1. Technik: Austauschen von Java-Methoden

Hier muss allgemein unterschieden werden zwischen statischen Texten und jenen, die mit Parametern vermischt sind.

Statischer Text

alt: subNode.getAnswerNode().addParagraphNode("Berechne die Norm des Vektors");
neu: subNode.getAnswerNode().addText("text_1");
LSP: text_1: Berechne die Norm des Vektors
alt: subNode.getAnswerNode().addMarkNode("Bla Bla Bla");
neu: subNode.getAnswerNode().addText("text_1", true);
LSP: text_1: Bla Bla Bla

Text mit Parametern

Parameter werden in Übersetzungen mit einem Dollarzeichen in den Text eingefügt (z.B. "$1" wofür die Eins für den ersten (und meist auch einzigen) Parameter steht). Somit steht für die dt. Übersetzung im LSP-Sheet z.B.: "Ihre Antwort war: $1"

alt: subNode.getAnswerNode().addMathObject("Text davor", irgendetwas);
neu: subNode.getAnswerNode().addText("text_1", irgendetwas);
LSP: text_1: Text davor $1

alt: subNode.getAnswerNode().addMathObject("Text davor", irgendetwas, "Text dahinter");
neu: subNode.getAnswerNode().addText("text_1", irgendetwas);
LSP: text_1: Text davor $1 Text dahinter

2. Technik: Benutzung eines TeX-Kommandos

alt: subNode.getAnswerNode().addParagraphNode("Berechne die Norm des Vektors");
neu: subNode.getAnswerNode().addParagraphNode("\\lsp{text_1}");
LSP: text_1: Berechne die Norm des Vektors
alt: subNode.getAnswerNode().addMarkNode("Bla Bla Bla");
neu: subNode.getAnswerNode().addMarkNode("\\lsp{text_1}");
LSP: text_1: Bla Bla Bla
alt: subNode.getAnswerNode().addMathObject("Text davor", irgendetwas);
neu: subNode.getAnswerNode().addMathObject("\\lsp{text_1}", irgendetwas);
LSP: text_1: Text davor

alt: subNode.getAnswerNode().addMathObject("Text davor", irgendetwas, "Text dahinter");
neu: subNode.getAnswerNode().addMathObject("\\lsp{text_1}", irgendetwas, "\\lsp{text_2}");
LSP: text_1: Text davor
LSP: text_2: Text dahinter
alt: sn.getExplanationNode().addParagraphNode("Die Determinate l\"asst sich von M_1-x\\cdot I_4\\quad sehr " +
                    "leicht bestimmen,");
     sn.getExplanationNode().addParagraphNode("da es sich um eine obere Dreiecksmatrix handelt.");
neu: sn.getExplanationNode().addParagraphNode("\\lsp{text_1} M_1-x\\cdot I_4\\quad \\lsp{text_2}");
LSP: text_1: Die Determinate l&auml;sst sich von  // statt des Latex-Sonderzeichens muss hier der richtige Umlaut eingetragen werden
LSP: text_2: sehr leicht bestimmen,<br>da es sich um eine obere Dreiecksmatrix handelt. // beachte das <br> als Zeilenumbruch (HTML-Anweisung)
alt: commonExpl.addMathObjects(new MathMLSerializable[]{
                new MString("p = "), p,
                new MString(", q = "), q,
                new MString(" und r = "), r
        });
neu: commonExpl.addMathObjects(new MathMLSerializable[]{
                new MString("p = "), p,
                new MString(", q = "), q,
                new MString(" \\lsp{and} r = "), r
        });
LSP: and: und
alt: subtask.getExplanationNode().addMathObjects(new MathMLSerializable[]{new MString("Das Bild von "),
             coordsv2a,new MString(" ist also nicht "), coordsw2a,new MString(".")});
neu: subtask.getExplanationNode().addMathObjects(new MathMLSerializable[]{new MString("\\lsp{text_1} "),
             coordsv2a,new MString(" \\lsp{text_2} "), coordsw2a,new MString(".")});
LSP: text_1: Das Bild von
LSP: text_2: ist also nicht

Behandlung von Unicode-Zeichen

Manche Correctoren sind gespickt mit Anweisungen à la "\u211D". Diese Zeichen können nicht in LSP-Sheets benutzt werden. Stattdessen müssen die "richtigen" Sonderzeichen in den Übersetzungen verwendet werden. Hier bietet sich folgende Vorgehensweise an:
  1. auf folgende Webseite gehen: [[http:_www.fileformat.info/search/google.htm?q=\u211D|http:_www.fileformat.info/search/google.htm?q=\u211D]]
  2. das Sonderzeichen in die Suche eingeben
  3. den obersten Treffen anklicken (beginnt mit Unicode Character)
  4. nach unten scrollen bis zu Java Data
  5. das Sonderzeichen in der 1. Spalte markieren und kopieren (STRG+C)
  6. zum LSP wechseln und dort das Sonderzeichen mittels STRG+V einfügen

Nach dieser Suche "offenbart" sich das Unicode-Zeichen "\u211D" als ℝ ;-)

Hinweise zu Fehlern

Bei dieser Arbeit können 2 unterschiedliche Arten von Fehlern auftreten:
  1. Kompilierfehler: der Quellcode kann nicht mehr kompiliert werden (meistens verursacht durch falsche oder fehlende Anführungszeichen). Diese Art von Fehler wird direkt im Quellcode als rote Kringellinie unterhalb des Fehlers angezeigt (so ähnlich wie in Word die Rechtschreibfehler angezeigt werden). Hier hilft nur richtig hingucken und verbessern. Änderungen können mit der Tastaturkombination Strg+z rückgängig gemacht werden.
  2. Kein oder falscher Text: dies wird durch eine fehlende addText(..)-Anweisung verursacht, das System behandelt den Schlüsselnamen als "richtigen" Text und zeigt diesen auch so an.

Sollten nichtsdestotrotz andere Fehler auftreten bitte Petrus, Markus, Rainer oder Michael fragen ;-)

Änderungen ins SVN hochladen

Zusätzlich zum Corrector müssen die LSP-Sheets ins SVN eingecheckt werden.

Add picture from clipboard (Maximum size: 500 MB)