This is the mail archive of the docbook-apps@lists.oasis-open.org mailing list .


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

RE: Re: Help project structure


| 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.

...

>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.

I don't completely understand.  And, I'm not familiar enough to know how
altering this link list would effect other processes aside from HTMLhelp
(forgive me of any ignorance).  By excluding items from this particular
list, does it effect the way we traverse the tree to process each node? If
so, I can see how this could be problematic.  If we are using this list for
keeping track of previous and next for the TOC (as mentioned below), maybe
there is a solution since we don't need to keep track of this for HTMLHelp?

Does it make it any easier to allow the chunking of certain node types?
Like all books and chapters aren't chunked, but all topics are?  In
HTMLHelp, Chapters (book/folder icons) may/may not have links to a topic.
By eliminating chapter chunking, do we make problems generating a TOC that
lists all the sections within that chapter?

Did you mean the index for compiled help?  If so, it wouldn't matter as the
index gets generated from <indexterm>?


| 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?

A linebreak between two paragraphs.  I was looking for a quick fix to a
browser compatability issue.  Why?  The generated htm file looked great in
IE 5.5, but not the compiled help file (HTMLHelp version 4.74.8702.0).  I
took another look this morning, and the root of the problem stemmed from my
use of a standard Microsoft provided style sheet that I was specifying an
invalid path to.  Once the path was fixed, I still had the problem.  Turns
out the specified style for the <p> tag was
p{margin-top:.6em;margin-bottom:0em;}.  Removing this style finally fixed
the problem, but it would have been nice to have a quick fix even if it
wasn't really "fixed".

| 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?

Nowhere.  I don't understand my own second sentence, sorry for any
confusion.  Also, when I reference book/folder (icons used in HTMLHelp), I
am refrencing the TOC of the compiled help file.

| 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?

There isn't one.  In fact, there is no need for the links provided in the
<head> tags to prev/next.  While prev/next would be nice for an online help
system, they aren't appropriate for a windows application help system.  They
don't hurt anything to be there either, so there's really no need to remove
them.  Maybe this helps with the "to chunk"/"not to chunk" problem?

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

>Not the book?

Nope.  If I used a title for the book I'd get a generated folder icon for it
in my compiled help file and all the chapters would be inside that one
book/folder icon.  The only thing in my compiled help file TOC that I want
is a list of icons (a book or folder icon) for each chapter.  Each chapter
should have a title, no link.  When you click on that chapter, you see a
list of topics.  Each topic (AKA: topic/<section>/article icon) inside that
chapter links to the topic's htm file.

One caveat is that I've seen help done two common ways:  each chapter (AKA
book/folder icon) has a title with no link to content OR each chapter has a
title and links to page content.

| 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.
7)At one point the title for a chapter was getting appended to the top of
each topic (<section>).  I fixed this during my customization, can't
remember which fix did it, but I could take another look.

8)I guess I thought that it would be nice to specify a name for the manually
generated context.h or alias.h files (like the params for specifying the
name for the .chm, .hhp, and .hhc files).

...

| 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.

Thanks for the perspective.

                                        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 |


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]