[css-content] Generation of bookmarks from CSS is not defined

[lrosenthol]

https://www.w3.org/TR/css-content-3/#bookmark-generation

There is no guidance given for how to produce a "bookmark tree" from a given set of CSS with Bookmark references.

Is the tree to be produced in the order that the content appears in the HTML? The order of definitions in the CSS? Other? What about if there are "sub-documents" with CSS references - for example, embedded SVG or even HTML in an iFrame? What about the level - is that relative the previous item (and if so, in what order)? What if you find a 2 before a 1, what is the expected behavior?

[dauwhe]

Is the tree to be produced in the order that the content appears in the HTML? The order of definitions in the CSS? Other?

The tree should appear in document order.

What about if there are "sub-documents" with CSS references - for example, embedded SVG or even HTML in an iFrame?

At least one implementation just ignores iframes. I don't currently have a use case for including bookmarks from external documents.

What about the level - is that relative the previous item (and if so, in what order)? What if you find a 2 before a 1, what is the expected behavior?

I don't think it should be relative to previous items. The document author controls bookmark level via CSS, but user agents choose to how to expose and display the bookmarks to users. For the purposes of the spec, level really only matters for determining which bookmarks are hidden when a bookmark is set to closed.

So if the first bookmark in a document has level 2, it is just displayed as a bookmark. It will never be closed, as there won't be a nearby previous element with lower bookmark level.

I'll work on adding spec prose.

[lrosenthol]

The tree should appear in document order.

Document order after execution of any/all scripts? So the "final DOM", if you will, for the document? Or the order as originally parsed, before execution?

(I'd prefer the final version, but as long as the spec is clear, I could live with either)

At least one implementation just ignores iframes. I don't currently have a use case for including bookmarks from external documents.

OK - I think that's perfectly fine. If you could make this clear in the spec, that would be helpful.

What about the level - is that relative the previous item (and if so, in what order)? I don't think it should be relative to previous items. The document author controls bookmark level via CSS, but user agents choose to how to expose and display the bookmarks to users.

If a level 2 is "subordinate" to level 1 (as I would expect it to be), how does a UA know which is the parent? It's not explicit in the CSS and there is no clue given in the spec. That was why I would ASSUME that its the previous one with the lower level (eg. 1 < 2). However, this needs to be stipulated in the spec so UAs can produce consist results.

For the purposes of the spec, level really only matters for determining which bookmarks are hidden >when a bookmark is set to closed.

But how does the UA know what the "set" is? A set is defined (IMO) as "all the children of a given parent" - so how does the UA know the parent?

What if you find a 2 before a 1, what is the expected behavior? So if the first bookmark in a document has level 2, it is just displayed as a bookmark. It will never be closed, as there won't be a nearby previous element with lower bookmark level.

but what is its parent??

[tabatkins]

Document order after execution of any/all scripts? So the "final DOM", if you will, for the document? Or the order as originally parsed, before execution?

CSS has no notion of document mutation (besides the hacked-in time/state management of Transitions and Animations); as far as it's concerned, the document is stable and has always been in that state, and if anything changes, it's always been in that new state.

OK - I think that's perfectly fine. If you could make this clear in the spec, that would be helpful.

Iframes are replaced elements, which CSS explicitly has no control over nor gets any information from besides sizing, unless otherwise explicitly specified. So we don't need to say anything special here; bookmark info just doesn't come from those.

[bradkemper]

bookmark-level doesn't seem like styling to me. It seems more like structure, and therefore aught to be in the markup language somewhere, as attributes maybe, or as a separate JSON or XML document or something. It isn't actually setting the presentation of the document content; it's providing structural information for something outside the document. Then 'bookmark-label' styles that outside thing with content.

[dauwhe]

I would argue this provides information to the user agent on how to present the document, which seems in scope for CSS. And there are at least four implementations.

[lrosenthol]

I have to agree with @bradkemper - this has nothing to do with presentation or styling. Putting them in CSS is a workaround to address the fact that the CSS committee is willing to make the necessary changes, while the HTML one will not.

Bookmarks (esp. in PDF, where the implementations you mention are focused) are entirely about navigation. This is clear from the fact that the sub-clause about them (12.3.3) is in Clause 12 (Interactive Features), Sub-Clause 3 (Document-Level Navigation).

Are there any HTML-based implementations?

[frivoal]

By HTML implementation, do you mean implementations of this CSS features that work on HTML? As far as I know, all the implementations support it for the CSS+HTML combo.

We (Vivliostyle) are also planning on supporting it, because there are multiple implementations of it, content to be compatible with, and market demand for it. And since our engine does not only render to PDF, but also to screen, we will be supporting it in both cases.

Whether believe it to be a great design or not, or whether it should have been added to something else than CSS is moot for us at this point. Standardization is here to unsure interoperability. This is a feature implemented as part of the CSS language by multiple parties, and interop is desirable.

[bradkemper]

@dauwhe It provides information to the user agent on how to present the document in about the same way that list-item embedding levels does.

@frivoal I understand your need to support it. It is similar to the need of browsers to support -webkit-* prefixes. But there should be a better way that we move towards.

[faceless2]

I agree with @dauwhe that the current specification for bookmarks is complete, works, and is widely implemented.

However I do have a beef with the syntax, which is that bookmark levels have to be specified explicitly. All the examples look a bit like this:

section h1 { bookmark-level: 1 }
section section h1 { bookmark-level: 2 }
section section section h1 { bookmark-level: 3 }
section section section section h1 { bookmark-level: 4 }
section section section section section h1 { bookmark-level: 5 }

which is a little absurd. If we were specifying this for the first time now that's not the approach we'd take, but we're stuck with it due to shipping implementations. But can we augment this to make managing large documents, in particular those assembled from multiple smaller ones before processing, a little easier?

I'd like to propose changing the syntax from

bookmark-level: none | <integer>

to

bookmark-level: none | <integer> | add(<integer>)

With "add" being defined as "add the specified value to the bookmark-level of the nearest ancestor that has a value other than "none". If no such ancestor exists, the values is added to 0"

This would allow you to change the structure above to

section { bookmark-level: add(1); bookmark-label: none }
h1 { bookmark-level: add(0); }

It's slightly complicated because bookmark-level is not an inherited property, and bookmark-label doesn't default to none - so you can't simply have values like increment and inherit. But traversing up the tree is something we do elsewhere (i.e. the concept of the decorating style for underlining), and the proposed syntax isn't unique (the proposed math-script-level property, which I believe is largely accepted.

Finally, existing implementations will simply not recognise this syntax as valid, and ignore it - the "legacy" explicit levels can exist earlier in the same stylesheet, as a fallback.

Values of add(-1) or add(99) woudn't make much sense, but as they collapse to an integer value their behaviour is already specified.

---

EDIT: given the only really useful values are "increment by one" or "increment by zero", an alternative would be something like bookmark-level: increment and bookmark-level: copy, or some other word that means inherit.