Re: [jamboost] Re: V2 documentation format: a resolution?

From: Reece Dunn (msclrhd_at_[hidden])
Date: 2004-02-09 17:22:56

Rene Rivera wrote:

>Reece Dunn wrote:
>
>>Zbynek Winkler wrote:
>>
>>>I do not think it is a good idea to start with such a huge toc. Maybe a 
>>>mix
>>>of
>>>condensed version and/or synopsis and/or "how to use this document" would
>>>be
>>>better.
>>
>>
>>If there is a consensus on this, I'll have a look into this, but can't
>>promise anything!
>
>A detailed TOC at the start of a book is somewhat standard. It gives one 
>the
>opportunity to see all that is included in the text. For online docs it 
>also
>gives the opportunity to briefly search for some specific topic you are 
>interested in, and go there directly. But having the TOC at each page is
>distracting and superfluous. I would recommend, and prefer, having only one
>detailed TOC.

I think Zbynek Winkler was referring to having a ToC similar to that found 
on the HTML docs (www.w3.org) where they have a simplified ToC that displays 
the chapters only and a "full ToC" available that includes sections, etc.

Having said that, modifying the ToC behaviour could prove more trouble than 
it is worth.

>About the navbar...

>The navbar is less than understandable as it stands. What does "Home" and 
>"Up"
>mean? Those terms don't tie in to any other page I can see. If one of those
>refers to going to the TOC, then the link should say "TOC". OK, I looked at
>the links themselves, both point to the same location, so why have both?
>Having the links be images with the words in them is pointless. Having 
>either
>a non-text image and a text label, or just having a text link is better. My
>ideal would be to put a TOC link on the top navbox only. And create a top 
>and
>bottom navbar with previous, current, and next indicators/links. For 
>example:

These are part of the DocBook stylesheets -- I have lifdted them to add them 
to the top of the page for a consistent top and bottom layout. I have no 
idea how difficult this would be to change (I presume it would depend how 
big a change you want...).

>Chapter 1. How to use... ---- Chapter 2. Installation ---- Chapter 3. 
>Tutorial
>(in which only chapter 1 and chapter 2 are links... and no images)

>This gives you the navigation, and an immediate frame of reference for what
>the links mean with regards to your current context.

The style that I have submitted has this kind of layout, but is:

Ch 1 | [Home] | Ch 3
[Prev] | [Up] | [Next]

Ch 2

>About headings...

>The coloring on chapter headings and sections is distracting. The more
>natural, from a typographical point of view, is to left-justify the 
>headers,
>and follow them with indented body text. The headers are already different
>enough from the rest of the text to not really need more highlighting.

I have changed the layout so that only the top-level title has the coloured 
background. But then again, these styles are not set in stone.

>Overall structure...

>I would really prefer to just have one page per chapter. It makes for much
>easier reading to just scroll down the logical sequence of the text, as
>opposed to having to flip back and forth through pages of closely related 
>text.

I suppose that this is a problem of the chunking code; modifying it's 
behaviour would be more trouble than it is worth.

>...To summarize, the current L&F has the style of email communications, not
>book communication.

Have you tried a "print preview" facility: the stylesheet discinguises 
between screen and print media types :). Also, the HTML pages should have a 
more "web" feel to them; the styles do not affect any of the other layouts, 
so the XSL:FO formatting retains its look & feel. But I have taken your 
thoughts into consideration.

Regards,
Reece

_________________________________________________________________
Express yourself with cool new emoticons http://www.msn.co.uk/specials/myemo