Re: DOCBOOK: A proposal to clarify the semantics of DocBook graphics

[Yann Dirson <ydirson at fr dot alcove dot com>]

On Wed, Feb 06, 2002 at 08:59:41AM -0500, Norman Walsh wrote:
> Proposal: http://sourceforge.net/docman/display_doc.php?docid=9357&group_id=21935
> 
> DocBook graphic elements have four attributes that relate to the size of
> the image: width, depth, scale, and scalefit. Recent list traffic, some
> offline conversations, and a bit of thought have convinced me that this
> simply isn't sufficient.
> 
> I propose that we add four additional attributes to DocBook graphic
> elements: content-width, content-depth, align, and valign

ImageData only ever occurs within a container (ie. MediaOject,
InlineMediaOject, MediaObjectCO).  When such a container is used to
specify alternative image formats, it is likely that the viewport will
be the same for all alternatives.  Then what about moving
viewport-size attributes to the container instead ?

> width
> 	  Specifies the width of the area in which the image will be
> 	  displayed (the reproduction area or viewport width). If
> 	  unspecified, the default value is implementation defined.

Maybe we should specify what units are available here.  People willing
to put papersize-dependant information here will want to use length
units, and the meaning of those is well understood.

To address the "scale to max width" problem, we will need something
like percentage values, which should be explicitely defined, for
example like "percentage values are relative to the maximum width
available to the processor".  But then, it seems to me that the only
useful value would be 100% - other values would be more of a
stylesheet issue (eg. "full-width images get a 5% margin").

But I can't see any meaning that height="100%" would have with an
occidental layout, although possibly languages with a top-to-bottom
layout would need this rather than width="100%" (although it's just a
wild supposition).

Maybe we just need a new value for scalefit ?  At the same time,
scalefit="1" could be replaced by something more adequate:

	scalefit	(none|dimensions|max)	none

where "dimensions" would stand for "1" (which we could keep for some
time for compatibility).


> content-width
>         Specifies the width of the actual image before scaling factors are
>         applied. If unspecified, the default value is the natural width of
>         the image. If the processor cannot determine the natural width of
>         the image, the results are implementation defined.

I'm not sure what that means.  The "natural width" of the image refers
to a number of pixel for bitmaps, and in a (default) length for vector
drawings, right ?

Is this just intended to hint the processor about dimensions it would
not be be able to determine ?

What is supposed to happen when the processor knows about dimensions ?

As the "scale it" idea seems not to make sense here, I'd suppose it
could be used to cheat about real dimensions, ie. crop (or not) the
image to the given dimension if it is smaller than the determined one,
and add some filling around it if it is larger ?

Maybe we should just state that if the given width does not match the
real image width, the results are implementation defined as well ?


> scale
[...]
> 	  If the post-scaled dimension of the image exceeds the
> 	  specified reproduction area size in that dimension, the results
> 	  are implementation defined.

You could add here: "If it is smaller than the specified reproduction
area size in that dimension, the result depends on the value of the
`align' or `valign' attributes".

Something that wasn't discussed, and is not addressed here, would be
the ability to crop within the viewport.  That would allow, for
example, when discussing a screenshot, to include isolated parts of a
single image file in various places in the document.

Such a feature would require to explicit the "implementation defined"
behaviour you mention, maybe with a "crop" attribute, like:

	crop	(crop|nocrop) #IMPLIED

with the implied behaviour being implementation defined.


> align
>         If the scaled content size is narrower than the specified width,
>         the image will be aligned within the width according to this value
>         (one of "left", "center", or "right").
> 
> valign
>         If the scaled content size is shorter than the specified depth,
>         the image will be aligned within the depth according to this value
>         (one of "top", "middle", or "bottom").

I feel like this would be much of a stylesheet issue.  Or do I miss
some particular uses ?

-- 
Yann Dirson <Yann.Dirson@fr.alcove.com>                 http://www.alcove.com/
Free-Software Engineer				      Ingénieur Logiciel-Libre
Free-Software time manager    	       Responsable du temps Informatique-Libre
Debian GNU/Linux developper <dirson@debian.org>