Re: [docbook-tc] testing xinclude in assembly

[Bob Stayton <bobs@sagehill.net>]

Hi Larry,

Thanks for this. I tested your example, and it validates. I also created my own small assembly XIncluding the resources element, with actual files to pull in, and it validates and reassembles as expected. Good work.

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net

On 2/12/2019 8:31 PM, Larry Rowland wrote:

This has certainly been an instructive exercise. Â I have not worked with documentation for long enough that Iâm rusty on how modern tools like master files work in an editor like oXygen. ÂAttached please find a ZIP file with the following in it:

-rwxr-x---@ 1 lrr staff  9880 Feb 12 21:07 assembly-with-xinclude-2.xml

-rwxr-x---@ 1 lrr staff  17606 Feb 12 14:03 assembly-without-xinclude-2.xml

-rw-rw-r--@ 1 lrr staff 625363 Feb 12 20:35 assembly.rng

-rw-rw-r--@ 1 lrr staff 649396 Feb 12 20:55 assemblyxi.rng

-rw-r--r--@ 1 lrr staff  1169 Feb 12 21:00 creation-chapter-module.xml

-rw-r--r--@ 1 lrr staff  6780 Feb 12 20:32 helpsystem-structure.xml

-rw-r--r--@ 1 lrr staff  1682 Feb 12 20:32 resource-block.xml

-rw-r--r-- 1 lrr staff   834 Feb 12 19:53 xinclude-assembly.xpr

The assembly files are referenced byÂassembly-with-xinclude-2.xmlÂandÂassembly-without-xinclude-2.xml. ÂI have added one element to the start definition in assembly.rng to allow a module as root of a file and modified assemblyxi.rng to allow xi:include in various places (mostly the direct descendants of the assembly, but also for external references to a module). ÂI also made all of the DocBook elements that allow xi:include allow it in this file.

The three files resource-block.xml, helpsystem-structure.xml and creation-chapeter-module.xml are portions of the original file I moved into eternal files and referenced via xi:include.

In order to make things validate in oXygen, two things have to be done:

1. Turn on Enable Xinclude Parsing under Preferences->XML->XML Parser.Â
2. Enable Master file processing from the Project menu. ÂOnce it is enabled, a Master Files folder shows up in the project view and you can create a link into it by dragging the assembly-with-xinclude-2.xml file into it (the file is linked rather than moved).

Not sure how to do the same things in other editors, but doing this allows validation in any of the files that are included into the master file.

This is NOT buildable since the referenced resources are not included (not sure they were ever created) but it is valid and demonstrates that it works with modern validation schemes thatÂunderstandÂthe master file model.

Sorry for the confusionÂâ not sure how I ended up with an early version of the assembly schema as the starting point for this, but this round was done based onÂV5.2b05Âand should be reasonable.

If this bounces from the mailing list since I am mailing it from home, Iâll resend it tomorrow morning from work.

Regards,

Larry Rowland

On Feb 12, 2019, at 4:01 PM, Rowland, Larry <larry.rowland@hpe.com> wrote:

I hate to admit this, but it appears I combined an early proposal of the assembly schema (that still allowed Âfileref attributes instead of using href and other things that were not implemented) with parts of the 5.1 and 5.2 versions of the DocBook schema. Itâs not really worth trying to get thigns working based on the schema I sent. Donât know how that happened, but as I was trying to work through things, it became obvious that things were just wrong. I am pulling down a clean copy of the V5.2b05 release of the schema and will redo things to get a clean schema based on the current working schema. My working model is going to be:

Â

1.ÂÂÂÂÂÂAdd the modifications for xi:include to assembly.rng to create a new assemblyxi.rng.

2.ÂÂÂÂÂÂModify the old assembly-sample-6.xml (renaming it) to make it validate against the existing assembly schema.

3.ÂÂÂÂÂÂBreak it up into chunks in other files and reference them using the xi:include to create a new version of the file with includes at various levels to reflect the discussion atÂhttps://github.com/docbook/docbook/issues/54.

Â

I apologize for the confusion. I worked on this part of last night and parts of today trying to understand what was happening and why it was so confusing and it took most of that to figure out what was going on. I also realized I made a mistake in the assembly extension when I copied how include was implemented in other areas of DocBook and will fix that problem. ÂIâll get this to the team as soon as possible.

Â

Regards,

Larry Rowland

From:Âdocbook-tc@lists.oasis-open.orgÂ[mailto:docbook-tc@lists.oasis-open.org]ÂOn Behalf OfÂRowland, Larry
Sent:ÂTuesday, February 12, 2019 7:38 AM
To:ÂBob Stayton <bobs@sagehill.net>;Âdocbook-tc@lists.oasis-open.org
Subject:ÂRE: [docbook-tc] testing xinclude in assembly

Â

I think I have found the issue and will have a fix in place as soon as possible. Iâm somewhat concerned that the schema has an ordered sequence of valid elements and Iâm going to end up with xi:include elements being valid anywhere in the sequence. I think that means anything can be pulled in anywhere. Maybe I donât understand enough about xi:include to be doing this change. Iâm way behind on things for tomorrowâs meeting.

Â

Regards,

Larry Rowland

Â

From:Âdocbook-tc@lists.oasis-open.orgÂ[mailto:docbook-tc@lists.oasis-open.org]ÂOn Behalf OfÂBob Stayton
Sent:ÂMonday, February 11, 2019 5:32 PM
To:Âdocbook-tc@lists.oasis-open.org
Subject:ÂRe: [docbook-tc] testing xinclude in assembly

Â

Yes, that one validated for me as well. But when you resolve the XInclude, the resulting file is not valid because a resources element appears after the structure element.

This file does not validate, even though the result after XInclude resolution is valid:

Â<assembly>
ÂÂ<xi:includeÂhref="./resource-block.xml"/>
 <structure>...</structure>
</assembly>

Bob Stayton

Sagehill Enterprises

bobs@sagehill.net

On 2/11/2019 3:50 PM, Scott Hudson wrote:

Hm. This example validated against that schemaâ

Â

--Scott

Â

From:Â<docbook-tc@lists.oasis-open.org>Âon behalf of Bob StaytonÂ<bobs@sagehill.net>
Date:ÂMonday, February 11, 2019 at 4:49 PM
To:Â"docbook-tc@lists.oasis-open.org"Â<docbook-tc@lists.oasis-open.org>
Subject:ÂRe: [docbook-tc] testing xinclude in assembly

Â

Well, the assembly schema says resources elements should appear before any structure elements. The XInclude is pulling in a resources element, so this example would place it after structure, which is not valid.

Bob Stayton

Sagehill Enterprises

bobs@sagehill.net

On 2/11/2019 2:39 PM, Scott Hudson wrote:

I think the include is in the wrong location? Shouldnât it be more like this:

Â

<?xml version="1.0" encoding="UTF-8"?>
<?xml-model href="" type="application/xml" schematypens="http://relaxng.org/ns/structure/1.0"?>
<assemblyÂxmlns="http://docbook.org/ns/docbook"Âxmlns:xi="http://www.w3.org/2001/XInclude">
ÂÂ<resources>
 ÂÂ<resourceÂxml:id="local-file"Âfileref="some/path/file.xml"/>
 ÂÂ<resource><xi:includeÂhref="stock-blocks.xml"Âxpointer="standard.disclaimers"Âparse="xml">
  ÂÂ<xi:fallback>
   ÂÂ<para><emphasisÂrole="strong">Boilerplate got lost!</emphasis></para>
  ÂÂ</xi:fallback>
 ÂÂ</xi:include></resource>
ÂÂ</resources>
ÂÂ<structure>
 ÂÂ<info>
  ÂÂ<title>My Test Assembly</title>
  ÂÂ<author>
   ÂÂ<personname>Some Poor Volunteer</personname>
   ÂÂ<affiliation><orgname>DocBook TC</orgname></affiliation>
  ÂÂ</author>
 ÂÂ</info>
 ÂÂ<moduleÂresourceref="standard.disclaimers"/>
ÂÂ</structure>
ÂÂ<xi:includeÂhref="./resource-block.xml"/>
</assembly>

Â

?

Â

Thanks,

Â

--Scott

Â

From:Â<docbook-tc@lists.oasis-open.org>Âon behalf of Bob StaytonÂ<bobs@sagehill.net>
Date:ÂMonday, February 11, 2019 at 12:24 PM
To:ÂDocBook Technical CommitteeÂ<docbook-tc@lists.oasis-open.org>, "Rowland, Larry"Â<larry.rowland@hpe.com>
Subject:Â[docbook-tc] testing xinclude in assembly

Â

Hi Larry,

I loaded the assemblyxi.rng into Oxygen XML for testing. I opened your test file that you included in the zip file "assembly-with-xinclude.xml" and I see that it XIncludes a file containing a <resources> element. But when I try to add a structure element after the <xi:include> element, it won't let me. I think a common scenario would be to XInclude a common resources file and then create a structure using those resources.ÂÂ

I am able to add a structure element after the literal resources element in the test file and before the xi:include, but not after the xi:include. I don't see what in the schema prevents that.

-- 

Bob Stayton

Sagehill Enterprises

bobs@sagehill.net