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

[Norman Walsh <ndw at nwalsh dot com>]

/ Yann Dirson <ydirson@fr.alcove.com> was heard to say:
| On Wed, Feb 06, 2002 at 08:59:41AM -0500, Norman Walsh wrote:
|> 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 ?

Well, one reason is that you might want to express the dimensions
differently for different alternatives. (In inches, for example, for
EPS figures and in pixels for PNGs).

|> 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.

I suppose we could identify a set of unit names. But I don't think we
should make it a closed set.

| 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").

I'm not sure what the scale to max width problem is, exactly. I think
I'm inclined to leave the meaning of percentages in width and depth
implementation dependent, mostly because I'm concerned about the
semantics of "the maximum width available to the processor".

| 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).

How is "max" different from "dimensions". Scalefit isn't anamorphic.

|> 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 ?

If I say content-width="3in", I want the image to be 3in across. If I
don't specify a content-width, I expect it to be the width of the
image. For some systems, that'd be naturally expressed in pixels, for
others in inches, but I don't think that's an important distinction.

| 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 ?

If the content-width (after scaling) exceeds the width, we do say the
results are implementation defined. If the content-width (after
scaling) is less than the width, the image is positioned within the
width according to the value of the align attribute.

|> 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".

Right. That's what I meant.

| 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.

I'm a little concerned about this because some systems may not be able
to crop (or not to crop).

|> 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 ?

I could live without these attributes, but I can imagine that someone might
say they want control over the placement of images that are smaller than their
respective widths or depths.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | As a general rule, the most
http://www.oasis-open.org/docbook/ | successful man in life is the man
Chair, DocBook Technical Committee | who has the best
                                   | information.--Benjamin Disraeli