[css-content] improve bookmark definitions, see #204

Author: dauwhe

css-content/Overview.bs

@@ -986,9 +986,11 @@ Automatic counters and numbering: the 'counter-increment' and 'counter-reset' pr
 <h2 id="bookmark-generation">
 Bookmarks
 </h2>
-Some document formats, most notably PDF, allow the use of <dfn>bookmarks</dfn> as an aid to navigation. Bookmarks provide a hierarchy of links to document elements, as well as text to label the links. A bookmark has three properties: 'bookmark-level', 'bookmark-label', and 'bookmark-state'.
+Some document formats, most notably PDF, allow the use of <dfn>bookmarks</dfn> as an aid to navigation. 
+Bookmarks provide a list of links to document elements, as well as text to label the links and a level value.  
+A bookmark has three properties: 'bookmark-level', 'bookmark-label', and 'bookmark-state'.
 
-A bookmark references that element in the document. When a user activates a bookmark, the user agent must bring that reference point to the user's attention, exactly as if navigating to that element by fragment URL. <span class="note">This will also trigger matching the '':target'' pseudo-class.</span> 
+When a user activates a bookmark, the user agent must bring that reference point to the user's attention, exactly as if navigating to that element by fragment URL. <span class="note">This will also trigger matching the '':target'' pseudo-class.</span> 
 
 <h3 id="bookmark-level">
 bookmark-level
@@ -1008,7 +1010,7 @@ Computed value: specified value
 </pre>
 <dl dfn-type="value" dfn-for="bookmark-level">
 <dt>&lt;integer>
-<dd>defines the level of the bookmark, with the highest level being 1 (negative and zero values are invalid).
+<dd>defines the level of the bookmark, with the top level being 1 (negative and zero values are invalid).
 <dt>none
 <dd>no bookmark is generated.
 </dl>
@@ -1022,6 +1024,11 @@ section section section h1 { bookmark-level: 3; }
 
 </div>
 
+  Note: Bookmarks do not need to create a strict hierarchy of levels. 
+
+
+  Issue: Should a bookmark be created for elements with <code>display: none</code>?
+
 
 <h3 id="bookmark-label">
 bookmark-label
@@ -1065,7 +1072,7 @@ The bookmark label will be “Loomings”.
 <h3 id="bookmark-state">
 bookmark-state
 </h3>
-Bookmarks typically toggle open and closed, with the open state displaying the next level of bookmarks.
+The 'bookmark-state' may be open or closed. The user must be able to toggle the bookmark state.
 
 <pre class="propdef">
 Name: bookmark-state
@@ -1079,9 +1086,9 @@ Computed value: specified value
 </pre>
 <dl dfn-type="value" dfn-for="bookmark-state">
 <dt>open
-<dd>The bookmarks of the nearest descendants of an element with a bookmark-state of open will be displayed.
+<dd>Subsequent bookmarks with 'bookmark-level' greater than the given bookmark are displayed, until reaching another bookmark of the same level or lower. If one of subsequent bookmark is closed, apply the same test to determine if its subsequent bookmarks should be displayed.
 <dt>closed
-<dd>any bookmarks of descendant elements are not initially displayed.
+<dd>Subsequent bookmarks of bookmark-level greater than the given bookmark are not displayed, until reaching another bookmark of the same level or lower. 
 </dl>
 
 Issue: is the initial bookmark state, or the bookmark state updated by the UA as appropriate?