Clarify NCX Reading System Requirements
| Project: | EPUB Maintenance |
| Component: | Open Packaging Format (OPF) |
| Category: | task |
| Priority: | normal |
| Assigned: | MGylling |
| Status: | accepted |
Jump to:
Section 2.4.1.2 of the OPF spec succinctly states "Reading Systems must support NCX."
I believe our original intent on this statement needs to be clarified since it is quite ambiguous (and if there is no understood original intent, to hash it out.)
For example, are Reading Systems required to present to the end-user a linkable table of contents generated from the primary navMap? And are Reading Systems required to present a link list for the optional navList and pageList?
The proposed resolution is to, in the 2.01 release of the OPF spec, make the following mods to section 2.4.1:
1) Rename the section title from "Declarative Table of Contents — the NCX" to "Declarative Global Navigation - the NCX"
2) In 2.4.1.2, extend the "OPS Publications must include an NCX" entry to include prose that clarifies
-- that the navMap is a required element in the NCX and that it provides navigational access to the major hierarchical structure of the book,
-- that the pageList must be included if the publication is designed to allow the user to navigate to pages,
-- and that one or several navLists may be included to allow navigation to other arbitrary constructs in the content (and refer to the example in 3 below).
3) Add an informative NCX example (see [3]). This means that the "Examples show links..." bullet in 2.4.2 can be removed.
4) clarify that the URI of the content element for navMap, pageList, and navLists alike resolves to OPS content document fragments
5) In section 2.4.2, change the next-last bullet ("The required NCX metadata items ...") to say that the list of required metadata given in [2] does not apply in EPUB; the only required meta item is that which contains a reference to the OPF UID; and for backwards compatibility reasons the name of that meta item remains "dtb:uid". (Note that content-wise, this is a backwards compatible clean-up change, and last I checked, EpubCheck does not check for the other ones, <meta name="dtb:depth"/> etc)
6) Replace 2.4.1.2 first sentence with the below (or create a dedicated section for it, making current 2.4.1.2 be about publication reqs only):
A Reading System should have the ability to, at user option, provide the user access to the NCX navMap in a fashion that allows the user to activate the links provided in the navMap, thus relocating the applications current reading position to the destination described by the selected NCX navPoint. The behavioral expectations described above apply to the NCX pageList and navList elements as well, if the given NCX contains said elements. Reading System implementors should be aware that in the forthcoming major revision of the EPUB specification, it will become a compliance criterion for Reading Systems to support the NCX navMap, pageList and navList as described above.
7). Changes that are really triggered by the making of @playOrder optional (see playorder-attribute-epub):
* change to the last bullet of section 2.4.2 (no more "remains required")
* remove of the sentence "No modifications to the DTD are necessary for use with OPF" in 2.4.1,
* change the sentence "The NCX file must be a valid XML document conforming to ncx-2005-1.dtd..." in 2.4.1.2; this is since if the NCX omits the now-optional playOrder attribute, it can no longer contain a DOCTYPE that references the canonical ANSI/NISO DTD. Change to "The NCX file must be a valid XML document conforming to ncx-2005-1.dtd, with the exception of the playOrder attribute, which is optional in EPUB NCX." The last part of the original sentence "and comply with the additional normative requirements..." is removed.
* Add (as discussed on the 2010-02-02 call) a note that clarifies that any NCX that contains a DOCTYPE that references the canonical NCX DTD must honor that DTD, thus including the playOrder attribute on all locations where it is required. NCX documents that do not contain a DOCTYPE may or may not include the playOrder attribute.
[1] http://www.daisy.org/epub/issues/playorder-attribute-epub
[2] http://www.niso.org/workrooms/daisy/Z39-86-2005.html#NavMeta
[3] Example illustrating an NCX with a navMap, a pageList, and a navList containing a list of illustrations:
<ncx xmlns="http://www.daisy.org/z3986/2005/ncx/" version="2005-1" xml:lang="en-US">
<head>
<meta content="org-example-5059463624137734586" name="dtb:uid"/>
</head>
<docTitle>
<text>Selections from "Great Pictures, As Seen and Described by Famous Writers"</text>
</docTitle>
<docAuthor>
<text>Esther Singleton</text>
</docAuthor>
<navMap>
<navPoint class="h1" id="ch1">
<navLabel>
<text>Chapter 1</text>
</navLabel>
<content src="content.html#ch_1"/>
<navPoint class="h2" id="ch_1_1">
<navLabel>
<text>Chapter 1.1</text>
</navLabel>
<content src="content.html#ch_1_1"/>
</navPoint>
</navPoint>
<navPoint class="h1" id="ncx-2">
<navLabel>
<text>Chapter 2</text>
</navLabel>
<content src="content.html#ch_2"/>
</navPoint>
</navMap>
<pageList>
<pageTarget id="p1" type="normal" value="1">
<navLabel><text>1</text></navLabel>
<content src="content.html#p1"/>
</pageTarget>
<pageTarget id="p2" type="normal" value="2">
<navLabel><text>2</text></navLabel>
<content src="content.html#p2"/>
</pageTarget>
</pageList>
<navList>
<navLabel>
<text>List of Illustrations</text>
</navLabel>
<navTarget id="ill-1">
<navLabel><text>Portratit of Georg Gisze (Holbein)</text></navLabel>
<content src="content.html#ill1"/>
</navTarget>
<navTarget id="ill-2">
<navLabel><text>The adoration of the lamb (Van Eyck)</text></navLabel>
<content src="content.html#ill2"/>
</navTarget>
</navList>
</ncx>
Comments
#1
I am pretty sure that we never discussed importing any feature other than table of content from NCX and the language in the spec is not sufficient to cover other uses. The result is a very ambiguous specification that is read differently by different people. If other features (page lists and navigation lists) are envisioned to be used with EPUB, at the minimum the following should be done:
This section of the spec caused us a lot of problems. I would prefer it completely reworked with normative description in EPUB spec itself, not in DTBook + list of changes, as the use context in DTBook differs significantly.
#2
I agree with Peter that we need to fully explain the NCX in terms of its role in OPF/ePub, and not leave any ambiguities as we have by referencing DTBook+changes. That is, OPF should provide sufficient information for producing a conforming NCX without having to refer to any DTBook spec. (Or, alternatively, to produce a special NCX specification separate from both OPF and DTBook.)
Among several issues to resolve is Reading System conformance when presented with an NCX.
Since NCX is an integral component of DAISY's DTBook, it is important for the DAISY folk to provide what they believe should be ePub Reading System requirements when presented with a conforming NCX, and of course what features (if not all of them), ePub should support.
#3
#4
First, regarding Peter's view that only navMap is the supported part of the NCX in Epub -- it is indeed unfortunate that this obscurity slipped through. Note however that section 2.4.1.1 (last sentence of last para) reads "Other elements such as pages, footnotes, figures, tables, etc. can be included in separate, nonhierarchical lists and can be accessed by the user as well."
What can we do in the short term to remedy this? I would assume that a major overhaul of this section (not using the diff method as suggested), is matter for the next EPUB revision. As mentioned also in the playorder issue [1], the forthcoming modularization of NCX will mean that in the next revision of EPUB, we can define our own version of the NCX grammar, do so properly by owning the driver schema, and define it in terms of itself instead of in relation to how it differs from DAISY NCX usage.
In the short term, would an errata for section 2.4.1, including the changes listed below, suffice?
1) rename the section title from " Declarative Table of Contents — the NCX" to "Declarative Global Navigation - the NCX"
2) In 2.4.1.2, extend the "OPS Publications must include an NCX" entry to include prose that clarifies
-- that the navMap is required and that it provides navigational access to the major hierarchical structure of the book,
-- that the pageList must be included if the Publication is designed to allow the User to navigate to pages,
-- and that 0-n navLists may be included to allow navigation to other arbitrary constructs in the content.
3) clarify globally that the URI of the content element for navMap, pageList, and navLists alike resolves to OPS content document fragments
4) See also this issue: [2], which is also an errata for this section
Regarding reading system conformance; I dont really have a strong opinion on what to require here. Suggestions welcome. The current sentence reads "Reading Systems must support NCX". Longer term, do we really want it to be illegal for a reading system to not offer any navigation features? Anyway, I would suggest clarifying to something along the lines of "Reading Systems must provide means for the User to utilize the NCX navigation features".
[1] http://www.daisy.org/epub/issues/playorder-attribute-epub
[2] http://www.daisy.org/epub/issues/section-2412-uses-phrase-if-publication-includes-ncx-which-implies-it-optional
#5
Below's an update of the change proposal. Needs further group discussion re Reading System requirements and the NCX (item 6 below).
The proposed resolution is to, in the next maintenance release of the OPF spec, make the following mods to section 2.4.1:
1) Rename the section title from "Declarative Table of Contents — the NCX" to "Declarative Global Navigation - the NCX"
2) In 2.4.1.2, extend the "OPS Publications must include an NCX" entry to include prose that clarifies
-- that the navMap is a required element in the NCX and that it provides navigational access to the major hierarchical structure of the book,
-- that the pageList must be included if the publication is designed to allow the user to navigate to pages,
-- and that 0-n navLists may be included to allow navigation to other arbitrary constructs in the content.
3) Add an informative NCX example (see [3]). This means that the "Examples show links..." bullet in 2.4.2 can be removed.
4) clarify that the URI of the content element for navMap, pageList, and navLists alike resolves to OPS content document fragments
5) In section 2.4.2, change the next-last bullet ("The required NCX metadata items ...") to say that the list of required metadata given in [2] does not apply in EPUB; the only required meta item is that which contains a reference to the OPF UID; and for backwards compatibility reasons the name of that meta item remains "dtb:uid". (Note that content-wise, this is a backwards compatible clean-up change, and last I checked, EpubCheck does not check for the other ones, <meta name="dtb:depth"/> etc)
6) @@@ Need decision on what to do with Reading System requirements (2.4.1.2 first sentence)
Note that this proposal as well as the resolution to make the playOrder attribute optional [1] results in a breakage towards the canonical NCX DTD, and the normative prose in the Z39.86-2005 specification. We
* need to change to the last bullet of section 2.4.2 (no more "remains required")
* need to remove of the sentence "No modifications to the DTD are necessary for use with OPF" in 2.4.1,
* need to change to the sentence "The NCX file must be a valid XML document conforming to ncx-2005-1.dtd" in 2.4.1.2; if the NCX omits the now-optional playOrder attribute, it can no longer contain a DOCTYPE (that references the canonical ANSI/NISO DTD).
[1] http://www.daisy.org/epub/issues/playorder-attribute-epub
[2] http://www.niso.org/workrooms/daisy/Z39-86-2005.html#NavMeta
[3] Example illustrating an NCX with a navMap, a pageList, and a navList containing a list of illustrations:
<ncx xmlns="http://www.daisy.org/z3986/2005/ncx/" version="2005-1" xml:lang="en-US"> <head> <meta content="org-example-5059463624137734586" name="dtb:uid"/> </head> <docTitle> <text>Selections from "Great Pictures, As Seen and Described by Famous Writers"</text> </docTitle> <docAuthor> <text>Esther Singleton</text> </docAuthor> <navMap> <navPoint class="h1" id="ch1"> <navLabel> <text>Chapter 1</text> </navLabel> <content src="content.html#ch_1"/> <navPoint class="h2" id="ch_1_1"> <navLabel> <text>Chapter 1.1</text> </navLabel> <content src="content.html#ch_1_1"/> </navPoint> </navPoint> <navPoint class="h1" id="ncx-2"> <navLabel> <text>Chapter 2</text> </navLabel> <content src="content.html#ch_2"/> </navPoint> </navMap> <pageList> <pageTarget id="p1" type="normal" value="1"> <navLabel><text>1</text></navLabel> <content src="content.html#p1"/> </pageTarget> <pageTarget id="p2" type="normal" value="2"> <navLabel><text>2</text></navLabel> <content src="content.html#p2"/> </pageTarget> </pageList> <navList> <navLabel> <text>List of Illustrations</text> </navLabel> <navTarget id="ill-1"> <navLabel><text>Portratit of Georg Gisze (Holbein)</text></navLabel> <content src="content.html#ill1"/> </navTarget> <navTarget id="ill-2"> <navLabel><text>The adoration of the lamb (Van Eyck)</text></navLabel> <content src="content.html#ill2"/> </navTarget> </navList> </ncx>#6
Thank you for the new suggestions and example. I find the example, in particular, quite useful.
My current comments:
* I support "pageList MUST be included if the publication is designed to allow the user to navigate to pages"
* I'm not (yet?) comfortable with saying reading systems MUST support pageList
* I am uncomfortable with breaking the canonical DTD reference by making playOrder attribute optional. I like the idea of making playOrder optional, but that seems like a big cost.
#7
Thanks for your comments Keith.
I had an action item from the previous call to propose prose for reading system requirements re NCX (the missing item 6 in the post above).
The suggestion below does not yet, Keith, take your pageList concerns into account. Further, it does not dictate *how* navMaps etc should be rendered; this, hopefully, can be left unspecified.
#8
#9
Moved to errata.
#10