Open Stack

> 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#standard-literal-block
> [3] http://docs.openstack.org/contributor-guide/index.html#search-in-this-guide