Open Stack

> There are already quite a few tutorials on RST, perhaps it's better to
reference these instead of writing a new one?

To me, an absolute newcomer, the overview on the Sphinx web site and the
markup conventions page in the wiki
(https://wiki.openstack.org/wiki/Documentation/Markup_conventions) were
sufficient to understand RST.

What might be useful is a pocket reference of those RST markups that we want
to use in our docs, perhaps added to the wiki page.

Bernd

-----Original Message-----
From: Andreas Jaeger [mailto:aj at suse.com] 
Sent: Friday, April 10, 2015 6:36 PM
To: Ying Chun Guo
Cc: openstack-i18n at lists.openstack.org; openstack-docs at lists.openstack.org
Subject: Re: [OpenStack-docs] [Openstack-i18n] Status of the RST
Documentation Toolchain

On 04/10/2015 11:04 AM, Ying Chun Guo wrote:
> Here are my thoughts.
>
> 1. I would like the toolchain could be extendable for the future 
> improvement.
> If we are able to make small and easy improvements before publishing, 
> like handling double stars and double colons (described in [1]), let's 
> do that.
> In the future, let's continue the improvement. The goal is to provide 
> an easily understandable source strings for translators.

I don't have a good idea how to convert transformations back like stars and
double colons. If anybody comes up with commands on how to do it, I'll
happily integrate them into the toolchain.

> 2. I would like the translators to be well educated about the RST markups.
> I will covert [2] into translators' view.
> ( I don't think translators would read through this long document to 
> pick out RST markups. ) Clearly list RST markups, give samples, and 
> describe the meanings.
> Thus the translators could easily understand which words and 
> punctuation characters should not be translated and need to keep them 
> unchanged carefully.



> 3. Next Thursday, I will have the team meeting with the translators. I
will
> collect their feedback to these RST markups.
>
> @ Andreas and Anne, let me know your feeling tho these thoughts.

Andreas

>
> Daisy
>
> [1]
> http://lists.openstack.org/pipermail/openstack-i18n/2015-April/001030.html
> [2] https://wiki.openstack.org/wiki/Documentation/Markup_conventions
>
> Andreas Jaeger <aj at suse.com> wrote on 2015/04/10 12:38:21:
>
>  > From: Andreas Jaeger <aj at suse.com>
>  > To: Ying Chun Guo/China/IBM at IBMCN
>  > Cc: "openstack-i18n at lists.openstack.org" <openstack-
>  > i18n at lists.openstack.org>, "openstack-docs at lists.openstack.org"
>  > <openstack-docs at lists.openstack.org>
>  > Date: 2015/04/10 12:38
>  > Subject: Re: [OpenStack-docs] [Openstack-i18n] Status of the RST
>  > Documentation Toolchain
>  >
>  > On 04/09/2015 02:16 PM, Ying Chun Guo wrote:
>  > > [...]
>  > > I investigated the translation process of RST document, asked by Anne
>  > > and Andreas.
>  > > While I made test, I used playground-user-guide, which was a quite
new
>  > > document.
>  > > I didn't pay attention to the pot content changes between the old
>  > > version and the new version.
>  > > I'm quite sorry for that.
>  > > I don't want to block anything.
>  > > In my mind, the toolchain could be improved continuously,
>  > > both before publication and after publication.
>  >
>  > With the analysis done by Daisy [1] (thanks!) and my scripted updates
to
>  > convert automatically what was possible [2] thus raising the number of
>  > translated strings for Japanese on the User Guides from 32 % to 37 %,
>  > and my patch for building the Japanese tools we have IMHO done
>  > everything we can do.
>  >
>  > Or has anybody suggestions for additional things to do now?
>  >
>  > If not, I think we're good to publish the new RST User Guides.
>  >
>  > So, I propose these next steps:
>  > * Get explicit ok by Daisy that we can continue based on her findings
>  > * Review and merge patch [3]
>  > * Anne decides when to publish User Guides
>  >
>  > Andreas
>  >
>  > [1]
>  >
> http://lists.openstack.org/pipermail/openstack-i18n/2015-April/001030.html
>  > [2]
>  >
> http://lists.openstack.org/pipermail/openstack-i18n/2015-April/001034.html
>  > [3] https://review.openstack.org/162424
>  > --
>  >   Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica:
jaegerandi
>  >    SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>  >     GF: Felix Imendörffer, Jane Smithard, Jennifer Guild, Dilip
Upmanyu,
>  >         Graham Norton, HRB 21284 (AG Nürnberg)
>  >      GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272
A126
>  >
>


-- 
  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
    GF: Felix Imendörffer, Jane Smithard, Jennifer Guild, Dilip Upmanyu,
        Graham Norton, HRB 21284 (AG Nürnberg)
     GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126


_______________________________________________
OpenStack-docs mailing list
OpenStack-docs at lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs