2. Information for Mahara user manual writers and translators

by Kristina D.C. Hoeppner

This is a list in progress as I work on the user manual. There are a number of things for which I created conventions. I want to keep them in a central space so that others have access to them and that I can refer to them as well. ;-)

The list is not in any particular order.

2.1. Install Sphinx

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

2.2. Getting the code

The code for the Mahara user manual is managed in git.

  1. Create a folder on your computer (if you don’t already) where you place git repositories, e.g. code.
  2. In the terminal, enter the folder “code”: cd code
  3. Do a checkout of the code:
    • 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
  4. In the terminal, enter the folder “manual”: cd manual
  5. Compile the user manual in English only. The following command assumes that you want to compile it for Mahara 15.10: make preview MAHARA=15.10
  6. Open the index.html file in a browser to view the manual. You can find it in the folder build/en/15.10.

2.3. Screenshots

  • are placed using the “figure” directive.
  • always include alt text and a figure description. That sets them apart from the text.
  • are generally placed above a list if they are part of step-by-step instructions.
  • should have as few instructions as possible about the steps that are to be taken in them. Preferably, only the step numbers so that they can be exchanged more easily and the text of the steps is translatable because it is text and not part of the image. That could also mean that translators can translate the steps but don’t immediately have to change the screenshots.
  • 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.
  • that have callouts refer to the steps that need to be taken and that are explained below the figure.
  • should only show the necessary area and not the entire screen or URL address bars etc. where not necessary.

Most screenshots are added with the figure directive.

Example of including a screenshot

Example of including a screenshot

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

    Note

    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 user 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. The third line must follow an empty line. This is the text that is displayed below the screenshot as figure description. In the PDF output, the descriptions will be numbered continuously.

  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 (but depends on how wide the screenshot is)
    • Tick for Stroke path
    • Stroke color: CCCCCC

Note

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. Admonitions in use are

  • note: for anything that should receive a bit more attention

    Note

    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: for anything that needs to be done with caution

    Warning

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

  • seealso: for references to other documents if they need special attention. References to other documents can also be included in the text inline.

    See also

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

  • Each section that is related to a navigation menu item should have the path listed, e.g. Content → 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 Content, Portfolio etc. are highlighted as emphasized text (with a single *).

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

  • An index entry should be created for each section.

  • 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 15.04; Sort order of files in the "Folder" block>`

  • 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 does not have a set hierarchy of heading levels. They depend on the individual files. However, to be consistent, the following convention exists:

    • Heading 1, e.g. 1.: ===============
    • Heading 2, e.g. 1.1.: —————
    • Heading 3, e.g. 1.1.1.: ~~~~~~~~~~~~~~~
    • Heading 4, e.g. 1.1.1.1.: ^^^^^^^^^^^^^^^

  • Headings below h4 should be avoided.

  • 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.6. In-text formatting

  • Bulletted lists have * as symbol to start each bullet point.
  • Numbered lists have #. to start each numbered item.
  • If you require an indented bulleted or numbered list, place a free line before the indented list and then indent each line with 3 spaces. There also needs to be an empty line when the indented list ends.
  • Emphasized text starts and ends with 1 *, e.g. *this*. It will then look like this.
  • Bold text starts and ends with 2 *, e.g. **this**. It will then look like this.

2.8. 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 in Git, for example for Mahara 15.10.
  • 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.

Note

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.