From 1e02140e5098d261015df016d4c620bb29550ad5 Mon Sep 17 00:00:00 2001
From: egasimus <adam@hack.bg>
Date: Tue, 9 Jan 2024 04:10:32 +0200
Subject: [PATCH 01/10] docs: add more nixos info

- install instructions
- enabling SPICE USB passthru
---
 README.md | 53 ++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 50 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 7c5bd7bd7b..0f212404b5 100644
--- a/README.md
+++ b/README.md
@@ -179,6 +179,37 @@ sudo apt update
 sudo apt install quickemu
 ```
 
+## NixOS
+
+To quickly try quickemu:
+
+```sh
+nix-shell -p quickemu
+```
+
+To install via Nix profile:
+
+```sh
+nix-env -iA pkgs.quickemu
+```
+
+To install via NixOS config:
+
+```nix
+# /etc/nixos/configuration.nix
+{pkgs, ...}: {
+   environment.systemPackages = with pkgs; 
+     quickemu 
+   };
+}
+```
+
+To install via Flakes:
+
+```sh
+# TODO (flake users, please add an example!)
+```
+
 ## Other Linux
 
 ``` bash
@@ -742,11 +773,27 @@ pass-through.
 ## SPICE redirection (recommended)
 
 Using SPICE for USB pass-through is easiest as it doesn't require any
-elevated permission, start Quickemu with `--display spice` and then
-select `Input` -\> `Select USB Device for redirection` from the menu to
+elevated permission:
+
+* Start Quickemu with `--display spice` and then
+* select `Input` -\> `Select USB Device for redirection` from the menu to
 choose which device(s) you want to attach to the guest.
 
-## Host redirection **NOT Recommended**
+### Enabling SPICE redirection on NixOS
+
+On NixOS, if you encounter this error:
+
+```
+Error setting facl: Operation not permitted
+```
+
+Try setting [the following option](https://search.nixos.org/options?channel=23.11&show=virtualisation.spiceUSBRedirection.enable&from=0&size=50&sort=relevance&type=packages&query=spiceusbredirec):
+
+```nix
+virtualisation.spiceUSBRedirection.enable = true;
+```
+
+## Host redirection (**NOT Recommended**)
 
 **USB host redirection is not recommended**, it is provided purely for
 backwards compatibility to older versions of Quickemu. Using SPICE is

From 56d605edda53fd1a3d3cd0afe8226f41a0786d33 Mon Sep 17 00:00:00 2001
From: egasimus <adam@hack.bg>
Date: Tue, 9 Jan 2024 16:04:35 +0200
Subject: [PATCH 02/10] docs(readme): introductory section

move repology status, discord link, and video, front and center
---
 README.md | 76 +++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 52 insertions(+), 24 deletions(-)

diff --git a/README.md b/README.md
index 0f212404b5..32af3e6074 100644
--- a/README.md
+++ b/README.md
@@ -1,25 +1,66 @@
-<h1 align="center">
-  <img src=".github/logo.png" alt="Quickemu" width="256" />
-  <br />
-  Quickemu
-</h1>
+<div align="center">
 
-<p align="center"><b>Quickly create and run optimised Windows, macOS and Linux desktop virtual machines.</b></p>
-<div align="center"><img src=".github/screenshot.png" alt="Quickemu Screenshot" /></div>
-<p align="center">Made with 💝 for <img src=".github/tux.png" align="top" width="18" /></p>
+<img src=".github/logo.png" alt="Quickemu" width="256" />
+
+# Quickemu
+
+**Quickly create and run optimised Windows, macOS and Linux desktop virtual machines.**
+
+<img src=".github/screenshot.png" alt="Quickemu Screenshot" />
+
+**Made with 💝 for <img src=".github/tux.png" align="top" width="24" />.**
+
+Packaging status by [Repology.org](https://repology.org/):
+
+<table>
+<tbody>
+<tr valign="top">
+<td>
+  
+[![Packaging
+status of quickemu](https://repology.org/badge/vertical-allrepos/quickemu.svg?header=quickemu)](https://repology.org/project/quickemu/versions)
+
+</td>
+<td>
+
+[![Packaging
+status](https://repology.org/badge/vertical-allrepos/quickgui.svg?header=quickgui)](https://repology.org/project/quickgui/versions)
+  
+</td>
+</tr>
+</tbody>
+</table>
+
+
+We have a Discord for this project:
+
+[![Discord](https://img.shields.io/discord/712850672223125565?color=0C306A&label=WimpysWorld%20Discord&logo=Discord&logoColor=ffffff&style=flat-square)](https://discord.gg/sNmz3uw)
+
+See this (old) video where I explain some of my motivations for creating
+Quickemu:
+
+[![Replace VirtualBox with Bash &
+QEMU](https://img.youtube.com/vi/AOTYWEgw0hI/0.jpg)](https://www.youtube.com/watch?v=AOTYWEgw0hI)
+
+</div>
 
 ## Introduction
 
+**Quickemu** is a wrapper for the excellent [QEMU](https://www.qemu.org/)
+that attempts to automatically *"do the right thing"*, rather than
+expose exhaustive configuration options.
+
 Quickly create and run highly optimised desktop virtual machines for
-Linux, macOS and Windows; with just two commands. You decide what
-operating system you want to run and Quickemu will figure out the best
-way to do it for you. For example:
+Linux, macOS and Windows, with just two commands:
 
 ``` bash
 quickget ubuntu-mate 22.04
 quickemu --vm ubuntu-mate-22.04.conf
 ```
 
+You decide what operating system you want to run
+and Quickemu will figure out the best way to do it for you.
+
 The original objective of the project was to enable quick testing of
 Linux distributions where the virtual machine configurations can be
 stored anywhere, such as external USB storage or your home directory,
@@ -52,19 +93,6 @@ Windows**.
 -   EFI (with or without SecureBoot) and Legacy BIOS boot
 -   Graphical user interfaces available
 
-Quickemu is a wrapper for the excellent [QEMU](https://www.qemu.org/)
-that attempts to automatically *"do the right thing"*, rather than
-expose exhaustive configuration options.
-
-We have a Discord for this project:
-[![Discord](https://img.shields.io/discord/712850672223125565?color=0C306A&label=WimpysWorld%20Discord&logo=Discord&logoColor=ffffff&style=flat-square)](https://discord.gg/sNmz3uw)
-
-See this (old) video where I explain some of my motivations for creating
-Quickemu.
-
-[![Replace VirtualBox with Bash &
-QEMU](https://img.youtube.com/vi/AOTYWEgw0hI/0.jpg)](https://www.youtube.com/watch?v=AOTYWEgw0hI)
-
 ## Requirements
 
 -   [QEMU](https://www.qemu.org/) (*6.0.0 or newer*) **with GTK, SDL,

From 2bdcc90be9923ea14869ab9b1255ff9c777b42d4 Mon Sep 17 00:00:00 2001
From: egasimus <adam@hack.bg>
Date: Tue, 9 Jan 2024 16:09:38 +0200
Subject: [PATCH 03/10] docs(readme): remove old repology badges

---
 README.md | 15 ---------------
 1 file changed, 15 deletions(-)

diff --git a/README.md b/README.md
index 32af3e6074..09905e1738 100644
--- a/README.md
+++ b/README.md
@@ -247,21 +247,6 @@ cd quickemu
 
 Now install all the **Requirements** documented above.
 
-### Other sources
-
-[Repology.org](https://repology.org/) found the following releases have
-been packaged.
-
-#### Quickemu
-
-[![Packaging
-status](https://repology.org/badge/vertical-allrepos/quickemu.svg)](https://repology.org/project/quickemu/versions)
-
-#### Quickgui
-
-[![Packaging
-status](https://repology.org/badge/vertical-allrepos/quickgui.svg)](https://repology.org/project/quickgui/versions)
-
 ## Ubuntu Guest
 
 `quickget` will automatically download an Ubuntu release and create the

From 81f782d5a858bf53ce6007a49b86d73ff0616b1c Mon Sep 17 00:00:00 2001
From: egasimus <adam@hack.bg>
Date: Tue, 9 Jan 2024 17:24:32 +0200
Subject: [PATCH 04/10] wip: docs(readme): hierarchy, ordering

---
 README.md | 269 ++++++++++++++++++++++++++++--------------------------
 1 file changed, 139 insertions(+), 130 deletions(-)

diff --git a/README.md b/README.md
index 09905e1738..51cf54b649 100644
--- a/README.md
+++ b/README.md
@@ -61,12 +61,12 @@ quickemu --vm ubuntu-mate-22.04.conf
 You decide what operating system you want to run
 and Quickemu will figure out the best way to do it for you.
 
-The original objective of the project was to enable quick testing of
-Linux distributions where the virtual machine configurations can be
-stored anywhere, such as external USB storage or your home directory,
+The original objective of the project was to enable [quick testing of
+Linux distributions](#linux-guests) where the virtual machine configurations can be
+stored anywhere (such as external USB storage or your home directory)
 and no elevated permissions are required to run the virtual machines.
-**Quickemu now also includes comprehensive support for macOS and
-Windows**.
+**Quickemu now also includes comprehensive support for [macOS](#macos-guests)
+and [Windows](#windows-guests)**.
 
 ## Features
 
@@ -93,7 +93,72 @@ Windows**.
 -   EFI (with or without SecureBoot) and Legacy BIOS boot
 -   Graphical user interfaces available
 
-## Requirements
+## Installation
+
+### Arch Linux hosts
+
+Quickemu is available from the AUR (Arch user repository), and can be
+installed via any AUR helper. Assuming your AUR helper is yay, Run the
+following command:
+
+``` bash
+yay -Sy quickemu
+```
+
+### Ubuntu hosts
+
+Quickemu is available from a PPA for Ubuntu users. The Quickemu PPA also
+includes a back port of QEMU 6.0.0 for 20.04 (Focal) and 21.04
+(Hirsute). To install Quickemu and all the dependencies run the
+following in a terminal:
+
+``` bash
+sudo apt-add-repository ppa:flexiondotorg/quickemu
+sudo apt update
+sudo apt install quickemu
+```
+
+### NixOS hosts
+
+To quickly try quickemu:
+
+```sh
+nix-shell -p quickemu
+```
+
+To install via Nix profile:
+
+```sh
+nix-env -iA pkgs.quickemu
+```
+
+To install via NixOS config:
+
+```nix
+# /etc/nixos/configuration.nix
+{pkgs, ...}: {
+   environment.systemPackages = with pkgs; 
+     quickemu 
+   };
+}
+```
+
+To install via Flakes:
+
+```sh
+# TODO (flake users, please add an example!)
+```
+
+### Other Linux hosts (installing from source)
+
+``` bash
+git clone --filter=blob:none https://github.com/wimpysworld/quickemu
+cd quickemu
+```
+
+Now install all the **Requirements** documented below:
+
+#### Requirements
 
 -   [QEMU](https://www.qemu.org/) (*6.0.0 or newer*) **with GTK, SDL,
     SPICE & VirtFS support**
@@ -119,9 +184,7 @@ Windows**.
 -   [zsync](http://zsync.moria.org.uk/)
 -   [unzip](http://www.info-zip.org/UnZip.html)
 
-### Installing Requirements
-
-For Ubuntu, Arch and nixos systems the
+For Ubuntu, Arch and NixOS hosts, the
 [ppa](https://launchpad.net/~flexiondotorg/+archive/ubuntu/quickemu),
 [AUR](https://aur.archlinux.org/packages/quickemu) or
 [nix](https://github.com/NixOS/nixpkgs/tree/master/pkgs/development/quickemu)
@@ -129,125 +192,67 @@ packaging will take care of the dependencies. For other host
 distributions or operating systems it will be necessary to install the
 above requirements or their equivalents.
 
-These examples may save a little typing
+These examples may save a little typing:
 
-Debian (and direct derivatives such as MX Linux):
+##### Install requirements on Debian hosts
 
-    sudo apt install qemu bash coreutils ovmf grep jq lsb-base procps python3 genisoimage usbutils util-linux sed spice-client-gtk libtss2-tcti-swtpm0 wget xdg-user-dirs zsync unzip
+This also applies to direct derivatives, such as MX Linux:
 
-Fedora:
+```sh
+sudo apt install qemu bash coreutils ovmf grep jq lsb-base procps python3 genisoimage usbutils util-linux sed spice-client-gtk libtss2-tcti-swtpm0 wget xdg-user-dirs zsync unzip
+```
+
+##### Install requirements on Fedora hosts
 
-    sudo dnf install qemu bash coreutils edk2-tools grep jq lsb procps python3 genisoimage usbutils util-linux sed spice-gtk-tools swtpm wget xdg-user-dirs xrandr unzip
+```sh
+sudo dnf install qemu bash coreutils edk2-tools grep jq lsb procps python3 genisoimage usbutils util-linux sed spice-gtk-tools swtpm wget xdg-user-dirs xrandr unzip
+```
 
-MacOS:
+##### Installing dependencies on macOS hosts
 
-This is a work in progress (see [issue
-248](https://github.com/quickemu-project/quickemu/issues/248) for other
-steps and changes that may enable running on MacOS)
+This is a work in progress (see [issue 248](https://github.com/quickemu-project/quickemu/issues/248)
+for other steps and changes that may enable running on MacOS)
 
-    brew install qemu bash coreutils grep jq python@3.10 cdrtools gnu-sed spice-gtk wget zsync
+```sh
+brew install qemu bash coreutils grep jq python@3.10 cdrtools gnu-sed spice-gtk wget zsync
+```
 
-# Usage
+## Usage
 
-## Graphical User Interfaces
+### GUI
 
 While `quickemu` and `quickget` are designed for the terminal, a
 graphical user interface is also available:
 
--   **[Quickgui](https://github.com/quickgui/quickgui)** by [Mark
-    Johnson](https://github.com/marxjohnson) and [Yannick
-    Mauray](https://github.com/ymauray).
+- **[Quickgui](https://github.com/quickgui/quickgui)** by [Mark Johnson](https://github.com/marxjohnson) and [Yannick Mauray](https://github.com/ymauray).
 
-Many thanks to [Luke Wesley-Holley](https://github.com/Lukewh) and
-[Philipp Kiemle](https://github.com/daPhipz) for creating the
-**[Quickemu icons](https://github.com/Lukewh/quickemu-icons)** 🎨
-
-### Quickgui for Ubuntu
+To install Quickgui on Ubuntu:
 
-``` bash
+```sh
 sudo add-apt-repository ppa:yannick-mauray/quickgui
 sudo apt update
 sudo apt install quickgui
 ```
 
-### quickemu quickget X terminal project
+Many thanks to [Luke Wesley-Holley](https://github.com/Lukewh) and
+[Philipp Kiemle](https://github.com/daPhipz) for creating the
+**[Quickemu icons](https://github.com/Lukewh/quickemu-icons)** 🎨
+
+### TUI
 
 From Nov 2023, there is also a multi option desktop integrated text
-interface, with lots of unique tools and utilities to help you make
+interface, the **quickemu quickget X terminal project**, a.k.a. **qqX**,
+with lots of unique tools and utilities to help you make
 light work of installations, snapshots and disk management
 
--   **[qqX](https://github.com/TuxVinyards/qqX)** is independently
-    curated by [Alex Genovese](https://github.com/TuxVinyards) (see the
-    github pages)
+-   **[qqX](https://github.com/TuxVinyards/qqX)** is independently curated
+    by [Alex Genovese](https://github.com/TuxVinyards) (see the github pages)
 
 ![qqX-vmm](https://github.com/TuxVinyards/qqX/assets/3956806/18e5c495-8072-49a5-8b9c-e1302549efcf)
 
-# Install Quickemu
-
-## Arch
-
-Quickemu is available from the AUR (Arch user repository), and can be
-installed via any AUR helper. Assuming your AUR helper is yay, Run the
-following command:
-
-``` bash
-yay -Sy quickemu
-```
-
-## Ubuntu
-
-Quickemu is available from a PPA for Ubuntu users. The Quickemu PPA also
-includes a back port of QEMU 6.0.0 for 20.04 (Focal) and 21.04
-(Hirsute). To install Quickemu and all the dependencies run the
-following in a terminal:
-
-``` bash
-sudo apt-add-repository ppa:flexiondotorg/quickemu
-sudo apt update
-sudo apt install quickemu
-```
-
-## NixOS
-
-To quickly try quickemu:
-
-```sh
-nix-shell -p quickemu
-```
-
-To install via Nix profile:
-
-```sh
-nix-env -iA pkgs.quickemu
-```
-
-To install via NixOS config:
-
-```nix
-# /etc/nixos/configuration.nix
-{pkgs, ...}: {
-   environment.systemPackages = with pkgs; 
-     quickemu 
-   };
-}
-```
-
-To install via Flakes:
+### CLI
 
-```sh
-# TODO (flake users, please add an example!)
-```
-
-## Other Linux
-
-``` bash
-git clone --filter=blob:none https://github.com/wimpysworld/quickemu
-cd quickemu
-```
-
-Now install all the **Requirements** documented above.
-
-## Ubuntu Guest
+#### Ubuntu Guest
 
 `quickget` will automatically download an Ubuntu release and create the
 virtual machine configuration.
@@ -266,7 +271,7 @@ quickemu --vm ubuntu-22.04.conf
         enable file sharing.
         -   `sudo apt install spice-webdavd`
 
-### Ubuntu devel (daily-live) images
+##### Ubuntu devel (daily-live) images
 
 `quickget` can also download/refresh devel images via `zsync` for Ubuntu
 developers and testers.
@@ -280,7 +285,7 @@ You can run `quickget ubuntu devel` to refresh your daily development
 image as often as you like, it will even automatically switch to a new
 series.
 
-### Ubuntu Flavours
+##### Ubuntu Flavours
 
 All the official Ubuntu flavours are supported, just replace `ubuntu`
 with your preferred flavour.
@@ -313,7 +318,7 @@ The `--show-iso-url` and `--test-iso-url` options **do not** work for
 `Windows` (`quickget` will begin downloading the requested release and
 edition of windows)
 
-## Other Operating Systems
+#### Other Operating Systems
 
 `quickget` also supports:
 
@@ -407,7 +412,7 @@ quickemu --vm debian-bullseye.conf
     -   Install the SPICE WebDAV agent (`spice-webdavd`) in the guest to
         enable file sharing.
 
-## macOS Guest
+#### macOS Guest
 
 `quickget` automatically downloads a macOS recovery image and creates a
 virtual machine configuration.
@@ -495,7 +500,7 @@ macos_release="catalina"
     -   And VirtIO Block Media (disks) are supported/stable in Catalina
         and newer.
 
-### macOS compatibility
+##### macOS compatibility
 
 There are some considerations when running macOS via Quickemu.
 
@@ -537,7 +542,7 @@ There are some considerations when running macOS via Quickemu.
     webdavd](https://gitlab.gnome.org/GNOME/phodav/-/merge_requests/24).
 -   Copy/paste via SPICE agent is **not available on macOS**.
 
-### macOS App Store
+##### macOS App Store
 
 If you see *"Your device or computer could not be verified"* when you
 try to login to the App Store, make sure that your wired ethernet device
@@ -553,7 +558,7 @@ sudo rm /Library/Preferences/SystemConfiguration/NetworkInterfaces.plist
 
 Now reboot, and the App Store should work.
 
-## Windows 8, 10 & 11 Guests
+### Windows 8, 10 & 11 Guests
 
 `quickget` can download
 [Windows10](https://www.microsoft.com/software-download/windows10) and
@@ -593,7 +598,9 @@ secureboot="off"
 -   `tpm="on"` instructs `quickemu` to create a software emulated TPM
     device using `swtpm`.
 
-# SPICE
+## Configuration
+
+### SPICE
 
 The following features are available while using the SPICE protocol:
 
@@ -612,7 +619,7 @@ quickemu --vm ubuntu-22.04.conf --display spice
 To enable copy/paste with a Windows guest, install [SPICE Windows guest
 tools](https://www.spice-space.org/download.html) in the guest VM.
 
-## Headless
+### Headless
 
 To start a VM with SPICE enabled, but no display attached use
 `--display none`. This requires that the `spicy` client is installed,
@@ -638,7 +645,7 @@ it from the host as follows:
 ssh -p 22220 your_vm_user@localhost
 ```
 
-# Accessibility
+### Accessibility
 
 Qemu provides support for using BrlAPI to display braille output on a
 real or fake device.
@@ -647,7 +654,7 @@ real or fake device.
 quickemu --vm ubuntu-22.04.conf --braille --display sdl
 ```
 
-# BIOS and EFI
+### BIOS and EFI
 
 Since Quickemu 2.1.0 `efi` is the default boot option. If you want to
 override this behaviour then add the following line to you VM
@@ -655,7 +662,7 @@ configuration to enable legacy BIOS.
 
 -   `boot="legacy"` - Enable Legacy BIOS boot
 
-# Tuning CPU cores, RAM & disks
+### Tuning CPU cores, RAM & disks
 
 By default, Quickemu will calculate the number of CPUs cores and RAM to
 allocate to a VM based on the specifications of your host computer. You
@@ -670,7 +677,7 @@ Add additional lines to your virtual machine configuration:
 -   `disk_size="16G"` - Specify the size of the virtual disk allocated
     to the VM
 
-## Disk preallocation
+### Disk preallocation
 
 Preallocation mode (allowed values: `off` (default), `metadata`,
 `falloc`, `full`). An image with preallocated metadata is initially
@@ -682,14 +689,14 @@ configuration.
 
 -   `preallocation="metadata"`
 
-## CD-ROM disks
+### CD-ROM disks
 
 If you want to expose an ISO image from the host to guest add the
 following line to the VM configuration:
 
 -   `fixed_iso="/path/to/image.iso"`
 
-## Floppy disks
+### Floppy disks
 
 If you're like [Alan Pope](https://popey.com) you'll probably want to
 mount a floppy disk image in the guest. To do so add the following line
@@ -697,12 +704,12 @@ to the VM configuration:
 
 -   `floppy="/path/to/floppy.img"`
 
-# File Sharing
+### File Sharing
 
 All File Sharing options will only expose `~/Public` (or localised
 variations) for the current user to the guest VMs.
 
-## Samba 🐧 🍏 🪟
+#### Samba 🐧 🍏 🪟
 
 If `smbd` is available on the host, Quickemu will automatically enable
 the built-in QEMU support for exposing a Samba share from the host to
@@ -723,15 +730,17 @@ If using a Windows guest, right-click on "This PC", click "Add a network
 location", and paste this address, removing `smb:` and replacing forward
 slashes with backslashes (in this example `\\10.0.2.4\qemu`).
 
-## SPICE WebDAV 🐧 🪟
+#### SPICE WebDAV 🐧 🪟
 
 -   TBD
 
-## VirtIO-9P 🐧 🍏
+#### VirtIO-9P 🐧 🍏
 
 -   TBD
 
-# Network port forwarding
+### Networking
+
+#### Port forwarding
 
 Add an additional line to your virtual machine configuration. For
 example:
@@ -743,14 +752,14 @@ In the example above:
 -   Port 8123 on the host is forwarded to port 8123 on the guest.
 -   Port 8888 on the host is forwarded to port 80 on the guest.
 
-# Disable networking
+#### Disable networking
 
 To completely disable all network interfaces in a guest VM add this
 additional line to your virtual machine configuration:
 
 -   `network="none"`
 
-# Restricted networking
+#### Restricted networking
 
 You can isolate the guest from the host (and broader network) using the
 restrict option, which will restrict networking to just the guest and
@@ -762,7 +771,7 @@ additional line to your virtual machine configuration:
 
 -   `network="restrict"`
 
-# Bridged networking
+#### Bridged networking
 
 Connect your virtual machine to a preconfigured network bridge. Add an
 additional line to your virtual machine configuration:
@@ -778,12 +787,12 @@ So you can generate your own MAC addresses with:
 
 -   `macaddr="52:54:00:AB:51:AE"`
 
-# USB redirection
+### USB redirection
 
 Quickemu supports USB redirection via SPICE pass-through and host
 pass-through.
 
-## SPICE redirection (recommended)
+#### SPICE redirection (recommended)
 
 Using SPICE for USB pass-through is easiest as it doesn't require any
 elevated permission:
@@ -792,7 +801,7 @@ elevated permission:
 * select `Input` -\> `Select USB Device for redirection` from the menu to
 choose which device(s) you want to attach to the guest.
 
-### Enabling SPICE redirection on NixOS
+##### Enabling SPICE redirection on NixOS
 
 On NixOS, if you encounter this error:
 
@@ -806,7 +815,7 @@ Try setting [the following option](https://search.nixos.org/options?channel=23.1
 virtualisation.spiceUSBRedirection.enable = true;
 ```
 
-## Host redirection (**NOT Recommended**)
+#### Host redirection (**NOT Recommended**)
 
 **USB host redirection is not recommended**, it is provided purely for
 backwards compatibility to older versions of Quickemu. Using SPICE is
@@ -833,14 +842,14 @@ like this:
                     sudo chown -v root:user /dev/bus/usb/001/005
                     ERROR! USB permission changes are required 👆
 
-# TPM
+### TPM
 
 Since Quickemu 2.2.0 a software emulated TPM device can be added to
 guest virtual machines. Just add `tpm="on"` to your VM configuration.
 `quickget` will automatically add this line to Windows 11 virtual
 machines.
 
-# All the options
+## All the options
 
 Here are the usage instructions:
 
@@ -957,7 +966,7 @@ which will override system default screen sizes. The VM size will be
 'pct' of the chosen screen. **If --fullscreen is chosen screen will be
 fullsize instead of being scaled down by --screenpct value.**
 
-# References
+## References
 
 Useful reference that assisted the development of Quickemu.
 

From 61bc845a9a1c99c1c734315dd21096fe8175a37a Mon Sep 17 00:00:00 2001
From: egasimus <adam@hack.bg>
Date: Tue, 9 Jan 2024 17:32:32 +0200
Subject: [PATCH 05/10] wip: docs(readme): merge introductory sections

---
 README.md | 46 +++++++++++++++++++++++-----------------------
 1 file changed, 23 insertions(+), 23 deletions(-)

diff --git a/README.md b/README.md
index 51cf54b649..28b6117574 100644
--- a/README.md
+++ b/README.md
@@ -4,13 +4,20 @@
 
 # Quickemu
 
-**Quickly create and run optimised Windows, macOS and Linux desktop virtual machines.**
+**Quickly create and run optimised Windows, macOS and Linux desktop virtual machines, with just two commands:**
+
+
+``` bash
+quickget ubuntu-mate 22.04
+quickemu --vm ubuntu-mate-22.04.conf
+```
 
 <img src=".github/screenshot.png" alt="Quickemu Screenshot" />
 
 **Made with 💝 for <img src=".github/tux.png" align="top" width="24" />.**
 
-Packaging status by [Repology.org](https://repology.org/):
+Quickemu is available in the repositories of the following distros
+(packaging status by [Repology.org](https://repology.org/)):
 
 <table>
 <tbody>
@@ -31,35 +38,18 @@ status](https://repology.org/badge/vertical-allrepos/quickgui.svg?header=quickgu
 </tbody>
 </table>
 
-
 We have a Discord for this project:
 
 [![Discord](https://img.shields.io/discord/712850672223125565?color=0C306A&label=WimpysWorld%20Discord&logo=Discord&logoColor=ffffff&style=flat-square)](https://discord.gg/sNmz3uw)
 
-See this (old) video where I explain some of my motivations for creating
-Quickemu:
-
-[![Replace VirtualBox with Bash &
-QEMU](https://img.youtube.com/vi/AOTYWEgw0hI/0.jpg)](https://www.youtube.com/watch?v=AOTYWEgw0hI)
-
 </div>
 
 ## Introduction
 
-**Quickemu** is a wrapper for the excellent [QEMU](https://www.qemu.org/)
-that attempts to automatically *"do the right thing"*, rather than
-expose exhaustive configuration options.
-
-Quickly create and run highly optimised desktop virtual machines for
-Linux, macOS and Windows, with just two commands:
-
-``` bash
-quickget ubuntu-mate 22.04
-quickemu --vm ubuntu-mate-22.04.conf
-```
-
-You decide what operating system you want to run
-and Quickemu will figure out the best way to do it for you.
+**Quickemu** is a wrapper for the excellent [QEMU](https://www.qemu.org/) that attempts to
+automatically *"do the right thing"*, rather than expose exhaustive configuration options.
+You decide what operating system you want to run, and Quickemu will figure out the best
+way to do it for you.
 
 The original objective of the project was to enable [quick testing of
 Linux distributions](#linux-guests) where the virtual machine configurations can be
@@ -68,6 +58,16 @@ and no elevated permissions are required to run the virtual machines.
 **Quickemu now also includes comprehensive support for [macOS](#macos-guests)
 and [Windows](#windows-guests)**.
 
+See this (old) video where I explain some of my motivations for creating
+Quickemu:
+
+<div align="center">
+
+[![Replace VirtualBox with Bash &
+QEMU](https://img.youtube.com/vi/AOTYWEgw0hI/0.jpg)](https://www.youtube.com/watch?v=AOTYWEgw0hI)
+
+</div>
+
 ## Features
 
 -   **macOS** Monterey, Big Sur, Catalina, Mojave & High Sierra

From 07e18ccddad1248b115e156d4825dcfa18c77000 Mon Sep 17 00:00:00 2001
From: egasimus <adam@hack.bg>
Date: Tue, 9 Jan 2024 17:33:24 +0200
Subject: [PATCH 06/10] fix(readme): code sample was centered wrong

---
 README.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/README.md b/README.md
index 28b6117574..7af043eb34 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,6 @@
 
 **Quickly create and run optimised Windows, macOS and Linux desktop virtual machines, with just two commands:**
 
-
 ``` bash
 quickget ubuntu-mate 22.04
 quickemu --vm ubuntu-mate-22.04.conf

From 4bb05a161c3637e745a68e2da9f02d4ab4fbf998 Mon Sep 17 00:00:00 2001
From: egasimus <adam@hack.bg>
Date: Tue, 9 Jan 2024 17:34:11 +0200
Subject: [PATCH 07/10] fix(readme): was it the space after the backticks?

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 7af043eb34..c9cde4835f 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@
 
 **Quickly create and run optimised Windows, macOS and Linux desktop virtual machines, with just two commands:**
 
-``` bash
+```bash
 quickget ubuntu-mate 22.04
 quickemu --vm ubuntu-mate-22.04.conf
 ```

From c0dec18402addfe22dce9f9585ed8f759540a938 Mon Sep 17 00:00:00 2001
From: egasimus <adam@hack.bg>
Date: Tue, 9 Jan 2024 17:53:21 +0200
Subject: [PATCH 08/10] docs(readme): alignment, sections

---
 README.md | 24 +++++++++++++-----------
 1 file changed, 13 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index c9cde4835f..6fe51757a3 100644
--- a/README.md
+++ b/README.md
@@ -4,13 +4,17 @@
 
 # Quickemu
 
-**Quickly create and run optimised Windows, macOS and Linux desktop virtual machines, with just two commands:**
+**Quickly create and run optimised Windows, macOS and Linux desktop virtual machines:**
+
+</div>
 
 ```bash
 quickget ubuntu-mate 22.04
 quickemu --vm ubuntu-mate-22.04.conf
 ```
 
+<div align="center">
+
 <img src=".github/screenshot.png" alt="Quickemu Screenshot" />
 
 **Made with 💝 for <img src=".github/tux.png" align="top" width="24" />.**
@@ -155,9 +159,7 @@ git clone --filter=blob:none https://github.com/wimpysworld/quickemu
 cd quickemu
 ```
 
-Now install all the **Requirements** documented below:
-
-#### Requirements
+When installing from source, you will need to install the following requirements manually:
 
 -   [QEMU](https://www.qemu.org/) (*6.0.0 or newer*) **with GTK, SDL,
     SPICE & VirtFS support**
@@ -193,7 +195,7 @@ above requirements or their equivalents.
 
 These examples may save a little typing:
 
-##### Install requirements on Debian hosts
+#### Install requirements on Debian hosts
 
 This also applies to direct derivatives, such as MX Linux:
 
@@ -201,13 +203,13 @@ This also applies to direct derivatives, such as MX Linux:
 sudo apt install qemu bash coreutils ovmf grep jq lsb-base procps python3 genisoimage usbutils util-linux sed spice-client-gtk libtss2-tcti-swtpm0 wget xdg-user-dirs zsync unzip
 ```
 
-##### Install requirements on Fedora hosts
+#### Install requirements on Fedora hosts
 
 ```sh
 sudo dnf install qemu bash coreutils edk2-tools grep jq lsb procps python3 genisoimage usbutils util-linux sed spice-gtk-tools swtpm wget xdg-user-dirs xrandr unzip
 ```
 
-##### Installing dependencies on macOS hosts
+#### Install requirements on macOS hosts
 
 This is a work in progress (see [issue 248](https://github.com/quickemu-project/quickemu/issues/248)
 for other steps and changes that may enable running on MacOS)
@@ -216,7 +218,7 @@ for other steps and changes that may enable running on MacOS)
 brew install qemu bash coreutils grep jq python@3.10 cdrtools gnu-sed spice-gtk wget zsync
 ```
 
-## Usage
+## Additional UIs
 
 ### GUI
 
@@ -249,7 +251,7 @@ light work of installations, snapshots and disk management
 
 ![qqX-vmm](https://github.com/TuxVinyards/qqX/assets/3956806/18e5c495-8072-49a5-8b9c-e1302549efcf)
 
-### CLI
+## Creating a VM
 
 #### Ubuntu Guest
 
@@ -597,7 +599,7 @@ secureboot="off"
 -   `tpm="on"` instructs `quickemu` to create a software emulated TPM
     device using `swtpm`.
 
-## Configuration
+## Usage
 
 ### SPICE
 
@@ -848,7 +850,7 @@ guest virtual machines. Just add `tpm="on"` to your VM configuration.
 `quickget` will automatically add this line to Windows 11 virtual
 machines.
 
-## All the options
+## Configuration
 
 Here are the usage instructions:
 

From 5d75b0026fe5305a46f693ada183eb8de30a38da Mon Sep 17 00:00:00 2001
From: egasimus <adam@hack.bg>
Date: Tue, 9 Jan 2024 17:56:25 +0200
Subject: [PATCH 09/10] docs(readme): guest os headings and emoji

---
 README.md | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 6fe51757a3..8a37c6d833 100644
--- a/README.md
+++ b/README.md
@@ -253,7 +253,9 @@ light work of installations, snapshots and disk management
 
 ## Creating a VM
 
-#### Ubuntu Guest
+### 🐧 Linux guests
+
+#### Ubuntu
 
 `quickget` will automatically download an Ubuntu release and create the
 virtual machine configuration.
@@ -272,7 +274,7 @@ quickemu --vm ubuntu-22.04.conf
         enable file sharing.
         -   `sudo apt install spice-webdavd`
 
-##### Ubuntu devel (daily-live) images
+#### Ubuntu devel (daily-live) images
 
 `quickget` can also download/refresh devel images via `zsync` for Ubuntu
 developers and testers.
@@ -286,7 +288,7 @@ You can run `quickget ubuntu devel` to refresh your daily development
 image as often as you like, it will even automatically switch to a new
 series.
 
-##### Ubuntu Flavours
+#### Ubuntu Flavours
 
 All the official Ubuntu flavours are supported, just replace `ubuntu`
 with your preferred flavour.
@@ -413,7 +415,7 @@ quickemu --vm debian-bullseye.conf
     -   Install the SPICE WebDAV agent (`spice-webdavd`) in the guest to
         enable file sharing.
 
-#### macOS Guest
+### 🍏 macOS Guests
 
 `quickget` automatically downloads a macOS recovery image and creates a
 virtual machine configuration.
@@ -501,7 +503,7 @@ macos_release="catalina"
     -   And VirtIO Block Media (disks) are supported/stable in Catalina
         and newer.
 
-##### macOS compatibility
+#### macOS compatibility
 
 There are some considerations when running macOS via Quickemu.
 
@@ -543,7 +545,7 @@ There are some considerations when running macOS via Quickemu.
     webdavd](https://gitlab.gnome.org/GNOME/phodav/-/merge_requests/24).
 -   Copy/paste via SPICE agent is **not available on macOS**.
 
-##### macOS App Store
+#### macOS App Store
 
 If you see *"Your device or computer could not be verified"* when you
 try to login to the App Store, make sure that your wired ethernet device
@@ -559,7 +561,7 @@ sudo rm /Library/Preferences/SystemConfiguration/NetworkInterfaces.plist
 
 Now reboot, and the App Store should work.
 
-### Windows 8, 10 & 11 Guests
+### 🪟 Windows 8, 10 & 11 Guests
 
 `quickget` can download
 [Windows10](https://www.microsoft.com/software-download/windows10) and

From 0a79820218e3811f78b04f9047f733793e44d82e Mon Sep 17 00:00:00 2001
From: egasimus <adam@hack.bg>
Date: Tue, 9 Jan 2024 17:59:25 +0200
Subject: [PATCH 10/10] docs(readme): flatten hierarchy

linux/mac/win get their own sections
---
 README.md | 36 +++++++++++++++++-------------------
 1 file changed, 17 insertions(+), 19 deletions(-)

diff --git a/README.md b/README.md
index 8a37c6d833..66b8ce4b7e 100644
--- a/README.md
+++ b/README.md
@@ -218,9 +218,7 @@ for other steps and changes that may enable running on MacOS)
 brew install qemu bash coreutils grep jq python@3.10 cdrtools gnu-sed spice-gtk wget zsync
 ```
 
-## Additional UIs
-
-### GUI
+## GUI (quickgui)
 
 While `quickemu` and `quickget` are designed for the terminal, a
 graphical user interface is also available:
@@ -239,7 +237,7 @@ Many thanks to [Luke Wesley-Holley](https://github.com/Lukewh) and
 [Philipp Kiemle](https://github.com/daPhipz) for creating the
 **[Quickemu icons](https://github.com/Lukewh/quickemu-icons)** 🎨
 
-### TUI
+## TUI (qqx)
 
 From Nov 2023, there is also a multi option desktop integrated text
 interface, the **quickemu quickget X terminal project**, a.k.a. **qqX**,
@@ -251,11 +249,9 @@ light work of installations, snapshots and disk management
 
 ![qqX-vmm](https://github.com/TuxVinyards/qqX/assets/3956806/18e5c495-8072-49a5-8b9c-e1302549efcf)
 
-## Creating a VM
-
-### 🐧 Linux guests
+## Creating Linux guests 🐧
 
-#### Ubuntu
+### Ubuntu
 
 `quickget` will automatically download an Ubuntu release and create the
 virtual machine configuration.
@@ -274,7 +270,7 @@ quickemu --vm ubuntu-22.04.conf
         enable file sharing.
         -   `sudo apt install spice-webdavd`
 
-#### Ubuntu devel (daily-live) images
+### Ubuntu devel (daily-live) images
 
 `quickget` can also download/refresh devel images via `zsync` for Ubuntu
 developers and testers.
@@ -288,7 +284,7 @@ You can run `quickget ubuntu devel` to refresh your daily development
 image as often as you like, it will even automatically switch to a new
 series.
 
-#### Ubuntu Flavours
+### Ubuntu Flavours
 
 All the official Ubuntu flavours are supported, just replace `ubuntu`
 with your preferred flavour.
@@ -321,7 +317,7 @@ The `--show-iso-url` and `--test-iso-url` options **do not** work for
 `Windows` (`quickget` will begin downloading the requested release and
 edition of windows)
 
-#### Other Operating Systems
+### Other Operating Systems
 
 `quickget` also supports:
 
@@ -390,6 +386,8 @@ edition of windows)
 -   `xerolinux` (XeroLinux)
 -   `zorin` (Zorin OS)
 
+### Custom Linux guests
+
 Or you can download a Linux image and manually create a VM
 configuration.
 
@@ -415,7 +413,7 @@ quickemu --vm debian-bullseye.conf
     -   Install the SPICE WebDAV agent (`spice-webdavd`) in the guest to
         enable file sharing.
 
-### 🍏 macOS Guests
+## Creating macOS Guests 🍏 
 
 `quickget` automatically downloads a macOS recovery image and creates a
 virtual machine configuration.
@@ -503,7 +501,7 @@ macos_release="catalina"
     -   And VirtIO Block Media (disks) are supported/stable in Catalina
         and newer.
 
-#### macOS compatibility
+### macOS compatibility
 
 There are some considerations when running macOS via Quickemu.
 
@@ -545,7 +543,7 @@ There are some considerations when running macOS via Quickemu.
     webdavd](https://gitlab.gnome.org/GNOME/phodav/-/merge_requests/24).
 -   Copy/paste via SPICE agent is **not available on macOS**.
 
-#### macOS App Store
+### macOS App Store
 
 If you see *"Your device or computer could not be verified"* when you
 try to login to the App Store, make sure that your wired ethernet device
@@ -561,16 +559,16 @@ sudo rm /Library/Preferences/SystemConfiguration/NetworkInterfaces.plist
 
 Now reboot, and the App Store should work.
 
-### 🪟 Windows 8, 10 & 11 Guests
+## Creating Windows guests 🪟
 
 `quickget` can download
-[Windows10](https://www.microsoft.com/software-download/windows10) and
-[Windows 11](https://www.microsoft.com/software-download/windows11)
+[**Windows 10**](https://www.microsoft.com/software-download/windows10) and
+[**Windows 11**](https://www.microsoft.com/software-download/windows11)
 automatically and create an optimised virtual machine configuration.
 This configuration also includes the [VirtIO drivers for
 Windows](https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/).
 
-Windows 8.1 is also supported but doesn't feature any automated
+**Windows 8.1** is also supported but doesn't feature any automated
 installation or driver optimisation.
 
 ``` bash
@@ -601,7 +599,7 @@ secureboot="off"
 -   `tpm="on"` instructs `quickemu` to create a software emulated TPM
     device using `swtpm`.
 
-## Usage
+## Connecting to your VM
 
 ### SPICE