Re: [docbook-tc] Questions about RFE 3368279

["Bob Stayton" <bobs@sagehill.net>]

Hi Norm,
As the originator of the RFE, I can clarify what I intended, and then we can go from 
there.

1.  My intention was not to make chapter completely empty. I was proposing something 
like:

   element chapter {
     db.chapter.attlist, db.chapter.info, db.component.contentmodel?
   }

In other words, keep title and info and make the block and section content optional, 
not required.

We don't need a completely empty chapter for assembly.  That could be achieved with a 
module element with renderas="chapter" and contentonly="yes" when referencing a normal 
chapter file.

My use case is where you are using a chapter file as a module that defines the 
chapter's id, title, and info, but not its content, which is assembled from other 
modular files.

2.  Regarding the list of elements, I had intended to include hierarchical elements 
that are likely to be modularized, so I would include sect1 through sect5 and 
simplesect, although I doubt simplesect would be further modularized in practice.

Now that you mention it, part and partintro should be included too.

I had not intended to include refentry and refsection, as a refentry is a cleanly 
defined module already. It differs from topic because topic can be used in a structure 
hierachy to morph into other structure elements using renderas.   I would include 
reference, because refentry elements are certainly modules and reference currently 
requires at least one refentry.

I had not intended to include non-hierarchical elements like procedure, blockquote, 
sidebar, or other titled elements.  Those are unlikely to be modularized in a 
structure.

3.  So I'm not proposing "Required bag of stuff" OR "empty", I'm proposing "Only title 
required".  8^)

I personally don't think it is necessary to customize this just for assembly. 
Creating a chapter with just a title and no other content may not be very useful, but 
it does not violate the rules of a hierarchical structure. And it can be useful in the 
early stages.  When I write in DocBook, I often create my whole hierarchy with just 
titles, but I currently must add empty paras so it validates.  With this change, I 
won't have to add the empty paras to get started.  8^)

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net


----- Original Message ----- 
From: "Norman Walsh" <ndw@nwalsh.com>
To: <docbook-tc@lists.oasis-open.org>
Sent: Friday, October 21, 2011 10:23 AM
Subject: [docbook-tc] Questions about RFE 3368279

Hi folks,

In RFE #3368279

 https://sourceforge.net/tracker/?func=detail&aid=3368297&group_id=21935&atid=384107

Bob says:

 When modularizing documentation, it is sometimes necessary to create
 empty modular elements whose content will be supplied during the
 assembly process. For example, a chapter might not need any
 introductory paragraphs and so just begin with the first section. If
 the chapter and sections are all in modular files that are put
 together with the new assembly element, then the chapter should
 contain only a title (and other info elements). However, such a
 nearly empty chapter does not currently validate, because a chapter
 must have either block content or sections (or both). To better
 support modularity, a chapter should be permitted to be empty of
 content. The same is true of appendix, preface, section, and topic.

 I propose that the content models be modified in 5.1 to allow for
 nearly empty elements.

And we agreed to these changes. But now as I sit down to actually make them,
I realize that I have questions and concerns:

1. The RFE asks us to allow a chapter to be empty, but also says the
  chapter might just contain title or an info.

  Is the request to allow this:

     <chapter/>

  Or this:

     <chapter><title>Hello Dennis</title></chapter>

  Or both?

2. The RFE calls out chapter, appendix, preface, section, and topic. I
  assume section convers all the sectioning elements. Is this really
  enough elements? What about part, partintro, refentry, refsection,
  etc.? What about simplesect, sidebar, blockquote, and procedure?
  How are we selecting the elements?

3. Ugh. There's something about this change that really makes me feel
  uncomfortable. "Required bag of stuff" OR "empty" just feels wrong.
  And that's before I even start to think about what that means for
  the DTD/XSD content models.

This is something that only occurs in assemblies, right? So, in fact,
do we even want plain, old ordinary DocBook documents to include empty
chapters?

Is this supposed to be valid?

 <book xmlns="http://docbook.org/ns/docbook";>
 <title>My Title</title>
 <chapter/>
 </book>

Maybe we should just publish an assembly customization layer that
allows this:

 include "assembly.rnc"
   { db.chapter |= db.empty.chapter }

 db.empty.chapter = element db.chapter
    { db.chapter.attlist, db.chapter.info?, db.chapter.contentmodel? }

Comments?

                                       Be seeing you,
                                         norm

--
Norman Walsh <ndw@nwalsh.com>      | Fast. Cheap. Well. Pick two.
http://www.oasis-open.org/docbook/ |
Chair, DocBook Technical Committee |