Open Stack

Based on experience with the installation and networking guides that
contain a variety of these blocks, using :: instead of an explicit
code-block tends to cause strange rendering issues with certain content.

On Fri, Nov 27, 2015 at 8:38 AM, Akihiro Motoki <amotoki at gmail.com> wrote:

> 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 at dream.daynight.jp>:
> >> On 2015-11-25 15:48, KATO Tomoyuki wrote:
> >> >>
> >> >>> On 25 Nov 2015, at 03:41, KATO Tomoyuki <tomo at 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 at lists.openstack.org
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-i18n
> >
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20151127/a694d344/attachment.html>