[src/trunk]: src/usr.sbin/makemandb Bring man pages in sync with reality.

[abhinav <abhinav%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/1ef5f9b5e779
branches:  trunk
changeset: 345399:1ef5f9b5e779
user:      abhinav <abhinav%NetBSD.org@localhost>
date:      Tue May 24 18:06:42 2016 +0000

description:
Bring man pages in sync with reality.

Remove man pages run_query_html.3 and run_query_pager.3 as the corresponding
functions have been removed from apropos-utils.c
Ok by wiz@

diffstat:

 usr.sbin/makemandb/apropos-utils.3   |    8 +-
 usr.sbin/makemandb/close_db.3        |    8 +-
 usr.sbin/makemandb/init_db.3         |   10 +-
 usr.sbin/makemandb/run_query.3       |   48 ++++---------
 usr.sbin/makemandb/run_query_html.3  |  116 -----------------------------------
 usr.sbin/makemandb/run_query_pager.3 |  106 -------------------------------
 6 files changed, 27 insertions(+), 269 deletions(-)

diffs (truncated from 427 to 300 lines):

diff -r a94eebaee711 -r 1ef5f9b5e779 usr.sbin/makemandb/apropos-utils.3
--- a/usr.sbin/makemandb/apropos-utils.3        Tue May 24 17:42:54 2016 +0000
+++ b/usr.sbin/makemandb/apropos-utils.3        Tue May 24 18:06:42 2016 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: apropos-utils.3,v 1.3 2013/04/02 18:35:28 wiz Exp $
+.\" $NetBSD: apropos-utils.3,v 1.4 2016/05/24 18:06:42 abhinav Exp $
 .\"
 .\" Copyright (c) 2011 Abhinav Upadhyay <er.abhinav.upadhyay%gmail.com@localhost>
 .\" All rights reserved.
@@ -29,7 +29,7 @@
 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd April 2, 2013
+.Dd May 23, 2016
 .Dt APROPOS-UTILS 3
 .Os
 .Sh NAME
@@ -38,7 +38,7 @@
 .Sh SYNOPSIS
 .In apropos-utils.h
 .Ft sqlite3 *
-.Fn init_db "int db_flag"
+.Fn init_db "mandb_access_mode db_flag" "const char * manconf"
 .Ft void
 .Fn close_db "sqlite3 *db"
 .Ft int
@@ -56,6 +56,6 @@
 .Sh SEE ALSO
 .Xr close_db 3 ,
 .Xr init_db 3 ,
-.Xr run_query 3 ,
+.Xr run_query 3
 .Sh AUTHORS
 .An Abhinav Upadhyay
diff -r a94eebaee711 -r 1ef5f9b5e779 usr.sbin/makemandb/close_db.3
--- a/usr.sbin/makemandb/close_db.3     Tue May 24 17:42:54 2016 +0000
+++ b/usr.sbin/makemandb/close_db.3     Tue May 24 18:06:42 2016 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: close_db.3,v 1.1 2012/02/07 19:13:32 joerg Exp $
+.\" $NetBSD: close_db.3,v 1.2 2016/05/24 18:06:42 abhinav Exp $
 .\"
 .\" Copyright (c) 2011 Abhinav Upadhyay <er.abhinav.upadhyay%gmail.com@localhost>
 .\" All rights reserved.
@@ -29,7 +29,7 @@
 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd August 17, 2011
+.Dd May 23, 2016
 .Dt CLOSE_DB 3
 .Os
 .Sh NAME
@@ -55,8 +55,6 @@
 .Sh SEE ALSO
 .Xr apropos-utils 3 ,
 .Xr init_db 3 ,
-.Xr run_query 3 ,
-.Xr run_query_html 3 ,
-.Xr run_query_pager 3
+.Xr run_query 3
 .Sh AUTHORS
 .An Abhinav Upadhyay
diff -r a94eebaee711 -r 1ef5f9b5e779 usr.sbin/makemandb/init_db.3
--- a/usr.sbin/makemandb/init_db.3      Tue May 24 17:42:54 2016 +0000
+++ b/usr.sbin/makemandb/init_db.3      Tue May 24 18:06:42 2016 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: init_db.3,v 1.2 2012/10/06 15:33:59 wiz Exp $
+.\" $NetBSD: init_db.3,v 1.3 2016/05/24 18:06:42 abhinav Exp $
 .\"
 .\" Copyright (c) 2011 Abhinav Upadhyay <er.abhinav.upadhyay%gmail.com@localhost>
 .\" All rights reserved.
@@ -29,7 +29,7 @@
 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd October 5, 2011
+.Dd May 22, 2016
 .Dt INIT_DB 3
 .Os
 .Sh NAME
@@ -38,7 +38,7 @@
 .Sh SYNOPSIS
 .In apropos-utils.h
 .Ft sqlite3 *
-.Fn init_db "int db_flag" "char *manconf"
+.Fn init_db "mandb_access_mode db_flag" "const char *manconf"
 .Sh DESCRIPTION
 The
 .Fn init_db
@@ -95,8 +95,6 @@
 .Sh SEE ALSO
 .Xr apropos-utils 3 ,
 .Xr close_db 3 ,
-.Xr run_query 3 ,
-.Xr run_query_html 3 ,
-.Xr run_query_pager 3
+.Xr run_query 3
 .Sh AUTHORS
 .An Abhinav Upadhyay
diff -r a94eebaee711 -r 1ef5f9b5e779 usr.sbin/makemandb/run_query.3
--- a/usr.sbin/makemandb/run_query.3    Tue May 24 17:42:54 2016 +0000
+++ b/usr.sbin/makemandb/run_query.3    Tue May 24 18:06:42 2016 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: run_query.3,v 1.3 2014/10/18 08:33:31 snj Exp $
+.\" $NetBSD: run_query.3,v 1.4 2016/05/24 18:06:42 abhinav Exp $
 .\"
 .\" Copyright (c) 2011 Abhinav Upadhyay <er.abhinav.upadhyay%gmail.com@localhost>
 .\" All rights reserved.
@@ -29,7 +29,7 @@
 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd December 3, 2011
+.Dd May 23, 2016
 .Dt RUN_QUERY 3
 .Os
 .Sh NAME
@@ -40,7 +40,7 @@
 .Sh SYNOPSIS
 .In apropos-utils.h
 .Ft int
-.Fn run_query "sqlite3 *db" "const char **snippet_args" "query_args *args"
+.Fn run_query "sqlite3 *db" "query_format fmt" "query_args *args"
 .Sh DESCRIPTION
 The
 .Fn run_query
@@ -60,32 +60,16 @@
 .It Fa sqlite3 *db
 Handle to the database connection which can be obtained by calling
 .Fn init_db .
-.It Fa const char *snippet_args
-An array of strings which specify the
-delimiters to the matching text in snippet.
-It is an optional argument and caller can supply a
-.Dv NULL
-value for it, in which case, a default value of
-.Brq \&"\&", \&"\&", \&"...\&"
-will be used.
-The 3 members of the array specify the following values:
-.Bl -enum -offset indent
-.It
-The first element marks the beginning of each matching token in the snippet.
-.It
-The second element the end of each matching token in the snippet.
-.It
-The third element is used to delimit the beginning and end of the snippet.
+.It Fa query_format fmt
+An enum value
+indicating the output format.
+Currently you can specify following values:
+.Bl -hang -width compact
+.It Dv APROPOS_PAGER
+.It Dv APROPOS_TERM
+.It Dv APROPOS_HTML
+.It Dv APROPOS_NONE
 .El
-For example for highlighting matching tokens in HTML style mark-up, use this
-value:
-.Bd -literal -offset indent
- const char **snippet_args = {
-       "<b>",
-       "</b>",
-       "..."
- };
-.Ed
 .It Fa query_args *args
 .Ft query_args
 is a struct which is defined in
@@ -120,6 +104,8 @@
 n records from the result-set will be omitted and rest m-n (or less) records will
 be available for processing inside the callback.
 Use a negative value if you don't wish to offset any records.
+.It Li int legacy
+If the output should be in legacy format (similary to classic apropos).
 .It Li const char *machine
 The machine architecture to which the searches should be restricted.
 Specify NULL if the search should not be restricted a particular machine architecture.
@@ -195,7 +181,7 @@
 args.callback = &query_callback;
 args.callback_data = NULL;
 args.errmsg = &errmsg;
-if (run_query(db, NULL, &args) < 0)
+if (run_query(db, APROPOS_PAGER, &args) < 0)
                errx(EXIT_FAILURE, "%s", errmsg);
 }
 
@@ -217,8 +203,6 @@
 .Sh SEE ALSO
 .Xr apropos-utils 3 ,
 .Xr close_db 3 ,
-.Xr init_db 3 ,
-.Xr run_query_html 3 ,
-.Xr run_query_pager 3
+.Xr init_db 3
 .Sh AUTHORS
 .An Abhinav Upadhyay
diff -r a94eebaee711 -r 1ef5f9b5e779 usr.sbin/makemandb/run_query_html.3
--- a/usr.sbin/makemandb/run_query_html.3       Tue May 24 17:42:54 2016 +0000
+++ /dev/null   Thu Jan 01 00:00:00 1970 +0000
@@ -1,116 +0,0 @@
-.\" $NetBSD: run_query_html.3,v 1.2 2012/02/07 21:02:33 wiz Exp $
-.\"
-.\" Copyright (c) 2011 Abhinav Upadhyay <er.abhinav.upadhyay%gmail.com@localhost>
-.\" All rights reserved.
-.\"
-.\" This code was developed as part of Google's Summer of Code 2011 program.
-.\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\"
-.\" 1. Redistributions of source code must retain the above copyright
-.\"    notice, this list of conditions and the following disclaimer.
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\"    notice, this list of conditions and the following disclaimer in
-.\"    the documentation and/or other materials provided with the
-.\"    distribution.
-.\"
-.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
-.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
-.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
-.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
-.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
-.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
-.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-.\" SUCH DAMAGE.
-.\"
-.Dd December 3, 2011
-.Dt RUN_QUERY_HTML 3
-.Os
-.Sh NAME
-.Nm run_query_html
-.Nd run a query against
-.Pa /var/db/man.db
-and returns the results in HTML format
-.Sh SYNOPSIS
-.In apropos-utils.h
-.Ft int
-.Fn run_query_html "sqlite3 *db" "query_args *args"
-.Sh DESCRIPTION
-The
-.Fn run_query_html
-is very much similar to
-.Fn run_query
-but with the following three differences.
-.Bl -enum -offset indent
-.It
-.Nm
-takes only two arguments.
-.It
-The snippet returned by
-.Nm
-uses <b> and </b> tags to highlight the matching pieces of text so that it
-appears bold in a web browser.
-.It
-.Nm
-will do limited quoting of the inline HTML fragments in the snippet.
-Concretely, it will replace <, >, ", & with &lt; &gt; &quot; and &amp;
-respectively.
-.El
-For more details, refer to the manual page of
-.Xr run_query 3 .
-.Sh RETURN VALUES
-On successful execution the
-.Fn run_query_html
-function will return 0 and in case of an error \-1 will be returned.
-.Sh FILES
-.Bl -hang -width -compact
-.It Pa /var/db/man.db
-The Sqlite FTS database which contains an index of the manual pages.
-.El
-.Sh EXAMPLES
-Following is a code excerpt of how
-.Nm
-can be used.
-.Bd -literal -offset indent
-#include <apropos-utils.h>
-query_args args;
-char *errmsg = NULL;
-int *sec_nums = {0, 1, 1, 0, 0, 0, 0, 0, 0};
-args.search_str = argv[1];
-args.sec_nums = sec_nums;
-args.nrec = 10;
-args.offset = -1;
-args.machine = NULL;
-args.callback = &query_callback;
-args.callback_data = NULL;
-args.errmsg = &errmsg;
-if (run_query(db, &args) < 0)
-               errx(EXIT_FAILURE, "%s", errmsg);
-}
-
-free(query);
-free(errmsg);
-