CSS-positioned TOC [was: Frame based html [was: Preventing indenting of toc in frame doc.]]

[Michael Smith <smith@xml-doc.org>]

Doug du Boulay <ddb@owari.msl.titech.ac.jp> writes:

> On Saturday 06 November 2004 20:54, Paul Taylor wrote:
> > I am creating a frame based document, which contains the table of
> > contents on the lhs and the main document on the right handside. 
> 
> Hi,
> 
> I'm curious to know was this a one-off transformation or are frame based 
> tocs a common html rendering for docbook documents? 
> Could someone point me to some examples?

"HTML Frameset" section in Bob Stayton's book -

  http://www.sagehill.net/docbookxsl/HtmlFrames.html

> What would be the pros and cons of any frame based styles versus the 
> tabular style used in docbook-website?

There is a a third, better, way: CSS

Take a look at the following simple example:

  http://docbook.sourceforge.net/css-example/

That is HTML output generated from the current DocBook XSL
stylesheets, with no mods to the code and no post-processing
(other than running it through tidy to indent it) -- though with
one significant non-default parameter -

  <xsl:param name="toc.list.type">ul</xsl:param>

That causes the list styling in the TOC to be ul/li instead of
dl/dt+dd.

Do "View Source" on that index page, and you will see that it's
the same as what you'd get if you generated it yourself.

All that I did was to add an external CSS stylesheet which:

  - causes the div that the TOC is in to be absolutely positioned
    on the left-most side of the page; and

  - causes the rest of the body of the page to be positioned
    starting a certain distance over from the left - so it falls
    to the right of the TOC

The CSS stylesheet that does that is at:

  http://docbook.sourceforge.net/css-example/style.css

A minimal CSS stylesheet for just the positioning is:

  body {
    margin: 0px 1em 0 13em;
  }

  div.toc {
    border-right: 1px dotted #ccc;
    padding: 0px 0 0 10px;
    position: absolute;
    left: 2px;
    top: 0; 
    width: 11em;
  }

That is nothing new -- it's the mechanism that many blogs use to
position the "menu" stuff and the mechanism that gurus from List
Apart and elsewhere have been promoting for years for doing
multi-column layouts without HTML tables.

As far as the current use of it with DocBook output: One
limitation is that the master TOC is available only on the
index/start page. Other chunks get either a blank left-hand pane
or get a TOC for just their sub-portion.

For the TOC to be rendered on each page, it would need to be part
of the HTML content of each generated page. I think it might be
possible to implement that as an option for a future DocBook XSL
stylesheets release.

I think there's a lot more that someone with better CSS chops than
me could do to refine it. Maybe we can manage to put together a
default "DocBook CSS" stylesheet for handling this and some other
other CSS formatting things discussed on docbook-apps recently.

There is even a pure-CSS way to make the TOC collapsible. It
doesn't work with IE but does work as expected with Gecko browsers
(Mozilla, Firefox, Safari). Take a look at:

  http://docbook.sourceforge.net/css-example/collapse.html

The minimal CSS stylesheet for doing that is:

  /* collapsible TOC */
  div.toc li ul {
    display: none;
  } 
  div.toc li:hover > ul {
    display: block;
  }

It relies on mouse-overs to expand the TOC, rather than click
actions. I think that handling change of state on click actions is
something that CSS can't do -- client-side scripting with
Javascript or something is needed instead.

smime.p7s