KFIND(1)

NAME
	kfind1, G1
	kfind2, G2

SYNOPSIS
	kfind1 [-kG] query
	kfind2 [-G] query
	G1 query directory
	G2 query file

DESCRIPTION
	These are front-end of Kirara search engine (ver.1.4 and ver.2.1).
	
	Once you have finished to construct Kirara, you can use these commands.
	Kfind (kfind1 and kfind2) finds words in the database using query in the argument.

	Kirara stores all data in lower case, so kfind and G (G1 and G2) also searches
	lower case strings.

	The syntax of query is defined as follows using syntax of ABNF.
	space = " "
	alphanum = (LATIN-ALPHA / DIGIT / "_")
	non-latin = NON-LATIN-ALPHA
	word = 2*aphanum / 2*non-latin
	wildcard = "?" / "*"
	term = word *(wildcard (1*alphanum / 1*non-latin) [wildcard]
	or-query = term *("|" term)
	and-query = or-query *("&" or-query)
	phrase-query = or-query *(space or-query)
	query = and-query / phrase-query

	In this ABNF, LATIN-ALPHA denotes Western Eulopean alphabet including English,
	German, Spanish, etc that are inside of unicode range 0000:0370.
	NON-LATIN-ALPHA includes Greek, Coptic, Cyrillic, Armenian, CJK Kanji,
	and Japanese Katakana.

	The precedence of these operator is as follows:
		1. ? *
		2. |
		3. & space

	The examples of querys are as follows:
		kfind1 'sn*y|sniffer&network'
		kfind1 'sn*y|sniffer network'

	Because query format of kirara2 is the same as kirara1, these query is valid also for kirara2.

	In the syntax, "?" and "*" denote wild card.
	Phrase query means to find files that include all given words in a lines.

	The word length must be at least $wordlen that is given in db.conf.
	The default value is 2.
	The word shorter than this value will work for many cases,
	but then the retrieval may miss something.

	The options for kfind are:
	-k	disable '&' to '|' conversion in output.
		Look examples below.
	-G	don't output "G query" fields. Then output is just directories.

	G (G1 and G2) is a grep for Kirara, but modified slightly: the argument is not a regular
	expression but a query expression. Therefore ampersand and space have
	special meaning. G finds words giving and-query or phrase-query in the specified file.

	The output of G is probably verbose, but you can use grep with combination
	to G. Remind that grep is a nice tool to filter out verbose output.

	Kfind internally uses:
		KR_trans
	which is included in the package Kirara. The original location is
		http://plan9.aichi-u.ac.jp/netlib/cmd/trans/
	in which you will find some other trans tools.

	Look MAN_KIRARA for more information.

EXAMPLES
	Here are some examples.

	For Kirara1
	term% kfind1 snoop
	G1 'snoop' /lib/
	G1 'snoop' /sys/lib/linux/var/lib/apt/lists/
	G1 'snoop' /sys/src/9/ip/
	G1 'snoop' /sys/src/cmd/ip/snoopy/
	G1 'snoop' /sys/src/cmd/mothra/
	G1 'snoop' /sys/src/cmd/spell/
	...
	term% G1 'snoop' /sys/src/9/ip/
	/sys/src/9/ip/devip.c:98: 		devdir(c, q, "snoop", qlen(cv->sq), cv->owner, 0400, dp);
	/sys/src/9/ip/ip.h:208: 	Ref	snoopers;		/* number of processes with snoop open */

	and for Kiarar2
	term% kfind2 snoop
	G2 'snoop' /lib/dicewords
	G2 'snoop' /lib/words
	G2 'snoop' /sys/src/9/ip/devip.c
	G2 'snoop' /sys/src/9/ip/ip.h
	G2 'snoop' /sys/src/cmd/ip/snoopy/main.c
	G2 'snoop' /sys/src/cmd/mothra/mkfile
	...
	term% G2 'snoop' /sys/src/cmd/ip/snoopy/main.c
	/sys/src/cmd/ip/snoopy/main.c:158: 		snprint(buf, Blen, "%s/snoop", file);
	term% 

	Note that Kirara1 shows directories, on the other hand, Kirara2 shows files.

	term% kfind1 'snoop*'
	G1 'snoop*' /lib/
	G1 'snoop*' /lib/dict/
	G1 'snoop*' /sys/doc/net/
	G1 'snoop*' /sys/lib/linux/var/lib/apt/lists/
	G1 'snoop*' /sys/lib/man/lookman/
	G1 'snoop*' /sys/lib/sysconfig/auth/
	G1 'snoop*' /sys/lib/sysconfig/proto/

	term% G1 'snoop*' /sys/doc/net/
	/sys/doc/net/net.html:276: <span style="font-size: 10pt">&#8729;  diagnostic interfaces for snooping software.
	/sys/doc/net/net.ms:221: diagnostic interfaces for snooping software.
	/sys/doc/net/net.ps:4916: (diagnostic interfaces for snooping software.) 970 2714 w
	term% 

	In most cases, the output of kfind is so much.
	Therefore "and-search" is supported by andlist.

	term% kfind1 'snoopy&proto'
	G1 'snoopy|proto' /sys/lib/linux/var/lib/apt/lists/
	G1 'snoopy|proto' /sys/lib/man/lookman/
	G1 'snoopy|proto' /sys/lib/sysconfig/auth/
	G1 'snoopy|proto' /sys/lib/sysconfig/proto/
	G1 'snoopy|proto' /sys/man/
	G1 'snoopy|proto' /sys/man/3/
	G1 'snoopy|proto' /sys/man/8/
	...
	term% 

	Note that '&' in the input is replaced by '|' in the output.
	This is intentional.
	Remined that kfind shows directories, which means that these directories
	include both "snoopy" and "proto". On the other hand,
		G1 'snoopy|proto' 
	tries to find files that include "snoopy" and/or "proto". These files should exist.

	term% G1 'snoopy|proto' /sys/man/8/
	/sys/man/8/INDEX.html:313: <DT><A HREF="/magic/man2html/8/snoopy">snoopy</A>
	/sys/man/8/INDEX.html:315: <DD><TT> snoopy</TT>
	/sys/man/8/INDEX:199: snoopy snoopy
	/sys/man/8/mk9660:159: .I proto

	However,
		G1 'snoopy&proto'
	tries to find files that include both "snoopy" and "proto".
	Even if a directory has both "snoopy" and "proto", there is no guarantee
	that there exist files that has both "snoopy" and "proto".

	Sometimes we will want to know files that include both "snoopy" and "proto".
	The -k option disables the conversion from '&' to '|'.

	Note that G2 does not have "-k" option. This is because "&" query such as
		G2 'snoop&protp'
	is meaningless.

	We will sometimes want to find files that include both "snoopy" and "proto" in a line.
	Then excute:

	term% kfind1 'snoopy proto'
	G1 'snoopy proto' /sys/lib/linux/var/lib/apt/lists/
	G1 'snoopy proto' /sys/lib/man/lookman/
	G1 'snoopy proto' /sys/lib/sysconfig/auth/
	G1 'snoopy proto' /sys/lib/sysconfig/proto/
	G1 'snoopy proto' /sys/man/
	G1 'snoopy proto' /sys/man/3/
	G1 'snoopy proto' /sys/man/8/
	G1 'snoopy proto' /sys/src/cmd/ip/
	G1 'snoopy proto' /sys/src/cmd/ip/snoopy/

	or

	term% kfind2 'snoopy proto'
	G2 'snoopy proto' /sys/lib/man/lookman/index
	G2 'snoopy proto' /sys/lib/sysconfig/auth/authproto
	G2 'snoopy proto' /sys/lib/sysconfig/proto/standalone
	G2 'snoopy proto' /sys/man/8/snoopy
	G2 'snoopy proto' /sys/man/searchindex
	G2 'snoopy proto' /sys/src/cmd/ip/measure.c
	G2 'snoopy proto' /sys/src/cmd/ip/snoopy/main.c
	...
	term%

	Many dirs or files are shown, however, most of them does not have lines
	that include both "snoopy" and "proto". If we do want to know such files
	and the lines, execute:
		kfind1 'snoopy proto' | rc
	or
		kfind2 'snoopy proto' | rc
	This might take much time.
	kfind2 is much faster than kfind1 (for example, 18 sec for kfind1 and 5 sec for kfind2)

	To reduce the time, put a filter using grep before rc as shown below.
	term% kfind1 'snoopy proto' |grep /sys/lib | rc
	/sys/lib/man/lookman/index:48401: proto	/sys/man/8/snoopy
	/sys/lib/sysconfig/proto/standalone:61: 		snoopy
	term% 

	Note that file name might be included in the matching target due to the algorithm
	applied to this problem.

SEE ALSO
	KIRARA(8)

SOURCE
	http://plan9.aichi-u.ac.jp/netlib/kirara/

AUTHER
	Kenji Arisawa
	arisawa@aichi-u.ac.jp