Release 23.08

CHANGELOG.md

@@ -2,10 +2,19 @@
 
 ## Project `accetto/headless-drawing-g3`
 
-[Docker Hub][this-docker] - [Git Hub][this-github] - [sibling Wiki][sibling-wiki] - [sibling Discussions][sibling-discussions]
+[User Guide][this-user-guide] - [Docker Hub][this-docker] - [Git Hub][this-github] - [sibling Wiki][sibling-wiki] - [sibling Discussions][sibling-discussions]
 
 ***
 
+### Release 23.08
+
+This release brings updated and significantly shortened README files, because most of the content has been moved into the new [User guide][this-user-guide].
+
+Updated applications:
+
+- `FreeCAD` to version **0.21.0**
+- `Inkscape` to version **1.3**
+
 ### Release 23.07.1
 
 This release brings some enhancements in the Dockerfiles and the script `user_generator.rc` with the aim to better support extending the images.
@@ -338,26 +347,34 @@ This is just a maintenance release.
 
 ***
 
+[this-user-guide]: https://accetto.github.io/user-guide-g3/
+
 [this-docker]: https://hub.docker.com/u/accetto/
+
 [this-github]: https://github.com/accetto/headless-drawing-g3/
 
 [accetto-docker-ubuntu-vnc-xfce-freecad-g3]: https://hub.docker.com/r/accetto/ubuntu-vnc-xfce-freecad-g3
 
-<!-- Sibling projects -->
-
 [accetto-github-ubuntu-vnc-xfce-g3]: https://github.com/accetto/ubuntu-vnc-xfce-g3
 
 [sibling-wiki]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki
+
 [sibling-discussions]: https://github.com/accetto/ubuntu-vnc-xfce-g3/discussions
 
 [sibling-wiki-building-stages]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki/Building-stages
+
 [sibling-wiki-how-ci-works]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki/How-CI-works
 
 [accetto-ubuntu-vnc-xfce-blender-g3]: https://hub.docker.com/r/accetto/ubuntu-vnc-xfce-blender-g3
+
 [accetto-ubuntu-vnc-xfce-drawio-g3]: https://hub.docker.com/r/accetto/ubuntu-vnc-xfce-drawio-g3
+
 [accetto-ubuntu-vnc-xfce-freecad-g3]: https://hub.docker.com/r/accetto/ubuntu-vnc-xfce-freecad-g3
+
 [accetto-ubuntu-vnc-xfce-gimp-g3]: https://hub.docker.com/r/accetto/ubuntu-vnc-xfce-gimp-g3
+
 [accetto-ubuntu-vnc-xfce-inkscape-g3]: https://hub.docker.com/r/accetto/ubuntu-vnc-xfce-inkscape-g3
+
 [accetto-ubuntu-vnc-xfce-opengl-g3]: https://hub.docker.com/r/accetto/ubuntu-vnc-xfce-opengl-g3
 
 [accetto-tigervnc-release-mirror]: https://github.com/accetto/tigervnc/releases

docker/xfce-chromium/src/home/readme-chromium.md

@@ -1,3 +1,5 @@
 # Readme `Chromium`
 
-Note that `Chromium Browser` in this container runs in `--no-sandbox` mode. You should be aware of the implications. The browser is intended for testing and development.
+Note that `Chromium Browser` in this container runs in `--no-sandbox` mode.
+You should be aware of the implications.
+The browser is intended for testing and development.

readme-builder.md

@@ -13,7 +13,8 @@
 
 ## Introduction
 
-This utility script can build and publish individual images. It can also execute the individual hook scripts of the building pipeline (`docker/hooks` folder).
+This utility script can build and publish individual images.
+It can also execute the individual hook scripts of the building pipeline (`docker/hooks` folder).
 
 Common usage pattern:
 
@@ -116,9 +117,12 @@ You can also use other ways to set the variables.
 
 ### Ensure `wget` utility
 
-If you are on Windows, you can encounter the problem of missing `wget` utility. It is used by refreshing the `g3-cache` and it's available on Linux by default.
+If you are on Windows, you can encounter the problem of missing `wget` utility.
+It is used by refreshing the `g3-cache` and it's available on Linux by default.
 
-On Windows you have generally two choices. You can build your images inside the `WSL` environment or you can download the `wget.exe` application for Windows. Make sure to update also the `PATH` environment variable appropriately.
+On Windows you have generally two choices.
+You can build your images inside the `WSL` environment or you can download the `wget.exe` application for Windows.
+Make sure to update also the `PATH` environment variable appropriately.
 
 ## Executing complete pipeline
 
@@ -143,7 +147,8 @@ You can skip the publishing to the **Docker Hub** by replacing the command `all`
 ./builder.sh blender all-no-push
 ```
 
-You can also provide additional parameters for the internally used Docker `build` command. For example:
+You can also provide additional parameters for the internally used Docker `build` command.
+For example:
 
 ```shell
 ./builder.sh blender all-no-push --no-cache
@@ -152,7 +157,8 @@ You can also provide additional parameters for the internally used Docker `build
 ### docker build --no-cache ...
 ```
 
-The optional `<docker-cli-options>` are passed only to the `pre_build` hook script, which passes them to the internally used `docker build` command. The `cache` hook script, however, doesn't use any Docker CLI commands.
+The optional `<docker-cli-options>` are passed only to the `pre_build` hook script, which passes them to the internally used `docker build` command.
+The `cache` hook script, however, doesn't use any Docker CLI commands.
 
 ## Executing individual pipeline steps
 
@@ -179,11 +185,14 @@ The building pipeline consists of the following steps, that can be executed also
 ./builder.sh blender post_push
 ```
 
-The optional `<docker-cli-options>` are passed to the each individual hook script, which can pass them to the internally used Docker CLI command. The `cache` hook script, however, doesn't use any Docker CLI commands.
+The optional `<docker-cli-options>` are passed to the each individual hook script, which can pass them to the internally used Docker CLI command.
+The `cache` hook script, however, doesn't use any Docker CLI commands.
 
 ### What about the 'cache' helper script
 
-The `cache` hook script has been introduced in the **second version** (G3v2) of the building pipeline in the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3]. It refreshes the local `g3-cache`, which must be always placed inside the Docker build context. The script is also used by the `pre_build` and `build` hook scripts.
+The `cache` hook script has been introduced in the **second version** (G3v2) of the building pipeline in the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3].
+It refreshes the local `g3-cache`, which must be always placed inside the Docker build context.
+The script is also used by the `pre_build` and `build` hook scripts.
 
 The `g3-cache` and the rules for its refreshing are described separately.
 

readme-ci-builder.md

@@ -20,7 +20,8 @@
 
 ## Introduction
 
-This utility script can build and publish sets of images. It can also extract selected information from the building log.
+This utility script can build and publish sets of images.
+It can also extract selected information from the building log.
 
 The common usage pattern
 
@@ -46,7 +47,7 @@ This script can:
 Usage: <script> <mode> <argument> [<optional-argument>]...
 
     ./ci-builder.sh [<options>] <command> group <blend> [<blend>]...
-    ./ci-builder.sh [<options>] <command> family <parent-blend> [<child-suffix>]...       
+    ./ci-builder.sh [<options>] <command> family <parent-blend> [<child-suffix>]...
     ./ci-builder.sh [--log-all] log get (digest|stickers|timing|errors)
 
 <options>      := (--log-all|--no-cache) 
@@ -58,7 +59,7 @@ Usage: <script> <mode> <argument> [<optional-argument>]...
                   |(complete[-chromium|-firefox|-latest|-blender|-drawio|-gimp|-inkscape])
                   |(latest|blender|drawio|gimp|inkscape)[-(chromium|firefox)])
 
-Family mode: The children are skipped if a new parent image was not actually built.       
+Family mode: The children are skipped if a new parent image was not actually built.
 Group mode : All images are processed independently.
 
 The command and the blend are passed to the builder script.
@@ -69,7 +70,9 @@ The script creates a complete execution log.
 
 The optional parameter `--no-cache` will be passed to the internally used script `builder.sh`.
 
-The optional parameter `--log-all` will cause that the script's output will be written into the log file in all cases. Normally the command line errors or the **log processing mode** commands are not logged. 
+The optional parameter `--log-all` will cause that the script's output will be written into the log file in all cases.
+Normally the command line errors or the **log processing mode** commands are not logged.
+
 
 ## Preparation
 
@@ -146,9 +149,12 @@ You can also use other ways to set the variables.
 
 ### Ensure `wget` utility
 
-If you are on Windows, you can encounter the problem of missing `wget` utility. It is used by refreshing the `g3-cache` and it's available on Linux by default.
+If you are on Windows, you can encounter the problem of missing `wget` utility.
+It is used by refreshing the `g3-cache` and it's available on Linux by default.
 
-On Windows you have generally two choices. You can build your images inside the `WSL` environment or you can download the `wget.exe` application for Windows. Make sure to update also the `PATH` environment variable appropriately.
+On Windows you have generally two choices.
+You can build your images inside the `WSL` environment or you can download the `wget.exe` application for Windows.
+Make sure to update also the `PATH` environment variable appropriately.
 
 ## Usage modes
 
@@ -164,7 +170,8 @@ The **group mode** usage pattern:
 
 #### Group mode examples
 
-The image tags can be listed in the command line. For example, all these images will be built independently of each other.
+The image tags can be listed in the command line.
+For example, all these images will be built independently of each other.
 
 ```shell
 ./ci-builder.sh all group blender drawio-firefox gimp inkscape
@@ -203,13 +210,16 @@ You can also use one of the **named groups**:
 
 The **family mode** is intended for an efficient building of the sets of dependent images.
 
-**Remark:** Since the version G3v3 of the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] is this mode for advanced use only. The previous images `accetto/ubuntu-vnc-xfce-g3:latest-fugo` and `accetto/ubuntu-vnc-xfce-firefox-g3:latest-plus` that used it are not published any more. The image `accetto/ubuntu-vnc-xfce-firefox-g3:latest-plus` has been renamed to `accetto/ubuntu-vnc-xfce-firefox-g3:latest`.
+**Remark:** Since the version G3v3 of the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] is this mode for advanced use only.
+The previous images `accetto/ubuntu-vnc-xfce-g3:latest-fugo` and `accetto/ubuntu-vnc-xfce-firefox-g3:latest-plus` that used it are not published any more.
+The image `accetto/ubuntu-vnc-xfce-firefox-g3:latest-plus` has been renamed to `accetto/ubuntu-vnc-xfce-firefox-g3:latest`.
 
 The dependency in this context is meant more technically than conceptually.
 
 The following example will help to understand the concept.
 
-This project currently does not include any images that are in such a relation. Therefore it will be explained using the images from the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3].
+This project currently does not include any images that are in such a relation.
+Therefore it will be explained using the images from the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3].
 
 The image `accetto/ubuntu-vnc-xfce-firefox-g3:latest-plus` added some additional features to the image `accetto/ubuntu-vnc-xfce-firefox-g3:latest`, but otherwise were both images identical.
 
@@ -245,7 +255,8 @@ The following command can also be used, but there would be no benefit comparing
 ./ci-builder.sh all family latest-chromium
 ```
 
-You can also skip the publishing to the **Docker Hub** by replacing the `all` command by the `all-no-push` one. For example:
+You can also skip the publishing to the **Docker Hub** by replacing the `all` command by the `all-no-push` one.
+For example:
 
 ```shell
 ### image 'latest-fugo' will be skipped if the 'latest' image doesn't need a re-build
@@ -254,7 +265,8 @@ You can also skip the publishing to the **Docker Hub** by replacing the `all` co
 
 ### Log processing
 
-The **log processing** mode is intended for evaluating the outcome of the latest image building session. The result are extracted from the **ci-builder log** by `grep` utility.
+The **log processing** mode is intended for evaluating the outcome of the latest image building session.
+The result are extracted from the **ci-builder log** by `grep` utility.
 
 The **log processing mode** usage pattern:
 
@@ -279,13 +291,14 @@ Building image 'headless-drawing-g3:gimp'
 Building image 'headless-drawing-g3:gimp-chromium'
 Building image 'headless-drawing-g3:gimp-firefox' 
 Built new 'headless-drawing-g3:gimp'.
-Built new 'headless-drawing-g3:gimp-chromium'.    
+Built new 'headless-drawing-g3:gimp-chromium'.
 Built new 'headless-drawing-g3:gimp-firefox'.
 ```
 
 #### Stickers command
 
-The `stickers` command extracts the information about the **version stickers** of the ephemeral helper images that have been built by the `pre_build` hook script. That does not mean that the final persistent images have also been built (and optionally also published).
+The `stickers` command extracts the information about the **version stickers** of the ephemeral helper images that have been built by the `pre_build` hook script.
+That does not mean that the final persistent images have also been built (and optionally also published).
 
 ```shell
 ./ci-builder.sh log get stickers

readme-g3-cache.md

@@ -21,9 +21,12 @@ You can learn more about the concept on the sibling Wiki page ["Concepts of `g3-
 
 ### Ensure `wget` utility
 
-If you are on Windows, you can encounter the problem of missing `wget` utility. It is used by refreshing the `g3-cache` and it's available on Linux by default.
+If you are on Windows, you can encounter the problem of missing `wget` utility.
+It is used by refreshing the `g3-cache` and it's available on Linux by default.
 
-On Windows you have generally two choices. You can build your images inside the `WSL` environment or you can download the `wget.exe` application for Windows. Make sure to update also the `PATH` environment variable appropriately.
+On Windows you have generally two choices.
+You can build your images inside the `WSL` environment or you can download the `wget.exe` application for Windows.
+Make sure to update also the `PATH` environment variable appropriately.
 
 ## Local `g3-cache`
 
@@ -48,9 +51,11 @@ The same shared `g3-cache` is usually used also by the sibling projects, for exa
 
 ## Helper script `cache`
 
-Both `g3-caches` are refreshed by the helper script `cache`, which is stored in the folder `docker/hooks/`. Therefore it's sometimes referenced as a hook script.
+Both `g3-caches` are refreshed by the helper script `cache`, which is stored in the folder `docker/hooks/`.
+Therefore it's sometimes referenced as a hook script.
 
-The script is used by the hook scripts `pre_build` and `build`. However, it can be executed also stand-alone.
+The script is used by the hook scripts `pre_build` and `build`.
+However, it can be executed also stand-alone.
 
 **Remark**: The current implementation of the cache refreshing code is not thread safe and it is not intended for parallel building of multiple images.
 

readme-local-building-example.md

@@ -105,9 +105,12 @@ You can also use other ways to set the variables.
 
 ### Ensure `wget` utility
 
-If you are on Windows, you can encounter the problem of missing `wget` utility. It is used by refreshing the `g3-cache` and it's available on Linux by default.
+If you are on Windows, you can encounter the problem of missing `wget` utility.
+It is used by refreshing the `g3-cache` and it's available on Linux by default.
 
-On Windows you have generally two choices. You can build your images inside the `WSL` environment or you can download the `wget.exe` application for Windows. Make sure to update also the `PATH` environment variable appropriately.
+On Windows you have generally two choices.
+You can build your images inside the `WSL` environment or you can download the `wget.exe` application for Windows.
+Make sure to update also the `PATH` environment variable appropriately.
 
 ## Building pipeline
 
@@ -120,11 +123,14 @@ The actual building pipeline consists of the following hook scripts stored in th
 
 The hook scripts are executed exactly in that order.
 
-The **second version** (G3v2) of the pipeline has added also the helper script `cache`, which ist stored in the same folder. It is used by the hook scripts `pre_build` and `build` and it refreshes the local `g3-cache`. It can be also executed  stand-alone.
+The **second version** (G3v2) of the pipeline has added also the helper script `cache`, which ist stored in the same folder.
+It is used by the hook scripts `pre_build` and `build` and it refreshes the local `g3-cache`.
+It can be also executed  stand-alone.
 
 Utilizing the local `g3-cache` brings a significant boost in the building performance and much shorter building times.
 
-There is also the helper script `util-readme.sh`, stored in the folder `utils/`. This script can be used for preparing the `README` file for the **Docker Hub**.
+There is also the helper script `util-readme.sh`, stored in the folder `utils/`.
+This script can be used for preparing the `README` file for the **Docker Hub**.
 
 ## Three ways of building images
 
@@ -138,7 +144,9 @@ Since the **second version** (G3v2) of the building pipeline there are the follo
 
 ### Building and publishing sets of images
 
-Building and publishing of sets of images is pretty easy. Let's say that we want to refresh the images that feature the `Blender`. We can do that by executing the following command:
+Building and publishing of sets of images is pretty easy.
+Let's say that we want to refresh the images that feature the `Blender`.
+We can do that by executing the following command:
 
 ```shell
 ### PWD = project's root directory
@@ -159,7 +167,9 @@ You can find more information and examples in the separate `readme` file, descri
 
 ### Building and publishing individual images
 
-Building and publishing of individual images is also very easy. Let's say we wan to refresh the image `accetto/ubuntu-vnc-xfce-opengl-g3:latest`. We could execute the following command:
+Building and publishing of individual images is also very easy.
+Let's say we wan to refresh the image `accetto/ubuntu-vnc-xfce-opengl-g3:latest`.
+We could execute the following command:
 
 ```shell
 ### PWD = project's root directory
@@ -179,7 +189,8 @@ You can find more information and examples in the separate `readme` file, descri
 
 ### Step-by-step building and publishing
 
-The building pipeline can executed also step-by-step. The hook scripts in the folder `docker/hooks/` can be executed directly or also by using the utility script `builder.sh`.
+The building pipeline can executed also step-by-step.
+The hook scripts in the folder `docker/hooks/` can be executed directly or also by using the utility script `builder.sh`.
 
 The script `builder.sh` is using the individual hook scripts internally.
 
@@ -205,7 +216,9 @@ This step builds the temporary helper image and creates the following temporary
 - `scrap-version_sticker-verbose_previous.tmp`
 - `scrap-demand-stop-building`
 
-The file `scrap-demand-stop-building` is created only if the verbose version sticker hasn't changed since the last time it has been published on the builder repository's **GitHub Gist** and if the environment variable `FORCE_BUILDING` is not set to `1`. **Its presence will block** the next hook script `build` from building a new persistent image. If you want to force the image building, you can delete this file manually.
+The file `scrap-demand-stop-building` is created only if the verbose version sticker hasn't changed since the last time it has been published on the builder repository's **GitHub Gist** and if the environment variable `FORCE_BUILDING` is not set to `1`.
+**Its presence will block** the next hook script `build` from building a new persistent image.
+If you want to force the image building, you can delete this file manually.
 
 The other option is to set the environment variable `FORCE_BUILDING=1` **before** executing the `pre_build` script.