docs/144515: [handbook] Expand handbook Table of contents

Fbsd8 fbsd8 at a1poweruser.com
Sat Jan 25 03:54:24 UTC 2014


Thomas Hoffmann wrote:
> On Thu, Jan 23, 2014 at 11:18 AM, Gabor Kovesdan <gabor at freebsd.org 
> <mailto:gabor at freebsd.org>> wrote:
> 
>     On 2014.01.23. 16 <tel:2014.01.23.%2016>:59, Thomas Hoffmann wrote:
> 
>         I agree, the TOC is already too long vertically. Adding
>         subsections would exacerbate the problem.
> 
>         By "horizontal page" I mean taking advantage of the full screen
>         width, for example, by using multi-columns or similar technique.
>         That would get more info on each screen page. Compare the TOC
>         with the x-config.html page (
>         http://www.freebsd.org/doc/en___US.ISO8859-1/books/handbook/x-__config.html
>         <http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/x-config.html>),
>         which uses the full page width.
> 
>     The problem with this is that TOC is a multiple level enumeration by
>     nature, which is conventionally listed vertically in order. Using
>     two columns may be confusing for people since it is not
>     conventional. And if we use 2 columns, what order would it follow?
>     Like this:
> 
>     1        2
>     1.1    2.1
>     1.2    2.2
>     1.3    2.3
> 
>     Or this:
> 
>     1
>     1.1        1.2
>     1.3        1.4
> 
>     And what to do on smaller screens if the two columns do not fit?
> 
>     I believe that a collapsible tree list would be the best option but
>     that requires JavaScript, which we prefer to avoid...
> 
>     Gabor
> 
> 
> Top to bottom, left to right would be the normal "western" approach, no?
> 
> Personally, I would have no problem with a TOC that only listed the 
> major chapters. If you want the details sections/subsections) you would 
> drill (click) down as required:
> 1.        6.
> 2.        7.
> 3         8.
> 4.        9.
> 5.       10.
> 
> or even
> 
> 1.
> 2.
> 3.
> 4.
> 5.
> 6.
> etc.
> 
> It would require less scrolling, but this might be objectionable to many.
> 
> I understand completely your desire to avoid JS.
> 
> This may simply be an intractable problem.
> 
> -Tom


Since the handbook is published using a new tool set, just how does this 
new tool set auto build the TOC?

If I remember correctly there was some posts a while back about forcing 
the publish tool to not build a complete TOC, ie: dropping the 
subsections. Maybe the simple solution is to allow the new tool set to 
build a complete TOC automatically.



More information about the freebsd-doc mailing list