Merge stable into master

docs/updating/update-to-40.md

@@ -32,6 +32,38 @@ This release introduces changes to the {@link features/images-overview image fea
 * Changes to an image (such as resize, etc.) will trigger the creation of those attributes. These attributes are crucial to proper content handling, and actions on a current image that does not have these improve this image's markup.
 * The `aspect-ratio` attribute has been added to the image's properties to handle situations when the file is resized or scaled with a tweaked aspect ratio.
 
+Image output HTML before:
+
+```html
+<p>
+	<img src="image.jpg" alt="">
+</p>
+```
+
+Image output HTML after (added the `width` and `height` attributes):
+
+```html
+<p>
+	<img src="image.jpg" alt="" width="400" height="300">
+</p>
+```
+
+Resized image output HTML before:
+
+```html
+<p>
+	<img class="image_resized" style="width:50%;" src="image.jpg" alt="">
+</p>
+```
+
+Resized image output HTML after (added the `aspect-ratio` style and the `width` and `height` attributes):
+
+```html
+<p>
+	<img class="image_resized" style="aspect-ratio:400/300;width:50%;" src="image.jpg" alt="" width="400" height="300">
+</p>
+```
+
 #### Changes to the model
 
 Due to the introduction of this new behavior, the following changes to model attributes have been introduced:
@@ -46,13 +78,37 @@ Therefore, the relation between styles and attributes toward model attributes lo
 * Attribute `width` → model `width` (new).
 * Attribute `height` → model `height` (new).
 
+Given the following input HTML:
+
+```html
+<p>
+	<img src="image.jpg" style="width:50%;" width="400" height="300" alt="">
+</p>
+```
+
+Previously, the model would set the resized value in the `width` model attribute and ignore the input `width` and `height` attributes:
+
+```html
+<paragraph>
+	<imageInline src="image.jpg" width="50%"></imageInline>
+</paragraph>
+```
+
+And now the resized value is stored in the `resizedWidth` attribute (the `width` attribute is now reserved for the natural width value):
+
+```html
+<paragraph>
+	<imageInline src="image.jpg" resizedWidth="50%" width="400" height="300"></imageInline>
+</paragraph>
+```
+
 #### Changes to the `srcset` attribute
 
 The `srcset` model attribute which provides parameters for responsive images, has been simplified. It is no longer an object `{ data: "...", width: "..." }`, but the value that was previously stored in the `data` part.
 
 #### Changes to content styles
 
-Last but not least, content styles have been updated with this release, which means you need to update them in your editor implementation to avoid any discrepancies. Please refer to the {@link installation/advanced/content-styles Content styles} guide to learn how to generate the stylesheet.
+Last but not least, content styles have been updated with this release, which means you need to update them in your editor implementation to avoid any discrepancies. Please refer to the {@link installation/advanced/content-styles Content styles} guide to learn how to generate the style sheet.
 
 ### Changes to the comments feature