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.
  • new in Mahara 1.6 get callouts worden gemaakt in Gimp met het script door Iñaki aangepast.
  • 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

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
  • warning: voor alles wat voorzichtig moet gebeuren
  • 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.
  • 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 *).

  • Er kunnen kleine knopjes in de tekst gezet worden, zoals edit, manage. Ze worden toegevoegd door vervanging. Alle vervangingen worden bijgehouden in het bestand shortcuts.rstext dat in elk bestand wordt toegevoegd waarin een vervanging is gebeurd door gebruik te maken van “.. include:: /shortcuts.rstext” in de eerste regel van het bestand. De referenties naar vervangingen kun je in de tekst terugvinden bijvoorbeeld als “*Edit* button |edit|” en tonen wat de actie is die je ermee wil doen. Vertalers mogen de vervanging zelf “|edit|” niet bewerken, maar enkel de “*Edit* knop” en er op letten om de * terug te plaatsen zonder spaties tussen de * en de tekst.

  • Er moet een indexverwijzing gemaakt worden voor elke sectie.

  • Nieuwe functies worden in de index opgenomen en krijgen de vorm “single: New in Mahara 1.6; [the functionality that is new]”.

  • Lange secties moeten verdeeld worden over meerdere pagina’s om het bewerken meer beheersbaar te maken.

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

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.
  • Vette tekst begint en eindigt met 2 **, vb. **dit**. Het zal er uitzien als dit.