From 054798ca11b9f0b71fbad302edf66b52519f5aa2 Mon Sep 17 00:00:00 2001
From: "Richard W.M. Jones" <rjones@redhat.com>
Date: Thu, 14 Dec 2023 17:47:10 +0000
Subject: [PATCH] file: Rework documentation for dir= parameter

The existing documentation tended towards jargon and lacked examples.

(cherry picked from commit 7cbd49ced6414e49fcf4ff1a967929a2b83ab44e)
---
 plugins/file/nbdkit-file-plugin.pod | 23 +++++++++++++++++------
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/plugins/file/nbdkit-file-plugin.pod b/plugins/file/nbdkit-file-plugin.pod
index 857ad21e..e47eae97 100644
--- a/plugins/file/nbdkit-file-plugin.pod
+++ b/plugins/file/nbdkit-file-plugin.pod
@@ -64,13 +64,23 @@ symbolic links.  Other special files in the directory (such as
 subdirectories, pipes, or Unix sockets) are ignored.
 
 When this mode is used, the file to be served is chosen by the export
-name passed by the client, where the client can request a list of
-available exports using NBD_OPT_LIST.  A client that requests the
-default export (C<"">) will be rejected.  However, you can use
-L<nbdkit-exportname-filter(1)> to adjust what export names the client
-sees or uses as a default.  For security, when using directory mode,
+name passed by the client.  For security, when using directory mode,
 this plugin will not accept export names containing slash (C</>).
 
+To list exports, use L<nbdinfo(1)> I<--list> option, for example:
+
+ nbdinfo --list nbd://localhost
+
+An NBD client can request a list of available exports using
+C<NBD_OPT_LIST>.
+
+A client that requests the default export (C<"">) will be rejected.
+However, you can use L<nbdkit-exportname-filter(1)> to adjust what
+export names the client sees, and which one the client uses as a
+default.  For example to make F</dir/file> be the default export:
+
+ nbdkit file dir=/dir --filter=exportname default-export=file
+
 =item B<dirfd=>FILE_DESCRIPTOR
 
 (nbdkit E<ge> 1.34, not Windows)
@@ -262,7 +272,8 @@ L<nbdkit-tmpdisk-plugin(1)>,
 L<nbdkit-exportname-filter(1)>,
 L<nbdkit-fua-filter(1)>,
 L<nbdkit-luks-filter(1)>,
-L<nbdkit-noextents-filter(1)>.
+L<nbdkit-noextents-filter(1)>,
+L<nbdinfo(1)>.
 
 =head1 AUTHORS
 
-- 
2.39.3