Open Stack

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