2. Informationen für Autoren und Übersetzer des Mahara Manuals

von Kristina D.C. Hoeppner

Diese Liste wird kontinuierlich während meiner Arbeit am Handbuch fortgeschrieben. Für verschiedene Teile wurden Festlegungen getroffen. Diese sollen zentral sichtbar sein, damit andere Zugriff haben und ich selbst immer wieder darauf zugreifen kann. ;-)

Die Reihenfolge der Einträge in dieser Liste ist zufällig.

2.1. Bildschirmfotos

  • werden über die Bild-Anweisung (‚figure‘) eingebunden
  • enthalten immer ‚Alt‘-Texte und Bildbeschreibungen. Die letztgenannten werden im PDF-Export durchnummeriert. Sie werden vom Text abgesetzt.
  • werden grundsätzlich vor einer Aufzählung der Schritt-für-Schritt-Anleitung platziert
  • sollten so wenige Schritte wie möglich enthalten und genau die Schritte beschreiben, die im Screenshot abgebildet sind. Dadurch können sie einfacher ausgetauscht und übersetzt werden. Übersetzer können daher im ersten Schritt die Texte übersetzen und müssen nicht zwangsläufig auch die Bilder austauschen.
  • verwende die Callouts aus Gimp, die mit dem Script von Iñaki erstellt wurden.
  • enthalten Ziffern, die die Reihenfolge der Arbeitsschritte verdeutlichen und im Text unter dem Bild beschrieben werden.
  • soll nur den erforderlichen Bildbereich zeigen und nicht den gesamten Bildschirm, wenn dies nicht unbedingt erforderlich ist.

Die meisten Screenshots enthalten Ziffern als Verweise auf den Text:

Example of including a screenshot

Beispiel zum Einbinden eines Screenshots

  1. Die erste Zeile enthält den Pfad zur Datei. * ersetzt die Dateinamenserweiterung und Sphinx wählt die passendste Datei aus. Es sind dadurch unterschiedliche Bilddateiformate oder Screenshots in verschiedenen Formaten möglich.
  2. Die zweite Zeile enthält den Alt-Text, der angezeigt wird wenn man mit der Maus über das Bild fährt oder die Seite mit einem Screenreader aufgerufen wird.
  3. Die dritte Zeile muss leer bleiben. Dies ist der Text, der als Bildbeschreibung unter dem Screenshot angezeigt wird. Bei der PDF-Ausgabe wird diese fortlaufend durchnummeriert.
  4. If you don’t want to display all the information from a screen but only the top and the bottom part, you can use the file z_omission.xcf and place it into your screenshot. The sinus waves were created using the gimp plugin Shape paths with the following settings:
    • Sine Wave
    • Start X: 0
    • Start Y: 200 and upon the second run 215 to get the gap between the lines
    • Amplitude: 3
    • Wavelength: 25
    • Number of cycles: 40 (abhängig von der Breite des Screens)
    • Tick for Stroke path
    • Stroke color: CCCCCC

Bemerkung

Wenn Sie ein Bild inline mit dem Text einbinden wollen und die Ziffernanordnung nicht übernehmen wollen oder können, müssen Sie einen Ersatz anlegen und in die shortcuts.rstext-Datei einfügen.

2.2. Wichtige Hinweise zum Gebrauch

  • Hinweis: für alles was etwas mehr Aufmerksamkeit benötigt

    Bemerkung

    Hinweise können direkt in eine Aufzählungsliste eingefügt werden. Vor und hinter dem Hinweis ist eine Leerzeile einzufügen. Der Warnhinweis muss um drei Leerzeichen eingerückt werden.

  • Warnung: für alles was mit großer Vorsicht angepackt werden muss

    Warnung

    Versuche nicht alles in den Warnhinweis zu packen. Die wirklich wichtige Information geht dann verloren.

  • auch wichtig: Verweise auf andere Dokumente wenn sie wichtig sind. Verweise auf andere Dokumente können in den Text integriert werden.

    Siehe auch

    The Sphinx user documentation is a great place to deepend your knowledge and understanding of using rST with Sphinx. If you have any questions, you can also check out the Sphinx discussion group.

  • To-Do’s: für die aktuelle Liste offener Punkte

2.3. Konventionen

  • Jeder Abschnitt, der auf ein Navigationsmenu verweist, beschreibt den Pfad, z.B. Inhalt → Dateien. Am besten kopieren Sie den Pfeil.

  • Buttons wie Speichern oder Kopieren und die Portfolioauswahl wie Inhalt, Portfolio usw, werden im Text hervorgehoben mit Hilfe eines einzelnen ‚Sternchen‘ (‚*‘)

  • Kleine Buttons können direkt in eine Textzeile eingefügt werden wie edit oder manage. Sie werden über einen Texteintrag eingefügt und dann automatisch ersetzt. Die Ersetzungen werden in der Datei shortcuts.rstext eingetragen. Diese wird in jede Datei eingefügt, in der Ersetzungen vorkommen. Dazu wird „.. include:: /shortcuts.rstext“ in die erste Zeile der Datei eingefügt.Im Text werden die Ersetzungen wie folgt eingesetzt „*Edit* button |edit|“. Übersetzer lassen den Eintrag zwischen den vertikalen Strichen unübersetzt „|edit|“. Übersetzt wird nur „*Edit* button“. Achte darauf, das * stehen zu lassen und kein Leerzeichen zwischen dem * und dem Text zu lassen, damit eine Hervorhebung erfolgt.

  • Ein Index-Eintrag sollte für jeden Abschnitt erzeugt werden.

  • Neue Funktionen erhalten einen Indexeintrag in der Form „single: New in Mahara 1.x, [the functionality that is new]“.

  • Lange Abschnitte sollten auf mehrere Seiten verteilt werden. Die Bearbeitung wird damit leichter.

  • reStructuredText hat keine vordefinierte hierarchische Überschriftenstruktur. Sie werden in jeder Datei neu definiert. Um ein einheitliches Gestaltungsbild zu erzielen, werden folgende Vorgaben definiert:

    • Überschrift 1, z.B. 1.: ===============
    • Überschrift 2, z.B. 1.1.: —————
    • Überschrift 3, z.B. 1.1.1.: ~~~~~~~~~~~~~~~
    • Überschrift 4, z.B. 1.1.1.1.: ^^^^^^^^^^^^^^^

  • Weitere Überschriftenebenen nach h4 sollten unbedingt vermieden werden, da sie nicht mehr der Übersichtlichkeit dienen.

  • Die Index-Seite enthält keine weiteren Überschriften neben der Hauptüberschrift. Überschriften als Hervorhebungen werden nur durch ** fett gesetzt.

2.4. Textformatierung

  • Aufzählungslisten erhalten ein * als Symbol zu Beginn jedes Aufzählungspunkts
  • Nummerierte Listen beginnen mit einem #. als Start jedes nummerierten Eintrags.
  • Eine eingerückte Aufzählung (Nummerierung oder Aufzählungspunkt) beginnt mit einer Leerzeile. Danach wird jeder Aufzählungspunkt mit drei Leerzeichen begonnen. Am Ende folgt ebenfalls eine Leerzeile.
  • Hervorgehobener (kursiver) Text beginnt und endet mit einem * wie bei ‚‘hier‘‚. Angezeigt wird dann dies hier.
  • Fette Textelemente beginnen und enden mit zwei *, e.g. **this**. Es sieht dann wie folgt aus this.

2.6. Indexeinträge

Indexeinträge werden verwendet, um auf wichtige Inhalte direkt springen zu können. Einträge können für eine Überschrift oder im Text erstellt werden. Im Text ist anzugeben, wohin genau auf einer Textseite gesprungen werden soll.

  • Inline Indexeinträge können bespielsweise so aussehen: :index:`Ihr Profilbild <single: New in Mahara 1.10; Link to profile pictures page>`.

2.7. Übersetzer vermeiden

  • Ändere das Ziel zwischen den spitzen Klammern nicht. Falls dies passiert, kann die Referenz nicht gefunden werden. Ein erklärender Text steht vor den Klammern. Dieser kann angepasst werden.
  • In ähnlicher Weise kann der Text für eine URL, nicht aber die URL selber angepasst werden, es sei denn, Sie wollen die URL durch eine Adresse in der übersetzten Sprache ersetzen.
  • Achte darauf, beim Übersetzen der Grafiken und anderer Bilder die gleiche Verzeichnisstruktur zu verwenden, wie sie in Gitorious zu finden ist.
  • Die Original-Bilder des Handbuchs befinden sich im Ordner „images_original“ und den Unterverzeichnissen. Sie können für die Übersetzung verwandt werden. Der Bildhintergrund kann ausgetauscht werden. Die Call-Outs müssen bestehen bleiben.
  • Es ist nicht notwendig, alle Bilder auszutauschen. Bilder, die keine zu übersetzenden Inhalte enthalten können einfach ausgelassen werden. Sie werden dann aus der englischen Version übernommen.
  • Das Nutzerhandbuch wird einmal täglich aktualisiert. Vor der Erstellung des Handbuchs werden die neu übersetzten Strings von Launchpad geholt und in Git geladen. Gleiches erfolgt mit den Bildern.
  • Derzeit kann nicht alles in Sphinx übersetzt werden. Vermutlich kann dies mit einer späteren Version gelöst werden. Daher bleiben einige Elemente in der englischen Originalversion.

Bemerkung

Wenn Sie die Namen der Hauptübersetzer im Handbuch in Ihrer Sprache erwähnen möchten, können Sie einen entsprechenden Satz nach „The Mahara user manual is written by Mahara community members.“ einfügen. Der Abschnitt erscheint dann vor dem Inhaltsverzeichnis. In der englischen Version fehlt der Hinweis, da es sich nicht um eine Übersetzung handelt.