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.
I completely agree.
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,
As far as I know, docs team guides mainly use "code-block". So, I'm okay to unify to "code-block" directive.
but I am not sure it is the right direction as "::" is widely used.
In my understand, most of developers like "::", which is simple RST format :)
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#standa... [3] http://docs.openstack.org/contributor-guide/index.html#search-in-this-guide