Open Stack

Hi Lana, hi Kato, hi all,

On 2016-01-29  9:05 Lana Brindley <openstack at lanabrindley.com> wrote:
>-----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. 

Yep, I know about the OpenStack rationale regarding vendor-specific
changes and I fully understand the reasons behind it.  

>Thanks for taking the time to explain :)

Np, thanks for accepting the ID change :)

Have a good week-end everyone,

Cheers,
Tanja

>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-----
>
>_______________________________________________
>OpenStack-docs mailing list
>OpenStack-docs at lists.openstack.org
>http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs