From 9960d67465932e3c7d991fe24e0fb909fbf5d066 Mon Sep 17 00:00:00 2001
From: CismonX <admin@cismon.net>
Date: Wed, 8 Jan 2025 11:58:15 +0800
Subject: [PATCH] doc: add doc for the Chromium backend

---
 doc/bookmarkfs.texi | 80 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)

diff --git a/doc/bookmarkfs.texi b/doc/bookmarkfs.texi
index 441b2a1..98bb0f3 100644
--- a/doc/bookmarkfs.texi
+++ b/doc/bookmarkfs.texi
@@ -876,6 +876,86 @@ on the bookmark storage before mounting with this option.
 @node Chromium
 @section Chromium Backend
 
+The Chromium backend provides access to the bookmark data of the web browser
+@uref{https://www.chromium.org/Home/, Chromium} and its derivatives,
+notably @uref{https://github.com/ungoogled-software/ungoogled-chromium,
+ungoogled-chromium}.
+
+Chromium bookmarks are stored in a text file (in JSON format)
+under the profile directory:
+
+@example
+~/.config/chromium/@var{$@{profile_name@}}/Bookmarks
+@end example
+
+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:
+
+@table @option
+@item filename=title|guid
+Whether to use the bookmark title or GUID as the bookmark file name.
+Defaults to ``title''.
+
+A bookmark GUID is a hex-encoded (``8-4-4-4-12'', lowercase) 128-bit string
+uniquely associated with a bookmark or bookmark folder.
+
+When creating a new file:
+
+@table @option
+@item title
+The GUID is randomly generated by the backend.
+It is guaranteed to be a valid version 4 UUID as specified by
+@uref{https://datatracker.ietf.org/doc/html/rfc4122, RFC 4122}.
+
+@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 set the GUID string as the bookmark title.
+@end table
+
+@item watcher=native|fallback|none
+The file watcher to use for the bookmark storage.
+Defaults to ``native'' when the filesystem is mounted read-only,
+``none'' otherwise.
+
+@table @option
+@item native
+Watch for file changes using platform-specific features.
+
+On Linux, @linuxmanpage{fanotify, 7} is used.
+Requires kernel version 5.13 or later for unprivileged users.
+@linuxmanpage{inotify, 7} does not have this limitation, however,
+it is incompatible with our sandboxing design.
+
+On FreeBSD, @freebsdmanpage{kevent, 2} with @code{EVFILT_VNODE} is used.
+
+@item fallback
+Watch for file changes by checking @code{st_ino} and @code{st_mtim} attributes
+with @code{fstatat()} periodically.
+
+Less efficient than ``native'' implementations, but should work on any
+POSIX-compatible system.
+
+@item none
+Do not watch for file changes.
+
+With @option{watcher=none}, changes on the bookmark storage are not visible
+to the filesystem.
+@end table
+@end table
+
+This 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.
+
+Another limitation is the lack of tags (@pxref{Tags}) and keywords
+(@pxref{Keywords}) support.
+Chromium does not have such concepts.
+
 
 @node Backend API
 @section Backend API