DOCBOOK-APPS: Re: Help project structure

[Norman Walsh <ndw at nwalsh dot com>]

/ "Maggie Strevell" <maggie@ssinc.com> was heard to say:
| 1) Specify whether or not an element should be chunked (chunk="yes" | "no").
| Applies especially to Set,Book,Chapter,Title.

Implementing completely arbitrary chunking has logical and performance
ramifications. I'm part way through a strategy that I think will solve
the performance problem, at the expense of a little more bookkeeping
for the author, but there's not much that can be done about the
logical problem.

Consider:

  <book>
    <dedication/>
    <chapter/>
    <chapter/>
    <chapter/>
  </book>

Today this would be chunked as follows:

  book,dedication->index (next=ch1, prev=null)
  chapter->ch1 (next=ch2, prev=index)
  chapter->ch2 (next=ch1, prev=ch1)
  chapter->ch3 (next=null, prev=ch2)

Suppose you had arbitrary chunking

  <book>          chunk=yes
    <dedication/> chunk=yes
    <chapter/>    chunk=yes
    <chapter/>    chunk=no
    <chapter/>    chunk=yes
  </book>

This would be chunked as follows:

  book,ch2->index (next=ded, prev=null)
  dedication->ded (next=ch1, prev=book)
  chapter->ch1 (next=ch3, prev=ded)
  chapter->ch3 (next=null, prev=ch1)

Note that the dedication would be "invisible" in the index file and
ch2 would appear in the index file apparently before the dedication
and ch1. I don't see any practical solution to this sort of problem.

If you chunk arbitrarily, chunk from the top down in every branch of
the tree, without skipping levels.

| 3) Add a template to add a linebreak, for those who like to customize
|    (If all <p>'s were changed to <br><br>, then you'd never need <p>)

Where would you need or want this linebreak?

| 4) Be allowed to add a topic in the TOC without having it be in a TOC
| book/folder.  Should be able to be first in the TOC, in the middle of the
| TOC, or at the end.

Where would it appear in the TOC?

| 5) Be allowed to exlude a topic in the TOC.  All other functions still apply
| like chunking the topic, add it to the index.  This is required for
| context-sensitive help for topics that might relate to a windows control
| which really don't need a help section in your TOC and possibly the printed
| manual too.

Where does it appear in the prev/next list? Or does a help file not have one?

| 6) Ability to specify the title of the help project.  Currently, for me, it
| defaults the title of my first <chapter>.

Not the book?

| 7) Ability to remove the appending of a chapter title to a section.
| 8) Ability to specify a name for a manually constructed context.h (maybe
| alias.h for someone else?).

I don't understand these.

| 9) A way to manage Help ID's specified in the dbhh PI.  We base our help
| ID's off the same number as the resource ID for each window control.  As my
| C++ GUI application is shared among many developers, resource ID's for each
| window control/button/dialogbox can get renumbered each time the app is
| built.  Therefore, our help ID's can change.  IDC_MY_BUTTON becomes a help
| ID of IDH_MY_BUTTON, both defined as "765".  Since my help ID defines are a
| moving target, I can do one of two things, manually maintain the alias.h
| file or find a way to automate it.  I'm big on automation, so possibly we
| could have the PI dbhh take a help ID name and then look up the number that
| is defined for it in the context.h file?

Sounds reasonable.

| I'd like to be able to understand chunking for some things I'd like
| customize.  Any descriptions or tutorials out there that describe what is
| going on? sounds like I might need some aspirin :)

There are basically two sets of templates that are important for
chunking in chunk.xsl. One set matches an element "x" and makes it a
chunk. The other decides for "x" what constitutes the previous element
and what constitutes the next.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | Simplicity is always a
http://www.oasis-open.org/docbook/ | virtue.--Edward Abbey
Chair, DocBook Technical Committee |