Open Stack

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