doc: refactor

doc/bookmarkfs.texi

@@ -27,12 +27,6 @@
 @uref{https://docs.kernel.org/\path\, \name\}
 @end macro
 
-@tex
-\global\def\linkcolor{0 0 1}
-\global\def\urlcolor{0 0 1}
-\global\urefurlonlylinktrue
-@end tex
-
 @copying
 This manual is for BookmarkFS, version @value{VERSION}.
 
@@ -116,8 +110,13 @@ won't work if you're trying to port BookmarkFS to Microsoft Windows.
 A BookmarkFS backend can be instructed to enter a sandboxed state,
 where it irrevocably relinquishes most access to the system resources
 that it's not supposed to touch.
-For example, it can only access the directory that contains the bookmark file;
+For example:
-it cannot establish socket connections; it cannot execute other files; @dots{}
+
+@itemize @bullet{}
+@item access local files other than the bookmark storage
+@item establish socket connections
+@item execute other files
+@end itemize
 
 This mechanism reduces the attack surface for exploit,
 if a vulnerability is discovered in BookmarkFS and/or its dependencies.
@@ -427,11 +426,19 @@ The @var{name1} and @var{name2} arguments are filenames under that directory.
 
 The @var{op} argument is the operation to perform on the directory:
 
-@itemize @bullet{}
+@table @code
-@item @code{swap} -- @code{BOOKMARKFS_PERMD_OP_SWAP}
+@item swap
-@item @code{move-before} -- @code{BOOKMARKFS_PERMD_OP_MOVE_BEFORE}
+Exchange the positions of the directory entries represented by @code{name1}
-@item @code{move-after} -- @code{BOOKMARKFS_PERMD_OP_MOVE_AFTER}
+and @code{name2}.
-@end itemize
+
+@item move-before
+Move the directory entry represented by @code{name1} to the position just
+@emph{before} the one represented by @code{name2}.
+
+@item move-after
+Move the directory entry represented by @code{name1} to the position just
+@emph{after} the one represented by @code{name2}.
+@end table
 
 @example
 bookmarkctl fsck @var{pathname} @var{op}
@@ -834,16 +841,19 @@ with a bookmark or bookmark folder.
 When creating a new file:
 
 @table @option
-@item @option{filename=title}
+@item title
 The GUID is randomly generated by the backend.
 
-@item @option{filename=guid}
+@item guid
 The filename must be a valid GUID, and must not duplicate with other files
 on the same filesystem, otherwise @code{open()} fails with @code{EPERM}.
 
-Also sets the GUID string as the bookmark title.
+Also set the GUID string as the bookmark title.
 @end table
 
+With @option{filename=title}, the GUID is available as an extended attribute
+(@pxref{Extended Attributes}), and vise versa.
+
 @item lock=exclusive|normal
 The database connection locking mode for the bookmark storage.
 Defaults to ``normal'' when the filesystem is mounted read-only,
@@ -855,10 +865,10 @@ This option corresponds to the
 With @option{lock=exclusive}, other process cannot access the bookmark storage
 until the filesystem is dismounted.
 
-The Firefox browser holds an exclusive lock on the bookmark storage by default.
+The Firefox browser holds an exclusive lock on the database by default.
 If you wish to mount the bookmarks while keeping the browser session open,
-turn off the @code{storage.sqlite.exclusiveLock.enabled} switch
+set the @code{storage.sqlite.exclusiveLock.enabled} browser preference
-in @indicateurl{about:config}.
+to @code{false}.
 
 @item assume_title_distinct
 If this options is provided, the backend assumes that bookmark names are
@@ -917,6 +927,9 @@ on the same filesystem, otherwise @code{open()} fails with @code{EPERM}.
 Also set the GUID string as the bookmark title.
 @end table
 
+With @option{filename=title}, the GUID is available as an extended attribute
+(@pxref{Extended Attributes}), and vise versa.
+
 @item watcher=native|fallback|none
 The file watcher to use for the bookmark storage.
 Defaults to ``native'' when the filesystem is mounted read-only,