Open Stack

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Hi Tanja,

Yes, I'm OK with this in this case. As far as the larger issue of vendor-specific requirements goes, though, while I think small changes like this are fine, I would probably not recommend larger-scale changes. Thanks for taking the time to explain :)

Cheers,
Lana

On 28/01/16 22:47, Kato, Tomoyuki wrote:
> Hi Tanja,
> 
> Thanks for clarification. I got the situation.
> 
> I guess this topic need more discussion from all.
> I'd like to work together from many verdors,
> and really appreciate contributions.
> On the other hand, I think it's subtle topic whether
> we accept the vendor-specific requirements or not.
> 
> I'm okay to add the explicite identifier as far as this topic.
> 
> Regards,
> KATO Tomoyuki
> 
>> Hi Kato,
>>
>> On 2016-01-28  9:37, Kato, Tomoyuki <kato.tomoyuki at jp.fujitsu.com>
>> wrote:
>>> Hi Tanja,
>>>
>>> Cloud you explain more detailed background?
>>> To be honest, I don't understand the reason as of now.
>>> Your explanation seems to be almost technical reason about Sphinx XML
>>> Builder. In my understand, however, we don't use and generate XML any
>>> more, with a few exceptions.
>>> Why do we need to convert RST to XML?
>>
>> No problem, I will try to clarify:
>>
>> You (the OpenStack project) don't need to use XML any more, but we
>> (SUSE doc team) contribute directly to the upstream manuals now and
>> include two of the upstream guides with a product of ours that is based
>> on OpenStack.
>>
>> (In the beginning, we wrote and maintained our own user manuals for
>> this product, but using the same license as the OpenStack project so you
>> (OpenStack) could take over and use any of the texts or the book
>> structure, which also happened).
>>
>> Our (SUSE) tool chain is largely based on DocBook XML (and we generate
>> 4 output formats for all of our product documentation). That's why we
>> use this conversion step from RST to DocBook now, which works fine
>> except for this one ID duplication that I explained below.
>>
>> Therefore the change proposed in $SUBJECT (which is hopefully not
>> intrusive for you) would simply make my life easier. :) But if it
>> should be declined, it's also fine with me, then I will fix it in our
>> generated XML sources.
>>
>> Thanks,
>> Tanja
>>
>>
>> On 2016-01-28  9:37 Kato, Tomoyuki <kato.tomoyuki at jp.fujitsu.com> wrote:
>>> Hi Tanja,
>>>
>>> Cloud you explain more detailed background?
>>> To be honest, I don't understand the reason as of now.
>>> Your explanation seems to be almost technical reason about Sphinx XML
>>> Builder. In my understand, however, we don't use and generate XML any
>>> more, with a few exceptions.
>>> Why do we need to convert RST to XML?
>>>
>>> Thanks,
>>> KATO Tomoyuki
>>>
>>>> Hi Darren, hi Kato, hi all,
>>>>
>>>> as the following might have exceeded the limits of the comments on
>>>> review.openstack.org, I thought I'd rather post it to this list.
>>>>
>>>> I'm contributing to the End User Guide and Admin User Guide and
>>>> we are generating XML from the RST sources (via Sphinx XML Builder)
>>>> and convert the resulting XML files to DocBook with a script.
>>>>
>>>> The Sphinx XML Builder automatically generates IDs for each section
>>>> title (in addition to any IDs that might be set in the RST files) and
>>>> derives the automatically generated IDs from the title. For example,
>>>> if the title is 'Attach a volume to an instance', the Sphinx XML
>>>> builder transform it to the following ID:
>>>> 'attach-a-volume-to-an-instance'.
>>>>
>>>> Due to the parallel structure of UI and CLI chapters in both user
>>>> guides, a lot of section titles appear twice, like for example
>>>> 'Attach a volume to an instance', which appears in both
>>>> 'cli_manage_volumes.rst' and 'dashboard_manage_volumes.rst' in the
>>>> End User Guide. (Let me add that our conversion script removes any
>>>> duplicate IDs from the resulting DocBook XML files _unless_ there is
>>>> a reference to a specific ID.)
>>>>
>>>> Now for the End User Guide, we stumbled across the following:
>>>>
>>>> There is a reference in 'cli_nova_launch_instance_from_volume.rst'
>>>> pointing to the section 'Attach a volume to an instance' in
>>>> 'cli_manage_volumes.rst', where the respective section has the
>>>> following ID in RST: '_Attach_a_volume_to_an_instance:'.
>>>>
>>>> As the Sphinx XML builder ignores case sensitivity and transforms
>>>> this ID to 'attach-a-volume-to-an-instance' (all lowercase!), we
>>>> ended up with exactly the same ID being generated by Sphinx XML
>>>> builder for the section in the *UI* chapter (which has no ID in the
>>>> RST files so far).
>>>>
>>>> And now DocBook has the same ID twice and cannot identify where the
>>>> reference (xref) contained in
>>>> 'cli_nova_launch_instance_from_volume.xml' should point to.
>>>>
>>>> To remedy this problem (without having to solve it manually each
>>>> time we update the guides from the RST sources), I proposed the
>>>> change request now under discussion in $SUBJECT.
>>>>
>>>> Alternatively, I could change the ID in 'cli_manage_volumes.rst' from
>>>> '_Attach_a_volume_to_an_instance:' to
>>>> '_attach_a_volume_to_an_instance_cli:' and change the reference in
>>>> 'cli_nova_launch_instance_from_volume.rst' accordingly, if you agree.
>>>> (But that seemed more intrusive to me, that's why I suggested the
>>>> change in https://review.openstack.org/273123 in the first place).
>>>>
>>>> BTW, we are developing and hosting the conversion script on GH - if
>>>> anyone here should be interested in the way back from RST to DocBook
>>>> for any reason, just let me know and I will post the link here. :)
>>>>
>>>> Kind regards,
>>>>
>>>> Tanja Roth, Documentation
>>>> SUSE Linux GmbH
>>>>
>>>> GF: Felix Imendörffer, Jane Smithard, Graham Norton
>>>> HRB 21284 (AG Nürnberg)
>>>>
>>>> _______________________________________________
>>>> OpenStack-docs mailing list
>>>> OpenStack-docs at lists.openstack.org
>>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>>> _______________________________________________
>>> OpenStack-docs mailing list
>>> OpenStack-docs at lists.openstack.org
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> 
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> 

- -- 
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
http://lanabrindley.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQEcBAEBCAAGBQJWqp6eAAoJELppzVb4+KUy2uwH/1ghP2DB6nRWYAHWCPnjbE9g
OGFzvKDh8UZ6pAsyCKTqPKOfDsVUeg6ScR5DToHnpOTMHyFTxiyRqXups/feGr1y
UT4TrK3i9rMNamU+L+5LutkWsL5I6yVXhi5yTWvpLrOVUMdJBTwRQXn1VqSAqQjG
oGhgnRQ12y3z5FphEXPvoUZo3X6L9WCLJoraNWZvfsvIEg2WZdmOTU9SmfRN09hh
v6/O4xTp5MfgqCIC/BMI9xjq/+1sTRbV5ARF3yNK5gSusJnjjO46J73vg7Uvj+bL
66IoIL6/oyh+/F5D/BEcFYW+IWm+Gc1vD7xN7/t+m3zVsbRh5FzU1CVyL4k9koI=
=ySDo
-----END PGP SIGNATURE-----