[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: My comments after adding DocBook Schema v5.2 support to our tools
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]