Skip to content

Clarify use of landmarks nav #1788

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 31, 2021
Merged

Clarify use of landmarks nav #1788

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f1da879
clarify uses of landmarks and add recommendation to only use a non-ne…
mattgarrish Aug 27, 2021
15ea01b
add change log entry
mattgarrish Aug 27, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 33 additions & 1 deletion epub33/core/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4558,7 +4558,12 @@ <h5>The <code>landmarks nav</code> Element </h5>

<p>The <code>landmarks</code>
<code>nav</code> element identifies fundamental structural components in the content to
enable Reading Systems to provide the user efficient access to them.</p>
enable Reading Systems to provide the user efficient access to them (e.g., through a
dedicated button in the user interface).</p>

<p>The <code>landmarks</code>
<code>nav</code> element SHOULD contain only a single <code>ol</code> descendant (i.e., no
nested sublists).</p>

<p>The <a href="#sec-epub-type-attribute"><code>epub:type</code> attribute</a> is REQUIRED on
<code>a</code> element descendants of the <code>landmarks</code>
Expand All @@ -4584,6 +4589,29 @@ <h5>The <code>landmarks nav</code> Element </h5>
<code>nav</code> MUST NOT include multiple entries with the same <code>epub:type</code>
value that reference the same resource, or fragment thereof.</p>

<p>EPUB Creators should limit the number of items they define in the <code>landmarks</code>
<code>nav</code> to only items that a Reading System is likely to use in its user interface.
The element is not meant to repeat the table of contents.</p>

<p>The following landmarks are recommended to include when available:</p>

<ul>
<li><a href="#bodymatter"><code>bodymatter</code></a> &#8212; Reading Systems often use this
landmark to automatically jump users past the front matter when they begin reading.</li>
<li><a href="#toc-1"><code>toc</code></a> &#8212; If the table of contents is available in
the spine, Reading Systems may use this landmark to take users to the document
containing it.</li>
</ul>

<p>Other possibilities for inclusion in the <code>landmarks</code>
<code>nav</code> are key reference sections such as indexes and glossaries.</p>

<p>Although the <code>landmarks</code>
<code>nav</code> is intended for Reading System use, EPUB Creators should still ensure that
the labels for the <code>landmarks</code>
<code>nav</code> are human readable. Reading Systems may expose the links directly to
users.</p>

<p>The <code>landmarks</code>
<code>nav</code> element is OPTIONAL in EPUB Navigation Documents and MUST NOT occur more
than once.</p>
Expand Down Expand Up @@ -9373,6 +9401,10 @@ <h2>Change Log</h2>
>Working Group's issue tracker</a>.</p>

<ul>
<li>27-Aug-2021: Add clarifications for including landmarks, such as limiting the number, recommending
known semantics, and ensuring the labels are human readable. Also added recommendation to not
include nested lists to match the page list. See <a
href="https://github.com/w3c/epub-specs/issues/1761">issue 1761</a>.</li>
<li>22-July-2021: Clarified TTS handling of images in media overlays. See <a
href="https://github.com/w3c/epub-specs/issues/1745">issue 1745</a>.</li>
<li>09-July-2021: Restored the custom attributes section due to known usage but without reference to the
Expand Down