2. Information for Mahara manual writers and translators

This is a list in progress. There are a number of things for which conventions were created. Here is the central space to keep them so that everyone has access to them.

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

2.1. Install Sphinx

The Mahara manual requires that Sphinx is installed on your computer. You can find information on how to install Sphinx on the Sphinx website.

The following instructions are for Debian / Ubuntu based systems and require that you work in the terminal.

1. Install the Python virtual environment: sudo apt-get install python-virtualenv

2. If you also want to generate PDFs, you will need to install all the LaTeX dependencies: sudo apt-get install texlive-xetex texlive-lang-all texlive-fonts-extra

3. Create a folder on your computer (if you don’t already have one) where you place git repositories, e.g. code.

4. In the terminal, enter the folder „code“: cd code

5. Do a checkout of the code for the manual:

   • via SSH: git clone git@git.mahara.org:user-manual/manual.git OR

   • via HTTS: git clone https://git.mahara.org/user-manual/manual.git

6. In the terminal, enter the folder „manual“: cd manual

7. Install the virtual environment for this folder: virtualenv venv

8. Activate the virtual environment: . venv/bin/activate

9. Install all requirements: pip install -r requirements.txt

10. Build the manual in HTML: make html

    Bemerkung

    This will create all translations that are available for the manual and will take a bit. If you only want to create the English manual, you can compile it with make preview MAHARA=18.10

    If you want to compile a PDF, you can do so via make latexpdf

11. Open the index.html file in a browser to view the manual. You can find it in the folder build/en/18.10.

12. Once you are done editing the manual, you can deactivate the virtual environment by typing deactivate in the terminal.

2.2. Make changes to the manual

Once you installed the manual on your computer, you can make changes. The following actions are performed in the terminal.

1. Enter your manual folder: cd code/manual

2. Start the virtual environment so you can compile the manual using Sphinx: . venv/bin/activate

3. Now make any changes in your preferred editor.

4. Compile a preview of the manual just in English: make preview MAHARA=18.10

   Bemerkung

   Change the version number depending on the version of Mahara that you are compiling.

5. Deactivate the virtual environment once you are done editing: deactivate

2.3. Bildschirmfotos

• werden über die Bild-Anweisung (‚figure‘) eingebunden

• always include alt text and a figure description. That sets them apart from the text.

• 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.

• get callouts that are pre-made and can be found in the Gimp file /images_originals/z_callouts.xcf.

• only get an arrow if an item is to be pointed out but there are no steps involved. The arrow can be found in the file /images_originals/z_arrow.png.

• 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.

Most screenshots are added with the figure directive.

Beispiel zum Einbinden eines Screenshots

1. The first line provides the path to the file.

   Bemerkung

   The * replaces the file extension and Sphinx chooses the file that is most appropriate. Thus, files could have different image extensions, or you could have the same screenshots in different file formats that are then chosen by the programme to best suit the end format of the manual.

   For the Mahara manual we use .png files in general as we work with screenshots. It is still good to use the * instead of the .png extension in case the file format is changed at some point.

2. The second line represents the alt text that is displayed when hovering over the image, when no images are displayed or when viewing the page via a screen reader.

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 /images_originals/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

If you want to include an image inline with the text and don’t want to or can’t use the regular figure, you should create a substitution and place it into the shortcuts.rstext file. There are plenty of examples in that shortcuts file already.

2.4. 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.

todo: for keeping a running ToDo list. ToDo lists are currently disabled.

2.5. Konventionen

Bemerkung

Languages that do not use spaces between words

Sphinx assumes that there is always a space before a command starts and after one ends. That is the only way that it has to recognize the markup characters as ones that tell Sphinx what to do.

This poses a problem in languages such as Japanese as there are no spaces between words.

You do need to put spaces into the text though. Otherwise, formatting won’t happen, index entries won’t get created, and substitutions are not done. Thus, replicate the spacing that you see in the English version. For example, put a space:

• before and after a substitution such as |edit|,

• before :index: and :ref: and when the index entry or reference ends.

• before * when it is followed by a word and after the closing *, e.g. *word* because that indicates that the formatting is changed to word. The same goes for words that begin and end with **.

• Each section that is related to a navigation menu item should have the path listed, e.g. Main menu → Create → Files. It is best if you copy the arrow to get the correct one.

• Buttons such as Save or Copy page and also portfolio sections such as Create, Share etc. are highlighted as emphasized text (with a single *).

• Kleine Buttons können direkt in eine Textzeile eingefügt werden wie oder . 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.

• New features receive an index entry as well in the form „single: New in Mahara x, [the functionality that is new]“. Index entries can be placed either above an entire section or inline. Inline is preferable for small functional changes so that readers are directly taken to the new functionality. This can be done like so:

  :index:`Decide on the sort order <single: New in Mahara 19.04; Sort order of files in the "Folder" block>`

  Warnung

  If there is not a punctuation mark just before „:index:“ and/or after „>`“, you have to insert a space just before „:index:“ and/or after „>`“.

• Long sections like the administration are broken up into several pages to make the editing more manageable instead of having everything on one very long page.

• 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.6. 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.7. Hyperlinks

• Externe Links: „`[VerlinkterText] <URL>`_“ - Übersetzt wird nur der Text zwischen den eckigen Klammern „[Verlinkter Text]“. Der Text in spitzen Klammern wird durch den URL-Pfad ersetzt.

• Interne Referenzen auf die von überall im Handbuch verwiesen werden kann werden durch „.. [reference_text]:“ in einer Zeile vor einer Überschrift erzeugt. Zwischen der Referenz und der Überschrift setzte ich in der Regel eine Leerzeile.

• Link auf eine interne Referenz: „:ref:`[text that is linked] <the internal reference>`“ - Übersetzt wird nur der Text in den eckigen Klammern „[text that is linked]“.

• Das ` ist ein Apostroph und nicht ein einfaches Anführungszeichen.

• An in-text target can be achieved by placing the text to be linked within accent marks preceded by an underscrore: _`the internal reference`. Referencing is the usual :ref:`[text that is linked] <the internal reference>`.

2.8. Ü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.

• If you translate the screenshots and other images, please ensure that you keep the folder structure of the „images“ folder as you can see in the respective branch of the manual version you are editing in Git, for example for Mahara 18.10.

• 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.

• The manual is updated once a day and new translation strings pulled in from Launchpad and images uploaded to Git prior to the compilation of the manual if there are any changes.

Bemerkung

If you want to mention the names of the main translators of the manual for your language, you can add a sentence right after „The Mahara manual is written by Mahara community members.“ That paragraph appears before the table of contents. There is no equivalent sentence in the English manual because it is not a translation.