Add some man pages.

diff --git a/meson.build b/meson.build
index a37a89f9ca8ce1beaca90d45b3a1c1a2f3701c60..5bf6d993fe1474604a6e588c7aa0a9b3558df30b 100644 (file)
--- a/meson.build
+++ b/meson.build
@@ -23,6 +23,8 @@ executable('plocate-build', 'plocate-build.cpp',
 install_data('update-plocate.sh',
        install_dir: '/etc/cron.daily',
        rename: 'plocate')
+install_man('plocate.1')
+install_man('plocate-build.8')
 
 # Requires having TurboPFor checked out, so not built by default.
 # Unless you have a recent Meson, there's no apparently good way

diff --git a/plocate-build.8 b/plocate-build.8
new file mode 100644 (file)
index 0000000..79b0a17
--- /dev/null
+++ b/plocate-build.8
@@ -0,0 +1,59 @@
+.TH plocate-build 1 "Oct 2020" plocate-build
+.SH NAME
+plocate-build \- generate index for plocate
+
+.SH SYNOPSIS
+.B plocate-build
+.I "[OPTION]..."
+.I "MLOCATE_DB"
+.I "PLOCATE_DB"
+
+.SH DESCRIPTION
+.B plocate-build
+creates an index from 
+.BR plocate (1)
+from an index earlier generated by
+.BR updatedb (1)
+from the
+.BR mlocate (1)
+package. This is currently the only way to build such an index.
+If
+.I MLOCATE_DB
+already exists, it will be overwritten (non-atomically). The file is
+created such that it is not world-readable, as the final access check
+is done by
+.BR plocate (1)
+during the search.
+
+.SH OPTIONS
+.TP
+\fB\-b\fR, \fB\-\-block\-size\fR \fISIZE\fR
+Create blocks containing
+.I SIZE
+filenames each, compress them together, and treat them as the same element
+in the posting lists. This makes the index smaller (because the compression
+algorithm gets more context to work with, and because there are fewer elements
+in each posting list), but also makes posting lists less precise, moving more
+work to weeding out false positives after posting list intersection.
+
+Making this number larger will make linear search (for \fB\-\-regex\fR,
+or very short patterns) faster, with diminishing returns around 256 filenames
+per block. However, making it too large will cause more false positives,
+reducing overall performance for typical queries. The default value is 32.
+Setting it to 1 makes one (compressed) block per filename.
+
+.TP
+.B \-\-help
+Print out usage information, then exit successfully.
+
+.TP
+.B \-\-version
+Print out version information, then exit successfully.
+
+.SH AUTHOR
+Steinar H. Gunderson <steinar+plocate@gunderson.no>
+
+.SH SEE ALSO
+\fBplocate\fP(1),
+\fB/etc/cron.daily/plocate\fR (which is called
+\fBupdate-plocate.sh\fR in the source distribution)

diff --git a/plocate.1 b/plocate.1
new file mode 100644 (file)
index 0000000..e58ad58
--- /dev/null
+++ b/plocate.1
@@ -0,0 +1,127 @@
+.TH locate 1 "Oct 2020" plocate
+.SH NAME
+plocate \- find files by name, quickly
+
+.SH SYNOPSIS
+.B plocate
+.I "[OPTION]..."
+.I "PATTERN..."
+
+.SH DESCRIPTION
+.B plocate
+finds all files on the system matching the given pattern (or all
+of the patterns if multiple are given). It does this by means of
+an index made by
+.BR plocate-build (8),
+which in turn reads the database made by 
+.BR updatedb (8).
+
+plocate is largely compatible with
+.BR mlocate (1),
+and reuses its database to create its index, but is significantly
+faster. In particular, it rarely needs to scan through its entire
+database, unless the pattern is very short (less than three bytes)
+or you want to search for a regular expression. It does not try to
+maintain compatibility with BSD locate, or non-UTF-8 filenames
+and locales. Most I/O is done asynchronously, but the results are
+synchronized so that output comes in the same order every time.
+
+When multiple patterns are given,
+.B plocate
+will search for files that match
+.I all
+of them. This is the main incompatibility with
+.BR mlocate (1),
+which searches for files that match one or more patterns, unless
+the \-a option is given.
+
+By default, patterns are taken to be substrings to search for.
+If at least one non-escaped globbing metacharacter (*, ? or []) is given,
+that pattern is instead taken to be a glob pattern (which means it needs
+to start and end in * for a substring match). If
+.B --regexp
+is given, patterns are instead taken to be (non-anchored) POSIX basic
+regular expressions, and if
+.B --regex
+is given, patterns are taken to be POSIX extended regular expressions.
+All of this matches
+.BR mlocate (1)
+behavior.
+
+Like
+.BR mlocate(1),
+shows all files visible to the calling user (by virtue of
+having read and execute permissions on all parent directories),
+and none that are not, by means of running with the setgid
+bit set to access the index (which is built as root), but by
+testing visibility as the calling user.
+
+.SH OPTIONS
+.TP
+\fB\-c\fR, \fB\-\-count\fR
+Do not print each match. Instead, count them, and print out a total
+number at the end.
+
+.TP
+\fB\-d\fR, \fB\-\-database\fR \fIDBPATH\fR
+Find matches in \fB/var/lib/mlocate/plocate.db\fR, instead of the given database.
+(
+.B plocate
+does not currently support multiple databases.)
+
+.TP
+\fB\-i\fR, \fB\-\-ignore\-case\fR
+Do a case-insensitive match as given by the current locale
+(default is case-sensitive, byte-by-byte match). Note that
+.B plocate
+does not support the full range of Unicode case folding rules;
+in particular, searching for \fIß\fR will not give you matches on \fIss\fR
+even in a German locale. Also note that this option will be
+somewhat slower than a case-sensitive match, since it needs to
+generate more candidates for searching the index.
+
+.TP
+\fB\-l\fR, \fB\-\-limit\fR \fILIMIT\fR
+Stop searching after
+.I LIMIT
+matches have been found. If
+.B \-\-count
+is given, the number printed out will be at most \fILIMIT\fR.
+
+.TP
+\fB\-0\fR, \fB\-\-null\fR
+Instead of writing a newline after every match, write a NUL
+(ASCII 0). This is useful for creating unambiguous output
+when it is to be processed by other tools (like \fBxargs\fP(1)), as filenames are
+allowed to contain embedded newlines.
+
+.TP
+\fB\-r\fR, \fB\-\-regexp\fR
+Patterns are taken to be POSIX basic regular expressions.
+See
+.BR regex(7)
+for more information. Note that this forces a linear scan
+through the entire database, which is slow.
+
+.TP
+.B \-\-regex
+Like \fB\-\-regexp\fR, but patterns are instead taken to
+be POSIX
+.I extended
+regular expressions.
+
+.TP
+.B \-\-help
+Print out usage information, then exit successfully.
+
+.TP
+.B \-\-version
+Print out version information, then exit successfully.
+
+.SH AUTHOR
+Steinar H. Gunderson <steinar+plocate@gunderson.no>
+
+.SH SEE ALSO
+\fBplocate-build\fP(8),
+\fBmlocate\fP(1),
+\fBupdatedb\fP(8)