## Copyright (C) 2008 Soren Hauberg
##
## This program is free software; you can redistribute it and/or modify it
## under the terms of the GNU General Public License as published by
## the Free Software Foundation; either version 3 of the License, or (at
## your option) any later version.
##
## This program is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
## General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with this program; see the file COPYING.  If not, see
## <http://www.gnu.org/licenses/>.

## -*- texinfo -*-
## @deftypefn {Function File} gen_doc_cache (@var{directory})
## Generate documentation caches for all functions in a specific directory.
##
## A documentation cache is generated for all functions in @var{directory}. The
## resulting cache is saved in the file @code{help_cache.mat} in @var{directory}.
## The cache is used to speed up @code{lookfor}.
##
## @seealso{gen_all_caches_in_path, lookfor}
## @end deftypefn

function gen_doc_cache (directory)
  ## Get list of functions in directory
  list = list_functions (directory);
  cache = {};
  
  ## For each function:
  for n = 1:length (list)
    f = list{n}.name;
    ## Get help text
    [text, format] = get_help_text (f);
    
    ## Take action depending on help text format
    switch (lower (format))
      case "plain text"
        status = 0;
      case "texinfo"
        [text, status] = makeinfo (text, "plaintext");
      otherwise
        status = 1;
    endswitch
    
    ## Did we get the help text?
    if (status != 0 || isempty (text))
      warning("gen_doc_cache: unusable help text in '%s'. Ignoring function.", f);
      continue;
    endif
    
    ## Get first sentence of help text
    first_sentence = get_first_help_sentence (f);
    
    ## Store the help text
    cache (1, end+1) = f;
    cache (2, end) = text;
    cache (3, end) = first_sentence;
  endfor
  
  ## Write the cache
  fn = fullfile(directory, "help_cache.mat");
  save ("-binary", fn, "cache"); # XXX: Should we zip it ?
endfunction