makary/bookmarkfs
1
0
Fork 0
mirror of https://git.sr.ht/~cismonx/bookmarkfs synced 2025-06-07 19:58:50 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: refactor

Browse source
This commit is contained in:
CismonX 2025-01-08 22:49:35 +08:00
parent 16e454c30c
commit a4878bfe6d
No known key found for this signature in database
GPG key ID: 3094873E29A482FB
1 changed files with 39 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

73
doc/bookmarkfs.texi
View file

@ -27,6 +27,10 @@
@uref{https://docs.kernel.org/\path\, \name\} @uref{https://docs.kernel.org/\path\, \name\}
@end macro @end macro
@macro rfcdoc {name, path}
@uref{https://datatracker.ietf.org/doc/html/\path\, \name\}
@end macro
@copying @copying
This manual is for BookmarkFS, version @value{VERSION}. 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 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. 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 @node Porting
@section Porting BookmarkFS @section Porting BookmarkFS
@ -138,20 +148,6 @@ On Linux, sandboxing is achieved using @linuxmanpage{seccomp, 2} and
On FreeBSD, @freebsdmanpage{capsicum, 4} is used. 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 @node Programs
@chapter Programs @chapter Programs
@ -428,16 +424,16 @@ The @var{op} argument is the operation to perform on the directory:
@table @code @table @code
@item swap @item swap
Exchange the positions of the directory entries represented by @code{name1} Exchange the positions of the directory entries represented by @var{name1}
and @code{name2}. and @var{name2}.
@item move-before @item move-before
Move the directory entry represented by @code{name1} to the position just Move the directory entry represented by @var{name1} to the position just
@emph{before} the one represented by @code{name2}. @emph{before} the one represented by @var{name2}.
@item move-after @item move-after
Move the directory entry represented by @code{name1} to the position just Move the directory entry represented by @var{name1} to the position just
@emph{after} the one represented by @code{name2}. @emph{after} the one represented by @var{name2}.
@end table @end table
@example @example
@ -448,15 +444,15 @@ The @command{fsck} sub-command checks for errors within a
BookmarkFS filesystem. BookmarkFS filesystem.
@xref{Filesystem Check}. @xref{Filesystem Check}.
The @command{pathname} argument is the path to the directory The @var{pathname} argument is the path to the directory to perform checks on.
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{} @table @code
@item @code{list} -- Display a list of errors found under the given directory. @item list
Display a list of errors found under the given directory.
Will not recurse into subdirectories. Will not recurse into subdirectories.
@end itemize @end table
For the full fsck functionalities, @pxref{fsck.bookmarkfs}. 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{}). (e.g. empty string; contains slash character, @dots{}).
@item ENOENT @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 @item EPERM
The backend does not support rearranging entries for this directory. 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. Whether to use the bookmark title or GUID as the bookmark file name.
Defaults to ``title''. Defaults to ``title''.
A bookmark GUID is a base64url-encoded 128-bit string uniquely associated A bookmark GUID is a @rfcdoc{base64url-encoded, rfc4648#section-5}
with a bookmark or bookmark folder. 128-bit string uniquely associated with a bookmark or bookmark folder.
When creating a new file: When creating a new file:
@ -846,7 +842,8 @@ The GUID is randomly generated by the backend.
@item guid @item guid
The filename must be a valid GUID, and must not duplicate with other files 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. Also set the GUID string as the bookmark title.
@end table @end table
@ -909,8 +906,15 @@ Backend-specific options:
Whether to use the bookmark title or GUID as the bookmark file name. Whether to use the bookmark title or GUID as the bookmark file name.
Defaults to ``title''. Defaults to ``title''.
A bookmark GUID is a hex-encoded (``8-4-4-4-12'', lowercase) 128-bit string A bookmark GUID is a hex-encoded 128-bit string uniquely associated
uniquely associated with a bookmark or bookmark folder. 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: When creating a new file:
@ -918,11 +922,12 @@ When creating a new file:
@item title @item title
The GUID is randomly generated by the backend. The GUID is randomly generated by the backend.
It is guaranteed to be a valid version 4 UUID as specified by 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 @item guid
The filename must be a valid GUID, and must not duplicate with other files 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. Also set the GUID string as the bookmark title.
@end table @end table