Re: DOCBOOK-APPS: Notes on graphics and HTML

[Paul Grosso <pgrosso@arbortext.com>]

At 12:41 2002 05 01 -0700, Norman Walsh wrote:
>I spent some time today working on new code to map DocBook V4.2 image
>semantics (a superset of previous semantics) to HTML. A number of
>compromises were required along the way.
>
>I probably won't be able to post the new code until I get back home,
>but here are the notes I wrote as I went. Comments, etc., most welcome.

I find use of the terms like "width" are ambiguous.  I've gotten into
writing things like docbook::graphic.width and html::img.width.

>  <!-- The HTML img element only supports the notion of content-area
>       scaling; it doesn't support the distinction between a content-area and
>       a viewport-area, so we have to make some compromises.

Pretty much true, but note that html::img.{width,height}=xx% implies
that the graphic should be scaled to xx% "of the available width"
(aka of the viewport-area).

One thing I'm confused about is whether docbook allows values of the
form xx% for docbook::graphics.{width,depth} and 
docbook::graphics.content-{width,depth} and, if so, what they all mean?

Unless I hear otherwise, I'll assume that docbook::graphics.{width,depth}
values can only be lengths with units being one of the following and 
nothing else:  cm, mm, in, pt, pc, px.

>       1. If only the content-area is specified, everything is fine.
>          (If you ask for a three inch image, that's what you'll get.)

Yep (as long as the XSL-HTML stylesheets convert 3in to pixels, since
the value of an html::img.{width,height} attribute has to be a unitless
number of pixels).

>       2. If only the viewport-area is provided:
>          - If scalefit=1, treat it as both the content-area and
>            the viewport-area. (If you ask for an image in a five inch
>            area scaled to fit, we'll make the image five inches to fill
>            that area.)
>          - If scalefit=0, ignore it.
>
>          Note: this is not quite the right semantic and has the additional
>          problem that it can result in anamorphic scaling, 

Why should this have to result in anamorphic scaling?  Can't we define the
semantic so that anamorphic scaling doesn't occur?

>which scalefit
>          should never cause.

True.

>       3. If both the content-area and the viewport-area is specified
>          on a graphic element, ignore the viewport-area.
>          (If you ask for a three inch image in a five inch area, we'll assume
>           it's better to give you a three inch image in an unspecified area
>           than a five inch image in a five inch area.

This is reasonable.  I assume one could wrap the 3in image in a 5in block,
but I suspect what you suggest above is more likely to make the user happy.

>       Relative units also cause problems. As a general rule, the stylesheets
>       are operating too early and too loosely coupled with the rendering engine
>       to know things like the current font size or the actual dimensions of
>       an image. Therefore:
>
>       1. We use a fixed size for pixels, $pixels.per.inch
>
>       2. We use a fixed size for "em"s, $points.per.em

Or just say that it is an error for docbook::graphics.{width,depth} to be
assigned a value whose unit is "em".

>       Percentages are problematic. In the following discussion, we speak
>       of width and contentwidth, but the same issues apply to depth and
>       contentdepth
>
>       1. A width of 50% means "half of the available space for the image."
>          That's fine. But note that in HTML, this is a dynamic property and
>          the image size will vary if the browser window is resized.
>
>       2. A contentwidth of 50% means "half of the actual image width". But
>          the stylesheets have no way to assess the image's actual size. Treating
>          this as a width of 50% is one possibility, but it produces behavior
>          (dynamic scaling) that seems entirely out of character with the
>          meaning.

Worse, mapping docbook::graphics.width="200%" to html::img.width="200%"
guarantees that the graphic will be twice as large as the window which
is almost never what the user wants to see.


>          Instead, the stylesheets define a $nominal.image.width.in.points
>          and convert percentages to actual values based on that nominal size.

While I can't see a good solution, I also can't imagine this working too well
either.  What kind of value do you choose for $nominal.image.width.in.points 
that works more often than it doesn't?

>       Scale can be problematic. Scale applies to the contentwidth, so
>       a scale of 50 when a contentwidth is not specified is analagous to a
>       width of 50%. 

This is confused/confusing.  You are talking about contentwidth and width
in the same sentence without making it clear if you are talking about
docbook::graphic.content-width or docbook::graphic.width or html::img.width.

I think you're talking about docbook::graphics.scale="50".  I think you're
saying that this is equivalent to docbook::graphics.content-width="50%".  (It 
sure isn't equivalent to html::img.width="50%".)  And maybe this is true, but 
it depends on my earlier question as to whether docbook::graphics.width and
docbook::graphics.content-width values can be xx% and if so what they mean.  
If you define docbook::graphics.content-width=xx% to mean what you say it means, 
then it means that.  But I really have to question if it makes sense at all to 
allow docbook::graphics.width and docbook::graphics.content-width to have xx% 
values, especially if that just means the same as docbook::graphics.scale="xx".

>(If a contentwidth is specified, the scaling factor can
>       be applied to that value and no problem exists.)
>
>       If scale is specified but contentwidth is not supplied, the
>       nominal.image.width.in.points is used to calculate a base size
>       for scaling.

Yuck.  But I don't have a better suggestion.

>       Warning: as a consequence of these decisions, unless the aspect ratio
>       of your image happens to be exactly the same as (nominal width / nominal height),
>       specifying contentwidth="50%" and contentdepth="50%" is NOT going to
>       scale the way you expect (or really, the way it should).

I don't follow, partly because I don't know what "these decisions" really are.

Why can't we define the semantics of contentwidth="xx%" and contentdepth="xx%"
means to scale="xx%" (all attrs on the docbook::graphic element)?  Then the 
only way someone can specify an anamorphic scaling is to say on the docbook::graphic
element contentwidth="xx%" and contentdepth="yy%" where xx and yy are different,
and it they do that, then they are clearly explicitly asking for anamorphic scaling
and that's what they should get (if the implementation supports that).

>       Don't do that. In fact, a percentage value is not recommended for content
>       size at all. Use scale instead.
>
>       Finally, align and valign are troublesome. Horizontal alignment is now
>       supported by wrapping the image in a <div align="{@align}"> (in block
>       contexts!). I can't think of anything (practical) to do about vertical
>       alignment.
>  -->

I'm running out of steam here.  I think the problem is that docbook::graphic
is a block-level thing and html::img is an inline-level thing, so alignment
is going to be weird.  Interestingly, xsl-fo::external-graphic is also an
inline-level thing, so we have the same problem in both cases.  (I assume
we are not planning to add align and valign to docbook::inlinegraphic.)

paul