>>> 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.
Good point. It ought to work in that case too, or, if that's not
possible, it should generate an error.
>>> 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?
If necessary, yes. The point is, inconvenience (or even "pain") to
developers is *NOT* sufficient or even *reasonable* grounds for
removing a feature.
>>> 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.
If implementation time were the only criterion, and our goal is a
bug-free, stable system, I'd say we should just revert the length unit
changes. That would take very little time.
I'm not serious. But look at it from this perspective:
1. Feature A already exists, and works reasonably well.
2. A new feature B is implemented.
3. Feature B breaks feature A, and shows us that feature A lacks unit
In the abstract, it would make more sense to revert the new feature B.
Do we remove feature A? No, we should fix it. Feature A (scale)
should not be removed because of B (units). If anything is to be
removed, they should be considered independently.
Taken to the extreme, the argument about "developer pain" would result
in a lot less software being written, probably including Docutils. I
know it has caused *me* a lot of pain over the years. But I believe
the benefits to the community have outweighed that pain.
>> 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.
Not true. Counter-example: the image could be something read-only
from an external source, whose dimensions may vary. APOD, the
Astronomy Picture of the Day, is a good example
> So "scale" is useful if and only if somebody wants to scale an image
> * the output format is HTML,
> * the image is locally available, and
> * the path is valid as-is as a URI.
You're over-simplifying and splitting hairs. Even if these items are
all true, they need not be (e.g., "scale" could be fixed for
> 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.
This mindset is bothering *me*. It is also evidenced in the proposed
deletions from the to-do list. So what if we have HTML-specific
features? As long as non-HTML output is not compromised by such
features (and it is *not*, here), I see nothing wrong.
> 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
The "narrow, format-dependent use case" happens to be the leading use
case of reST.
> * Practical problems -- it takes much developer time, while
> providing only a convenience to the user.
That line of reasoning is completely invalid. User convenience is the
whole point. Developer inconvenience is immaterial.
> This is why I think it causes harm and should be removed.
I think arguing about the feature is causing more harm than the
feature ever would.
Removing a feature should never be done lightly.
Practicality beats purity.
>> [image.scale] should be removed.
> On a second thought, adding a deprecation warning and phasing it out
> seems a lot more reasonable, of course...
-1. "scale" stays. Let's add an entry to the to-do list to fix it,
and move on.
David Goodger <http://python.net/~goodger>