runtime/khelpcenter/searchhandlers/README.searchhandlers

   1 KHelpcenter Search Handlers
   2 ===========================
   3
   4 Searching documents in KHelpcenter is handled by document-type-specific search
   5 handlers. Each searchable document provides provides a document type in its meta
   6 data and if a corresponding handler is found, it can be searched.
   7
   8 Search handlers are described by a desktop file which is put in the khelpcenter
   9 app directory in a "searchhandlers" directory. The desktop file contains the
  10 information about which document types the handler covers, how to do a search
  11 query and how to create a search index.
  12
  13 A search handler has to provide a command line tool based interface. There has
  14 to be a command to do a query and, if previous creation of an index is required,
  15 a command to create a search index. The search commands returns its results as
  16 HTML on stdout.
  17
  18
  19 Search Query
  20 ------------
  21
  22 KHelpcenter reads the command to execute for submitting a search query from the
  23 search handler's desktop file ("SearchCommand"). The search command can contain
  24 some symbols which are replaced by KHelpcenter with the data for the concrete
  25 search request:
  26
  27 %i  Identifier of document (usually the name of the document's desktop file)
  28 %w  Words to be searched for
  29 %o  Operation for combining multiple search words. Allowed values: "and" and
  30     "or".
  31 %m  Maximum number of results
  32 %d  Directory containing search indices
  33
  34 Search Query Result
  35 -------------------
  36
  37 The result has to be returned as HTML page. The content of the <body> tag will
  38 be extracted and inserted in the search results page. If there is no body tag,
  39 the complete result text will be inserted.
  40
  41
  42 Building a Search Index
  43 -----------------------
  44
  45 KHelpcenter reads the command to build a search index from the search handler's
  46 desktop file ("IndexCommand"). The indexing command can contain some symbols
  47 which are replaced by KHelpcenter with the data for the concrete index creation
  48 call:
  49
  50 %i  Identifier of document (usually the name of the document's desktop file)
  51 %d  Directory containing search indices
  52 %p  Path to document to be indexed
  53
  54 Index Creation Result
  55 ---------------------
  56
  57 As result of the indexing command an index is created in the directory specified
  58 by KHelpcenter. The format and structure of the index is handler-specific. When
  59 index creation is finished the indexing command has to create a special file
  60 with the name "<identifier>.exists", where <identifier> has to have the value
  61 passed by the %i symbol. This file indicates the existance of the index.