On Fri, Dec 08, 2023 at 03:43:51PM +0100, Laszlo Ersek wrote:
On 12/7/23 16:08, Richard W.M. Jones wrote:
We generally prefer to give specific parameters and avoid indirection. Therefore avoid defining "ID" and repeat the items instead.
Use B<> (bold) consistently for invariant parts of the option. --- options/key-option.pod | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-)
diff --git a/options/key-option.pod b/options/key-option.pod index 6bc04df..ee515fa 100644 --- a/options/key-option.pod +++ b/options/key-option.pod @@ -1,22 +1,30 @@ =item B<--key> SELECTOR
Specify a key for LUKS, to automatically open a LUKS device when using -the inspection. C<ID> can be either the libguestfs device name, or -the UUID of the LUKS device. +the inspection.
=over 4
-=item B<--key> C<ID>:key:KEY_STRING +=item B<--key> NAMEB<:key:>KEY_STRING + +=item B<--key> UUIDB<:key:>KEY_STRING + +C<NAME> is the libguestfs device name (eg. C</dev/sda1>). C<UUID> is +the device UUID.
Use the specified C<KEY_STRING> as passphrase.
-=item B<--key> C<ID>:file:FILENAME +=item B<--key> NAMEB<:file:>FILENAME + +=item B<--key> UUIDB<:file:>FILENAME
Read the passphrase from F<FILENAME>.
-=item B<--key> C<ID>:clevis +=item B<--key> NAMEB<:clevis>
-Attempt passphrase-less unlocking for C<ID> with Clevis, over the +=item B<--key> UUIDB<:clevis> + +Attempt passphrase-less unlocking for the device with Clevis, over the network. Please refer to L<guestfs(3)/ENCRYPTED DISKS> for more information on network-bound disk encryption (NBDE).
Should we use C<NAME> and C<UUID>? The removed part was C<ID>, not just ID.
We're not very consistent about that elsewhere. However one specific problem is that in man pages, POD puts double quotes around C<> markup so it would render as: --key "UUID":clevis which is not wrong, but a bit busy.
Reviewed-by: Laszlo Ersek <lersek@redhat.com>
Thanks! Rich. -- Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones Read my programming and virtualization blog: http://rwmj.wordpress.com virt-builder quickly builds VMs from scratch http://libguestfs.org/virt-builder.1.html