diff --git a/doc/bookmarkfs.texi b/doc/bookmarkfs.texi index f317d95..881221d 100644 --- a/doc/bookmarkfs.texi +++ b/doc/bookmarkfs.texi @@ -27,6 +27,10 @@ @uref{https://docs.kernel.org/\path\, \name\} @end macro +@macro rfcdoc {name, path} +@uref{https://datatracker.ietf.org/doc/html/\path\, \name\} +@end macro + @copying This manual is for BookmarkFS, version @value{VERSION}. @@ -80,6 +84,12 @@ Public License, either version 3, or any later version of the license. You should have received a copy of the GNU General Public License along with BookmarkFS. If not, see @uref{https://www.gnu.org/licenses/}. +BookmarkFS is +@uref{https://savannah.nongnu.org/projects/bookmarkfs, hosted on Savannah}. +Write to the +@uref{https://savannah.nongnu.org/mail/?group=bookmarkfs, mailing lists} +for bug reports, feature requests, and other discussions. + @node Porting @section Porting BookmarkFS @@ -138,20 +148,6 @@ On Linux, sandboxing is achieved using @linuxmanpage{seccomp, 2} and On FreeBSD, @freebsdmanpage{capsicum, 4} is used. -@node Contributing -@section Contributing to BookmarkFS - -BookmarkFS is hosted on Savannah. -Write to the -@uref{https://savannah.nongnu.org/mail/?group=bookmarkfs, mailing lists} -for bug reports, feature requests, and other discussions. - -BookmarkFS is a personal hobby project, and is currently in -experimental stage. -Thus, it it not yet ready for open collaboration, -which means patches are generally rejected unless trivial (e.g. typo fix). - - @node Programs @chapter Programs @@ -428,16 +424,16 @@ The @var{op} argument is the operation to perform on the directory: @table @code @item swap -Exchange the positions of the directory entries represented by @code{name1} -and @code{name2}. +Exchange the positions of the directory entries represented by @var{name1} +and @var{name2}. @item move-before -Move the directory entry represented by @code{name1} to the position just -@emph{before} the one represented by @code{name2}. +Move the directory entry represented by @var{name1} to the position just +@emph{before} the one represented by @var{name2}. @item move-after -Move the directory entry represented by @code{name1} to the position just -@emph{after} the one represented by @code{name2}. +Move the directory entry represented by @var{name1} to the position just +@emph{after} the one represented by @var{name2}. @end table @example @@ -448,15 +444,15 @@ The @command{fsck} sub-command checks for errors within a BookmarkFS filesystem. @xref{Filesystem Check}. -The @command{pathname} argument is the path to the directory -to perform checks on. +The @var{pathname} argument is the path to the directory to perform checks on. -The @command{op} argument is the operation to perform on the directory: +The @var{op} argument is the operation to perform on the directory: -@itemize @bullet{} -@item @code{list} -- Display a list of errors found under the given directory. +@table @code +@item list +Display a list of errors found under the given directory. Will not recurse into subdirectories. -@end itemize +@end table For the full fsck functionalities, @pxref{fsck.bookmarkfs}. @@ -774,7 +770,7 @@ Write or search permission is denied for the directory. (e.g. empty string; contains slash character, @dots{}). @item ENOENT -The directory does not contain @code{name1} or @code{name2}. +The directory does not contain entries named @code{name1} or @code{name2}. @item EPERM The backend does not support rearranging entries for this directory. @@ -835,8 +831,8 @@ Backend-specific options: Whether to use the bookmark title or GUID as the bookmark file name. Defaults to ``title''. -A bookmark GUID is a base64url-encoded 128-bit string uniquely associated -with a bookmark or bookmark folder. +A bookmark GUID is a @rfcdoc{base64url-encoded, rfc4648#section-5} +128-bit string uniquely associated with a bookmark or bookmark folder. When creating a new file: @@ -846,7 +842,8 @@ The GUID is randomly generated by the backend. @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}. +on the same filesystem, otherwise @code{open()} or @code{mkdir()} fails +with @code{EPERM}. Also set the GUID string as the bookmark title. @end table @@ -909,8 +906,15 @@ Backend-specific options: 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. +A bookmark GUID is a hex-encoded 128-bit string uniquely associated +with a bookmark or bookmark folder. +The GUID string has a ``8-4-4-4-12'' format, while all alphabetic characters +are in lowercase. +For example: + +@example +0bc5d13f-2cba-5d74-951f-3f233fe6c908 +@end example When creating a new file: @@ -918,11 +922,12 @@ When creating a new file: @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}. +@rfcdoc{RFC 4122, rfc4122}. @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}. +on the same filesystem, otherwise @code{open()} or @code{mkdir()} fails +with @code{EPERM}. Also set the GUID string as the bookmark title. @end table