FXL: viewport size declaration in package file

[GoogleCodeExporter]

Kind: new package property; relation to html/head@viewport and svg/@viewbox 
specification needed in case of conflict. 

Rationale: RS developers have pointed out that having to introspect each 
document head to retrieve the viewport size is a nuisance.

Original issue reported on code.google.com by markus.g...@gmail.com on 21 Mar 2013 at 2:44

[GoogleCodeExporter]

Markus, currently there is no requirent for consistent viewport sizes (or even 
aspect ratios) across <spine> items of an FL document.  Are you proposing that 
here?  That would render some existing content out of compliance.

I don't even really see that a default value is workable -- as that would imply 
that the entire publication was fixed, and potentially obviate mixes fixed 
(identified by having a viewport) and flowing <spine> items.

I think I would propose not action on this front (unless, of course, I'm 
missing something!)

Original comment by ga...@google.com on 21 Mar 2013 at 2:58

[GoogleCodeExporter]

If we would go this route, the idea would be to allow both global statements, 
and per-spine-item overrides of the global statement, as we do for the other 
fxl properties in opf.

For the record, doing this was discussed during the authoring of the FXL1.0 
document, but was not included because it would duplicate information in opf vs 
content docs. That counter-argument still stands. The main reason I add this 
issue is that several RS devs have requested this... 

Original comment by markus.g...@gmail.com on 21 Mar 2013 at 3:01

[GoogleCodeExporter]

For discussion.

Original comment by ga...@google.com on 21 Mar 2013 at 8:55

• Added labels: Priority-Medium

[GoogleCodeExporter]

Original comment by ga...@google.com on 22 Mar 2013 at 1:34

• Changed state: NeedDiscussion

[GoogleCodeExporter]

Original comment by mgarrish on 28 Mar 2013 at 8:58

• Changed state: NeedsDiscussion

[GoogleCodeExporter]

I support the idea. Not having viewport information in package document is 
causing more issues than it solves.

1. RS vendors introduce their own proprietary extension for the viewport size 
because it's not defined, and it's causing multiple properties to publications, 
and confusions to RS developers.
2. html/head@viewport is proprietary, under-defined specirifcation. CSS may 
define viewport in future, but CSS WG just decided not to define against paged 
media because it's too much complicated to define at this point.
3. RS needs to set viewport size to rendering engine before it loads contents 
to the rendering engine. Load contents, retrieve size, and resize the engine 
would hit performance.

I understand and agree with the motivation to sync with CSS and any other W3C 
specs, but the benefit is only when W3C spec is well-defined and stable. In 
this case, having our own definition helps more. Consideration for when CSS 
defines viewport might be good though.

Note that, as Markus said above, this is not about document v.s. spine. I would 
like EPUB 3.0.1 to define both document and spine-level viewport, with its 
priority/conflict resolution defined. This is about whether to delegate 
viewport sizes to content documents, or have definition in EPUB specification, 
and I support the latter.

Original comment by kojii...@gmail.com on 31 Mar 2013 at 9:02

[GoogleCodeExporter]

Hi Folks,

I'm still not sure I love this approach, but I may be coming around!  :-)

So, making the request slightly more concrete, would we be looking for 
something like:
Name    
rendition:viewport
Description 
Specifies the content dimensions of the Publication or spine item in CSS pixels.
Value   
height=xxx, width=yyy
Usage   
Package Document meta element
Package Document itemref element
Initial 
In meta: absent
In itemref: inherited from meta
Cardinality 
In metadata: zero or one
In itemref: zero or one

Higher specificity would "win" -- that is:

-- an "itemref" specification would override a "metadata" specification
-- an XHTML "viewport" or SVG "viewBox" would override either an "itemref" or a 
"metadata" specification

I'm not really an SVG guy, so, a question: would SVG FL documents "work" 
without a "viewBox", or would be above only be viable for XHTML FL content 
documents?

Best,
  Garth

Original comment by ga...@google.com on 10 Apr 2013 at 4:04

[GoogleCodeExporter]

Thanks for a detailed proposal, it looks great. A few minor discussion points 
are:
1. Should this be itemref or item? I wonder, since it's a property of the 
source, maybe item element works better.
2. Which works better: width and height properties or single viewport property? 
I have mild preference to width and height properties since it doesn't require 
additional parser.
3. "in CSS pixels" is questionable, as only XHTML content document uses CSS 
pixels. How about using description such as "Specifies the initial coordinate 
system of the Publication or item," or if "coordinate system of the 
Publication" sounds like strange, maybe "Specifies the initial coordinate 
system of the item" and "Specifies the default initial coordinate system of all 
items"?

For your question, I'm not an SVG guy either, but as far as I read:
http://www.w3.org/TR/SVG/coords.html#ViewBoxAttribute
http://www.w3.org/TR/SVG/struct.html#SVGElement
viewBox is optional. The latter link says:
]]
If an SVG document is likely to be referenced as a component of another 
document, the author will often want to include a ‘viewBox’ attribute on 
the outermost svg element of the referenced document. This attribute provides a 
convenient way to design SVG documents to scale-to-fit into an arbitrary 
viewport.
[[

Original comment by kojii...@gmail.com on 20 Apr 2013 at 4:03

[GoogleCodeExporter]

My choice with "height=xxx, width=yyy" and use of CSS pixels, was to provide 
syntactic and semantic overlap with our existing HTML <meta> viewport, which 
seems important since we're augmenting an existing methodology.  Though, I may 
be wrong.  I'd certainly be interested in other opinions!

Original comment by ga...@google.com on 20 Apr 2013 at 9:26

[GoogleCodeExporter]

Understood, and confirmed it's written so in the current FX spec. My motivation 
is that it's probably wrong to say so for SVG, and also people uses it today to 
express physical pixels of inner images, which is not CSS pixels. The semantics 
written in SVG spec is probably the correct way I guess.

Original comment by kojii...@gmail.com on 21 Apr 2013 at 11:21

[GoogleCodeExporter]

Discussed on the June 6th call -- likely need to be discussed when Koji on the 
call.

Generally agreed that *if* such metadata additions were made, we should 
continue to require the specification at the markup level (XHMLT meta viewport 
or SVG viewBox); this would always "win" -- such that we don't break backwards 
compatibility.  

Further, we could have the requirement that any OPF specification must match 
what's in the markup, such that epubcheck could verify.

I chose to propose the (potential) new metadata be allowed on itemref (not 
item) to match all other similar FLX metadata.

The issue of CSS pixels versus other metics panel #8.3 was not discussed, but 
with the above, probably means we need a single metric.

We should discuss this again when Koji is on the call.

Original comment by ga...@google.com on 6 Jun 2013 at 10:53

[GoogleCodeExporter]

Sorry I missed the call on June 6th.

I agree to keep requiring the current ICB definition, and requiring both needs 
to match. With these two requirement, do we need to define which would win? I'm 
fine for the markup to win if we want to define it though.

Whether to make it item or itemref, I don't have strong opinion here. item 
looks slightly natural to me, but I'm no expert here, I'm fine with whichever 
you propose.

Regarding the unit, it looks to me that it's a bug to say SVG viewBox is CSS 
pixels. SVG spec says "By establishing a new viewport, you also implicitly 
establish a new viewport coordinate system, a new user coordinate system, and, 
potentially, a new clipping path" so the unit should be defined by the document 
and ICB merely establish a new user coordinate system for the document to 
consume. For XHTML documents, it'll be CSS pixels, but for SVG documents, it'll 
be SVG user unit.

But this is probably just for perfection; practically I don't think anyone 
would implement/use differently by saying it's a CSS pixels, so this isn't 
strong either.

Original comment by kojii...@gmail.com on 7 Jun 2013 at 12:55

[GoogleCodeExporter]

Agreed on call -- to be reviewed by Koji, post drafting:

-- Add new metadata, per panel #7

-- continue to require the specification at the markup level (XHMLT meta 
viewport or SVG viewBox); this would always "win" -- such that we don't break 
backwards compatibility.

-- any OPF specification must match what's in the markup, such that epubcheck 
could verify

-- Use CSS pixels in package-level viewport metadata

Original comment by ga...@google.com on 13 Jun 2013 at 10:37

• Changed state: Accepted

[GoogleCodeExporter]

Will this be required in OPF?
If it is required then all current document are invalid.

Original comment by ori@helicontech.co.il on 14 Jun 2013 at 1:29

[GoogleCodeExporter]

No, optional.

Original comment by ga...@google.com on 14 Jun 2013 at 1:42

[GoogleCodeExporter]

I don't think this proposal can work as presented.

The spine itemref overrides are all boolean flags that incorporate the override 
value with the property name (and are defined in our spec vocbularies). We've 
never established a means of defining arbitrary values at the spine level. 
(These aren't truly overrides, either, as there is no "default" dimension in 
the absence of a global rentition:viewport property being set, but that's a 
minor nit.)

If we define the height and width dimensions as part of the itemref "flag" 
(rendition:viewport=xxx,yyy) or define separate height/width properties to do 
the same (rendition:viewport-width=xxx and rendition:viewport-height=yyy), 
we're no longer valid to the requirement that the properties attribute must 
contain a space-separated list of property values (we'd technically have to 
define every possible combination of '=xxx,yyy').

Can we turn a bit of a blind eye to our own requirements here and create a 
spine override property called rendition:viewport=xxx,yyy where we assume every 
possible numeric combination? A bit of a hack, but...

I can only think of two other ways to make item-level declarations possible:

1) Allow meta tags to refine manifest items to attach the override/specific 
dimensions, but that seems like a painful and messy way to go.

2) Define height/width attributes on spine itemrefs.

If you see an option I'm missing, please add, but I'll need additional guidance 
on what to do with this.

Original comment by mgarrish on 19 Jun 2013 at 1:26

[GoogleCodeExporter]

Well, Matt, you know how  to ruin a party!  :-)

I'd add #3: allow global viewport setting only, "un-refined" "meta" elements, 
as originally proposed:

         <meta property="rendition:viewport">height=xxx, with=yyy</meta>

If there is really a desire to support itemref-level overrides, I like your #1 
better than #2:

         <meta refines="#itemref-id" property="rendition:viewport">height=xxx, with=yyy</meta>

One could make that an item-id, but keeping it to the spine item itself seems 
better (to me).

Original comment by ga...@google.com on 19 Jun 2013 at 5:47

[GoogleCodeExporter]

I try my best to be the grumpy neighbour upstairs! ;)

I wasn't sure if we could refine a spine item, but looking at the def it says 
resources or elements, and elements does include itemrefs last I checked, so 
count me wrong there. Sounds like a better approach, although it could still 
lead to a plentiful amount of meta tags setting viewport sizes.

I'll keep the prose I have now for the package-level def uncommitted, and 
assume we'll look for consensus on what to do with spine-level defs on the call 
tomorrow.

Original comment by mgarrish on 19 Jun 2013 at 7:27

[GoogleCodeExporter]

One additional clarification before I make a commit of the draft: does this 
property only exist for use with xhtml/svg content documents, or can it be set 
for bitmaps in the spine?

I'm assuming it's not useful for bitmaps and hence no mention of it for that 
purpose, but as it affects which rs reqs I need to update in content docs I 
just want to make sure.

Original comment by mgarrish on 21 Jun 2013 at 2:04

[GoogleCodeExporter]

I would say FL -- XHTML/SVG "rendition:layout" "pre-paginated" -- only.

Original comment by ga...@google.com on 21 Jun 2013 at 3:01

[GoogleCodeExporter]

I've updated the publications and content docs specs. Diff of the changes is 
available here:

https://code.google.com/p/epub-revision/source/detail?r=4662

As I had to make a number of changes, here's a quick summary:

In Publications:

- made the third bullet in 3.3 slightly more precise about how to obtain the 
dimensions
https://epub-revision.googlecode.com/svn-history/r4662/trunk/build/301/spec/epub
30-publications.html#sec-package-rs-conf

- added the viewport property def changing "allowed values" to "required value" 
(as there are no options) and adding both meta cardinalities
https://epub-revision.googlecode.com/svn-history/r4662/trunk/build/301/spec/epub
30-publications.html#viewport

- changed the note about setting dimensions in rendition:layout into a 
normative statement in the usage section and added a note about using 
rendition:viewport
https://epub-revision.googlecode.com/svn-history/r4662/trunk/build/301/spec/epub
30-publications.html#fxl-property-layout

- added the section on using rendition:viewport but not following the typical 
fxl model, since there are no allowed values and the spine overrides are 
expressed through the refines attribute
https://epub-revision.googlecode.com/svn-history/r4662/trunk/build/301/spec/epub
30-publications.html#fxl-property-viewport

In Content Docs:

- modified the xhtml and svg reading system conformance reqs to allow the 
dimensions to be retrieved from the package metadata
https://epub-revision.googlecode.com/svn-history/r4662/trunk/build/301/spec/epub
30-contentdocs.html#sec-fxl-rs-conf

Original comment by mgarrish on 21 Jun 2013 at 7:00

[GoogleCodeExporter]

Original comment by mgarrish on 21 Jun 2013 at 7:01

• Changed state: FinalReview

[GoogleCodeExporter]

Hi Matt,

A couple of comments below�

In:

Reading Systems must ignore this property when it is applied to spine items 
whose rendition:layout property has not been set to pre-paginated. Reading 
Systems must also ignore this property on spine items that are not XHTML or SVG 
Content Documents (e.g., bitmap images).

I'd remove the "(e.g., bitmap images)" as I don't view bitmaps as an example of 
SVG documents (generally).

In:

� It should allocate the full content rendering area for the document.

� It should use the dimensions expressed in the viewport meta tag, but may use 
the equivalent dimensions expressed in the rendition:viewport property 
[Publications30] to render XHTML Content Documents.

� It should use the dimensions expressed in the viewBox attribute, but may use 
the equivalent dimensions expressed in the rendition:viewport property 
[Publications30] to render SVG Content Documents.

� It must use the intrinsic physical dimensions of bitmap images when they are 
referenced in the spine.

Given that if there is a discrepancy between the <meta> viewport and the 
content viewport/viewbox the RS MUST use the latter:

Reading Systems may use the package metadata expressions without checking the 
ICB dimensions expressed in the content, but must use the dimensions expressed 
in the content if discrepancies are found.

I'd think the two middle SHOULD's above might want to be MUST, or maybe "if 
they are not the same, the RS MUST use the content ones."

I'd drop the last bullet -- doesn't look like we'll have images in the spine -- 
and if they are there, with fallbacks, I don't view it as too relevant to FL.

Best,
  Garth

Original comment by ga...@google.com on 24 Jun 2013 at 4:35

[GoogleCodeExporter]

Okay, hopefully this update will improve some the points you've noted:

https://code.google.com/p/epub-revision/source/detail?r=4664

I removed the RS requirement to respect the content expressions from the 
Publications specification and replaced the fourth bullet with the part about 
which mechanism wins. The goal was always to express requirements in only one 
location, and seems like this statement is already, and beter, stated in 
Content Documents.

I've also made the bullets MUSTs and reforumlated the package lookup to MAY get 
the dimensions from there. HTML build can be viewed here:

https://epub-revision.googlecode.com/svn/trunk/build/301/spec/epub30-contentdocs
.html#sec-fxl-rs-conf

I also realized after updating that there was still some bitmap prose in the 
FXL section in Content Docs, so I cleaned that out in another commit:

https://code.google.com/p/epub-revision/source/detail?r=4665

Only a minor change, though.

Original comment by mgarrish on 24 Jun 2013 at 7:16

[GoogleCodeExporter]

Original comment by markus.g...@gmail.com on 17 Jul 2013 at 8:30

• Changed state: Done