RE: [docbook-tc] resource fragments

["Rowland, Larry" <larry.rowland@hp.com>]

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:

   <resource xml:id="svn.properties"
      fileref="subversion/properties.xml#using.properties"/>
  ...
  <module resourceref="svn.properties"/>

Here the resource's fileref includes a fragment identifier, and the module's 
resourcref is a straight IDREF.

2.  Reference a fragment of a whole resource from a module:

   <resource xml:id="svn.properties"
      fileref="subversion/properties.xml"/>
   ...
   <module resourceref="svn.properties#using.properties"/>

Here the resource's fileref does not have a fragment identifier, and the module's 
resourceref does.


In case 1, the fileref attribute is a URI and # is a true URI fragment identifier.

In case 2, the resourceref is not a URI but a IDREF. Adding fragment identifier syntax 
after it would not be a valid IDREF, so its definition would have be changed to CDATA 
to accept such syntax.  The interpretation of the syntax would be to fetch the 
resource element by its id and attach the fragment identifier to its fileref value. 
Also, this syntax mixes information from the assembly (the resource's xml:id) and the 
resource (the id in the file named properties.xml).

Are references like case 2 to be permitted?  My first instinct is "no", but I'm sure 
that someone will be asking for it at some point. Consider a resource that is pretty 
large, non-editable, and you want to pull multiple fragments from it.  If we permit 
only case 1, for each fragment you want to reference from that large resource, you 
would have to define a new resource element using "filename#id" syntax.  Then, after 
you have done this twenty times, you find you need to move the resource file.  Now you 
must update twenty resource elements to fix the fileref path.   Allowing case 2 would 
avoid that problem.

Perhaps a different syntax might work better:

3.  Reference a fragment of a whole resource from a module using another attribute:

   <resource xml:id="svn.properties"
      fileref="subversion/properties.xml"/>
   ...
   <module resourceref="svn.properties" fragment="using.properties"/>

This would allow a single resource element to reference the file, keeps resourceref as 
an IDREF, and permits referencing a fragment of a resource.  It means adding another 
attribute to module, though.

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net



---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php