HyperKWIC is a tool for generating software documentation that combines the instant connectivity of hypertext with the analytical strengths of KeyWord In Context. It produces HTML documents that provide a fully interactive alternative to traditional documentation.
Figure 1 A HyperKWIC Report
hyperkwic *.c *.h
hyperkwic *.f90 lib\*.f90 include\*.inc
This will create a small HTML file called _hyperkwic.htm and a directory called _kwic containing further data required for the report. The report may be viewed by opening _hyperkwic.htm in a web browser. You may copy or move _hyperkwic.htm and _kwic to a different location, providing that they remain together.
The list of files may also be specified in a plain text list file, with one file name per line. The name of the list file must follow an '@' character on the command line.
Note that there must be no spaces in the value string, or on either side of the '='.
specifies that reserved words should not be excluded from the analysis. If this switch is not presenet hyperkwic uses the file extension to determine what language is in use, and reads a list of reserved words for that language from the configuration file KWIC_reserved.txt (see section 3).
specifies that hyperkwic should include comments in its analysis. If this switch is not presenet hyperkwic uses the file extension to determine what language is in use, and excludes sections which are comments in that language. The rules for identifying comments are read from the configuration file KWIC_reserved.txt (see section 3).
If both NORESERVED and INCLUDECOMMENTS are required, the form OPTION=NORESERVED_INCLUDECOMMENTS should be used.
specifies a title to be used to identify the browser tab containing the report. The default is HyperKWIC Report.
specifies the name of the HTML file to which the HyperKWIC report is written. The default file name is _hyperkwic.htm.
specifies the name of the directory which, if it does not exist, will be created by hyperkwic, and which will contain other files and directries required for the HyperKWIC report. The default is _kwic.
When the hyperkwic is started, it reads a plain text file called KWIC_reserved.txt in the installation directory. This file contains some details of the syntax of the computer languages that hyperkwic recognises, and it may be modified by the user to allow new languages to be processed, or to correct or extend the existing settings. An example of a section in KWIC_reserved.txt which specifies reserved words and some other details of the C language is shown below:
#======================================================================================================================= Language: C Extensions: .c .h EOLComment: // InLineComment: /*comment*/ CaseSensitive: Yes CPreProcessor: Yes EscapeCharacter: \ Reserved: also auto break case char const continue default do double else entry enum extern float for goto Reserved: if int long register return short signed sizeof static struct switch typedef union unsigned void Reserved: volatile while Reserved: fopen freopen fflush fclose remove rename tmpfile tmpnam setvbuf setbuf Reserved: fprintf printf sprintf vprintf vfprintf vsprintf Reserved: fscanf scanf sscanf fgetc fgets fputc fputs getc getchar gets putc putchar puts ungetc Reserved: size_t fread fwrite fseek ftell rewind fgetpos fsetpos Reserved: clearerr feof ferror perror Reserved: isalnum isalpha iscntrl isdigit isgraph islower isprint ispunct isspace isupper isxdigit tolower toupper Reserved: strcopy strncopy strcat strncat strcmp strncmp strchr strrchr strspn strcspn strpbrk strstr strlen strerror strtok Reserved: memcpy memmove memcmp memchr memset Reserved: sin cos tan asin acos atan atan2 sinh cosh tanh exp log pow sqrt ceil floor fabs ldexp frexp modf fmod Reserved: atof atoi atol strtod strtol strtoul rand srand calloc malloc realloc free abort exit atexit system getenv bsearch qsort abs labs div ldiv Reserved: assert va_list va_start va_arg va_end setjmp longjmp Reserved: signal raise clock time difftime mktime asctime ctime gmtime localtime strftime Reserved: __LINE__ __FILE__ __DATE__ __TIME__ __STDC__ #======================================================================================================================= Language: Pascal ..
KWIC_reserved.txt smay contain blank lines, comment lines with '#' as the first non-blsnk character, and keyword lines, which begin with one of the keywords shown in the table below, followed by a colon, followed by one or more space-delimited values. Usage examples may be found in the section quoted above.
|Language||The name of the language to be specified in the following section. A Language section is terminated by another Language keyword, or the end of the file.|
|Extensions||The space delimted list of file name extensions (with a leading ".") which hyperkwic will use to associate a file with a language specification.|
|EOLComment||A space delimited list of character strings, any of which, in the current language, specifies that the remainder the current line is a comment. An end of ilne comment is not initiated by characters within a quoted string. hyperkwic ignores comments unless OPTION=INCLUDECOMMENTS is specified on the command line.|
|InlineComment||A space delimited list of character strings, each of which defines a method, in the current language, for specifying inline comments, possibly spanning multiple lines of source code. Each character string should contain the charcacters which specify the start of an inline comment, followed by the word "comment", followed by the charcacters used to terminate the comment. An inilne comment is not initiated or teminated by characters within a quoted string. hyperkwic ignores comments unless OPTION=INCLUDECOMMENTS is specified on the command line.|
|CaseSensitive||The value Yes should be specified for languages in which keywords are case sensitive. By default, keywords are assumed not to be case sensitive.|
|CPreProcessor||The value Yes should be specified if the code may contain C Preprocessor directives such as #define and #include. By default, it is assumed that CPP is not active.|
|EscapeCharacrer||A single character such as "\" that is used as an escape character in quoted strings.|
|Reserved||A space delimited list of reserved words. There may be many lines of reserved words, each beginning with Reserved:. hyperkwic ignores reserved words unless OPTION=NORESERVED is specified on the command line.|
|FortranFixedForm||Should have the value Yes for Fortran fixed form source code. When set, hyperkwic recognises, lines with "C" or "*" in column 1 as an comments. This option is inactive by default.|