1 Introduction

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

annotated HyperKWIC screen shot

Figure 1 A HyperKWIC Report

Figure 1 shows a typical HyperKWIC report. It comprises 4 resizable panes, each with scroll bars where appropriate: 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.

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

For Programmers

2 Creating Reports

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. Versions of this program are available for Windows, Mac and Linux. Detailed instructions for configuring and using hyperkwic may be found is sections 2 and 3 of this manual.

2.1 Licensing

Non-commercial users may download and use this program free of charge. Government and commercial users may use it to evaluate HyperKWIC in their own environment. Government/Commercial licences are available at a modest cost from the online shop at www.fortran.uk.

2.2 Installation

The procedures used to install HyperKWIC are system dependent, and are described in a separate guide included with the installation kit.

2.3 Running hyperkwic

To run hyperkwic, simply open a command shell which includes the HyperKWIC installation directory on its PATH. Then navigate to a convenient directory, and enter 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

2.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 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).

OPTION=INCLUDECOMMENTS

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.

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.

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