RE: DOCBOOK-APPS: Help project structure

[Maggie Strevell <maggie@ssinc.com>]

First, a previous topic prompted me to abandon using <sect1> <sect2> for my
topics and I am now using nested <section>.  This should give you the depth
you are looking for.  I have this working, but I don't need the depth you
mention so I haven't taken it that far.

I would love to see a parameter that allows you to exclude the generation of
book and chapter files.  I've tried to eliminate the chunking of chapters
and books by using the following code in the chunker.xsl file, but the best
I end up with is my sections at a depth of two get generated, and then the
transformation fails because saxon can't make the chapter file.

<xsl:when test="local-name(.)='chapter'">
  <xsl:message terminate="no">
  <xsl:text>Skipping Writing of Chapter File</xsl:text>
 </xsl:message>
 </xsl:when>

While I couldn't prevent the book and chapter files from generating, I can
exclude them from my table of contents and I have customized the book and
chapter templates in my driver file to make chapter titles not link.    I
suppose I will need to also exclude them from my .hhp file if I cannot
eliminate their existence entirely.  I do this with the following code:
   <xsl:template match="book" mode="hhc">
  <xsl:variable name="title">
    <xsl:if test="$htmlhelp.autolabel=1">
      <xsl:variable name="label.markup">
        <xsl:apply-templates select="." mode="label.markup"/>
      </xsl:variable>
      <xsl:if test="normalize-space($label.markup)">
        <xsl:value-of
select="concat($label.markup,$autotoc.label.separator)"/>
      </xsl:if>
    </xsl:if>
    <xsl:apply-templates select="." mode="title.markup"/>
  </xsl:variable>

  <xsl:if
test="part|reference|preface|chapter|appendix|bibliography|article|colophon"
>
      <xsl:apply-templates
select="part|reference|preface|chapter|bibliography|appendix|article|colopho
n"
			   mode="hhc"/>
    <xsl:text>&lt;/UL&gt;</xsl:text>
  </xsl:if>
</xsl:template>

<xsl:template match="chapter"
              mode="hhc">
  <xsl:variable name="title">
    <xsl:if test="$htmlhelp.autolabel=1">
      <xsl:variable name="label.markup">
        <xsl:apply-templates select="." mode="label.markup"/>
      </xsl:variable>
      <xsl:if test="normalize-space($label.markup)">
        <xsl:value-of
select="concat($label.markup,$autotoc.label.separator)"/>
      </xsl:if>
    </xsl:if>
    <xsl:apply-templates select="." mode="title.markup"/>
  </xsl:variable>

  <xsl:text>&lt;LI&gt; &lt;OBJECT type="text/sitemap"&gt;
    &lt;param name="Name" value="</xsl:text>
	<xsl:value-of select="normalize-space($title)"/>
    <xsl:text>"&gt; &lt;/OBJECT&gt;</xsl:text>
    <xsl:text>&lt;UL&gt;</xsl:text>
  <xsl:if
test="reference|preface|chapter|appendix|refentry|section|sect1|bibliodiv">
      <xsl:apply-templates

select="reference|preface|chapter|appendix|refentry|section|sect1|bibliodiv"
	mode="hhc"/>
  </xsl:if>
      <xsl:text>&lt;/UL&gt;</xsl:text>
</xsl:template>

I also have files for which I want in the help file, but I don't want in my
table of contents.  Still working on that too.

Maggie



-----Original Message-----
From: denisb@rational.com [mailto:denisb@rational.com]
Sent: Thursday, January 31, 2002 11:47 AM
To: docbook-apps@lists.oasis-open.org
Subject: RE: DOCBOOK-APPS: Help project structure


> RE: using recursive sections for topics instead of chapters in HTML Help

I've been testing docbook 1.48 (and the latest htmlhelp.xsl from CVS) on the
following help project structure:
<book>
    <chapter>
        <title>Help for My App</title>
	 &topic1;
             &topic2;
       </chapter>
</book>

Previously I maintained the project file and toc by hand because the
generated .hhp and .hhc files were not usable. 1.48 enhances this
automation, but I'm having the following problems with it:

1. htmlhelp.xsl  generates chunks for book and chapter, and also lists them
in FILES section of .hhp project file. What's the best way to NOT generate
these elements and to exclude them from the .hhp project file? I couldn't
get any parameters to do it.

2. When coded this way, the topic structure must be very flat, right?
Suppose I want to end up with nested TOC items like this:

Help for App
     Using App
            Getting started
                  Installing
                  After installing

Of course, some of the items might be just titles, like the first one, which
is the chapter and has no link. But all actual topics are siblings - 1st
level sections in the chapter - so I'm not sure how to get them to nest in
the generated hhc file, as shown above.

To be honest, neither of these problems is a show stopper for us. The book
and chapter file are just messy, they don't affect anything. And in our last
project it was very easy to maintain the .hhc manually (in HTML Help
Workshop), where the TOC structure can be completely independent of the XML
topic structure.

Finally, even without the automation, coding all topics as sections enables
us to potentially reuse them. Just thought I'd check with the experts before
I abandon the automation - I'd appreciate any suggestions.
 _____
 Denis