Re: WANTED: Design for documentation

[Patrick McCarty]

On Tue, Jul 22, 2008 at 10:22 AM, Reinhold Kainhofer
<address@hidden> wrote:
> Am Dienstag, 22. Juli 2008 schrieb Patrick McCarty:
>>
>> ** I moved the "tocframe" div to the top of the body
>
> Hmm, I put the tocframe at the bottom on purpose, because otherwise browsers
> with CSS turned off (or browsers that don't support absolute positioning)
> will print the whole TOC before the contents and the user has to scroll
> wayyyy down to get to the real contents of the page. Try it out in
> firefox: "View" -> "Page Style" -> "No Style" will turn off CSS support and
> format the html without the css. Also, I suppose that screen readers and
> similar devices will probably be fooled by a long list at the top of the
> page. In particular, for blind users reading the docs will be even harder if
> every page starts with dozens of irrelevant TOC entries...
>
> One of the credos of good CSS design is that the page should also look okay
> with CSS turned off, so I'd prefer a solution where the TOC can be placed
> after the contents in the HTML file. On the other hand, the other (and even
> more important) idea of good CSS design is that the page should look with CSS
> turned on. It seems that IE doesn't allow both, so I suppose I'll just have
> to bite the grape and move the TOC before the contents :(

A trick I use is to include an anchor above the TOC that says "Skip
Navigation", and then use CSS to make it invisible, like so:

#skip {
  margin:0;
  padding:0;
  width:0;
  height:0;
  overflow:hidden;
}

This anchor can link to div#main further down the page.  Using
visibility:hidden hides the line from screen readers, so using the
above rules is a better solution.

Try viewing this without styles to see what I mean:

http://uoregon.edu/~pmccarty/texi2html/

That being said, this still is not the perfect solution because the
first item on the page is "Skip Navigation", which does not uniquely
identity the page.  Having the h1 header near the top is better.

I will experiment more with the TOC at the end of the body, as you
currently have, since it seems like a better solution.  But placing
the TOC at the top of the body is so much easier to implement in IE!
Oh well.

Thanks,
Patrick