My comments after adding DocBook Schema v5.2 support to our tools

[Hussein Shafie <hussein@xmlmind.com>]

Hello,

To my knowledge "DocBook 5.2: The Definitive Guide" 
(https://tdg.docbook.org/tdg/5.2/) is the reference documentation of the 
DocBook Schema Version 5.2. Therefore all my comments are about this 
document.


* What's the purpose of
- structure/info (https://tdg.docbook.org/tdg/5.2/structure)
- structure/revhistory (https://tdg.docbook.org/tdg/5.2/revhistory)
- module/info (https://tdg.docbook.org/tdg/5.2/module)

I mean, do the above elements contribute to the realized document or is 
it just merge (https://tdg.docbook.org/tdg/5.2/merge)?

My understanding is that the above elements do NOT contribute to the 
realized document. However this needs to be made very clear as an author 
may be tempted to write:
---
<module renderas="section">
  <info>
    <title>Using a mouse</title>
  </info>
  <module>...</module>
</module>
---
instead of (less intuitive):
---
<module renderas="section">
  <merge>
    <title>Using a mouse</title>
  </merge>
  <module>...</module>
</module>
---


* merge https://tdg.docbook.org/tdg/5.2/merge

"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."

In my understanding, merge may be also used to ADD (not just replace) 
meta-information to the corresponding realized element, and this, 
whether there is an included resource or not.


* Is there a way to "merge" common attributes (not just meta-information)?

Example:
---
<module renderas="chapter">
  <merge>
    <title>Introduction</title>
  </merge>
  ...
</module
---
I would like the xml:id of realized chapter to be "intro".


* module (https://tdg.docbook.org/tdg/5.2/module)

"You can also create structures that serve as modular components of a 
larger structure. A module in a larger structure can set its resourceref 
attribute to the value of the xml:id of a modular structure element in 
the same assembly to incorporate it."

Please clarify "incorporate it".


* structure (https://tdg.docbook.org/tdg/5.2/structure)

"You can also create modular structures. If a module element within in a 
main structure has a resourceref attribute that matches the xml:id of 
another structure, then the modules of that structure are incorporated 
into the main structure."

Please clarify this feature.

Last example is:

"This example assembles two substructures into a main structure:"
---
<structure xml:id="chapter1-structure" resourceref="chap1">
  <module resourceref="topic1" renderas="chapter">
    <module resourceref="topic2" renderas="section"/>
  </module>
</structure>

<structure xml:id="chapter2-structure" resourceref="chap2">
  <module resourceref="topic3" renderas="chapter">
    <module resourceref="topic4" renderas="section"/>
  </module>
</structure>

<structure renderas="book">
  <merge>
    <title>Name of the book</title>
  </merge>
  <module resourceref="chapter1-structure"/>
  <module resourceref="chapter2-structure"/>
</structure>
---

Please clarify this example by explaining what resources "chap1" and 
"chap2" contain and by giving the equivalent structure renderas="book" 
after "chapter1-structure" and "chapter2-structure" have been 
"incorporated".


* relationships (https://tdg.docbook.org/tdg/5.2/relationships)
relationship (https://tdg.docbook.org/tdg/5.2/relationship)
instance (https://tdg.docbook.org/tdg/5.2/instance)

Please explain relationship/@type, relationship/association, 
instance/@linking and give more examples of these elements.


* instance/@linkend points to the xml:id of a resource but is it OK to 
make it point to the xml:id of a module?

Example:
---
<resource xml:id="quick_start" href="quick_start.xml" />
...
<module renderas="chapter" xml:id="intro">
  <merge>
    <title>Introduction</title>
  </merge>
  ...
</module>
...
<relationship>
  <instance linkend="intro"/>
  <instance linkend="quick_start"/>
</relationship>
---


* Please add at least an example to the documentation of these new elements:

enumsynopsis (https://tdg.docbook.org/tdg/5.2/enumsynopsis)
macrosynopsis (https://tdg.docbook.org/tdg/5.2/macrosynopsis)
typedefsynopsis (https://tdg.docbook.org/tdg/5.2/typedefsynopsis)
unionsynopsis (https://tdg.docbook.org/tdg/5.2/unionsynopsis)

This is especially needed for macrosynopsis whose content model is not 
easy to understand (at least for me).


===========================================
What follows are simply typos found in TDG:

* 3.1. Resources (https://tdg.docbook.org/tdg/5.2/ch06#assemblies_s3)

"An optional description attribute may also be used to provide a 
description of the resource."

but description is a child element.


* output (https://tdg.docbook.org/tdg/5.2/output)

Last example is:
---
<module resourceref="topic1" renderas="section">
  <module resourceref="topic2">
    <output contentonly="true" omittitles="true"/>
  </module>
</module>
---

but output has no contentonly and omittitles attributes.


* resource (https://tdg.docbook.org/tdg/5.2/resource)

"Attributes
...
grammar
    Identifies the markup grammar of a resource
...
transform
    Identifies the markup grammar of a resource
"

but transform does not identify a grammar.


Best regards,

--
Hussein SHAFIE, Product Manager, hussein@xmlmind.com
XMLmind Software, 35 rue Louis Leblanc, 78120 Rambouillet, France
Phone: +33 (0)9 52 80 80 37, Fax: +33 (0)9 57 80 80 37, www.xmlmind.com