Open Stack

Sounds like a great addition. 

~sean

On Jul 18, 2013, at 5:04 PM, "David Cramer" <david.cramer at rackspace.com> wrote:

> On 07/18/2013 05:43 PM, Denis Bradford wrote:
>> While you're brainstorming, I'm curious why we don't use olinks, since
>> it's designed to handle cross-document references like this.
> 
> Funny you should mention that :-) It's next on my list and I've been
> trying to get to it all summer, but one thing or another keeps coming
> up. It's still a high priority for me though.
> 
> As I understand it, olinks would not have changed anything in this case
> however. The document would have passed the gate job (which effectively
> would no longer check links at all), but still failed in the maven
> plugin since the target would be missing.
> 
> What happened here is the system worked and prevented a mistake by
> alerting us to a real problem.
> 
> The way I intend to implement olinks is that a preprocessing step will
> first check to see if the olink is to a target in the current book. If
> that's the case, I'll convert it to an xref (or link if the link text is
> set). If not, then I'll let normal olink processing happen based on an
> olink db generated at build time.
> 
> So olinks will give us two things:
> 
> 1. An easy way to insert cross references for Oxygen users since Oxygen
> can read an olink db and present the writer with a toc of things to link
> to (i.e. a toc of the _titles_ of potential targets). The writer can
> enter some text in the filter field an see a subset of things to link
> to. By selecting an item and clicking OK, the appropriate markup is entered.
> 
> 2. The ability to link to a section in a different document with the
> link text generated at build time.
> 
> David
> 
>> 
>> On Thu, Jul 18, 2013 at 4:22 PM, David Cramer
>> <david.cramer at rackspace.com> wrote:
>>> On 07/18/2013 03:08 PM, Lorin Hochstein wrote:
>>>> David:
>>>> 
>>>> Yes, the validation script are only looking at individual files right
>>>> now, which is why they don't catch missing cross-references.
>>>> 
>>>> I agree that maven would be better for gating. But maven isn't currently
>>>> gating, is it?
>>> 
>>> Now that I think of it more, Maven is the only thing that can really
>>> validate this because you might have a file that's valid on the file
>>> system but invalid after profiling:
>>> 
>>> Say you have <section xml:id="foo" condition="rhel">...</section> and
>>> elsewhere <xref linkend="foo"/>. When you build validate with your
>>> script, all is well because the IDREF linkend="foo" matches
>>> xml:id="foo", but if you build with profileCondition=ubuntu, that
>>> section is removed and you have a broken link.
>>> 
>>> The build will blow up if there's an IDREF without a matching ID in the
>>> document UNLESS failOnValidationError=no.
>>> 
>>> As of 1.6.x, Maven validates the doc twice: first after resolving
>>> xincludes it validates without checking IDREFs, then again towards the
>>> end after all profiling etc, it checks IDREFs as well. This is to catch
>>> the situation where the doc was valid but was made invalid by filtering
>>> out content. In 1.8.0, I give you a more helpful error message that
>>> suggests opening an intermediate file in the target dir and validating
>>> it so you can see the actual error (line numbers are meaningless since
>>> the original source file has been manipulated by resolving xincludes etc).
>>> 
>>> Does that make sense?
>>> 
>>> If leaving the failOnValidationError=no door available is a bad thing, I
>>> could easily make it so failOnValidationError is ignored if
>>> branding=openstack. Or perhaps Jenkins could pass in
>>> failOnValidationError=yes, which would override what's in the pom (or
>>> some other trick to make sure Jenkins never builds something where
>>> validation doesn't kill the build).
>>> 
>>> David
>>> 
>>> _______________________________________________
>>> 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