UCM version v5_1

Web access to Source Repositories

Author: Peter Kasper

Contents:
UVMHTML: The command used to create the web pages.
Using the pages: What they contain an how they work.
Hyperlinking: How to add hyperlinks to source files.
See the Table of Contents for more information.

The World Wide Web provides a convenient method for access to computerized information. In order to exploit this medium, UCM provides a script which produces a set of CGI scripts that enable web access to information about UVM or CVS source repositories and the contents of RCS elements within them.

UCM version v5_1

UVMHTML: Creating the pages

The command to create the web pages is:-

uvmhtml input_directory output_directory [-t "html title"]

The input_directory specifies the location of the libraries to be documented. All libraries found in the directory tree indicated by this parameter will be documented. The output_directory indicates where the web pages will be created. The top level page is invoked by simply referencing the cgi-bin script UVMroot. (The name of this script can be changed to whatever the user deems appropriate but it cannot be moved to another directory.)

The html text "html title" will replace the default title of the top level page. The default title will look like:-

UVM libraries

A list of the UVM libraries contained in:-
input_directory
 or (if the input directory is a CVS repository):-

CVS Modules

A list of the CVS Modules contained in:-
input_directory

All of the files placed in the output directory are cgi_bin scripts which create the pages and execute a variety of UVMI and/or RCS commands. The uvmhtml command determines the paths to these commands and imbeds them into these scripts. Thus in order for the scripts to work correctly the command should be run on the same machine that the web-server runs on. However, when the script runs it will give the user an opportunuity to change the input and output directory specifications and also the UVMI and RCS path names.

UVMHTML creates the following files in the output directory:-

UCM version v5_1

Using the Pages

The Library Contents Page

The links from the root page invoke a separate html page for each library. These pages contain two forms. The first is used to invoke commands which display information about the entire library and appears as shown below.
Option:
Clicking on one the "submit" buttons invokes the corresponding command and converts the output into a web page. Each command can be modified by providing an appropriate option value in the space provided.

The second form on the page is shown below and is followed by lists of links to sub-libraries and library elements.

default revision tag:-
Clicking an element link will produce a page containing the contents of the element revision specified in the text box. These links can be modified to display a different revision by typing the desired revision specification into the text box and clicking the "Change" button. The revision can be specified with a symbolic tag name, a date/time, or an explicit revision number.

The Element Contents Page

This page displays the contents of a specific revision of an element. The script which produces this information also searches for special hyperlinking commands which can be used to insert links into the element contents. These commands can either be imbedded directly into the element or added in real time when its contents are piped through the UVMuser script.

This page also provides a form (shown below) which can invoke commands to display information about the element.

Option:
Clicking on one the four submit buttons invokes the corresponding "uvm show" command and converts the output into a web page. Each command can be modified by providing an appropriate "Option" value in the space provided.

UCM version v5_1

Creating Hyperlinks

UVMHTML provides the user with a simple mechanism for cross-referencing source code with hyperlinks. This is done by inserting a "hyperlink command line" before each line in the element which is to contain the link. This can be done either by changing the element itself or by using UVMuser script to add them at the time the element is displayed.

Hyperlink Commands

A "hyperlink command line has the form :- 
[text] uvm F='value' [F='value' ...] [text]
where the argument flags, F, can be any of S, U, N, L, E, or A.

The optional text preceeding and following the hyperlink command is used to turn the line into a compiler "comment" line when the commands are imbedded into source code.

Three different hyperlink commands are recognized:-

Note that links to other elements use the default revision specification in the last "Library Content Page".

Using UVMuser to add Hyperlinks

UVMHTML creates a user modifiable script, UVMuser, which can be used to imbed hyperlink commands into an element without actually changing it.

The default version of UVMuser (shown below) is a PERL script which reads a link-map file called "map" and uses it to construct hyperlinking commands. The "map" file is assumed to reside in the same directory as the scripts and contains two lines per "link map". The first line contains a regular expression used to identify lines in the element to which the hyperlink command will be attached. The second line contains the arguments for the hyperlink command. 

#!/usr/local/bin/perl
# Open and read a link map file if it exists
# The link map contains two lines per entry ..
#   1) A PERL regular expression which identifies lines to which will be
#      preceded by a hyperlink command
#   2) The argument list to be used in the hyperlink command
if( open( MAP, "map" ) ) {
  while( $str = <MAP> ) {
    chop( $str );
    $args = <MAP>
    $map{$str} = $args;
  }
  close(MAP);
}
# Loop over the element lines
while( $line = <> ) {
  $add = "";			# reset the hyperlink command line
# Loop over the link map entries
  while( ($str,$args) = each(%map) ) {
    if( $line =~ /$str/ ) {		# Check if line requres a hyperlink
      $add = "UVM $args";		# Create hyperlink command
    }
  }
  $line =~ s/&/&amp;/g;	# Translate & to corresponding html code
  $line =~ s/</&lt;/g;	#           <
  $line =~ s/</&gt;/g;	#           >
  if( $add ) { print $add; }	# Print the hyperlink command
  print $line;			# Print the element line
}