RE: DOCBOOK-APPS: Re: Help project structure

[Maggie Strevell <maggie at ssinc dot com>]

I know others are using the straw proposal you mention.  Being so new, I
can't quite understand it's implementation.  Given that the stylesheets
themselves reference element like "chapter" and "section" makes it easier
for me to hunt down items I need to customize in the stylesheets.  Not sure
how this would work if a topic was an alias to a section (someone new would
need to translate a "section" as a "topic to figure anything out).  Once
again, I'm new to all of this, so you'll have to pardon my ignorance.

I can tell you my wish list, items that a little customization would go a
long way (mostly just the XSL?).  Rather than a straw proposal (isn't that
just more work for someone to maintain?) doesn't it make more sense to add
an attribute or a customizable parameter (or mode?) to the original
structures (DTD, XSL) that allow more control... whether or not you are
writing for a typical book structure or a help file?  The items on my list
most likely would be handled through XSL.

For a help project, I'd like to be able to:
1) Specify whether or not an element should be chunked (chunk="yes" | "no").
Applies especially to Set,Book,Chapter,Title.
2) Be allowed to specify which file is the default in the .hhp file
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>)
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.
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.
6) Ability to specify the title of the help project.  Currently, for me, it
defaults the title of my first <chapter>.
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?).
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?  Otherwise, I could write a
post-operation script to replace the context.h with my own, then coordinate
the numbering scheme between the auto-generated alias.h file with the
context.h that was created by my GUI application.

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 :)

Maggie


-----Original Message-----
From: Norman Walsh [mailto:ndw@mercury]On Behalf Of Norman Walsh
Sent: Friday, February 01, 2002 4:51 AM
To: David Cramer
Cc: denisb@rational.com; docbook-apps@lists.oasis-open.org
Subject: DOCBOOK-APPS: Re: Help project structure


/ David Cramer <dcramer@broadjump.com> was heard to say:
[...]
| Btw., there was a discussion on the docbook list on what changes should
| be made to the dtd to accomodate a help system, but I fell behind around
| that time and never have made it back to glean wisdom from those
| threads.

http://lists.oasis-open.org/archives/docbook/200110/msg00082.html

Comments still most welcome.

                                        Be seeing you,
                                          norm

--
Norman Walsh <ndw@nwalsh.com>      | All our foes are mortal.--Val\'ery
http://www.oasis-open.org/docbook/ |
Chair, DocBook Technical Committee |