Commit 3eebb088 authored by Kristina Hoeppner's avatar Kristina Hoeppner

doc_info: Add info on languages that don't use spaces

parent 746bdb70
......@@ -5,9 +5,7 @@
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. ;-)
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.
The list is not in any particular order.
......@@ -121,6 +119,19 @@ Admonitions in use are
Conventions
--------------
.. note::
**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 *Content*, *Portfolio* etc. are highlighted as emphasized text (with a single \*).
* Little buttons can be included in the text like |edit|, |manage|. 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.
......@@ -129,6 +140,9 @@ Conventions
| ``:index:`Decide on the sort order <single: New in Mahara 18.10; Sort order of files in the "Folder" block>```
.. warning::
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 does not have a set hierarchy of heading levels. They depend on the individual files. However, to be consistent, the following convention exists:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment