Skip to content
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.

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

What makes primary resources "primary" #55

Closed
mattgarrish opened this issue Aug 28, 2017 · 22 comments

Comments

@mattgarrish
Copy link
Member

commented Aug 28, 2017

Given the new definitions for primary and secondary resources, what gives primary resources any primacy?

Being in the default reading order doesn't make them materially any different from top-level content that the user can reach in other ways.

Something like EPUB's distinction of "spine resources" might be less confusing for times when we need to speak specifically about resources in the default reading order.

@BigBlueHat

This comment has been minimized.

Copy link
Member

commented Aug 29, 2017

Pasting the definitions from the current version for simplicity and clarity:

Primary Resource
A primary resource is one that is listed in the default reading order.
Secondary Resource
A secondary resource is one that is required for the processing or rendering of a Web Publication.
@mattgarrish

This comment has been minimized.

Copy link
Member Author

commented Aug 29, 2017

A primary resource is one that is required for the processing or rendering of a Web Publication, so the distinction has nothing really to do with primacy.

Again, I would call them all "Web Publication Resources" and then find some new name for what a resource in the default reading order is called, if we actually need a special name for such a thing.

Outside of the default reading order, it's not clear we'll need to distinguish resources. Plus, if the default reading order does not contain all of the primary content, talking only about the resources in it as though that's true isn't helpful.

@HadrienGardeur

This comment has been minimized.

Copy link
Contributor

commented Aug 30, 2017

Outside of the default reading order, it's not clear we'll need to distinguish resources. Plus, if the default reading order does not contain all of the primary content, talking only about the resources in it as though that's true isn't helpful.

Agree that outside of the default reading order, we don't need to distinguish resources and can have HTML/CSS/JS/images/videos/audio all in a single flat list.

I'll repeat what I said before in a PR comment:

  • primary = default reading order
  • secondary = part of the publication, not in the default reading order, may be packaged or cached for offline viewing
  • external = anything else referenced in the publication, not in any list in the manifest, won't be packaged or cached for offline viewing

In Readium, we still use spine instead of primary and resources instead of secondary.

@mattgarrish

This comment has been minimized.

Copy link
Member Author

commented Aug 30, 2017

In Readium, we still use spine instead of primary and resources instead of secondary.

I think this is the safer approach, or at least the less connotation filled one.

To swipe the secondary definition from google:

coming after, less important than, or resulting from someone or something else that is primary.

If we don't want to go near "spine", at least let's kill off "secondary" and leave it to the resources section to define these:

The infoset MUST include a list of resources required for the processing or rendering of the Web Publication, although the list is not required to be exhaustive.
This list MUST include all primary resources.

I'm not a big fan of the latter statement, though, as it returns us to EPUB.

If we need it for the case of HTML parsing avoidance, let's make that a qualifier.... " when the default reading order is a linked table of contents." (Forgetting this has to be done, regardless.)

Or make it a requirement for the user agent to compile these into the list: "The user agent MUST include all primary resources in this list. These MUST NOT be duplicated in the resource list in the manifest."

@HadrienGardeur

This comment has been minimized.

Copy link
Contributor

commented Aug 30, 2017

There's a massive difference between parsing a list in HTML (more painful than working with JSON) and parsing all HTML documents + CSS to figure out what the resources are (and not being able to differentiate between secondary and external resources).

Regarding secondary resources:

  • I agree that calling them "secondary" is confusing and we need another term
  • it's hard to have MUST/SHOULD statements for them because there's one giant twist: you MUST list secondary resources to support packaging and offline, but deciding if a resource is secondary or external is entirely up to the author to decide
@mattgarrish

This comment has been minimized.

Copy link
Member Author

commented Aug 30, 2017

parsing all HTML documents + CSS to figure out what the resources

Right, I was only wondering about parsing a linked toc to get the list of primary resources. It can't be avoided if that's how the reading order is specified by the author, so there will be a representation of the list available.

@llemeurfr

This comment has been minimized.

Copy link
Contributor

commented Sep 1, 2017

If we don't want to go near "spine" ...

Why should we reject the term spine? it clearly represents an ordered sequence of things, after all, and the term is used by the publishing community for a while.

An alternative adjective, IMO usable in this context, is linear. "Linear resources" would be resource in default reading order. It would be better to avoid the term "non-linear" for other resources, as it has another scope in EPUB.

@danielweck

This comment has been minimized.

Copy link

commented Sep 1, 2017

I would avoid linear, because it is reminiscent / semantically-associated with non-linear in epub3.
I don't mind the term spine, but default reading order is also used elsewhere in WP, and perhaps more appropriate (albeit more verbose than spine).

@mattgarrish

This comment has been minimized.

Copy link
Member Author

commented Sep 1, 2017

Why should we reject the term spine?

I wasn't trying to suggest reject; it would be my preference. There just wasn't agreement on it in a previous discussion, so if we don't want to tackle that now let's at least find something else generic like it.

Words that impart importance or primacy to the default reading order are just masking linear/non-linear, in my opinion.

@dauwhe

This comment has been minimized.

Copy link
Contributor

commented Sep 1, 2017

"What should we call a sequence of content documents?"
"Um, how about 'spine'?"
"Isn't that a JS library?"
"Well, yes, but books have spines."
a voice is heard from offstage, sounding remarkably like Bill Kasdorf: "It's not just books, right?"
"If I tell a web dev that this HTML doc should be a spine item, what would she say?"
"Give me some of what you're smoking!"
"Right. It's an historical artifact from the days of EPUB. Would we really use a term so closely tied to the manufacture of printed books in this digital age?"
"So what should we call it?"
"Remember that the number one job of working groups is bikeshedding. We could easily spend a year figuring this out. primary, main, order, sequence—there are all sorts of possibilities."
"Cool. I'll open a new issue. I'll bet you a case of beer that we'll get more than two hundred comments."
"Deal. Now what were you saying about JSON?"

@BigBlueHat

This comment has been minimized.

Copy link
Member

commented Sep 1, 2017

How about "binding"? Still tied to history, but much clearer what's happening technically too--as I think of "spine" as supportive...like the one in my back...

@mattgarrish

This comment has been minimized.

Copy link
Member Author

commented Sep 1, 2017

So why is this document primary?
Because it's in the reading order.
But why is it in the reading order?
Because it's primary.
So does primary mean it contains the primary narrative?
No.
So secondary contains primary content, too?
Yes.
And primary are secondary?
Yes.
Oh, goodie.

@mattgarrish

This comment has been minimized.

Copy link
Member Author

commented Sep 1, 2017

So can everyone live with "resources" and "spine resources"?

That's the usual test. Not do you love it and is it perfect.

If some people might not know what a spine is, they'll discover it easily enough from the definition... or to modify the above:

what is a "spine" resource?
it's one that defines the default reading order
so why is it called "spine"?
it's a bit of useful legacy print nomenclature for defining a contiguous sequence of documents
Ahhh, that's some good definitioning!

@danielweck

This comment has been minimized.

Copy link

commented Sep 1, 2017

+1 to Matt's above "definitioning" ;)
(for as long as we don't have to standardise that term too)

@llemeurfr

This comment has been minimized.

Copy link
Contributor

commented Sep 1, 2017

+1 with this, defining spine resources only,

  • stating in the definition of a Web Publication that "A Web Publication is a collection of one or more resources, organized together through a manifest into a single logical work, with a default reading order. ...".
  • stating in 3.7: "The infoset must include a list of the spine resources of the Web Publication.
    The infoset also should list all resources required for the processing or rendering of a Web Publication, although the list is not required to be exhaustive".
@WSchindler

This comment has been minimized.

Copy link

commented Sep 1, 2017

IMO a "spine" resource is part of the default reading order, but not that it defines it, because the default reading order is an ordered list of such "spine" resources.

@lrosenthol

This comment has been minimized.

Copy link

commented Sep 1, 2017

@BillKasdorf

This comment has been minimized.

Copy link

commented Sep 1, 2017

[from offstage:] I'm mulling a term like "top level" as being pretty generic and generally understandable. . . . My reservation, though, is that although this has the implication of not being contained in a higher level resource, the other resources aren't actually "contained" in such "top level" resources, they're just referenced by them; and a top level resource can reference another top level resource. Plus it eliminates the concept of reading order, leaving "default reading order" to be otherwise addressed. [exit stage left, wondering if this comment was at all helpful]

@TzviyaSiegman

This comment has been minimized.

Copy link
Contributor

commented Sep 1, 2017

Maybe we should find something else to think about? I mean this is fun, but we have almost 3 years to wordsmith. Maybe we should spend some energy on other items?

@mattgarrish

This comment has been minimized.

Copy link
Member Author

commented Sep 2, 2017

I'm mulling a term like "top level" as being pretty generic and generally understandable

Tried to attach that to primary and it didn't work. Without restricting what resources are allowed in the default reading order, any resource in the reading order is by default top level, even if it's a style sheet.

The one place where we do seem to want to distinguish resources is in the resource list: that some ancillary resources might not be listed. That's originally where primary/secondary came from, but after rationalizing those original definitions to the default reading order, what we're left with doesn't match the original names.

If we're making an exception for fonts, scripts, or whatever, we can find better terminology and explanations.

At any rate, I don't want to spin wheels on new names. That wasn't my intention. The PR I added does away with primary/secondary and nothing particularly suffers from the lack of them.

@HadrienGardeur

This comment has been minimized.

Copy link
Contributor

commented Sep 4, 2017

Since we can't agree on terminology, can we at least agree on the scope and how we'll use each list?

@mattgarrish

This comment has been minimized.

Copy link
Member Author

commented Sep 4, 2017

@HadrienGardeur I'd like to close this off now. I've opened two more issues related to it, but if there's anything else you think we need agreement on please do the same.

@mattgarrish mattgarrish closed this Sep 5, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
10 participants
You can’t perform that action at this time.