Norm's proposed changes for DocBook 5.2

[Bob Stayton <bobs@sagehill.net>]

DocBook TC member Norman Tovey-Walsh has been actively reviewing DocBook 5.2 and has recently made several suggestions to improve the schema, using issues and PRs submitted on the Github site where the schema is maintained. I believe the TC can use email to discuss and decide on these before the next meeting. What follows is my quick summary of all the items he has brought up, along with a link to each Github page. Following that list is my proposal for how we can proceed on these.

PR 147, Proposed fix for issues related to new synopsis elements. Norm is suggesting 16 changes to the DocBook schema regarding the new synopsis elements. This is the most extensive change he has proposed. https://github.com/docbook/docbook/pull/147

PR 155, Add a general 'meta' element in info. The element would be <meta name="foo" content="bar"/>, and would provide a mechanism for adding miscellaneous metadata in the content attribute, with a name attribute to specify its purpose. This PR implements the change suggested in Issue #153. https://github.com/docbook/docbook/pull/155

Issue 141, The definition of db._any is too narrow. Norm says "The db._any pattern exists to allow 'escape hatches' in DocBook, places where arbitrary content is allowed. For example, info elements can contain arbitrary metadata.
The current definition has two problems: it rejects HTML elements for no apparent reason and it's recursive so it doesn't allow DocBook elements to be nested inside the metadata." According to the issue's comments, Norm's suggested change was acceptable to Bob, Scott, and Jirka. We could probably put this one to a vote. https://github.com/docbook/docbook/issues/141

Issue 142, Update the DocBook namespace page to reflect the current status. The webpage http://docbook.org/ns/docbook currently describes DocBook 5.0 as "The DocBook TC expects to publish the following schemas soon", so it predates the release of 5.0. I propose we update the page to indicate the schema with that namespace was released on a given date and is currently in use. Since the namespace applies to all 5.* versions, I suggest the page not describe the current version, but just point to the Schemas page. That way it would not get out of date. https://github.com/docbook/docbook/issues/142

Issue 143, The content model for typedefsynopsis allows unwrapped inlines. Norm's fix for this is included in the big set of changes in PR147. https://github.com/docbook/docbook/issues/143

Issue 144, The content model for namespacesynopsis is inconsistent with the rest of DocBook. Norm's fix for this is included in the big set of changes in PR147. https://github.com/docbook/docbook/issues/144

Issue 148, Should simplesect be allowed in legalsection? Currently legalsection can contain "db.all.blocks" and nested legalsection. Norm's comment on this issue is "It's a terminal section element, often used for headings that shouldn't appear in the ToC." https://github.com/docbook/docbook/issues/148

Issue 149, Should legalsection be allowed in topic? In the comments Norm suggests this might be a mistaken omission, and Scott agrees. I also agree. https://github.com/docbook/docbook/issues/149

Issue 150, Support legal sections with a class attribute? Here Norm is arguing to replace the new legalsection element with section plus class attribute. His comment on the issue consists of six paragraphs. https://github.com/docbook/docbook/issues/150

Issue 151, Add a schematron rule for the callout type constraint. Norm says "In a calloutlist, the only valid targets for an IDREF are areaset, area, and co. The schema should include a Schematron rule to enforce this constraint. https://github.com/docbook/docbook/issues/151

Issue 152, Add schematron rules for productionset reference constraints. Norm says "In a productionset there are a couple of referential integrity constraints that should be checked with Schematron, <productionrecap> and <constraint>." https://github.com/docbook/docbook/issues/152

Issue 153, Future use comments for XLink elements. This issue motivated the addition of a new meta element, with a proposed implementation in PR155. https://github.com/docbook/docbook/issues/153

Issue 156, docbookxi doesn't support XInclude 1.1. Norm says "It's missing the fragid attribute."ÂÂ A second comment says "The schema for XInclude also forbids href="" which is a bug."Â And a third comment suggests allowing XIncludes anywhere, including in inline elements. https://github.com/docbook/docbook/issues/156

------------------------------------------------------------------------------------------------------------------------------------

I think we can most cleanly manage these in email if each different topic is covered by one TC email thread with a specific subject line. That keeps a clear record of discussion and action on each topic in the email archive, keeps the discussion focused on one item at a time, and allows the items to be spread out over time. Some of these will be easy and quick, but others will require more discussion. I propose to start a new thread on a new topic every few days. Where possible I will consolidate (for example, PR 155 and Issue 153 are the same topic).

How does that sound?

-- 
Bob Stayton
bobs@sagehill.net