Code block in RST and translation
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#standa... [3] http://docs.openstack.org/contributor-guide/index.html#search-in-this-guide
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
On 25 Nov 2015, at 03:41, KATO Tomoyuki <tomo@dream.daynight.jp> wrote:
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 :)
Maybe we could add a gate check that looks for “::” in the end of the strings (original and translated)? It would enable developers to use whatever they are used to. Matjaz
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
_______________________________________________ OpenStack-docs mailing list OpenStack-docs@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
On 25 Nov 2015, at 03:41, KATO Tomoyuki <tomo@dream.daynight.jp> wrote:
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 :)
Maybe we could add a gate check that looks for “::” in the end of the strings (original and translated)? It would enable developers to use whatever they are used to.
Nice idea! Sounds good to me, as a non-vote job. Regards, KATO Tomoyuki
Matjaz
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
_______________________________________________ OpenStack-docs mailing list OpenStack-docs@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
On 2015-11-25 15:48, KATO Tomoyuki wrote:
On 25 Nov 2015, at 03:41, KATO Tomoyuki <tomo@dream.daynight.jp> wrote:
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 :)
Maybe we could add a gate check that looks for “::” in the end of the strings (original and translated)? It would enable developers to use whatever they are used to.
Nice idea! Sounds good to me, as a non-vote job.
Regards, KATO Tomoyuki
But who will monitor this and correct it? We already see warnings in translated code that everybody ignores, let's find a good way to monitor and fix these problems first before we add more tests... Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
On 2015-11-25 15:48, KATO Tomoyuki wrote:
On 25 Nov 2015, at 03:41, KATO Tomoyuki <tomo@dream.daynight.jp> wrote:
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 :)
Maybe we could add a gate check that looks for “::” in the end of the strings (original and translated)? It would enable developers to use whatever they are used to.
Nice idea! Sounds good to me, as a non-vote job.
Regards, KATO Tomoyuki
But who will monitor this and correct it?
We already see warnings in translated code that everybody ignores, let's find a good way to monitor and fix these problems first before we add more tests...
When I heard the idea, I thinked it's a job, like "checkniceness-2", that simply checks syntax of the code, not a job builds translated documents. So, the patch submitter and reviewers can easily check the result. For example, when FAIL(non-voting), Line xx: found the usge of :: directive, This style is harded for translators to traslate than code-block. We recommend use code-block directive instead of :: directive.... KATO
Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
Do we have an agreement? If so, we would like to change the corresponding section in the Documentation Contributor Guide [1]. BTW, why is '::' at the end of line called 'Standard literal block' and is 'code-block' directive called 'Non-Standard'? Is it because '::' is a common convention used in RST format and 'code-block' is from Sphinx? [1] http://docs.openstack.org/contributor-guide/rst-conv/source-code.html Akihiro 2015-11-26 7:31 GMT+09:00 KATO Tomoyuki <tomo@dream.daynight.jp>:
On 2015-11-25 15:48, KATO Tomoyuki wrote:
On 25 Nov 2015, at 03:41, KATO Tomoyuki <tomo@dream.daynight.jp> wrote:
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 :)
Maybe we could add a gate check that looks for “::” in the end of the strings (original and translated)? It would enable developers to use whatever they are used to.
Nice idea! Sounds good to me, as a non-vote job.
Regards, KATO Tomoyuki
But who will monitor this and correct it?
We already see warnings in translated code that everybody ignores, let's find a good way to monitor and fix these problems first before we add more tests...
When I heard the idea, I thinked it's a job, like "checkniceness-2", that simply checks syntax of the code, not a job builds translated documents. So, the patch submitter and reviewers can easily check the result.
For example, when FAIL(non-voting),
Line xx: found the usge of :: directive, This style is harded for translators to traslate than code-block. We recommend use code-block directive instead of :: directive....
KATO
Andreas -- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany GF: Felix Imendörffer, Jane Smithard, Graham Norton, HRB 21284 (AG Nürnberg) GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
_______________________________________________ Openstack-i18n mailing list Openstack-i18n@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n
participants (4)
-
Akihiro Motoki
-
Andreas Jaeger
-
KATO Tomoyuki
-
Pančur, Matjaž