#################################################################

    Client/Server system for searching in pkgsrc packages.

     Dictionary protocol (RFC-2229) is used for searching.

 There is nothing specific to pkgsrc. It can easily be adopted
              to any other packaging system.

##########

useful URLs:

  http://www.dict.org
  http://www.pkgsrc.org

#################################################################

Requirements:

  Server side (building utilities):

    - pkg_src_summary (for building summary for packages from
      pkgsrc/ tree)

      packaged in pkgsrc/wip/pkg_src_summary

    - dictfmt > 1.10.10,

      http://sourceforge.net/projects/dict/,
      packaged in pkgsrc/textproc/dict-server

    - pipestatus

      http://sourceforge.net/projects/pipestatus/,
      packaged in pkgsrc/devel/pipestatus

    - dictd dictionary server > 1.10.10,

      http://sourceforge.net/projects/dict
      packaged in pkgsrc/wip/dict-server

    - mk-configure
      http://sourceforge.net/projects/mk-configure/
      packaged in wip/mk-configure

  Client side:

    - dictionary protocol client compatible with 'dict >= 1.10.9'

      http://sourceforge.net/projects/dict
      packaged in pkgsrc/textproc/dict-client

    - pipestatus

      http://sourceforge.net/projects/pipestatus,
      packaged in pkgsrc/devel/pipestatus

    - netcat,
      packaged in pkgsrc/net/netcat

    - pkg_summary-utils>=0.49,
      packaged in pkgsrc/wip/pkg_summary-utils

    - mk-configure
      http://sourceforge.net/projects/mk-configure/
      packaged in wip/mk-configure

Installation:

  If you want to install everything

     mkcmake all install  

  If you want to install client or server run the following

     mkcmake all-client install-client

  or
     export PREFIX=/usr/pkg EGDIR=/usr/pkg/share/examples/pkg_online
     mkcmake all-server all-doc install-server install-doc

  Sample configuration files are installed to ${EGDIR}

Sample of client usage:

  Initialization.

    export PKG_ONLINE_SERVER=your.server.org  # default - dict.mova.org
    export PKG_ONLINE_PORT=your.port          # default - 2628
    # By default my server dict.mova.org:26280 is used

    export PKG_ONLINE_NETCAT=/usr/pkg/sbin/nc # default - nc

  Running.
    # pkg_online client consists of two tools:
    #   low-level tool 'pkg_online_client'
    #   and higher-level 'pkg_online_find'

    # ask programs for their options and abilities
    pkg_online_client -h
    pkg_online_find -h

    # ask server for a list of available search strategies
    pkg_online_client -s
    pkg_online_find -s

    # ask server for a list of fields to search in
    pkg_online_client -f
    pkg_online_find -f

    # obtain information about packages (PKGNAME here, not PKGPATH!)
    pkg_online_client -1 xxkb
    pkg_online_client -3 dict-server dict-client
    pkg_online_client -9 dictem

    # obtain information about packages (Either PKGNAME or PKGPATH)
(***)
    pkg_online_find -1 x11/xxkb
    pkg_online_find -3 dict-client
    pkg_online_find -9 wip/distbb

    # low-level search tool (full names for strategies and fields!)
    # pkg_online_client displays PKGNAMEs as a result
    pkg_online_client 'MAINTAINER:prefix:jlam@'
    pkg_online_client 'PKGPATH:suffix:/dictem'
    pkg_online_client 'PKGPATH:prefix:wip/p5-'
    pkg_online_client 'COMMENT:re:hash.*table'

    # multiple queries together (logical <AND>) and short names for
    # strats and fields
    pkg_online_find -1 '::dict'
    pkg_online_find    'n:s:dict' 'm:p:cheusov'
    pkg_online_find -9 'c:w:vpn'
    pkg_online_find    'c:r:dns.*server'
    pkg_online_find -3 'c:r:dns.*server' 'p:p:net'

    Here field 'c' means COMMENT, 'm' means MAINTAINER
    and 'p' means PKGPATH. Search strategy 'p' means 'prefix',
    '' means '.' (default search strategy, may be set individually per field
    on the server side),
    'r' means 're' (ERE regular expression) and 'w' means 'word'.
    Do forget that list of fields and search strategies with their short
    synonyms are shown by 'pkg_online_find -s' and 'pkg_online_find -f'

    For the list of synonyms look inside pkg_online_client.env.
    Of course it is allowed to combine full names and short synonyms.
    Synonyms are overridable, for this you can set a number of
    environment variables, see pkg_online_client.env

    As of pkg_online version 0.4.0 pkg_online_find and
    pkg_online_client utilities allow queries not only in
    field:strategy:query format. Now it also allows plain text query.
    In this case a number of tries will be made to guess what you
    actually want (kind of AI :-) ). For each FIELD:STRATEGY pair in
    environment variable PKG_ONLINE_FALLBACK_RULES search is run until
    something is found.  By default PKG_ONLINE_FALLBACK_RULES contains the
    following search rules:

         PKGNAME:exact
         PKGPATH:exact
         PKGNAME:substring
         COMMENT:word
         COMMENT:substring

    As you can see first two items are PKGNAME:exact and PKGPATH:exact.
    This is why example (***) above works.
    Samples of usage:

      pkg_online_find -1 dictem
      pkg_online_find -3 dict
      pkg_online_find -1 dictionary
      pkg_online_find    presentation

   You can override PKG_ONLINE_FALLBACK_RULES in your .profile.  Also
   note that the default value of this variable may change in the future.

   In order to see how powerful pkg_online's AI, try the following

      pkg_online_find dns server
      pkg_online_find dictionary server

Environment variables:

   PKG_ONLINE_SERVER () - dictionary server host name
   PKG_ONLINE_PORT ()   - dictionary server port
   PKG_ONLINE_CLIENT (pkg_online_client) - override it if you want to,
      also see pkg_digger(1) and variable PKG_DIGGER_BACKEND.
   PKG_ONLINE_DICT (dict) - path to dictionary protocol client.
   PKG_SUMMARY_TYPE (src) - "src" or "bin" for source or binary summary
      (output of 'wip/pkg_src_summary' or 'pkg_info -X')
   PKG_ONLINE_NETCAT (nc) - path to netcat program

Running the server:
XXX:
   export PKG_SUMMARY_TYPE=src # or bin depending on your summary type
   pkg_summary2all summary.txt
   mv *.index *.dict /path/to/dictd/databases/
   pkg_online_mkconf /path/to/dictd/databases > /path/to/dictd/config.conf
   finish configuring /path/to/dictd/config.conf
   run dictd

Basic concepts:
XXX:
   dictionary protocol server serves a number of
   databases (dictionaries). All these dictionaries are
   specially named, e.g. pkgsrc-src-index-COMMENT,
   pkgsrc-src-index-MAINTAINER and pkgsrc-src-info.
   pkgsrc-src-index-* are for indexing fields
      (field -> pkgname).
   pkgsrc-src-info keeps information about all packages
      (pkgname -> info).
   Dictionary server also provides a number of
   so called search strategies, e.g. exact, prefix, suffix etc.

   Look inside pkg_online_client to understand
   how dictionary protocol/server/client are used.

http://www.dict.org
http://sourceforge.net/projects/dict
RFC-2229

#################################################################
