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

From: Vladimir Prus (ghost_at_[hidden])
Date: 2004-02-10 03:10:33

Rene Rivera wrote:

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

I don't think there's anything wrong with putting some introduction before 
TOC.

There's conflict of interest between new user and existing user. New user 
looks and toc and thinks "ok, where should I look?". Old user looks at 
introduction and thinks "I want docs on 'exe' rule, where's my TOC?".
(That's why I think about some Boost library docs). 

Short introduction followed by TOC is the best of all words.

> But having the TOC at each page
> is distracting and superfluous. I would recommend, and prefer, having only
> one detailed TOC.

I disagree. Chapter TOC sometimes happen in books, too -- TC++PL is the first 
example which comes to mind.

The problem with on TOC is that if we represent all nesting there, it will be 
huge. So user will have problems finding the right section. With two-level 
scheme, main toc can list only chapters and sections.

> > I have been working on getting navlinks at the top (which will be
> > available when they get checked in). There was a few comments about
> > retaining some of the original look & feel, so I tried to keep the top as
> > close to the original as I could.
>
> About the navbar...

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

IMO, background for chapters/section is nice.

> 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 think this should be customizable in Docbook. We really need to settle 
logical structure first, though. For example, I plan to split the "Advanced" 
chapter into "Writing Jamfiles", "Configuration", and "Invocation" section, 
moving some material from other chapters. It might make the chapter too long, 
or not -- need to see.

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

But it's HTML, I suspect that PDF output will have more of a book look.

- Volodya