Some comments on the viewport meta tag

[rdeltour]

First, sorry about missing the discussion in #2292, #2341, and #2350 last summer. It went totally under my radar! 😅

A couple (late) comments:

• there has been recent developments around the concept of viewport:
  • viewport is one of the topics of the interop 2022 project
  • the CSS WG resolved a while ago to retire the CSS Device Adaptation spec, remove the definition of @viewport, and move the viewport meta tag definition to a new spec. A CSS Viewport draft was just created.
• the new EBNF syntax of the viewport meta tag in EPUB 3.3 is somewhat restrictive when compared to the parsing algorithm defined in CSS Viewport (formerly CSS Device Adaptation).
  • the parsing algorithm in css-viewport does not produce errors, but always returns a (possibly empty) se tof name/value pairs.
  • in contrast, our definition defines a static syntax, but does not completely tell how RS should deal with an invalid value (except for number-prefixed height/width values).
  • for example, for a viewport value of ",invalid,,height=200,width=,width=100" the algorithm returns the name/value pair list ("height","200"),("width","100"), when our spec just says the value is invalid.
  • that said, the CSS algorithm itself has room for improvement: it could define parsing errors, error handling, and how to deal with duplicate properties. (also, it would be worth being rewritten based on Infra).

Some concerns:

• is it ok to reference css-device-adapt (even informatively) when we know the spec is doomed?
  At least, I would rephrase the following:

  The syntax of this grammar is also influenced by the processing model for transforming viewport meta tags to @viewport CSS rules, as defined in css-device-adapt.

  to something along the lines of:

  The syntax of this grammar is also influenced by the parsing algorithm for the viewport meta element, as defined in css-device-adapt.

  (so that we no longer reference the for-now-defunct @viewport at-rule.

• I have a (slightly) nagging feeling with having our own normative definition of the viewport meta element in EPUB:

  • what if this definition conflicts with whatever will (hopefully) be defined in CSS Viewport? It already kinda does. Although our definition seems to be a subset: something valid to the EPUB definition will be parsed as expected by the CSS algorithm, but not all values that are parsed into something by the CSS algorithm are conforming to our definition.
  • how confident are we that this definition matches the reality of implementations? (the existing EPUB tests not extensively evaluate the syntax variations)
  • can our syntax be informative only, somehow?
  • these types of structured values are better defined algorithmically (in my opinion), so that the algorithm can both define syntax (i.e. parsing errors) and error handling (i.e. recoverable errors that still produce a returned value).

[mattgarrish]

• The syntax of this grammar is also influenced by the parsing algorithm for the viewport meta element, as defined in css-device-adapt.

This is certainly doable. We can also change the reference to the new spec, as this is in an informative section.

• can our syntax be informative only, somehow?

We have to define a syntax because we require the height/width to be specified for HTML FXL docs. We can't reference the apple spec for the syntax so we can't jump over to parsing a tag we haven't defined for a value we require. That's the conundrum that led to having to define our own syntax.

The reading system spec is more permissive than the authoring. An invalid authored tag doesn't mean a reading system can't still parse out the specific values it's looking for. We don't define a parsing algorithm, so a reading system could use the CSS algorithm.

• what if this definition conflicts with whatever will (hopefully) be defined in CSS Viewport?

Note, that reading systems have to ignore the tag for both FXL and reflowable docs per s. 8.3. I'm not sure if there's any practical gain in ensuring compatibility beyond avoiding errors where a tag is probably invalid anyway.

[iherman]

• The syntax of this grammar is also influenced by the parsing algorithm for the viewport meta element, as defined in css-device-adapt.

This is certainly doable. We can also change the reference to the new spec, as this is in an informative section.

Agreed

• can our syntax be informative only, somehow?

We have to define a syntax because we require the height/width to be specified for HTML FXL docs. We can't reference the apple spec for the syntax so we can't jump over to parsing a tag we haven't defined for a value we require. That's the conundrum that led to having to define our own syntax.

Exactly. We cannot get around this. Taking into account that the CSS spec may take ages to become (if it becomes) a standard, we are stuck with our normative definition.

• what if this definition conflicts with whatever will (hopefully) be defined in CSS Viewport?

We cannot/should not speculate on this. It may take a long time, we might have more implementation experience and, in a future EPUB 3.X we can see what we can do. Maybe the implementation experience is such that it will be all right to reduce "our" syntax even more (we had the discussion this summer and, if I remember well, we started with a much more restrictive syntax than what we have now).

[rdeltour]

This is certainly doable. We can also change the reference to the new spec, as this is in an informative section.

ok. Another possibly relevant ref is the WHATWG meta extension registry, which is a live doc and will likely be updated to point to the latest relevant viewport-defining spec?

We have to define a syntax because we require the height/width to be specified for HTML FXL docs. We can't reference the apple spec for the syntax so we can't jump over to parsing a tag we haven't defined for a value we require. That's the conundrum that led to having to define our own syntax.

Exactly. We cannot get around this. Taking into account that the CSS spec may take ages to become (if it becomes) a standard, we are stuck with our normative definition.

right, I understand. I was thinking that we could leave it open by simplifying the requirement to:

For XHTML fixed-layout documents, the initial containing block [css2] is obtained from the REQUIRED viewport meta tag.

and then leave the work on how to extract the required info to the RS.

This would make the EPUB spec compatible with whatever comes next on the viewport front, at the cost of it being less strict on the authoring front. (but then, EPUBCheck could still report warnings for informatively-invalid viewport syntax).

My primary concern is the following:

how confident are we that this definition matches the reality of implementations? (the existing EPUB tests currently do not extensively evaluate the syntax variations)

for instance:

• our spec says RS should treat invalid values as device-width/device-height, this doesn't appear to be tested.
• the syntax allows multiple values for the same property name, but the spec then mentions "the height property" and "the width property". Do we know what happens when width is specified twice? and when one of these two has an invalid value?

The devil is always in the details 😊 I'm wondering if the EPUB spec is not more strict than needed here (for the sake of spec theoretical completeness) when we lack data or testing to better understand the landscape. But then, it's my own not-so-well-informed questioning; if you're confident that the normative syntax restriction cannot hit us back, then I'm OK (except for the duplicate-property case that is still worth being clarified IMO).

[mattgarrish]

if you're confident that the normative syntax restriction cannot hit us back, then I'm OK

For me, the requirement for reading systems to ignore the tag makes any concerns moot. We'd have to return to the tag in the future, at the very least, to undo that restriction if we decide it should be used for rendering.

The syntax matches valid viewport meta tags as they are now, and as we've defined them for FXLs, so I'm okay with leaving things as they are.

[rdeltour]

For me, the requirement for reading systems to ignore the tag makes any concerns moot. We'd have to return to the tag in the future, at the very least, to undo that restriction if we decide it should be used for rendering.

Sure, for reflowable documents I totally agree the point is moot.

The syntax matches valid viewport meta tags as they are now, and as we've defined them for FXLs, so I'm okay with leaving things as they are.

A couple examples to make it clear what concerns me:

• <meta name="viewport" content="width=600,height=1200,width=1200"> conforms to the EBNF, but it is unclear what width value a RS should pick.
• <meta name="viewport" content="anything,width=600,height=1200> does not conform to the EBNF. The current spec says the RS should treat that as width=device-width and height=device-height, but if the RS processing was define algorithmically it would be easy to extract the intended values. It would be relevant to test how real-world RS process that.

[iherman]

I must admit I am a bit worried about turning the EBNF into an algorithmic specification; we know that it takes an awful lot of time to do that right, and we are a bit late in the process (wearing my W3C hat I have to worry about these things...)...

To answer to the first issue, I am happy extending the specification by an additional constraint into the spec section whereby all property names MUST be unique. Which would "simply" make your first example invalid as well, and that would not keep me awake at night. Also reacting on your second remark, I am not sure if we should really go into the discussion on whether the RS processing may easily extract suitable values or not; being draconian may be the right way to go here.

You are right that tests are missing on device-width and device-height and on whether these defaults are indeed used. I am happy adding those tests if we otherwise agree.

Interestingly, though, the RS spec says (in §8.1.2):

If the viewport meta does not contain a width or a height value, or if these values are invalid, reading systems SHOULD consider these as having the values device-width and device-height, respectively.

i.e., it is a SHOULD not a MUST. I guess the reason is that this is probably not widely implemented...

[mattgarrish]

I guess the reason is that this is probably not widely implemented...

It was only added this revision. Given that a reading system could opt to not display the document as FXL, or choose some other way to define the ICB, and that would have been valid for the last decade, a recommendation seems appropriate.

[davemanhall]

Wow, a lot of content in this thread! Some thoughts / responses:

Some current testing behavior for Apple Books:

• <meta name="viewport" content="width=600,height=1200,width=1200"> conforms to the EBNF, but it is unclear what width value a RS should pick.

Currently, Apple Books finds and uses the first width, height for this example.

• <meta name="viewport" content="anything,width=600,height=1200> does not conform to the EBNF. The current spec says the RS should treat that as width=device-width and height=device-height, but if the RS processing was define algorithmically it would be easy to extract the intended values. It would be relevant to test how real-world RS process that.

Currently, the width and height are found and used for this example.

For <meta name="viewport" content=",invalid,,height=200,width=,width=100" /> width=0, height=200 is found, and the content fails to render.

I'm guessing you all have been through discussions around the following, but here are some high level thoughts:

• The goal of the specification in general should be such that authors can generate proper content, so that as many reading systems as possible have a chance of properly parsing the content and properly displaying the content as to the authors intent.
• It seems that the desire to specify things that would cause a reading system to fail / ignore the content is to ensure that as authors are generating their documents, they don't generate things that are invalid.
  -- If this is the real desire, a great thing for a reading system to do would be to inform the author of the specific thing in the epub that caused it to fail parsing the authors intent, but of course the end user does not want to see this technical detail, but rather they want to read the content, even if there are potential errors.
• Authors are going to initially test with whatever reading system they happen to have handy. I'm guessing that chances are slim that they are going to utilize epub-check themselves to validate their document, but rather, if they submit it for publishing, that is the point at which epub-check gets utilized to validate the syntax.
• For authoring tools, having clear specifications is always a benefit

Some conclusions for the reading application:

• I find it doubtful that a reading application would change behavior in such a way that would invalidate or detrimentally change the behavior of an existing library of documents a user may have (and may have paid for). This would potentially require re-validating a large library of existing content.
• Reading applicaitons probably tend to opt towards backwards compatability, and permissive parsing with reasonable, functional fallbacks.
• As epub-check has evolved, the ingestion systems in place have gotten better at detecting errors in newly submitted documents, but there exist a base of documents that made it into the system previous to tool improvements.

[iherman]

Without checking the details... but one way forward would be:

• the definition of viewport stays as is in the core spec
• the reading system spec would say that the RS MUST (or SHOULD?) provide an error report to the user about an erroneous viewport definition and should do a best attempt to display the content as it can. This means that the behaviour of Mac Books, as described by @davemanhall is fine for the anything,width=600,height=1200 case.
• the case when the viewport is missing altogether is still a question to me. There seem to be two strategies (beyond reporting about the missing meta):
  • use the device dimensions; or
  • use the dimensions of the previous content in the spine, if defined; otherwise, use the device dimensions.

[iherman]

The issue was discussed in a meeting on 2022-10-07

List of resolutions:

• Resolution No. 1: Ivan to adjust language to reflect content creator/EPUBCheck responsibility for viewport.

View the transcript

1. Some comments on the viewport meta tag (issue epub-specs#2442)

See github issue epub-specs#2442.

Romain Deltour: I had a late review of new viewport spec.
… wondering if it was too strict.
… is it enough for reading systems?.
… talking about viewports meta tag for FXL.
… for reflowable we are covered (RS must ignore viewport).
… in FXL this is important because it sets ICB.
… there's an EBNF grammar to defined.
… it's more constrained than what's in the CSS draft it comes from.
… it's more constrained than what browsers/reading systems can extract info from.
… so should we relax the grammar a bit.
… or further specify how reading systems should extract useful values from it.

Ivan Herman: to pick up on what romain said.
… the spec does say somewhere that if the viewport spec is wrong,, it should use device height/width.
… it's not only strict, it.

Ivan Herman: #2442 (comment).

Ivan Herman: for example Apple can make sense of an invalid viewport tag.
… what I propose is to relax the requirement to use device sizes when there is a problem.
… and instead say the RS should warn the user/author.
… and then it can do a best attempt to do something sensible.
… it can try to extract a window size.
… the only place where there's a different problem.
… if you have a number of content files and forget to set the viewport for one of them.
… today there is nothing there so you use device sizes.
… the other possibility is to [1] warn user and [2] go back to previous spine element and use that viewport size.

Romain Deltour: I agree that the spec already set that device height/width should be used when faced with an invalid value.
… so maybe relaxing RS spec is the way to go.
… I'm not convinced RSs should warn users.

Wendy Reid: +1.

Romain Deltour: if the reading system can do its best to render something, or make up a value that's good enough.
… as transparently as possible.
… there's a caase with valid viewport but specifies the width several times.
… this is valid per grammar but don't say if it should pick first/last/any.
… do we need to say something in RS spec? If there's dupes then it becomes invalid?.

David Hall: I like your rec there.
… I would lean toward should report errors to user.
… some could be unrecoverable, like xml parsing errors.
… or there could be dev mode and remotely inspect.
… but most readers won't be interested.
… so "should" warn the users.
… on multiple width values, add something to spec to prefer first value found.

Romain Deltour: or even MAY warn the users.

David Hall: separately, what to do when there isn't anything specced.
… typically in FXL books you have the same page size throughout.
… different page size present challenges to the RS.
… I like the idea of falling back to the most recent valid viewport.
… if nothing is defined, do you fall back to device dimensions or something else?.
… because device dimensions change with orientation.
… and what happens when dimensions change?.

Wendy Reid: as much as i like the idea of warning the user.
… in the real world of RSs, telling the user that something is wrong with their viewport isn't helpful. There's nothing they can do..
… this puts an undue burden on the user.
… I think this should be an epubcheck thing.
… I like idea of preferring first value.
… RSes do lots of things to optimize for speed when they render FXL.
… we use first viewport value and don't reparse.
… so we don't support changing viewport sizes.

Brady Duga: agree with David and Wendy.
… I would not say should warn the user, it's a bad idea.
… and these are often kid's books :).
… we have end users and publishers.
… might be helpful to talk about these two groups.
… I want my publishers to know but not my users.
… you can reject something with a bad viewport.
… I'm agnostic on which to pick of multiple values.
… I think we do support multiple page sizes.

Ivan Herman: we have multiple viewports in the spec.

Rick Johnson: +1 to Brady (et. al.) and differentiating messaging between readers and publishers.

Ivan Herman: (different page sizes for different files).
… we can't change that.
… if they don't implement that's ok.
… for reporting, I understand that I don't want reports going to kid.
… I like the safari analogy of David.
… I wonder if we should say something in the spec.
… from standards point of view it's ok to say reading systems should issue a warning.
… matt and I can come up with a larger PR.

David Hall: when I think of users, do you think of author and publisher as the same user.

Ivan Herman: we don't specify that.

David Hall: I can see a publisher being interested in results from epubcheck.
… I can see that authors that write their own epubs would benefit from warnings from RS.
… do we use term "May"?.

Ivan Herman: yes.

Dave Cramer: We're talking a lot about the situation where the author messed up the viewport.
… what choices the RS has in that case.
… this sounds like EPUBCheck's job.
… is the viewport parse-able.
… compatibility issues, maybe it's a warning.
… seems wrong to put this on the end user.

Wendy Reid: if we reach any sort of consensus we don't want to put anything on the end user/reader.
… we do want to warn the content creator (publisher/author).
… maybe we want to increase robustness of the section.

Bill Kasdorf: I would recommend "EPUB creator" vs. "content creator" because the person writing the book created the content but not the EPUB.

Wendy Reid: but we want requirements around validity of viewport.
… RSes rely on epubcheck.

Brady Duga: +1 to using may instead of should.
… this section isn't a real world problem except there was no spec to reference.
… we're not actually seeing real problems in FXL books.

Charles LaPierre: Q about checking viewport on mobile devices.

Dave Cramer: viewport is property of EPUB not device, spec says how to adapt.

Resolution #1: Ivan to adjust language to reflect content creator/EPUBCheck responsibility for viewport.

[rickj]

I checked with our team on what we (VitalSource Bookshelf) do if a viewport is missing:

Our stand is that viewport is required to be specified by the standard for a fixed layout document.
So if the viewport is missing, it’s actually bad content. At one point in time we used to check for it at book open, and open it as reflowable if the viewport was missing. It was too big of a performance hit so we stopped doing that. What we do instead is just generate error html. (And then people have to go fix the book.)
The problem with trying to guess at a viewport is, it just isn’t going to render correctly. You’ll get a mess if you don’t render it at the page size it was designed to be displayed at.

[iherman]

Thanks @rickj. That does mean that the strategy described in #2442 (comment) for missing viewport should be a SHOULD. (And would be a MAY report an error.)

Is that ok?

[rickj]

I agree.