Menu ▾ ▴

#77 Clarifications needed about common attributes processing in an assembly

open
nobody
None
5
2015-05-10
2015-05-10
Hussein Shafie
No

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:

  1. How to add or replace common attributes to/in the realized
    structure?

  2. 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:

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.

Discussion