Clarifications needed about common attributes processing in an assembly

Hussein Shafie — Sun, 10 May 2015 08:28:28 -0000

In my understanding, something like: snippet #1:

<module>
  <output renderas="appendix"/>
  <info>
    <title>Troubleshooting spindle and bearing problems</title>
  </info>

or like this (where "tut3" points to a topic having no
xml:id and containing no info element other than a title):
snippet #2:

<module resourceref="tut3">
  <output renderas="appendix"/>
  <merge>
    <title>Troubleshooting spindle and bearing problems</title>
  </merge>

gives the following realized structure:

<appendix>
  <info>
    <title>Troubleshooting spindle and bearing problems</title>
  </info>

My questions are then:

How to add or replace common attributes to/in the realized
structure?
How to add info elements to the realized structure?

Let's suppose I want the realized structure to be:

<appendix xml:id="spindle_bearing_problems">
  <info>
    <title>Troubleshooting spindle and bearing problems</title>
    <author><orgname>ACME Corp.</orgname></author>
  </info>

(1) Do I need to change snippet #1 to:

<module xml:id="spindle_bearing_problems">
  <output renderas="appendix"/>
  <info>
    <title>Troubleshooting spindle and bearing problems</title>
    <author><orgname>ACME Corp.</orgname></author>
  </info>

or is it:

<module>
  <output renderas="appendix" xml:id="spindle_bearing_problems"/>
  <info>
    <title>Troubleshooting spindle and bearing problems</title>
    <author><orgname>ACME Corp.</orgname></author>
  </info>

(2) Do I need to change snippet #2 to:

<module resourceref="tut3">
  <output renderas="appendix"/>
  <merge xml:id="spindle_bearing_problems">
    <title>Troubleshooting spindle and bearing problems</title>
    <author><orgname>ACME Corp.</orgname></author>
  </merge>

In "DocBook 5.1: The Definitive Guide" V1.4.14, II. DocBook
Assembly Element Reference, I can read:

Element structure
http://docbook.org/tdg51/en/html/structure.html

Common attributes on the structure element are generally copied onto the
output root element.

However there is no such indication on element module
http://docbook.org/tdg51/en/html/module.html which seems
to be inconsistent because a structure is basically a top
level module.

Element merge
http://docbook.org/tdg51/en/html/merge.html
- How to merge (that is, add or replace) common attributes is not
  specified.
- I can read:
  
  When used in a module, the merge element indicates
  elements in the meta-information of the included resource
  that should be replaced with the content of the merge
  element.
  
  Each element in the merge replaces all elements of
  the same name in the meta-information of the
  included resource.
  
  But what about adding info elements? Shouldn't the
  above paragraph read:
  
  When used in a module or in a structure, the merge
  element indicates elements in the meta-information of the
  included resource that should be merged, that is added or
  replaced, with the content of the merge element.

Recent changes to 77: Clarifications needed about common attributes processing in an assembly

Clarifications needed about common attributes processing in an assembly