9 HyperKWIC

9.1 Anatomy of a HyperKWIC Report

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 17 A HyperKWIC Report

Figure 17 shows a typical HyperKWIC report. It comprises 4 resizable panes, each with scroll bars where appropriate:

The top left pane contains the HyperKWIC logo, and some summary information, including the number of source code files that have been analysed, the total linces of code, the number of distinct keywords found (excluuding reserved words), and the total number of keyword occurrences.
The bottom left pane contains either an alphabetical list of source files, or an alphabetical list of keywords, and buttons to switch between the two lists. Clicking on a keyword causes a KWIC report to appear in the top right pane. Clicking on a file name causes a source listing to appear in the bottom right pane.
The top right pane shows a Keyword in Context report for a keyword. The left margin has the file name and line number for each keyword occurrence. Each occurrence of the current keyword is shown in red, and other keywords are shown as hypertext links. Clicking on keyword causes a new KWIC report to appear in the top right pane. Clicking on file name/line number causes a source listing to appear in the bottom right pane, if possible with the specified line number at the top of the pane.
The bottom right pane shows a listing of a source file, with keywords displayed as hypertext links. Clicking on a link causes a new KWIC report to appear in the top right pane.

You can interact with sample HyperKWIC reports for large Fortran and C programs by clicking here and here. HyperKWIC reports can be viewed on any system with a reasonably capable web browser, including tablets and smart-phones.

9.2 How Is It Used?

HyperKWIC was developed primarily for use as a documentation tool by software engineers and programmers, but may possibly be used in other fields. It is designed around the concepts of keywords, and plain text source files containing lines, and in which a line is often a meaningful unit.

For Project Managers and Team Leaders

Meet requirements for accurate and complete software documentation with the aid of HyperKWIC reports which are generated automatically and quickly.
Update as often as required, and publish to your team and to other stakeholders. HyperKWIC reports may be stored locally or published on an internal or external website.
Impact Analysis: Even small changes to an established code base can have consequences that propagate through the entire program. With HyperKWIC you can quickly assess possible changes and produce a plan to minimize coding effort.

For Programmers

Keep HyperKWIC software documentation open in your web browser for an instant answer to those constant questions:-
- where is that defined?
- which routine set that value?
- what else uses that?
- is that redundant?
HyperKWIC is aware of programming language syntax, including comments and reserved words. Syntax rules for several common languages are defined in an external file, which may be customized as required.
R-click to open a separate tab for reports you will need again later.

9.3 Running hyperkwic

The reports are created by a command line program (hyperkwic) which reads and analyses the source code, and writes the HTML files which comprise the report.

hyperkwic can be invoked from within PFFE, or from a command prompt by typing hyperkwic followed by a list of source and include files to be analysed. Wildcards are permitted.

Examples

      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.

Example

      hyperkwic @myprog.lst

9.4 Command Line Switches

The operation of hyperkwic may be modified by adding switches to the command line. These take the form name=val where name is the parameter name. Permissible parameter names are detailed below. val is a value to be assigned to the parameter. (e.g. TITLE=MyProg_Documentation)

Note that there must be no spaces in the value string, or on either side of the '='.

OPTION=NORESERVED	specifies that reserved words should not be excluded from the analysis. If this switch is not present *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).
OPTION=INCLUDECOMMENTS	specifies that *hyperkwic* should include comments in its analysis. If this switch is not present *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.
TITLE=	specifies a title to be used to identify the browser tab containing the report. The default is HyperKWIC Report.
HTML=	specifies the name of the HTML file to which the HyperKWIC report is written. The default file name is _hyperkwic.htm.
BASE_DIRECTORY=	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.

9.5 Language Syntax Configuration

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-blank 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.