What is the use of the top reference to a resource in every sample?

[llemeurfr]

In every sample from the proposal, there is a top reference (textref, audioref or imgref), a role and a set of children nodes.
I don't see the use of the top reference:

• it breaks the symmetry of the guide-navigation file (every child node has two references, which maps one media to another, in a reversible way).
• what will the client do with it?

[llemeurfr]

Maybe this top reference implicitly means that the client app should first display the "full" resource, with no alternative media, before going through child node. In this case the spec must clearly describe such processing. And if this is the case I only see it used for images (display the full page before going down into a guided navigation experience).

[HadrienGardeur]

In these examples, what you call a "top-reference" have their own Guided Navigation Object because they either:

• convey information about the strucure/semantics of the publication (for example in an audiobook, there's no other way to indicate where chapters start/end, the ToC doesn't tell you if an item is a chapter)
• and/or because the creator of the Guided Navigation Document would like to present the entire resource

it breaks the symmetry of the guide-navigation file (every child node has two references, which maps one media to another, in a reversible way)

That's not the only use case for Guided Navigation in my opinion. For example panel by panel navigation could only use imgref throughout the Guided Navigation Document.
We're not trying to reproduce SMIL with this spec, the scope is larger, as we can see with our discussions related to read aloud and accessible comics.

what will the client do with it?

This is up to the client to decide based on the role, but I've already answered to that question by mentioning panel by panel navigation without any further attempt at accessibility using description, text and/or textref.

[llemeurfr]

After reading your comments, I still think that for the sake of clarity, the following modifications should be applied to the different samples:

Synchronizing text with pre-recorded audio: remove textref in the top node. It has no use for the client.
Synchronizing an audiobook with text using references: remove audioref in the top node. It has no use for the client.
Synchronizing an audiobook with text using embedded text: remove audioref in the top node. It has no use for the client.

the imgref of the Guided navigation in a manga and Text equivalent of a speech bubble in a comic book have a logic there; in the first case the client must display the full page first; in the second case the cllent must display the panel first.

[HadrienGardeur]

If the client is simply interested in using Guided Navigation for navigation (pretty much the only way you can truly structure an audiobook), these elements would remain useful, whereas the children elements would be ignored.

This spec has a larger scope than SMIL, for visual and auditory formats, it also replaces the use of DPUB ARIA.

I can remove it from synchronizing text with pre-recorded audio since there are other means of achieving the same goal, but I don't think it would be a good idea to drop it from the audiobook example.

[llemeurfr]

In an audiobook the track-by-track navigation is provided through the spine and an optional fine tuned navigation is provided through a ToC. This extra "top" element in the guided navigation still makes no sense to me.

[HadrienGardeur]

In an audiobook the track-by-track navigation is provided through the spine and an optional fine tuned navigation is provided through a ToC. This extra "top" element in the guided navigation still makes no sense to me.

The tracks say nothing about the stucture of an audiobook. A single track could contain an entire audiobook, multiple chapters or you could even have an extra long chapter divided between multiple tracks.
The ToC gives you a mean of navigating through a tree-like structure, but it doesn't contain semantics (although it could do so with epub:type, not so much with role).

I can remove it from synchronizing text with pre-recorded audio since there are other means of achieving the same goal, but I don't think it would be a good idea to drop it from the audiobook example.

I've looked back at the SMIL examples in the EPUB 3.3 specification and I retract that statement. Here's a full example: https://www.w3.org/TR/epub-33/#example-mo-nesting

Let's look at the top elements of this example:

<smil
    xmlns="http://www.w3.org/ns/SMIL"
    xmlns:epub="http://www.idpf.org/2007/ops"
    version="3.0">
   <body>

      <!-- a chapter -->

      <seq
          id="id1"
          epub:textref="chapter1.xhtml#sectionstart"
          epub:type="chapter">

         <!-- the section title -->

         <par id="id2">
            <text
                src="chapter1.xhtml#section1_title"/>
            <audio
                src="chapter1_audio.mp3"
                clipBegin="0:23:23.84"
                clipEnd="0:23:34.221"/>
         </par>

Since we don't have an equivalent of seq/par (we decided a long time ago against it), this is how this would be translated as Guided Navigation:

"guided": [
  {
    "textref": "chapter1.xhtml#sectionstart",
    "role": ["chapter"],
    "children": [
      {
        "textref": "chapter1.xhtml#section1_title",
        "audioref": "chapter1_audio.mp3#t=1403.84,1414.221"
      }
    ]
  }
]

I'm a little confused about what's actually bothering you:

• Is it the presence of a Guided Navigation Object that doesn't reference two different types of media? Because as we can see, there are multiple use cases for that.
• Or is it the fact that these textref/audioref do not reference a fragment? Because I think that there are legitimate use cases for that too.

[llemeurfr]

I'm bothered with the constant presence in the samples of a top level reference which appears - because of its ubiquity - to be a rule, while it does not correspond to a useful indication for the client app.
The initial seq in the Media Overlays sample you show is a design choice made by the author, not a spec constraint. If a json guided navigation is a transform from such a Media Overlays structure, I don't see any issue having a top textref in the target json structure.
From https://www.w3.org/TR/epub/#sec-media-overlays-structure, the seq tag is a way to offer RS playback options tailored to the layout of the content (e.g. escape segments). We should find the same kind of note and intent in the guided navigation spec: nested structures can be added to offer RS playback options tailored to the layout of the content.
If the samples you provide, such intent is far from being obvious.

[HadrienGardeur]

@llemeurfr the latest commit should address your concern: d784fcd

Keep in mind though that this is still a work in progress, I've been gradually building up from what we had in the PR on the architecture repo, but this is far from done.

[llemeurfr]

I'm quite ok with the updated set of samples.

In example 1, what is the intended processing for the reading system when it encounter the top textref? is it to display (/ focus on) the position selected by textref before playing the media overlays?
This information should be present as a note below the sample, IMO.

[HadrienGardeur]

@llemeurfr it could be used for that but may also prove useful for providing additional navigation and/or escaping capabilities

This information should be present as a note below the sample, IMO.

We'll get there, but once again, that's a first draft. We'll definitely have fuller examples at some point with a lot more structural elements which will help with that.