[Docutils-develop] Re: Remove image.scale

[Felix W. <Fel...@gm...>]

David Goodger wrote:

> Felix Wiemann wrote:
>
>> The "scale" attribute [...] should be removed.
>>
>> * Case 2: Neither width nor height is specified.
>>
>>   In this case the image has to be scaled from its "natural" size.
>>   However, often there is no such natural size, e.g. when rendering
>>   PNG images in typeset documents.
>
> So we add a note to the directive docs that says something like:
>
>     The "scale" option applies only to screen-oriented rendering
>     (e.g., HTML); it does not apply to paper-oriented output.

This is not a clean solution because if you specify width=10cm and
scale=50, you'd be badly surprised if you get a 10cm image on paper.

>> the HTML writer [...] tries to access the image using PIL.
>>
>>   2. The behavior is unpredictable.  This causes testability
>>      problems; the HTML writer code which uses the PIL is not
>>      covered by the test suite at the moment.
>
> So we add tests.

I takes too much time, so I don't want to.  Do you?

>>   3. If there is no PIL installed, the behavior is wrong (the image
>>      isn't scaled), and the error passes silently.
>
> Is it an error though?  The docs say that PIL is required for its use.
> If it is an error, let's generate a proper system message.

Yes, I think it is an error.  But that's even more to implement.  Again
the question: Do you want to implement this and write tests?  (If yes,
please don't do so yet -- let's finish this discussion first.)

>> and given the pain it causes for developers,
>
> That's not a valid reason for removing a feature.

It is.  Since the available developer time is limited, we have to decide
what to spend our time on.  So the fact that a feature eats up developer
time *is* a valid reason, and even more so for an open source project,
where even less time is available.

> Anyhow, what pain?

Writing tests (see above), adding error handling (see above),
implementing it in the LaTeX writer (esp. in combinations with the width
and height attributes), implementing it in any writer to-be-written (we
want to make writing writers easy!).

> You omitted the most common use case: the author wants an image in
> their web page, at 50% scale.  Perhaps the image isn't under the
> author's control,

If the image is not under the author's control, then "scale" won't work
because PIL can't access the image.

> or the image dimensions may change from time to time, or the author
> may just be lazy.  Either way, the simplest use is:
>
>     .. image:: picture.png :scale: 50

So "scale" is useful if and only if somebody wants to scale an image and

* the output format is HTML,
* the image is locally available, and
* the path is valid as-is as a URI.

Especially the first point is bothering me.  reStructuredText should be
independent of the output-format, but in this case we have a feature
highly biased towards one single output format, namely the screen-based
HTML.

So the "scale" attribute causes two types of problems:

* Design problems -- it has a very narrow, format-dependent use case,
  and it's not always applicable (when the image is unavailable).
* Practical problems -- it takes much developer time, while providing
  only a convenience to the user.

This is why I think it causes harm and should be removed.

-- 
For private mail please ensure that the header contains 'Felix Wiemann'.

"the number of contributors [...] is strongly and inversely correlated with the
number of hoops each project makes a contributing user go through."      -- ESR