2. Informatie voor schrijvers van de Mahara handleiding en vertalers

Door Kristine D.C. Hoeppner

Dit is een lijst die wijzigt tijdens het werken aan de handleiding. Er zijn een aantal conventies. De conventies worden hier centraal bewaard, zodat anderen ze kunnen zien en zodat ik er kan naar verwijzen ;-)

Deze lijst staat niet in een bepaalde volgorde.

2.1. Schermafdrukken

• worden geplaatst door gebruik te maken van het label “figure”.
• gebruik altijd alt-teksten en een afbeeldingsbeschrijving. Die zullen genummerd worden in de PDF-export, wat hen onderscheidt van de teksten.
• worden meestal geplaatst boven een lijst als ze deel zijn van stap voor stap-instructies.
• zouden zo weinig mogelijk instructies moeten bevatten over de stappen die er voor moeten genomen worden. Bij voorkeur enkel de stapnummers, zodat ze gemakkelijk uitgewisseld en vertaald kunnen worden vermits de tekst dan geen deel is van de afbeelding. Dat kan ook betekenen dat de vertalers de stappen kunnen vertalen en niet onmiddellijk de afbeeldingen moeten vervangen.
• get callouts that are created in Gimp with the script that Iñaki adapted.
• hebben tekstballonnetjes die refereren naar de stappen die genomen moeten worden en die onder de figuur uitgelegd worden.
• zou enkel de nodige zone mogen tonen en niet het hele scherm, de URL, knoppenbalken en dergelijke.

De meeste screenshots worden toegevoegd met het figure directief

Example of including a screenshot

1. De eerste lijn geeft het pad naar het bestand. De * vervangt de bestandsextentie en Sphinx kiest het bestand dat het meest geschikt is. Daarom kunnen bestanden verschillende extenties hebben of je kunt hetzelfde screenshot in verschillende bestandsopmaken voorzien, waarbij het programma dan de meest geschikte opmaak kiest voor het uiteindelijk formaat van de handleiding.
2. De tweede regel geeft de alt-tekst die getoond wordt wanneer je de muisaanwijzer over een afbeelding schuift, wanneer er geen afbeelding getoond wordt of wanneer de pagina met een schermlezer bekeken wordt.
3. De derde regel moet na een lege regel komen. Dit is de tekst die getoond wordt onder het screenshot als afbeeldingsbeschrijving. In de PDF worden de beschrijvingen doorlopend genummerd.

Notitie

Als je een afbeeling inline met de tekst wil zetten en je kunt of wil het standaard figure niet gebruiken, dat moet je een vervanging maken en die zetten in het shortcuts.rstext-bestand.

2.2. Gebruikte waarschuwingen zijn

• note: voor alles wat wat meer aandacht nodig heeft

  Notitie

  Notes can be placed directly within a bulleted list. As usual, an empty line before and after the note must be placed and the admonition must be indented by 3 spaces.

• warning: voor alles wat voorzichtig moet gebeuren

  Waarschuwing

  Try not to put everything into an admonition because then the truly important information is lost.

• seealso: voor referenties naar andere documenten als daar speciale aandacht voor nodig is. referneties naar andere documenten kunnen ook in de tekst inline opgenomen worden.

  Zie ook

  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: om een lopende ToDo-lijst bij te houden

2.3. Conventies

• Elke sectie die met het navigatiemenu te maken heeft, zou het pad moeten tonen, vb Inhoud → Bestanden. Je kunt best te pijl kopiëren om de juiste te hebben.

• Knoppen zoals * Bewaar* of Kopieer pagina en ook portfoliosecties zoals Inhoud; Portfolio enz worden benadrukt als vette tekst (met een enkele *).

• Little buttons can be included in the text like , . They are added through a substitution. All replacements are kept in the file shortcuts.rstext which is included in each file in which a substitution is used by placing “.. include:: /shortcuts.rstext” in the first line of the file. Substitutions are referenced in the text as “*Edit* button |edit|” for example pointing out what the action is that you do with them. Translators should not edit the substitution “|edit|” itself, but only change “*Edit* button” taking care to include the * again without placing any spaces between the * and the text to ensure that the word appears highlighted.

• Er moet een indexverwijzing gemaakt worden voor elke sectie.

• New features receive an index entry as well in the form “single: New in Mahara 1.x, [the functionality that is new]”.

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

• reStructuredText heeft geen hiërarchische set voor hoofding. Ze hangen af van de individuele bestanden. Om consistent te zijn, bestaat volgende afspraak:

  • Hoofding 1, vb. 1.: ===============
  • Hoofding 2, vb. 1.1.: —————
  • Hoofding 3, vb. 1.1.1.: ~~~~~~~~~~~~~~~
  • Hoofding 4, vb. 1.1.1.1.: ^^^^^^^^^^^^^^^

• Hoofdingen kleiner dan h4 moeten vermeden worden.

• The index page does not have headings besides the main heading. That prevents the table of contents and the other sections that have headings to be the main chapters of the manual. Keep index page headings to just bold with **.

2.4. In-text opmaak

• Ongenummerde lijsten krijgen een * als symbool om elk bolletje te beginnen.
• Genummerde lijsten krijgen # om elk genummerd item mee te beginnen.
• Als je lijst moet inspringen, zet dan een lege regel voor de inspringende lijst en laat elke regel met 3 spaties inspringen. Er moet ook een lege regel zijn aan het einde van de inspringende lijst.
• Benadrukte tekst begint en eindigt met 1 *, vb. *dit*. Het zal er uitzien als dit.
• Bold text starts and ends with 2 *, e.g. **this**. It will then look like this.

2.5. Hyperlinks

• Externe links: “`[gelinkte tekst] <URL>`_” - Vertalers moeten enkel de “[gelinkte tekst]” vervangen.
• Internal references to which can be linked from elsewhere in the manual are created by placing “.. [reference_text]:” in a line right before a heading. I usually leave an empty line between the reference and the heading.
• Linken naar een interne verwijzing: “:ref:`[gelinkte tekst] <de interne verwijzing>`” - Vertalers mogen enkel “[gelinkte tekst]” vervangen.
• Het ` is een accent en geen recht enkel aanhalingsteken.

2.6. Translators beware

• Do not change the target for internal links that is placed between < >. If you do, the reference cannot be found. There should always be an explanatory text right before the pointy brackets. You can change that.
• Similarly, you can change the text for a URL but not the URL itself unless you want to replace it with a URL to a site in your language.
• 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 on Gitorious.
• You can find original images used for the manual in the folder “images_original” and then their respective subfolders. You can use them for your own translations if you only want to exchange the background but keep the callouts.
• You do not have to redo any images that you do not “translate”, e.g. block icons, general buttons around Mahara and the text editor buttons. Any images that are not in your translation will be taken from the English original.
• The user 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.
• Currently, not everything can be translated in Sphinx. Hopefully, later versions will fix that.

Notitie

If you want to mention the names of the main translators of the user manual for your language, you can add a sentence right after “The Mahara user 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.