OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [docbook-apps] Frames like HTML view of TOC and document


I use a persistent TOC for all of my HTML output.  I've adapted it for use w/ DocBook, and it works well, although I've done a little hacking to make DocBook play nice w/ contemporary CSS (I'm looking forward to Bob's updates there).

My advice is to use Divs and CSS to create your page. Leave frames behind; for all the usual reasons: bad SEO, ugly layout, uncontrollable following, etc.

I probably do the inelegant thing quite often with my solution, especially for the DocBook end of things, but here's what I do:

1. Create two Divs and position them on the page with CSS. Like this: 

HTML:  <div id="content">...</div> and <div id="toc">...</div>
CSS: DIV#content {
			top: 0;
			left: 2em;

DIV#toc {
	top: 25px;
	right: 2em; 


You'll need to add margin and padding, width min/max and possibly z-index etc to suit your needs, of course...

2. Use an include to pull in the TOC content. This way you write one TOC file and push it to as many pages as you like. I use PHP includes, but you can use SSI includes just as well.  
	<?php include("assets/includes/toc.html"); ?>

3. If you want to collapse and expand your TOC, use JavaScript. I like Matt Kruse's code: http://www.JavascriptToolbox.com/

4. Create your custom .xsl for DocBook. This is where I get fairly hacky and there's likely a better way, but...

Chunk the output:

<xsl:import href="chunk.xsl"/>

I like to use xml:ids for filenames:
<xsl:param name="use.id.as.filename" select="1" />

Yes, please indent output so it's nominally readable:
<xsl:param name="chunker.output.indent">yes</xsl:param>

Get rid of inline styling whenever possible. This turns off inline styles for tips, notes, cautions, and importants, I think -->
<xsl:param name="admon.style" select="0" />

Point to my own stylesheet, thank you:
<xsl:param name="html.stylesheet" select="'../assets/mystyle.css'"/>

I need my Table of Contents to output as <ul>
<xsl:param name="toc.list.type">ul</xsl:param>

Please create IDs: 
<xsl:param name="generate.id.attributes" select="1"></xsl:param>

5. I then use CSS to turn off a few things in DocBook. For example my TOC only needs the first two levels of the nested <ul>, so I turn off the rest w/ a display:none.

6. When I post the help, I have to copy the generated TOC from DocBook and paste it into my prepared file.  That's the only part that isn't automated.

That's a bare bones look, and there are a few other niggling things, but that should give you some ideas, at least.


On Dec 4, 2009, at 10:50 PM, Aaron Larson wrote:

> I'm new to the list, but a longtime (closet?) DocBook user.  For a
> number of years one of the customizations that I've maintained is a
> script and javascript that permits a DocBook document to be viewed in
> a frames environment with the table of contents on the side, and the
> document next to it:
>  1. Intro          |  The main part of the document goes here
>    1.1 bla         |  and on and on.
>  2. Good stuff     |
>   + hidden toc part|  Etc.
>                    |
> Having the toc always visible certainly makes navigating the document
> more pleasant.  The toc can have sections collapse and expand etc.
> Looks very nice, but HTML frames implementation is undesirable.  I
> started looking at converting my frames to CSS, but there are lots of
> issues:
>  1. Resizing browser frames is handled by the browser, CSS requires
>     javascript.
>  2. CSS cross browser vagaries
>  3. The DocBook HTML structure is causing my css some gas.
>  4. etc.
> I started looking at various javascript frameworks to get the job
> done, then decided I should find out if someone has done something
> like what I'm attempting.  I didn't find anything, so I'm asking.
> Anyone have something that provides good TOC navigation aids for
> DocBook documents viewed as HTML?  Any better/ alternative ideas?
> Aaron.
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]