Open Stack

On 08/26/2013 07:46 AM, Lorin Hochstein wrote:
> Andreas:
> 
> I think we should turn off individual file verification in validate.py,
> since we're now building the books as part of the validation process,
> and it seems to be giving us false positives.
> 
> I proposed the change here:  https://review.openstack.org/43696

+1

> David: 
> 
> The tools/validate.py script was checking against
> the http://www.oasis-open.org/docbook/xml/5.0b5/rng/docbookxi.rng Relax
> NG schema. Is this the right schema? Or is there one that's a closer
> match to what we are using for doc generation? Seems like this schema is
> stricter than the one that's actually being used by maven, which is
> causing false positives.

So in this case, it isn't differences in the schema that cause the
different validation results but the fact that validate.py validates
individual files while the maven build validates the entire book. The
deal is that the DocBook schema (for reasons that aren't clear to
me...I'll bring this up on the DocBook list) only allows certain
elements to be the root of a document. When the maven build validates,
it's essentially validating just the book xml AFTER xincludes have been
resolved, so it has no idea that some of the individual files are rooted
at the <table> element.

If we find we need to continue using validate.py, I can customize the
schema to be less constrained in what it allows at the root (it's an
easy change). I do plan to make this same change in the schema oXygen uses.

Currently the only differences between the straight DocBook schema and
the one the maven build uses is that the maven build also allows
elements from the wadl schema at certain places. For all but the api-ref
doc, this is immaterial for OpenStack. At Rackspace we include wadl in
more of our guides.

Regards,
David

> 
> Lorin
> 
> 
> 
> On Mon, Aug 26, 2013 at 8:26 AM, Andreas Jaeger <aj at suse.com
> <mailto:aj at suse.com>> wrote:
> 
>     Now I wonder why tools/validate does not like the new tables:
> 
>     /home/aj/Software/vcs/OpenStack/openstack-manuals/doc/src/docbkx/common/tables/swift-proxy-server-(app:proxy-server).xml:6:0:ERROR:RELAXNGV:RELAXNG_ERR_ELEMNAME:
>     Expecting element setindex, got para
>     /home/aj/Software/vcs/OpenStack/openstack-manuals/doc/src/docbkx/common/tables/swift-proxy-server-(app:proxy-server).xml:6:0:ERROR:RELAXNGV:RELAXNG_ERR_ELEMWRONG:
>     Did not expect element para there
>     /home/aj/Software/vcs/OpenStack/openstack-manuals/doc/src/docbkx/common/tables/swift-proxy-server-(app:proxy-server).xml:7:0:ERROR:RELAXNGV:RELAXNG_ERR_EXTRACONTENT:
>     Element para has extra content: table
>     /home/aj/Software/vcs/OpenStack/openstack-manuals/doc/src/docbkx/common/tables/swift-proxy-server-(app:proxy-server).xml:9:0:ERROR:RELAXNGV:RELAXNG_ERR_CONTENTVALID:
>     Element table failed to validate content
>     /home/aj/Software/vcs/OpenStack/openstack-manuals/doc/src/docbkx/common/tables/swift-proxy-server-(app:proxy-server).xml:8:0:ERROR:RELAXNGV:RELAXNG_ERR_EXTRACONTENT:
>     Element caption has extra content: literal
> 
>     Anybody has an idea?
> 
>     Andreas
>     --
>      Andreas Jaeger aj@{suse.com <http://suse.com>,opensuse.org
>     <http://opensuse.org>} Twitter/Identica: jaegerandi
>       SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>        GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg)
>         GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126
> 
>     _______________________________________________
>     Openstack-docs mailing list
>     Openstack-docs at lists.openstack.org
>     <mailto:Openstack-docs at lists.openstack.org>
>     http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> 
> 
> 
> 
> -- 
> Lorin Hochstein
> Lead Architect - Cloud Services
> Nimbis Services, Inc.
> www.nimbisservices.com <http://www.nimbisservices.com>