update READMEwip-2019-12-pre

1 files changed, 33 insertions, 21 deletions

diff --git a/README b/README
index a2d91f6..36b12fe 100644
--- a/README
+++ b/README
@@ -10,31 +10,36 @@ virtual machine image creation
 
 To create a new virtual machine image, run
 
-  $> ./pvmbootstrap.sh [path to image] [arch]
+  $> ./pvmbootstrap.sh <path to image> <arch>
 
-where arch is one of the supported parabola arches, which are currently:
+... where <arch> is one of the parabola arches, which are currently:
 
-  official:   [ i686, x86_64, armv7h ]
-  unofficial: [ ppc64le, riscv64 ]
+  supported:    [ i686, x86_64, armv7h ]
+  experimental: [ ppc64le, riscv64 ]
 
-the script will attempt to bootstrap a virtual machine of the selected
-archituecture in the output file specified. If the output file already exists,
+The script will attempt to bootstrap a virtual machine of the selected
+archituecture to the output file specified. If the output file already exists,
 the script will emit a warning and ask for confirmation to proceed.
 
-the creation can be influenced by providing one or more of the following
+The creation can be influenced by providing one or more of the following
 arguments to pvmbootstrap.sh:
 
-  -s size   -- set the size of the created VM image (default: 64G)
-  -M mirror -- set the mirror to fetch packages from
-               (default: https://repo.parabola.nu/$repo/os/$arch)
-  -H hook   -- add a confiuration hook to be executed. this can be the path to
-               a shell script or one of the existing hooks described below
+  -H <hook>      -- Enable a hook to customize the created image. This can be
+                    the path to a script, which will be executed once within
+                    the running VM, or one of the predefined hooks described
+                    below. This option can be specified multiple times
+  -k <kernel>    -- Choose the kernel package (default: linux-libre)
+  -M <mirror>    -- Set the mirror from which to fetch packages
+                    (default: https://repo.parabola.nu/$repo/os/$arch)
+  -O             -- Bootstrap an openrc system instead of a systemd one
+  -s <img_size>  -- Set the size (in GB) of the VM image (minimum: 1, default: 64)
+  -S <swap_size> -- Set the size (in MB) of the swap partition (default: 0)
 
 The creation hooks currently supported are:
 
-ethernet-dhcp:
+'ethernet-dhcp':
 
-  this hook will setup ethernet in the VM by enabling systemd-resolved and
+  This hook will setup ethernet in the VM by enabling systemd-resolved and
   openresolv properly, as well as creating and enabling a systemd-networkd
   configuration.
 
@@ -43,32 +48,39 @@ virtual machine boot
 
 To boot a created virtual machine, run:
 
-  $> ./pvmboot.sh [path to image] [additional qemu args...]
+  $> ./pvmboot.sh <path_to_image> [additional qemu args...]
 
-the script will attempt to determine the architecture of the provided virtual
+The script will attempt to determine the architecture of the provided virtual
 machine image, and set the qemu executable and sane default flags for the qemu
 invocation automatically, including kvm acceleration, if available for the
 target architecture.
 
-additionally, the script will evaluate the DISPLAY environment variable to
+Additionally, the script will evaluate the DISPLAY environment variable to
 determine whether a graphical desktop environment is available, and will start
 the image in serial console mode if necessary. This behavior can be forced by
 unsetting DISPLAY before executing the script:
 
-  $> DISPLAY= ./pvmboot.sh [...]
+  $> DISPLAY= ./pvmboot.sh ./an.img [...]
+
+When the VM will boot into graphical mode, the serial console can be redirected
+to the host console by passing the -r option.
+
+  $> ./pvmboot.sh -r ./an.img
 
 The default flags can be overwritten or extended, for example to allocate more
 memory to the machine, by specifying additional qemu parameters on the command
 line following the virtual machine image name:
 
-  $> DISPLAY= ./pvmboot [path to image] -m 2G
+  $> DISPLAY= ./pvmboot ./an.img -m 2G
 
 release tarball creation
 ------------------------
 
 To convert a virtual machine image into a parabola release tarball, run:
 
-  $> ./pvm2tarball.sh [path to image]
+  $> ./pvm2tarball.sh <path_to_image>
 
 This will attempt to mount the rootfs and the /boot partition, and tar the
-contents to an output file, filtering out all unneeded files.
+contents to an output file, filtering out all unneeded files. The /boot
+partition is optional if the kernel and initramfs are in /boot; though
+'pvmbootstrap.sh' always creates a /boot partition.