RE: [docbook-tc] assembly metadata container

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

I would prefer to avoid another namespace, since I think of this as being 
an integral part of the assembly model, and I think of namespaces as being 
used to combine other things with DocBook.  Adding a class or type attribute 
would be preferable to a namespace (possibly "supplemental" -- the reasoning 
is provided below) but I think a different element is a better solution.

I think "override" is not really accurate, since it implies that this element 
overrides the info element that is contained in the original resource and it 
may actually provide additional information.  Similarly, I think that "merge" 
may not be a more appropriate modifier.  When I looked it up, the definition 
was "To combine or unite" and that is not quite what I think is happening.  
However, it seemed to be going in the right direction.  After exploring 
synonyms for a bit, I found "supplement" with the following definitions:

     1. Something added to complete a thing, make up for a
        deficiency, or extend or strengthen the whole. 
     2. A section added to a book or document to give further
        information or to correct errors. 

which seems to be what we are actually doing, that is we are either 
correcting (when we provide an alternative to the title in the resource being
referenced) or providing additional information (like a titleabbrev for use 
in a help system).  What about infosupplement (or infosupp, although we are
not the longest element in DocBook with infosupplement).  I am dropping the 
dash in the name, since as you point out, there are no other instances of 
hyphenated names where things are combined for elements like programlisting 
or inlinemediaobject.  I would favor avoiding it since it might make people 
ask for adding hyphens to other elements.

I also did not camel-case the name, even though in SGML days that appears to
have been done, we have gone to lower-case since we moved to XML where case 
matters and my own experience with camel-case indicates it is harder for 
people to remember than all lower- or upper-case.

I would prefer merge to override although I don't consider either of them to
be accurate.  I don't think adding resource to info is really making it 
clearer what is going on.

Regards,
Larry Rowland

It's no wonder that truth is stranger than fiction. 
Fiction has to make sense.
- Mark Twain

-----Original Message-----
From: Bob Stayton [mailto:bobs@sagehill.net] 
Sent: Monday, February 22, 2010 10:26 AM
To: DocBook Technical Committee
Subject: [docbook-tc] assembly metadata container

I'm following up on my action item from the last DocBook TC. We agreed that <info> 
would be used in assembly elements to document the assembly element that contains the 
info, which follows the current usage of info in DocBook. We agreed that any override 
information that would be used when a resource is used in a module when it is 
assembled should be in another container element within module.  We need to decide on 
the name of that container now.  The three suggestions from the meeting were:

1.  info in a different namespace

2.  info-override

3.  info-resource.


I'll add one more:

4.  info-merge, to indicate this info is applied when topics are merged into a 
document.


I'll make one observation on naming style: currently DocBook has no elements with 
hyphens in the name.  There is certainly no rule against it, but I thought I would 
point out that fact.

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