[OpenStack-docs] Code block in RST and translation

Akihiro Motoki amotoki at gmail.com
Sat Nov 21 12:24:54 UTC 2015


Hi,

According to [1], we use two types of code blocks in RST documentations.
The one is to end a line with "::" [2] and the other is to use 'code-block'.

During translation, I noticed the first style can be a wrong
formatting in translated documents
(it will be considered as "block quote" as far as I tested).

It is not easy that translators understand "::" at end of line has a
special meaning.
To keep the format, translators MUST keep "::" at the end of line, but
":" is rarely used in some languages and I think they will forget "::" easily.
In addition, it is hard to detect this kind of things during
translation reviews.

Note that other RST conventions are easier to be recognized as special
because they are very different from usual strings.

On the other hand, ending a line with "::" is a standard ReST convention
and it is widely used in writing documents in ReST format.

My idea at now is to use "code-block" directive as possible as we can,
but I am not sure it is the right direction as "::" is widely used.

Thought?

Thanks,
Akihiro

[1] http://docs.openstack.org/contributor-guide/rst-conv/source-code.html
[2] http://docs.openstack.org/contributor-guide/rst-conv/source-code.html#standard-literal-block
[3] http://docs.openstack.org/contributor-guide/index.html#search-in-this-guide



More information about the OpenStack-docs mailing list