"DocBook 5.1: The Definitive Guide" V1.4.14 needs updates to be in sync with assembly.rng V5.1CR3

Hussein Shafie — Sat, 09 May 2015 09:56:26 -0000

I'm using the DocBook V5.1CR3 RELAX NG Schema of assemblies
as a reference and after carefully reading everyting related
to assemblies in "DocBook 5.1: The Definitive Guide"
V1.4.14, I think I've found the following discrepancies:

6. DocBook Assemblies

All over this chapter:
http://docbook.org/tdg51/en/html/ch06.html
- Attribute type is discussed in many places. However
  according to the schema, only structure has a type
  attribute, not elements output, filterin, filterout.
  
  Moreoever, attribute type is set on elements output,
  filterin, filterout in several examples.
  
  In my understanding, except on element structure, attribute
  type should be replaced by attribute outputformat.
- In some examples, attribute format is set on element
  output. In my understanding, attribute type should be
  replaced by attribute outputformat.
"3.5. Transformations"
http://docbook.org/tdg51/en/html/ch06.html#transformations

A use case for attribute grammar should be given.

4.1. Describing a Help System with an Assembly,
Example 6.1. Resources for a Help System
http://docbook.org/tdg51/en/html/ch06.html#assemblies.15.6

Some resource elements are missing required attribute href.

4.1. Describing a Help System with an Assembly,
Example 6.3. The Front End
http://docbook.org/tdg51/en/html/ch06.html#assemblies.15.6

A module element cannot contain <toc/> or <index/>. In my
understanding, one should reference a resource pointing to a
topic containing <toc/> or <index/>.

1. Example: Assembling a Printed Book
  http://docbook.org/tdg51/en/html/ch06.html#ex-book

Same problem as above.

1. Example: Assembling a Printed Book
  http://docbook.org/tdg51/en/html/ch06.html#ex-book

In paragraph and in the example which follows:

Instead, we introduce one more convention: if a module
refers to another resource and contains an info element,
then the elements within that info replace any elements of
the same name in the referenced resource's metadata. (If the
referenced resource has no metadata, then the specified info
becomes the first child of the referenced resource.)

in my understanding, element info should be replaced by element merge.

1. Example: Assembling an Online Book
  http://docbook.org/tdg51/en/html/ch06.html#ex-html

Same problem as above in the example.

1. Example: Assembling an Online Book
  http://docbook.org/tdg51/en/html/ch06.html#ex-html

Please clarify the effect of elements filterin, filterout on
the contents pulled from the resource referenced by a
module.

For example, just writing "print only content is excluded
globally" to describe

<structure xml:id="user-guide">
    ...
    <filterout type="web" condition="print"/>

is not very clear.

(In contrast, writing "If no conditions are specified on
filterout, the module is unconditionally excluded" is quite
clear.)

II. DocBook Assembly Element Reference

"Examples" in element transform:
http://docbook.org/tdg51/en/html/transform.html

attribute fileref must be replaced by attribute href

"Attributes" in element structure:
http://docbook.org/tdg51/en/html/structure.html

Please clarify attributes type, defaultformat.

Recent changes to 76: "DocBook 5.1: The Definitive Guide" V1.4.14 needs updates to be in sync with assembly.rng V5.1CR3

"DocBook 5.1: The Definitive Guide" V1.4.14 needs updates to be in sync with assembly.rng V5.1CR3

6. DocBook Assemblies

II. DocBook Assembly Element Reference