[Openstack-i18n] Code block in RST and translation
tomo at dream.daynight.jp
Wed Nov 25 02:41:39 UTC 2015
> According to , we use two types of code blocks in RST documentations.
> The one is to end a line with "::"  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 :)
>  http://docs.openstack.org/contributor-guide/rst-conv/source-code.html
>  http://docs.openstack.org/contributor-guide/rst-conv/source-code.html#standard-literal-block
>  http://docs.openstack.org/contributor-guide/index.html#search-in-this-guide
More information about the Openstack-i18n