DOCBOOK-APPS: Re: Help project structure

[Norman Walsh <ndw at nwalsh dot com>]

/ David Cramer <dcramer@broadjump.com> was heard to say:
|> I would love to see a parameter that allows you to exclude 
|> the generation of
|> book and chapter files.  
|
| What you (and I) really want is for the xsl to check to see if there's
| content in the chapter or section before the next section begins. So the
| following two cases would be handled differently:
|
| Case 1: The following sibling of title != section... so there is a
| separate chunk and toc entry for the section titled Foo.
|
| <section>
| <title>Foo</title>
| <para>The following sections contain stuff about foo</para>
| <section>
| <title>A subsection about foo</title>
| ...
|
| Case 2: The following sibling of the title = section, so there is no
| separate chunk for the section titled Foo. There could be a toc entry,
| but it would take you to a chunk that contains the title for Foo, the
| title for A subsection about foo, and the rest of A subsection about
| foo..." 
|
| <section>
| <title>Foo</title>
| <section>
| <title>A subsection about foo</title>

What you're suggesting would lead to very irregular structure:

  Section           [chunk]
    Section         [no chunk]
      Section       [chunk]
      Section       [chunk]
        Section     [chunk]
      Section       [no chunk]
        Section     [chunk]
   Section          [no chunk]
     Section        [chunk]
  Section           [no chunk]
     Section        [chunk]

This would make calculating the previous and next chunks (for any
given chunk) really hard.

The experimental chunking stuff that I have never finished writing was
intended to make it easier to tell what nodes to chunk. The idea was
you list all the chunks in a separate file:

chunk.data
  <section id="foo"/>
  <section id="bar"/>
  ...

and a node becomes a chunk if and only if it has an entry in the chunk
file.

Maintaining the chunk file would be an extra headache, but it'd give full
control without having to deal with...

| The xsl for chunking is pretty hairy. It always hurts my head when I
| look at it.

...the really hairy stuff. <aside>Look at the code in DSSSL if you really
want a headache.</aside>

| that makes all sections chunk. Currently I require the writers to put at
| least an introductary para in places where there would otherwise be an
| empty chunk, but that's not a very satisfactory solution.

Hmm. Maybe, maybe not. For online help systems, you're probably right,
but for documentation in general, I think it's a bad sign for two
section titles to occur in a row.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | If you run after wit you will
http://www.oasis-open.org/docbook/ | succeed in catching
Chair, DocBook Technical Committee | folly.--Montesquieu