W3C home > Mailing lists > Public > www-style@w3.org > August 2012

Re: [css3-gcpm] bookmark-label: keyword definitions and whitespace processing

From: Simon Sapin <simon.sapin@kozea.fr>
Date: Fri, 17 Aug 2012 16:15:46 +0200
Message-ID: <502E5212.8050106@kozea.fr>
To: Håkon Wium Lie <howcome@opera.com>
CC: Brad Kemper <brad.kemper@gmail.com>, "www-style@w3.org" <www-style@w3.org>
Le 16/08/2012 15:59, Håkon Wium Lie a écrit :
>   > For each element where the computed value of neither bookmark-level or
>   > bookmark-label is 'none', generate a bookmark entry.
> Isn't is sufficient that 'bookmark-label' is different from 'none'?
> In a simple book with several consecutive chapters, you'd want to say:
>    h2 { bookmark-label: contents }
> And not having to say:
>    h2 {
>      bookmark-label: contents;
>      bookmark-level: 2
>    }

You mention below that h1..h6 get a bookmark-label value in the HTML UA 
stylesheet. I think it’s hard to generate a bookmark if bookmark-level 
is none. Where would you put it in a PDF outline tree, for example?

>   > The used value of
>   > bookmark-label is as described for the string-set property, with the
>   > text taken *after* white space processing (according to the white-space
>   > property.)
> According to the white-space value of the element in question?

Yes. This is what I implemented, but it could change.

> I'd probably suggest always processing white-space as if 'white-space:
> normal' had been set on the label.

I don’t see a strong argument either way. 'normal' is the initial value 
so headings rarely have another value for white-space anyway.

>   > By the way, I think that the initial value of bookmark-label should be
>   > 'contents', not 'none'. Actually I’m not even sure that 'none' is ever
>   > useful. 'bookmark-level: none' (the initial) is enough to say "this
>   > element does not generate a bookmark".
> I agree that 'bookmark-level' can be used as the on/off switch for
> bookmarks, but I'd probably prefer to use 'bookmark-label' as the
> switch. This way one can have (say) this in the default style sheet:
>    h1 { bookmark-level: 1 }
>    h2 { bookmark-level: 2 }
>    h3 { bookmark-level: 3 }
> without triggering the generation of bookmarks. Bookmarks can then be
> switched on with:
>    h1, h2, h3 { bookmark-label: contents }
> (or something)
> Thus, one can turn on bookmarks with one declaration rather than
> having to use (and remember) many levels.

If no bookmark is generated by default I agree that it is interesting 
for authors not to have to specify levels explicitly. But in WeasyPrint 
we chose to have h1..h6 generate bookmarks by default. (Again, nothing 
set in stone.) In that case, opting-out is also easy:

     /* Limit bookmarks to 3 levels */
     h4, h5, h6 { bookmark-level: none }

>   > bookmark-level specifies what "depth" this entry is supposed to be at,
>   > in the bookmark tree. The UA stylesheet for HTML has something like this:
>   >
>   > h1 { bookmark-level: 1 } /* ... */ h6 { bookmark-level: 6 }
>   >
>   > The order of the generated bookmarks is always the same as the tree
>   > order of the corresponding elements. If the values of bookmark-level are
>   > inconsistent (for example a level 1 entry followed by a level 3, without
>   > a level 2 in-between) the levels are adjusted somehow to make a proper
>   > tree without "holes".
> This requires more intellingence than we should expect from
> implementations, no? (A similar rule for elements would convert all h3
> elements into h2 if no h2 element was found.)

I was only describing our implementation. I think it is good to leave 
such details unspecified so that implementation can but do not have to 
make a smart algorithm for broken pages.

>   > The bookmark "target" is a single point. We picked the before-start
>   > corner (top-left in horizontal-tb ltr) of the margin edge of the first
>   > box/fragment generated by the element.
> That seems reasonable. Is this what browsers do?

Actually I switched from margin box to border box after writing the 
quoted emails:


I do not know of a browser that implements bookmarks, but the closest is 
internal hyperlinks. Apparently browsers scroll the top of the *border 
box* to the top of the viewport (assuming a box far enough from the top 
and bottom of the document.) Horizontally things are more subtle. If the 
box is narrower than the viewport, browsers scroll horizontally as 
little as possible so that the whole width of the border box is visible.

But in PDF we do not have such fine-grained control: the targets for 
outlines and internal hyperlinks is a single (X, Y) point on a page.

Simon Sapin
Received on Friday, 17 August 2012 14:16:14 UTC

This archive was generated by hypermail 2.4.0 : Friday, 25 March 2022 10:08:20 UTC