view release on metacpan or  search on metacpan

acelib/helpsubs.c  view on Meta::CPAN

/************************************************************/
/* return the current helpDirectory or 
   initialise if not previously set */
UTIL_FUNC_DEF char *helpGetDir (void)
{
  if (!*helpDir)
    return (helpSetDir(0)) ;

  return (char*)&helpDir[0];
} /* helpGetDir */



/************************************************************/
/* pop up help on the given subject, depending on the registered
   display function, that will be textual, in the built-in
   simple HTML browser or even launch an external browser
   to display the help document */
/************************************************************/
UTIL_FUNC_DEF BOOL helpOn (char *subject)
{
  char *helpFilename;

  if (!helpGetDir() || !filName(helpGetDir(), "", "rd"))
    {
      messout ("Sorry, No help available ! "
	       "Could not open the HTML help directory "
	       "%s\n"
	       "(%s)",
	       helpGetDir(),
	       messSysErrorText());
      
      return FALSE;
    }
  
  helpFilename = helpSubjectGetFilename(subject);
  /* may be NULL if file could not be found,
     the registered helpOnRoutine has to cope
     with this case and may decide to display an 
     index instead */
  
  if (helpOnRoutine)
    return ((*helpOnRoutine)(helpFilename));


  return (helpPrint (helpFilename)); /* textual help as default */
} /* helpOn */
/************************************************************/


UTIL_FUNC_DEF char *helpSubjectGetFilename (char *subject)
/* this function attempts to find the file name corresponding
   to a particular help-subject.
   It will attempt to find a matching file according to
   the current settings of helpDir and HELP_FILE_EXTENSION.
   
   the subject '?' will just return ? again. This is a special
   code within the help system to tell the help display
   function that the user required some kind of help.
   Usually the helpOnRegister'd function would display a
   dynamically created index of the help-directory.

   this function can be even cleverer by doing keyword searches
   on <TITLE> and <H1> strings in files that might be relevant
   of no obvious match is found.
*/
{
  static char filename_array[MAXPATHLEN] = "";
  char *filename = &filename_array[0];
  char *subject_copy;
  Array dirList;

  if (subject == NULL) 
    return NULL;

  if (strlen(subject) == 0) 
    return NULL;

  if (strcmp(subject, "?") == 0)
    {
      /* return ? to signal that the calling 
	 function needs to display a dynamically
	 created index or show some kind of help. 
       */
      /* if the construct
	 page = htmlPageCreate(helpGetFilename(subject_requested));
	 is used, the resulting page will therefor be a marked up
	 directory listing of helpsubjects
       */
      strcpy (filename, "?");
      return filename;
    }

  subject_copy = strnew (subject, 0);

  strcpy (filename, "");	/* intialise, if this is
				   non-empty at the end of the loop,
				   we found a matching helpfile */
  while (TRUE)
    {
      /* simple attempt to locate file - path/helpDir/subject.html */
      sprintf(filename, "%s%s%s.%s", 
	      filGetFullPath(helpGetDir()),
	      SUBDIR_DELIMITER_STR,
	      subject_copy, HELP_FILE_EXTENSION);

      if (filName(filename, 0, "r"))
	break;

      /* advanced attempt, try to find a matching file from
	 the list of available ones by scanning the directory
	 contents of the helpdirectory */
      if ((dirList = filDirectoryCreate
	   (helpGetDir(), HELP_FILE_EXTENSION, "r")) )
	{
	  int i;
	  int matches;
	  char *s;