function post_install(pinfo);

% Function post_install(pinfo)
% 
% is called by pkg(), when the package is being installed.
% 
% The input argument pinfo is a struct provided by pkg(). It
% contains information on the packaged being installed, such
% as pinfo.name and pinfo.dir.
% 
% With the same input argument pinfo, function
% post_install() first calls internally:
%   post_install_extra(pinfo);
% The m-file for this function resides in the same location
% as post_install.m. Normally, post_install_extra() does
% nothing, but a sensible function could have been defined
% in the "post_install_extra" field of the package
% configuration file "..../mk-pkg-dir-<sname>.cfg" for the
% package generation by function mk_pkg().
% 
% Secondly, the function internally calls mk_pkg_doc(),
% which can be equivalently summarised as:
%   idir = [pkg("prefix") "/../../mk_pkg_doc/input/"];
%   odir = [pkg("prefix") "/../../mk_pkg_doc/html/"];
%   mk_pkg_doc(idir,odir);
% 
% See the help text of mk_pkg_doc.m for details how it
% works.
% 
% The function internally calls the following non-standard
% m-files:
% -- post_install_extra.m
% -- mk_pkg_doc.m
% 
% 
% (c) 2026 fabien van mook
% 
% 2026.08.20 release of this file within package "fvm-hgeo" under GNU GPLv3+

% 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 can read the GNU General Public License on
% <https://www.gnu.org/copyleft/gpl.html>.


try,

  printf("Post-install for package \"%s\":\n",pinfo.name);

  if 0,
    % experimenting:

    path

    pinfo

    % error with following: "package .... is not installed":
    %pkg("load",pinfo.name)

    % post_install.m is executed via:
    %   pkg at line 692 column 9
    %   install at line 242 column 7
    %   install>finish_installation at line 828 column 7
    % which states:
    %   function finish_installation (desc, packdir, global_install)
    %     ## Is there a post-install to call?
    %     if (exist (fullfile (packdir, "post_install.m"), "file"))
    %       wd = pwd ();
    %       try
    %         cd (packdir);
    %         post_install (desc);
    %         cd (wd);
    %       catch
    % ....
    % thus, we are now within the package directory:
    %
    printf("pwd is now: %s\n",pwd);
    printf("its contents:\n");
    dir
    printf("contents of its subdirectory src/:\n");
    cd src
    dir
    % help() succesfully returns text for a .cc file, when in src/
    try,
      s = help("rayintersect")
    catch,
      warning("Error at getting help text of rayintersect by post_install.m: \"%s\".",lasterror.message);
    end_try_catch;
    cd ..
    printf("contents of its subdirectory inst/:\n");
    cd inst
    dir
    % help() succesfully returns text for a .m file, when in inst/
    try,
      s = help("check_rayintersect")
      s = help("rayintersect")
    catch,
      warning("Error at getting help text of rayintersect by post_install.m: \"%s\".",lasterror.message);
    end_try_catch;
    cd ..

  endif;

  printf("Calling post_install_extra()...\n");
  post_install_extra(pinfo);
  printf("End of post_install_extra().\n");

  % installation prefix directory, e.g.
  % "~/.local/share/octave/api-v61/packages/":
  %
  prefix = pkg("prefix");

  if ( (length(prefix) > 0) && isfolder(prefix) ),
    % input directory for documentation within the unzipped
    % package:
    udir   = [pinfo.dir "/doc/mk_pkg_doc/"];
    upgcfg = [udir "general.cfg"];
    uppcfg = [udir "package-" pinfo.name ".cfg"];
    updir  = [udir pinfo.name "/"];

    % eventual input directory for documentation:
    idir = [prefix "/../../mk_pkg_doc/input/"];
    ipdir = [idir pinfo.name "/"];

    % remove existing ipdir:
    if isfolder(ipdir),
      printf("Removing temporary \"%s\"...\n",ipdir);
      confirm_recursive_rmdir(0,"local");
      rmdir(ipdir,"s");
    endif;

    if (~ isfolder(idir)),
      mkdir(idir);
    endif;

    printf("Copying input files for documenation...\n");
    copyfile({upgcfg,uppcfg,updir},idir,"f");

    printf("Calling mk_pkg_doc()...\n");
    % output directory for documentation:
    odir = [prefix "/../../mk_pkg_doc/html/"];
    mk_pkg_doc(idir,odir);
  else,
    error("installation prefix directory \"%s\" is not found",prefix);
  endif;

  printf("End of post-install for package \"%s\".\n",pinfo.name);
  printf("Please ignore warnings saying \"doc_cache_create: unusable help text found in file ...\".\n\n");

catch,
  warning("Error at running post_install.m for package \"%s\": \"%s\".",pinfo.name,lasterror.message);
end_try_catch;

% l = pkg("list")
% returns:
% ....
%
% [1,55] =
%
%     scalar structure containing the fields:
%
%       name = zeromq
%       version = 1.5.6
%       date = 2023-08-11
%       author = John Donoghue <john.donoghue@ieee.org>
%       maintainer = John Donoghue <john.donoghue@ieee.org>
%       title = ZeroMQ Toolbox
%       description = ZeroMQ bindings for GNU Octave
%       depends =
%       {
%         [1,1] =
%
%           scalar structure containing the fields:
%
%             package = octave
%             operator = >=
%             version = 4.0.0
%
%       }
%
%       autoload = no
%       license = GPLv3+
%       loaded = 0
%       dir = C:\Program Files\GNU Octave\Octave-10.3.0\mingw64\share\octave\packages\zeromq-1.5.6
%       archprefix = C:\Program Files\GNU Octave\Octave-10.3.0\mingw64\lib\octave\packages\zeromq-1.5.6
%
% }

% octave:52> l = pkg("list","fvm-textblock")
% l =
% {
%   [1,1] =
%
%     scalar structure containing the fields:
%
%       name = fvm-textblock
%       version = 2026.01.26
%       date = 2026.01.26
%       author = fabien van mook
%       maintainer = fabien van mook
%       title = fvm-textblock
%       description = fvm-textblock
%       categories = repmatfit textblockalign textblockbreak textblockcat textblockfit textblockframe textblockpad textblockprepend textblocksize
%       depends = {}(0x0)
%       dir = C:\Users\fmo\AppData\Roaming\octave\api-v60\packages\fvm-textblock-2026.01.26
%       archprefix = C:\Users\fmo\AppData\Roaming\octave\api-v60\packages\fvm-textblock-2026.01.26
%       loaded = 0
%
% }

endfunction;
