I guess the corner cases are where it always gets interesting. This is
a good one to bring up.
The original concept was certainly that the resource element was where
what was being pulled in was defined, and it would pull in the fragment
if that is what was needed. I also thought that adding the xml:base
attribute to the resources element would handle most moves of files,
although admittedly it was based on moving files from one repository
to another rather than structural moves within the repository, which
are also a possibility, and would introduce the problem of editing the
twenty URIs that you mentioned. However, in the XML editors I am
typically using, search and replace would allow a blanket edit of all
the paths in question up to the ID value with little real effort. I
had really conceived of the resource element as being the bridge
between the external content and the internal description of the
assembly.
I would prefer to keep the shorthand method of indicating the path to
the file and the ID within the file all as part of the fileref URI value
since I find it very clear and easy to follow. However, if general
markup is allowed within the resource definition (as has been brought up
at least a couple of times) then the problem of referencing an ID within
a resource becomes an issue that must be dealt with. There is also the
case you described of having to modify 20 fileref values that could be
considered burdensome by some users. In cases where the ID must be
specified on the module rather than in the resource, I would favor using
the additional attribute on the module to identify the fragment, since
it was much easier to work with the resourceref/xml:id relationship that
would be lost if resourceref became CDATA.
I would, however, wonder if we are making the markup more complex to
accommodate an issue that may not be a frequent problem (people who are
trying to do modular documents should not be doing too much based on
large chunks that cannot be edited, although I know that dealing with
legacy can be a real problem).
Whether we add an attribute to module or not, I would like to keep the
shorthand method of specifying a portion of a file as a resource that
the current model provides. Adding an attribute is more work in every
editor I know than adding to the text in a URI string and provides a
simpler model for the human processing engine that has to interpret the
assembly on the fly (understanding the meaning of the file#attribute
string requires less processing for a person than interpreting the
significance of a second attribute that may be on another line in the
file).
LRR
Original Message-----
From: Bob Stayton [mailto:bobs@sagehill.net]
Sent: Tuesday, February 16, 2010 12:08 PM
To: DocBook Technical Committee
Subject: [docbook-tc] resource fragments
I have a question regarding referencing fragments of a resource. It seems there could
be two ways to include a fragment of a resource in your document:
1. Define the resource element as a fragment, as in this example from Larry's sample: