doc: update doc for programs and backends

doc/bookmarkfs.texi

@@ -155,16 +155,23 @@ On FreeBSD, @freebsdmanpage{capsicum, 4} is used.
 @node mount.bookmarkfs
 @section @command{mount.bookmarkfs}
 
+The @command{mount.bookmarkfs} program mounts a BookmarkFS filesystem.
+
 @example
 mount.bookmarkfs [@var{options}] @var{src} @var{target}
 @end example
 
-The @command{mount.bookmarkfs} program mounts a BookmarkFS filesystem to the
+@table @var
-location specified by @var{target}.
+@item src
+The bookmark storage, presumably the pathname of a regular file
+that contains bookmark data.
 
-The @var{src} argument is presumably the pathname of a file that stores
+The exact interpretation of this option is backend-defined.
-bookmark data.
+
-Its exact interpretation is backend-defined.
+@item target
+Pathname to the directory where the filesystem shall be mounted on
+(i.e. the ``mountpoint'').
+@end table
 
 To unmount a BookmarkFS filesystem, run @linuxmanpage{fusermount3, 1} or
 @linuxmanpage{umount, 8} on @var{target}.
@@ -298,13 +305,13 @@ Nonetheless, the user can still update atime explicitly (e.g. with
 @node fsck.bookmarkfs
 @section @command{fsck.bookmarkfs}
 
+The @command{fsck.bookmarkfs} program checks and optionally repairs a
+BookmarkFS filesystem.
+
 @example
 fsck.bookmarkfs [@var{options}] @var{pathname}
 @end example
 
-The @command{fsck.bookmarkfs} program checks and optionally repairs a
-BookmarkFS filesystem.
-
 Filesystem check on BookmarkFS has a different purpose compared to
 on-disk filesystems.
 @xref{Filesystem Check}.
@@ -395,12 +402,19 @@ Print version and feature information, and then exit.
 @node mkfs.bookmarkfs
 @section @command{mkfs.bookmarkfs}
 
+The @command{mkfs.bookmarkfs} program creates a new BookmarkFS filesystem.
+
 @example
 mkfs.bookmarkfs [@var{options}] @var{pathname}
 @end example
 
-The @command{mkfs.bookmarkfs} program creates a BookmarkFS filesystem
+@table @var
-on the file specified by @var{pathname}.
+@item pathname
+The underlying bookmark storage for the new filesystem.
+
+This option is equivalent to the @var{src} argument for
+@command{mount.bookmarkfs}.
+@end table
 
 Available options:
 
@@ -414,7 +428,7 @@ A backend-specific option.
 This option can be provided multiple times.
 
 @item -o force
-Overwrite existing files when creating the filesystem.
+If the file referred to by @var{pathname} already exists, overwrite it.
 
 @item -h
 Print help text, and then exit.
@@ -426,27 +440,36 @@ Print version and feature information, and then exit.
 @node bookmarkctl
 @section @command{bookmarkctl}
 
+The @command{bookmarkctl} program is a command-line wrapper for various
+I/O controls of a BookmarkFS filesystem.
+
 @example
 bookmarkctl @var{subcmd} [@var{args}]
 @end example
 
-The @command{bookmarkctl} program is a command-line wrapper for various
+Sub-commands:
-I/O controls of a BookmarkFS filesystem.
+
+@table @command
+@item permd
+Re-arranges the order of the directory entries obtained from @code{readdir()}.
+@xref{Permute Directory Entries}.
 
 @example
 bookmarkctl permd @var{pathname} @var{op} @var{name1} @var{name2}
 @end example
 
-The @command{permd} sub-command re-arranges the order of the directory entries
+@table @var
-returned from @code{readdir()} calls.
+@item pathname
-@xref{Permute Directory Entries}.
+Path to the directory.
 
-The @var{pathname} argument is the path to the directory.
+@item name1
-The @var{name1} and @var{name2} arguments are filenames under that directory.
+@item name2
+Filename of entries under the directory.
 
-The @var{op} argument is the operation to perform on the directory:
+@item op
+Operation to perform on the directory:
 
-@table @code
+@table @samp
 @item swap
 Exchange the positions of the directory entries represented by @var{name1}
 and @var{name2}.
@@ -459,38 +482,37 @@ Move the directory entry represented by @var{name1} to the position just
 Move the directory entry represented by @var{name1} to the position just
 @emph{after} the one represented by @var{name2}.
 @end table
+@end table
+
+@item fsck
+Check for errors within a BookmarkFS filesystem.
+@xref{Filesystem Check}.
 
 @example
 bookmarkctl fsck @var{pathname} @var{op}
 @end example
 
-The @command{fsck} sub-command checks for errors within a
+@table @var
-BookmarkFS filesystem.
+@item pathname
-@xref{Filesystem Check}.
+Path to the directory to perform checks on.
 
-The @var{pathname} argument is the path to the directory to perform checks on.
+@item op
+Operation to perform on the directory:
 
-The @var{op} argument is the operation to perform on the directory:
+@table @samp
-
-@table @code
 @item list
 Display a list of errors found under the given directory.
 Will not recurse into subdirectories.
 @end table
+@end table
 
 For the full fsck functionalities, @pxref{fsck.bookmarkfs}.
 
-@example
+@item help
-bookmarkctl help
-@end example
-
 Print help text, and then exit.
-
+@item version
-@example
-bookmarkctl version
-@end example
-
 Print version information, and then exit.
+@end table
 
 
 @node Filesystem
@@ -993,7 +1015,7 @@ When mounting the filesystem, this pathname shall be passed as the @var{src}
 argument (@pxref{mount.bookmarkfs}).
 Actual path for the profile directories may differ across distributions.
 
-Backend-specific options:
+Backend-specific options (@command{mount.bookmarkfs} only):
 
 @table @option
 @item filename=title|guid
@@ -1005,7 +1027,7 @@ A bookmark GUID is a @rfcdoc{base64url-encoded, rfc4648#section-5}
 
 When creating a new file:
 
-@table @option
+@table @samp
 @item title
 The GUID is randomly generated by the backend.
 
@@ -1047,6 +1069,20 @@ It is recommended to perform a full filesystem check (@pxref{Filesystem Check})
 on the bookmark storage before mounting with this option.
 @end table
 
+If launched from @command{fsck.bookmarkfs}, all backend-specific options
+are ignored, and always enforces the @option{lock=exclusive} option.
+
+Backend-specific options (@command{mkfs.bookmarkfs} only):
+
+@table @option
+@item date_added=@var{timestamp}
+File creation time for the bookmark root directories.
+Defaults to the current time.
+
+Value of @var{timestamp} must be a decimal representing number of microseconds
+since the Unix epoch.
+@end table
+
 
 @node Chromium
 @section Chromium Backend
@@ -1067,7 +1103,7 @@ When mounting the filesystem, this pathname shall be passed as the @var{src}
 argument (@pxref{mount.bookmarkfs}).
 Actual path for the profile directories may differ across distributions.
 
-Backend-specific options:
+Backend-specific options (@command{mount.bookmarkfs} only):
 
 @table @option
 @item filename=title|guid
@@ -1086,7 +1122,7 @@ For example:
 
 When creating a new file:
 
-@table @option
+@table @samp
 @item title
 The GUID is randomly generated by the backend.
 It is guaranteed to be a valid version 4 UUID as specified by
@@ -1108,7 +1144,7 @@ The file watcher to use for the bookmark storage.
 Defaults to @samp{native} when the filesystem is mounted read-only,
 @samp{none} otherwise.
 
-@table @option
+@table @samp
 @item native
 Watch for file changes using platform-specific features.
 
@@ -1134,7 +1170,21 @@ to the filesystem.
 @end table
 @end table
 
-This backend does not scale well with large bookmark storage,
+If launched from @command{fsck.bookmarkfs}, all backend-specific options
+are ignored, and always enforces the @option{watcher=none} option.
+
+Backend-specific options (@command{mkfs.bookmarkfs} only):
+
+@table @option
+@item date_added=@var{timestamp}
+File creation time for the bookmark root directories.
+Defaults to the current time.
+
+Value of @var{timestamp} must be a decimal representing number of microseconds
+since the Windows @code{FILETIME} epoch (134774 days ahead of the Unix epoch).
+@end table
+
+The Chromium backend does not scale well with large bookmark storage,
 since it keeps everything in memory, and has to parse the entire JSON file
 whenever a reload is required.