docs: improve make-disk-image docs using my text calculator

Co-authored-by: Janik <80165193+Janik-Haag@users.noreply.github.com>

docs/reference.md

@@ -44,46 +44,70 @@ Options:
   run with set -x
 ```
 
-## Generating Disk Images with secrets included
+# Generating Disk Images with Secrets Included using Disko
 
-If you have a system config that uses disko then you can run a script that generates a `.raw` VM image.
-This image can be used as a VM image, but you can also dd the `.raw` image on to a physical drive and just boot it.
-To execute the script replace the `mySystem` part in the snippet below and run it.
-```
-nix build .#nixosConfigurations.mySystem.config.system.build.diskoImagesScript
-```
-Now you will have a result file which will output something like this:
-```
-./result --help
-Usage: $script [options]
+Using Disko on NixOS allows you to efficiently create `.raw` VM images from a
+system configuration. The generated image can be used as a VM or directly
+written to a physical drive to create a bootable disk. Follow the steps below to
+generate disk images:
 
-Options:
-* --pre-format-files <src> <dst>
-  copies the src to the dst on the VM, before disko is run
-  This is useful to provide secrets like LUKS keys, or other files you need for formating
-* --post-format-files <src> <dst>
-  copies the src to the dst on the finished image
-  These end up in the images later and is useful if you want to add some extra stateful files
-  They will have the same permissions but will be owned by root:root
-* --build-memory
-  specify the ammount of memory that gets allocated to the build vm (in mb)
-  This can be usefull if you want to build images with a more involed NixOS config
-  By default the vm will get 1024M/1GB
-* --write-to-disk </dev/disk>
-  use an actuall disk instead of writing to a file
-  This only works if your conifg has only one disk specified
-  There is no check if the specified path is actually a disk so you can also write to another file
-```
-If you intend to use it with a virtual drive you have to set `disko.devices.disk.<drive>.imageSize = "32G"; #set your own size here` in your disko config.
-If you just run the result script it will generate a file per drive specified in `disko.devices.disk.<drive>` called `<dirve>.raw`
-There is a small problem with this approach because the `.raw` file will have the size that's specified in `imageSize`+padding.
-So with a `imageSize` of `64G` you end up with a `69G` image and if you copy/move that file you end up reading and writing a lot of zeros.
-At this point it's probably note worth that there is no auto resizing in disko and it's not planed (but open for contributions).
-One way to circumvent that is to use the `--write-to-disk` option and just directly write to a drive,
-this only works with one drive but can be useful for simple setups like a laptop configuration.
+## Generating the `.raw` VM Image
 
-The way images are generated is basically:
-Every file specified in `--pre-format-files` and `--post-format-files` will be copied to a buffer in `/tmp`.
-And then copied to the specified locations in the VM before and after the disko partitioning script ran.
-After that the NixOS installer will be run which will have access to every file in `--post-format-files` but not `--pre-format-files` because they will already be discarded.
-The VM will be shutdown once the installer finishes and then move the `.raw` disk files to the local directory.
+1. **Build the disko image script:** Replace `mySystem` in the command below with your
+   specific system configuration name:
+   ```bash
+   nix build .#nixosConfigurations.mySystem.config.system.build.diskoImagesScript
+   ```
+2. **Execute the result file:** Execute the generated result file. Running
+   `./result --help` will output the available options:
+
+   ```
+   ./result --help
+   Usage: $script [options]
+
+   Options:
+   * --pre-format-files <src> <dst>
+     copies the src to the dst on the VM, before disko is run
+     This is useful to provide secrets like LUKS keys, or other files you need for formating
+   * --post-format-files <src> <dst>
+     copies the src to the dst on the finished image
+     These end up in the images later and is useful if you want to add some extra stateful files
+     They will have the same permissions but will be owned by root:root
+   * --build-memory
+     specify the ammount of memory that gets allocated to the build vm (in mb)
+     This can be usefull if you want to build images with a more involed NixOS config
+     By default the vm will get 1024M/1GB
+   * --write-to-disk </dev/disk>
+     use an actuall disk instead of writing to a file
+     This only works if your conifg has only one disk specified
+     There is no check if the specified path is actually a disk so you can also write to another file
+   ```
+
+## Additional Configuration
+
+- For virtual drive use, define the image size in your Disko configuration:
+
+  ```bash
+  disko.devices.disk.<drive>.imageSize = "32G"; # Set your preferred size
+  ```
+
+- If the `.raw` image size is not optimal, use `--write-to-disk` to write
+  directly to a drive. This bypasses the `.raw` file generation, which saves on read/write operations
+  and is suitable for single disk setups.
+
+## Understanding the Image Generation Process
+
+1. Files specified in `--pre-format-files` and `--post-format-files` are
+   temporarily copied to `/tmp`.
+2. Files are then moved to their respective locations in the VM both before and
+   after the Disko partitioning script runs.
+3. The NixOS installer is executed, having access only to `--post-format-files`.
+4. Upon installer completion, the VM is shutdown, and the `.raw` disk files are
+   moved to the local directory.
+
+> **Note**: The auto-resizing feature is currently not available in Disko.
+> Contributions for this feature are welcomed. Adjust the `imageSize`
+> configuration to prevent issues related to file size and padding.
+
+By following these instructions and understanding the process, you can smoothly
+generate disk images with Disko for your NixOS system configurations.