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

On May 27, 2012, at 10:41 AM, Simon Sapin wrote:

> Le 24/05/2012 18:30, Brad Kemper a écrit :
>> I'd be happy if it described what you are supposed to do with this
>> property. What's its effect?
> 
> 
> Quoting http://dev.w3.org/csswg/css3-gcpm/#bookmarks
> 
>> Some document formats have the capability of holding bookmarks.
>> Bookmarks are typically shown outside the document itself, often a
>> tree-structured and clickable table of contents to help navigate in
>> the electronic version of the document.
> 
> Bookmarks are called outlines in the PDF spec. They are organized in a tree structure. Each entry has a textual label and points to a specific position in the document encoded as (page_number, X, Y). Clicking makes the viewer display the document at that position.
> 
> 
> The GCPM spec is indeed lacking on details. This is how we filled the blanks when implementing it in WeasyPrint:
> 
> For each element where the computed value of neither bookmark-level or bookmark-label is 'none', generate a bookmark entry. 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.)
> 
> 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".
> 
> 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.

Thank you for the explanation and example. It is much more clear to me now. 

> 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".

I suppose that can be up to the UA, but it seems like it would not always be what the author intended, and may cause problems if the document is changing via script. I'd think that sometimes a level 2 might be reserved for a label that is sometimes there in between a section heading and a chapter heading, but not for every section. I'd still want all the chapter headings to line up in the Table of Contents.

I think part of my problem is that I am jumping ahead to thinking of how to style the TOC, and that isn't part of this spec. I realize that would often be outside of the control of the author, but perhaps sometimes not? I think a :toc pseudo-class would be nice for styling the actual bookmark tree.

> 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.

This is still unclear to me. You mean that when you click on the element in the generated bookmark tree, then the H1 (or whatever) is scrolled into view, to be shown in the upper left corner?

> We did not implement bookmark-target because we did not understand what it is supposed to do.

The example is confusing, given that it is a hyperlink. Perhaps it is for when you want the generated TOC to include some of the document's links to other documents.

> (And bookmark-state because we did not need it yet.)

This is for when the bookmark is like a disclosure element?

Received on Sunday, 3 June 2012 02:06:30 UTC