Update QUIP 21

An earlier patch got accidentally pushed, approved and published.

Fixed the Post-History value, links to references, and the level of
the References heading.

Change-Id: Ib47d5c6f566b1ee4e5425776fe50ad466614fc95
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>

1 files changed, 36 insertions, 38 deletions

diff --git a/quip-0021-images-in-docs.rst b/quip-0021-images-in-docs.rst
index 89a8fbd..36e84e9 100644
--- a/quip-0021-images-in-docs.rst
+++ b/quip-0021-images-in-docs.rst
@@ -4,7 +4,7 @@ Author: Leena Miettinen
 Status: Active
 Type: Process
 Created: 2023-11-13
-Post-History: https://doc.qt.io/qtcreator-extending/qtcreator-documentation.html#using-images
+Post-History: https://lists.qt-project.org/pipermail/development/2023-November/044706.html
 
 Overview
 ========
@@ -20,26 +20,25 @@ You can use the following types of images in Qt documentation:
 Saving images
 =============
 
-QDoc supports the following image formats:
+QDoc can create references to images of any format. The image is shown if
+the user's tool or browser supports the image format. Most browsers support the
+following image formats:
 
-- GIF
-- JPEG
-- WebP
-- PNG
-- SVG
+- GIF (``.gif``)
+- JPEG (``.jpg``)
+- WebP (``.webp``)
+- PNG (``.png``)
+- SVG (``.svg``)
 
 You can find reasons for picking a particular image format in the following
 sections.
 
-Use the ``images.fileextensions`` variable [0] in the documentation configuration
-file (``.qdocconf``) to get support for more image formats.
-
 Locations
 ---------
 
 Save images in the Git repositories in an ``images`` folder. QDoc looks for
-images in folders that you specify as values of the ``imagedirs`` variable [1]
-in the documentation configuration file.
+images in folders that you specify as values of the ``imagedirs`` variable [0]_
+in the documentation configuration file (``.qdocconf``).
 
 You can create subfolders for particular types of images, such as icons or
 images used in examples.
@@ -64,9 +63,9 @@ QDoc commands and macros
 
 Use QDoc commands to refer to images from the text:
 
-- ``\image`` places the image on a separate line [2]
-- ``\inlineimage`` places the image inline, surrounded by text [3]
-- ``\youtube`` embeds a video from YouTube [4]
+- ``\image`` places the image on a separate line [1]_
+- ``\inlineimage`` places the image inline, surrounded by text [2]_
+- ``\youtube`` embeds a video from YouTube [3]_
 
 Screenshots
 ===========
@@ -89,7 +88,7 @@ Follow these guidelines when taking screenshots:
   reduced visual quality and increases the file size. Also, the CSS we use
   online scales down images that are wider than 800 pixels.
 - To highlight parts of the screenshot, use the images of numbers
-  that are stored in [5].
+  that are stored in [4]_.
 - If you use PNG images, optimize them before you submit them to the repository.
 
 Note: Do not rely on screenshots to present reasonable example values to
@@ -97,21 +96,21 @@ users, but always place example values also in the text.
 
 Note: The selected screen resolution is a compromise that offers acceptable
 quality with acceptable image file size. We are looking for solutions to using
-high-DPI images [6].
+high-DPI images [5]_.
 
 Highlighting parts of the screen
 ---------------------------------
 
 You can use number icons in screenshots to highlight parts of the screenshot
 (instead of using arrows or borders, for example). You can then refer to the
-numbers in text. For example, see [7].
+numbers in text. For example, see [6]_.
 
 This improves the consistency of the look and feel of Qt documentation,
 and eliminates the need to describe parts of the UI in the text because
 you can just insert the number of the element you are referring to in
 brackets.
 
-You can find images of numbers from 1 to 10 in [5].
+You can find images of numbers from 1 to 10 in [4]_.
 
 To use the numbers, copy-paste the number images on the screenshot to the
 places that you want to refer to from text.
@@ -119,25 +118,25 @@ places that you want to refer to from text.
 Icons
 =====
 
-You can view Qt Documentation online [8] in dark and light modes. To make the
+You can view Qt Documentation online [7]_ in dark and light modes. To make the
 icons used in the docs visible in both modes, save icon files as gray-scale
 images with a transparent background.
 
 If you receive a large number of icons that are not visible in either light
 or dark mode or have a solid background, run the ``recolordocsicons.py``
 Python script from the ``qttools/util/recolordocsicons`` folder. For options
-and examples, see [9].
+and examples, see [8]_.
 
 Animated images
 ===============
 
 Sometimes, it is easier to explain how something works by recording a short
 animation in lossless WebP or GIF format. You can use any tool you like, such
-as the screen recorder in Qt Creator [10] or ScreenToGif [11]. Animated images
+as the screen recorder in Qt Creator [9]_ or ScreenToGif [10]_. Animated images
 are typically bigger than screenshots, so try to make them as short and to the
 point as you can.
 
-Use the ``\image`` command [2] to refer to WebP and GIF files from the
+Use the ``\image`` command [1]_ to refer to WebP and GIF files from the
 documentation.
 
 Note: If the animation is very long, consider recording a video and embedding
@@ -146,22 +145,21 @@ it from YouTube.
 YouTube videos
 ==============
 
-You can use the ``\youtube`` macro [4] to embed a YouTube video in the HTML.
+You can use the ``\youtube`` macro [3]_ to embed a YouTube video in the HTML.
 When QDoc generates offline documentation (``.qch``), it adds an external
 link to the video with a thumbnail image.
 
 References
-----------
-
-.. [0] `images.fileextensions variable https://doc.qt.io/qt-6/22-qdoc-configuration-generalvariables.html#images.fileextensions`
-.. [1] `imagedirs variable https://doc.qt.io/qt-6/22-qdoc-configuration-generalvariables.html#imagedirs`
-.. [2] `\image command https://doc.qt.io/qt-6/09-qdoc-commands-includingimages.html#image-command`
-.. [3] `\inlineimage command https://doc.qt.io/qt-6/09-qdoc-commands-includingimages.html#inlineimage-command`
-.. [4] ``macro.youtube`` in ``qtbase/doc/global/macros.qdocconf``
-.. [5] Number icons in ``qtdoc/doc/images/numbers/``
-.. [6] `QTBUG-63366 https://bugreports.qt.io/browse/QTBUG-63366`
-.. [7] `Qt Creator: User Interface https://doc.qt.io/qtcreator/creator-quick-tour.html`
-.. [8] `Qt Documentation https://doc.qt.io/`
-.. [9] `How to recolor icons for doc.qt.io qttools/util/recolordocsicons/README.md`
-.. [10] `Qt Creator: Record screens https://doc.qt.io/qtcreator/creator-how-to-record-screens.html`
-.. [11] `ScreenToGIF https://www.screentogif.com/`
+==========
+
+.. [0] https://doc.qt.io/qt-6/22-qdoc-configuration-generalvariables.html#imagedirs
+.. [1] https://doc.qt.io/qt-6/09-qdoc-commands-includingimages.html#image-command
+.. [2] https://doc.qt.io/qt-6/09-qdoc-commands-includingimages.html#inlineimage-command
+.. [3] ``macro.youtube`` in ``qtbase/doc/global/macros.qdocconf``
+.. [4] ``qtdoc/doc/images/numbers/``
+.. [5] https://bugreports.qt.io/browse/QTBUG-63366
+.. [6] https://doc.qt.io/qtcreator/creator-quick-tour.html
+.. [7] https://doc.qt.io/
+.. [8] ``qttools/util/recolordocsicons/README.md``
+.. [9] https://doc.qt.io/qtcreator/creator-how-to-record-screens.html
+.. [10] https://www.screentogif.com/