home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Interactive Guide / c-cplusplus-interactive-guide.iso / c_ref / csource5 / 334_01 / help.c < prev    next >
Text File  |  1991-02-06  |  16KB  |  599 lines
  1. #include <stdio.h>
  2.  
  3. extern int errno;
  4.  
  5. extern int strcmp();
  6. extern int strlen();
  7. extern char *strcpy();
  8. extern char *strncpy();
  9. extern char *strcat();
  10. extern char *strncat();
  11. extern char *getenv();
  12. extern FILE *fopen();
  13. extern char *malloc();
  14.  
  15. extern int instring();
  16.  
  17. #define    SAME    0    /* for strcmp() */
  18.  
  19. #include "help.h"    /* values passed back */
  20.  
  21. /* help -- help subsystem that understands defined keywords
  22. **
  23. ** Looks for the desired keyword in the help file at runtime, so you
  24. ** can give extra help or supply local customizations by merely editing
  25. ** the help file.
  26. **
  27. ** The original (single-file) idea and algorithm is by John D. Johnson,
  28. ** Hewlett-Packard Company.  Thanx and a tip of the Hatlo hat!
  29. **
  30. ** Much extension by David Kotz for use in gnutex, and then in gnuplot.
  31. ** Added output paging support, both unix and builtin. Rewrote completely
  32. ** to read helpfile into memory, avoiding reread of help file. 12/89.
  33. **
  34. ** The help file looks like this (the question marks are really in column 1):
  35. **
  36. **     ?topic
  37. **     This line is printed when the user wants help on "topic".
  38. **     ?keyword
  39. **     ?Keyword
  40. **     ?KEYWORD
  41. **     These lines will be printed on the screen if the user wanted
  42. **     help on "keyword", "Keyword", or "KEYWORD".  No casefolding is
  43. **    done on the keywords.
  44. **     ?subject
  45. **     ?alias
  46. **     This line is printed for help on "subject" and "alias".
  47. **     ?
  48. **    ??
  49. **     Since there is a null keyword for this line, this section
  50. **     is printed when the user wants general help (when a help
  51. **     keyword isn't given).  A command summary is usually here.
  52. **    Notice that the null keyword is equivalent to a "?" keyword
  53. **    here, because of the '?' and '??' topic lines above.
  54. **   If multiple keywords are given, the first is considered the 
  55. **   'primary' keyword. This affects a listing of available topics.
  56. **     ?last-subject
  57. **     Note that help sections are terminated by the start of the next
  58. **     '?' entry or by EOF.  So you can't have a leading '?' on a line
  59. **     of any help section.  You can re-define the magic character to
  60. **    recognize in column 1, though, if '?' is too useful.  (Try ^A.)
  61. */
  62.  
  63. #define    KEYFLAG    '?'    /* leading char in help file topic lines */
  64.  
  65. /*
  66. ** Calling sequence:
  67. **    int result;        # 0 == success
  68. **    char *keyword;        # topic to give help on
  69. **    char *pathname;        # path of help file
  70. **    result = help(keyword, pathname);
  71. ** Sample:
  72. **    cmd = "search\n";
  73. **    helpfile = "/usr/local/lib/program/program.help";
  74. **    if (help(cmd, helpfile) != H_FOUND)
  75. **        printf("Sorry, no help for %s", cmd);
  76. **
  77. **
  78. ** Speed this up by replacing the stdio calls with open/close/read/write.
  79. */
  80. #ifdef    WDLEN
  81. #  define    PATHSIZE    WDLEN
  82. #else
  83. #  define    PATHSIZE    BUFSIZ
  84. #endif
  85.  
  86. typedef int boolean;
  87. #ifndef TRUE
  88. #define TRUE (1)
  89. #define FALSE (0)
  90. #endif
  91.  
  92. typedef struct line_s LINEBUF;
  93. struct line_s {
  94.     char *line;            /* the text of this line */
  95.     LINEBUF *next;            /* the next line */
  96. };
  97.  
  98. typedef struct linkey_s LINKEY;
  99. struct linkey_s {
  100.     char *key;                /* the name of this key */
  101.     LINEBUF *text;            /* the text for this key */
  102.     boolean primary;        /* TRUE -> is a primary name for a text block */
  103.     LINKEY *next;            /* the next key in linked list */
  104. };
  105.  
  106. typedef struct key_s KEY;
  107. struct key_s {
  108.     char *key;                /* the name of this key */
  109.     LINEBUF *text;            /* the text for this key */
  110.     boolean primary;        /* TRUE -> is a primary name for a text block */
  111. };
  112. static LINKEY *keylist;        /* linked list of keys */
  113. static KEY *keys = NULL;        /* array of keys */
  114. static int keycount = 0;        /* number of keys */
  115.  
  116. static int LoadHelp();
  117. static void sortkeys();
  118. static int keycomp();
  119. static LINEBUF *storeline();
  120. static void storekey();
  121. static KEY *FindHelp();
  122. static boolean Ambiguous();
  123.  
  124. /* Help output */
  125. static void PrintHelp();
  126. static void ShowSubtopics();
  127. static void StartOutput();
  128. static void OutLine();
  129. static void EndOutput();
  130. static FILE *outfile;        /* for unix pager, if any */
  131. static int pagelines;        /* count for builtin pager */
  132. #define SCREENSIZE 24        /* lines on screen (most have at least 24) */
  133.  
  134. /* help:
  135.  * print a help message 
  136.  * also print available subtopics, if subtopics is TRUE
  137.  */
  138. help(keyword, path, subtopics)
  139.     char *keyword;            /* on this topic */
  140.     char *path;            /* from this file */
  141.     boolean *subtopics;        /* (in) - subtopics only? */
  142.                         /* (out) - are there subtopics? */
  143. {
  144.     static char oldpath[PATHSIZE] = "";    /* previous help file */
  145.     char *oldpathp = oldpath;    /* pointer to same */
  146.     int status;            /* result of LoadHelp */
  147.     KEY *key;                /* key that matches keyword */
  148.  
  149.     /*
  150.     ** Load the help file if necessary (say, first time we enter this routine,
  151.     ** or if the help file changes from the last time we were called).
  152.     ** Also may occur if in-memory copy was freed. 
  153.     ** Calling routine may access errno to determine cause of H_ERROR.
  154.     */
  155.     errno = 0;
  156.     if (strncmp(oldpathp, path, sizeof oldpath) != SAME)
  157.      FreeHelp();
  158.     if (keys == NULL) {
  159.        status = LoadHelp(path);
  160.        if (status == H_ERROR)
  161.         return(status);
  162.  
  163.        /* save the new path in oldpath */
  164.        if (strlen(path) < sizeof oldpath)
  165.         (void) strcpy(oldpathp, path);
  166.        else {                /* not enough room in oldpath, sigh */
  167.           (void) strncpy(oldpathp, path, sizeof oldpath);
  168.           oldpath[sizeof oldpath] = NULL;
  169.        }
  170.     }
  171.  
  172.     /* look for the keyword in the help file */
  173.     key = FindHelp(keyword);
  174.     if (key != NULL) {
  175.        /* found the keyword: print help and return */
  176.        PrintHelp(key, subtopics);
  177.        status = H_FOUND;
  178.     } else {
  179.        status = H_NOTFOUND;
  180.     }
  181.  
  182.     return(status);
  183. }
  184.  
  185. /* we only read the file once, into memory */
  186. static int
  187. LoadHelp(path)
  188.     char *path;
  189. {
  190.     FILE *helpfp = NULL;
  191.     char buf[BUFSIZ];        /* line from help file */
  192.     LINEBUF *head;            /* head of text list  */
  193.     boolean primary;        /* first ? line of a set is primary */
  194.  
  195.     if ((helpfp = fopen(path, "r")) == NULL) {
  196.        /* can't open help file, so error exit */
  197.        return (H_ERROR);
  198.     }
  199.     
  200.     /*
  201.     ** The help file is open.  Look in there for the keyword.
  202.     */
  203.     (void) fgets(buf, sizeof buf, helpfp);
  204.     while (!feof(helpfp)) {
  205.        /*
  206.         ** Make an entry for each synonym keyword, pointing
  207.         ** to same buffer. 
  208.         */
  209.        head = storeline( (char *)NULL ); /* make a dummy text entry */
  210.        primary = TRUE;
  211.        while (buf[0] == KEYFLAG) {
  212.           storekey(buf+1, head, primary);    /* store this key */
  213.           primary = FALSE;
  214.           if (fgets(buf, sizeof buf, helpfp) == (char *)NULL)
  215.             break;
  216.        }
  217.        /*
  218.         ** Now store the text for this entry.
  219.         ** buf already contains the first line of text.
  220.         */
  221.        while (buf[0] != KEYFLAG) {
  222.           /* save text line */
  223.           head->next = storeline(buf);
  224.           head = head->next;
  225.           if (fgets(buf, sizeof buf, helpfp) == (char *)NULL)
  226.             break;
  227.        }
  228.     }
  229.  
  230.     (void) fclose(helpfp);
  231.  
  232.     /* we sort the keys so we can use binary search later */
  233.     sortkeys();
  234.     return(H_FOUND); /* ok */
  235. }
  236.  
  237. /* make a new line buffer and save this string there */
  238. static LINEBUF *
  239. storeline(text)
  240.     char *text;
  241. {
  242.     LINEBUF *new;
  243.  
  244.     new = (LINEBUF *)malloc(sizeof(LINEBUF));
  245.     if (new == NULL)
  246.      int_error("not enough memory to store help file", -1);
  247.     if (text != NULL) {
  248.        new->line = (char *) malloc((unsigned int)(strlen(text)+1));
  249.        if (new->line == NULL)
  250.         int_error("not enough memory to store help file", -1);
  251.        (void) strcpy(new->line, text);
  252.     } else
  253.      new->line = NULL;
  254.  
  255.     new->next = NULL;
  256.  
  257.     return(new);
  258. }
  259.  
  260. /* Add this keyword to the keys list, with the given text */
  261. static void
  262. storekey(key, buffer, primary)
  263.     char *key;
  264.     LINEBUF *buffer;
  265.     boolean primary;
  266. {
  267.     LINKEY *new;
  268.  
  269.     key[strlen(key)-1] = '\0'; /* cut off \n  */
  270.     
  271.     new = (LINKEY *)malloc(sizeof(LINKEY));
  272.     if (new == NULL)
  273.      int_error("not enough memory to store help file", -1);
  274.     new->key = (char *) malloc((unsigned int)(strlen(key)+1));
  275.     if (new->key == NULL)
  276.      int_error("not enough memory to store help file", -1);
  277.     (void) strcpy(new->key, key);
  278.