When checking the validity of cross references with -Tlint,

[mandoc.git] / mansearch.3

diff --git a/mansearch.3 b/mansearch.3
index 38051528d6f51997fa6010d50837305982e2df5c..b94815a02b45a896a033ec3d9bf9c178deb986d8 100644 (file)
--- a/mansearch.3
+++ b/mansearch.3
@@ -1,4 +1,4 @@
-.\"    $Id: mansearch.3,v 1.1 2014/04/15 20:18:26 schwarze Exp $
+.\"    $Id: mansearch.3,v 1.5 2017/03/30 22:22:05 schwarze Exp $

 .\"
 .\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\"
 .\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
 .\"


@@ -14,27 +14,22 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"

-.Dd $Mdocdate: April 15 2014 $
+.Dd $Mdocdate: March 30 2017 $

 .Dt MANSEARCH 3
 .Os
 .Sh NAME
 .Dt MANSEARCH 3
 .Os
 .Sh NAME

-.Nm mansearch ,
-.Nm mansearch_setup
+.Nm mansearch

 .Nd search manual page databases
 .Sh SYNOPSIS
 .Nd search manual page databases
 .Sh SYNOPSIS

-.In manpath.h
+.In stdint.h
+.In manconf.h

 .In mansearch.h
 .Ft int
 .In mansearch.h
 .Ft int

-.Fo mansearch_setup
-.Fa "int start"
-.Fc
-.Ft int

 .Fo mansearch
 .Fa "const struct mansearch *search"
 .Fa "const struct manpaths *paths"
 .Fa "int argc"
 .Fa "char *argv[]"
 .Fo mansearch
 .Fa "const struct mansearch *search"
 .Fa "const struct manpaths *paths"
 .Fa "int argc"
 .Fa "char *argv[]"

-.Fa "const char *outkey"

 .Fa "struct manpage **res"
 .Fa "size_t *sz"
 .Fc
 .Fa "struct manpage **res"
 .Fa "size_t *sz"
 .Fc


@@ -43,7 +38,7 @@ The
 .Fn mansearch
 function returns information about manuals matching a search query from a
 .Xr mandoc.db 5
 .Fn mansearch
 function returns information about manuals matching a search query from a
 .Xr mandoc.db 5

-SQLite3 database.
+database.

 .Pp
 The query arguments are as follows:
 .Bl -tag -width Ds
 .Pp
 The query arguments are as follows:
 .Bl -tag -width Ds


@@ -52,23 +47,11 @@ Search options, defined in
 .In mansearch.h .
 .It Fa "const struct manpaths *paths"
 Directories to be searched, defined in
 .In mansearch.h .
 .It Fa "const struct manpaths *paths"
 Directories to be searched, defined in

-.In manpath.h .
+.In manconf.h .

 .It Fa "int argc" , "char *argv[]"
 Search criteria, usually taken from the command line.
 .El
 .Pp
 .It Fa "int argc" , "char *argv[]"
 Search criteria, usually taken from the command line.
 .El
 .Pp

-The
-.Fa "const char *outkey"
-selects which data to return in the
-.Va output
-field of the
-.Fa res
-structures.
-It takes any of the macro keys defined in
-.Pa mansearch_const.c
-and described in
-.Xr apropos 1 .
-.Pp

 The output arguments are as follows:
 .Bl -tag -width Ds
 .It Fa "struct manpage **res"
 The output arguments are as follows:
 .Bl -tag -width Ds
 .It Fa "struct manpage **res"


@@ -88,19 +71,6 @@ array itself.
 Returns the number of result structures contained in
 .Fa res .
 .El
 Returns the number of result structures contained in
 .Fa res .
 .El

-.Pp
-To speed up searches, the
-.Fn mansearch_setup
-function can optionally be called with a
-.Fa start
-argument of 1 before
-.Fn mansearch
-to set up an SQLite3 pagecache.
-If it was called, it has to be called again with a
-.Fa start
-argument of 0 after the last call to
-.Fn mansearch
-to release the memory used for the pagecache.

 .Sh IMPLEMENTATION NOTES
 For each manual page tree, the search is done in two steps.
 In the first step, a list of pages matching the search criteria is built.
 .Sh IMPLEMENTATION NOTES
 For each manual page tree, the search is done in two steps.
 In the first step, a list of pages matching the search criteria is built.


@@ -111,103 +81,26 @@ array.
 .Pp
 All function mentioned here are defined in the file
 .Pa mansearch.c .
 .Pp
 All function mentioned here are defined in the file
 .Pa mansearch.c .

-No functions except
-.Fn mansearch
-and
-.Fn sql_statement
-build any SQL code, and no functions except
-.Fn mansearch ,
-.Fn buildnames ,
-and
-.Fn buildoutput
-execute it.

 .Ss Finding matches
 .Ss Finding matches

-The query is built using the following grammar:
-.Bd -literal -offset indent
-<query>     ::=        "SELECT * FROM mpages WHERE" <condition>
-<condition> ::=        "(" <condition> ")" |
-               <condition> "OR" <condition> |
-               <condition> "AND" <condition> |
-               "desc" <operator> "?" |
-               "id IN (SELECT pageid FROM" <subquery> ")"
-<subquery>  ::=        "names WHERE name" <operator> "?" |
-               "keys WHERE key" <operator> "? AND bits & ?"
-<operator>  ::=        "MATCH" | "REGEXP"
-.Ed
-.Pp
-The MATCH and REGEXP operators are implemented by the functions
-.Fn sql_match
-and
-.Fn sql_regexp ,
-respectively.
-This is required because SQLite3 natively neither supports
-case-insensitive substring matching nor regular expression matching,
-but only string identity, shell globbing, and the weird home-brewed
-LIKE operator.
-.Pp

 Command line parsing is done by the function
 .Fn exprcomp
 building a singly linked list of
 .Vt expr
 structures, using the helper functions
 Command line parsing is done by the function
 .Fn exprcomp
 building a singly linked list of
 .Vt expr
 structures, using the helper functions

-.Fn exprterm
+.Fn expr_and

 and
 and

-.Fn exprspec .
-The resulting SQL statement is assembled by the function
-.Fn sql_statement
-and evaluated in the main loop of the
-.Fn mansearch
-function.
+.Fn exprterm .

 .Ss Assembling the results
 The names, sections, and architectures of the manuals found
 are assembled into the
 .Va names
 field of the result structure by the function
 .Ss Assembling the results
 The names, sections, and architectures of the manuals found
 are assembled into the
 .Va names
 field of the result structure by the function

-.Fn buildnames ,
-using the following query:
-.Pp
-.Dl "SELECT * FROM mlinks WHERE pageid=? ORDER BY sec, arch, name"
-.Pp
-If the
-.Fa outkey
-differs from
-.Qq Nd ,
-the requested output data is assembled into the
-.Va output
-field of the result structure by the function
-.Fn buildoutput ,
-using the following query:
-.Pp
-.Dl "SELECT * FROM keys WHERE pageid=? AND bits & ?"
+.Fn buildnames .

 .Sh FILES
 .Bl -tag -width mandoc.db -compact
 .It Pa mandoc.db
 The manual page database.
 .El
 .Sh FILES
 .Bl -tag -width mandoc.db -compact
 .It Pa mandoc.db
 The manual page database.
 .El

-.Sh EXAMPLES
-The simplest invocation
-.Pp
-.Dl apropos keyword
-.Pp
-results in the following SQL query:
-.Bd -literal
-SELECT * FROM mpages WHERE (
-  id IN (SELECT pageid FROM names WHERE name MATCH 'keyword') OR
-  desc MATCH 'keyword'
-);
-.Ed
-.Pp
-A more complicated request like
-.Pp
-.Dl apropos -s 2 Nm,Xr=getuid
-.Pp
-results in:
-.Bd -literal
-SELECT * FROM mpages WHERE (
-  id IN (SELECT pageid FROM names WHERE name MATCH 'getuid') OR
-  id IN (SELECT pageid FROM keys WHERE key MATCH 'getuid' AND bits & 4)
-) AND id IN (SELECT pageid FROM keys WHERE key REGEXP '^2$' AND bits & 2);
-.Ed

 .Sh SEE ALSO
 .Xr apropos 1 ,
 .Xr mandoc.db 5 ,
 .Sh SEE ALSO
 .Xr apropos 1 ,
 .Xr mandoc.db 5 ,


@@ -222,6 +115,6 @@ subsystem first appeared in
 A module to search manual page databases was first written by
 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
 in 2011, at first using the Berkeley DB;
 A module to search manual page databases was first written by
 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
 in 2011, at first using the Berkeley DB;

-he rewrote it for SQLite3 in 2012.
-The current version received major changes from
-.An Ingo Schwarze Aq Mt schwarze@openbsd.org .
+he rewrote it for SQLite3 in 2012, and
+.An Ingo Schwarze Aq Mt schwarze@openbsd.org
+removed the dependency on SQLite3 in 2016.