Web Based Source Code Editor
Software Requirements Document
Developed by
The Mean Green Code Team
Table of Contents
Table of Contents ...............................................................................................................1
Introduction........................................................................................................................2
System Requirements ........................................................................................................3
Software Requirements .....................................................................................................4
I.
II.
III.
IV.
V.
VI.
VII.
Some things that will appear on all pages....................................................4
Starting the Application ...............................................................................4
File Selection Screen....................................................................................5
Module Action page.....................................................................................6
Editor............................................................................................................8
File Specifications for header and implementation files............................12
INI Control files.........................................................................................14
Glossary ............................................................................................................................16
1
Introduction
The Web Based Source Code Editor (WBSCE) is an application that takes standard C or
C++ files that meet certain criteria and provides an environment in which the user can
edit the code and the documentation.
The editor will provide information on the routines within the files, such as:
ƒ The date of the last update
ƒ The number of lines of code
ƒ The number of lines of documentation
The editor will provide several different views of the code, including:
ƒ A source code only view
ƒ A documentation only view
ƒ A source code and documentation view
ƒ A line numbered code only view
The WBSCE can be accessed by anyone with a personal computer connected to the
Internet.
2
System Requirements
This section includes the System Requirements for the Web Based Source Code Editor.
In order for the application to work properly the following requirements will need to be
met:
I.
User Requirements. The minimum system requirements for the user are the
following:
ƒ
ƒ
ƒ
ƒ
II.
Personal Computer: Pentium 100 MHz+ or equivalent.
Modem or Network Card
Internet Access
Internet Browser: Netscape 4.0 or higher or Internet Explorer 5.0 or higher.
Server Requirements. The minimum requirements for the server are the following:
ƒ
ƒ
Web Server able to execute scripts: PHP, ASP, PERL, CGI.
Permission to read and write files within a directory.
3
Software Requirements
This section includes the WBSCE Project software requirements and specifications as
stated by the user. The following section describes the various interfaces, application
behavior, and file specifications. Also included is a description of the INI control files,
which the user can use to manipulate the look and feel of the application.
I.
Some things will appear on all pages, excluding error pages, these are:
A.
B.
C.
D.
II.
A Copyright notice for the application.
A Project name if specified in the Project Control INI file.
The full path to the selected file.
The date of the most recent modification of the file or module.
Starting the Application: to access the Web Based Source Code Editor,
A. The user types the URL in the address bar of the browser. Below are the three
ways to start the application:
1. The application URL is entered into a browser; the Startup page is opened
with a list of all modules in the default directory.
e.g. http://students.csci.unt.edu/~bob/editor.cgi
2. The application URL is entered into a browser followed by a “?” and then
the desired directory name; the Startup page is opened with a list of all
modules in the specified directory.
e.g. http://students.csci.unt.edu/~bob/editor.cgi?/usr/bob/project
3. The application URL is entered into a browser followed by a “?” and then
the path of an existing c/c++ implementation or header file:
a. If the specified file is an implementation file it is opened in the Module
Action Page.
e.g. http://students.csci.unt.edu/~bob/editor.cgi?/usr/bob/filename.cc
b. If the specified file is a header file it is opened in the editor screen.
e.g. http://students.csci.unt.edu/~bob/editor.cgi?/usr/bob/filename.h
B. Possible errors:
1. If the directory or filename specified is invalid the default directory is
shown.
4
III. File selection screen: This is the default view for the WBSCE application.
A. Actions
1. Lists available C/C++ files available in the project directory for editing.
2. Allows user to click on a filename:
a. If the file is a header file, a new window opens with the file in the editor
window.
b. If the file is an implemenation file the user is taken to the module action
page (see section IV).
3. Allows user to add a new source file to the current directory.
B. Possible errors
1. Trying to create a file that already exists will result in an error message.
2. Trying to create a file that does not have a valid C/C++ extension will result
in an error message.
Note: See File Specification Page (Section VI) for a list of valid C/C++ extensions
Figure 1: Mock up of File Selection Screen
5
IV. Module Action Page
A. Routine List
1. Lists all the routines available for editing within a specific C/C++
implementation file.
2. Displays the total number of source code lines within a routine.
3. Displays the total number of lines of documentation for a specific routine.
4. Displays the date the routine was last edited.
5. Allows user to click on a routine name to open it for editing.
B. Editing the Introduction to a file
1. Displays the introduction to the file.
2. Displays the date of the last modification of the introduction.
3. Allows the user to edit and save the introduction.
C. Adding, deleting, and rearranging Routines
1. Allows the user to add a routine. To add a routine:
a. Type in the name of the new routine.
b. Select the routine before which to insert the new routine.
c. Click on the “Add Routine” button to add the new routine.
d. The page is reloaded.
2. Allows the user to delete a routine. To delete a routine:
a. Select (a) routine(s) in the Routine List.
b. Click on the “Delete Routine” button to delete the routine(s).
c. The page is reloaded.
3. Allows the user to reorder the routines within the source file.
a. Rearrange the routines as they appear in the text box.
b. Click “Rearrange Routines”.
c. The page is reloaded.
D. Possible errors
1. Trying to create a routine whose name already exists will result in an error
message.
2. When creating a new routine, if no routine is selected the new routine is
added at the end of the list.
3. Creating a routine when no name is specified will result in the new routine
being named “New Routine”.
4. Trying to delete a routine when none has been selected will result in an error
message.
6
Figure 2: Mock up of Module Action Page
7
V.
Editor Screen
A. Editing a Header File
1. Only one view is available when editing a header file. This view displays
source code and comments.
2. Allows the user to save changes to the header file by clicking the “Save”
button.
B. Editing an Implementation File
1. The user can choose between four display modes. Three buttons will be
available that change the view mode (the current view will not be available
as a button).
a. Documentation only: This displays the routine comments only
b. Code only: This only displays the source code in the routine.
c. Code and Documentation: This will be a window that is broken into 2
text boxes that will have documentation in one text box, and the source
code in the other text box.
d. Display line numbers (opens in a new window): This is a read-only
view displaying the routine code preceded by a line number. The view
cannot be changed from this window.
2. The editor will remember the last view mode of a routine and will default to
that view the next time the routine is opened.
3. Saving
a. Changes can be saved by clicking the “Save” button.
b. Changes are automatically saved when changing view modes.
C. There are no possible error messages for this screen.
Note: The special characters used by the editor to parse the file should not be
displayed (see section VI).
8
Figure 3: Mock up of Editor Screen in Code only mode:
9
Figure 4: Mock up of Editor screen in Code and Documentation Screen:
10
Figure 5: Mock up of Source code with line numbers screen:
11
VI. File specifications for header and implementation files
A. Header files require no special formatting.
B. Formatting implementation files for the editor:
1. File introduction
a. The file introduction is anything at the beginning of the file before the
first routine marker, “/*!”.
b. Lines proceeded by a “//!” will not be displayed as part of the
introduction.
2. Routines
a. The beginning of a routine is noted by a “/*!”.
b. The routine name must be specified on the first line after the “/*!”
marker and must be proceeded by “**”.
c. The last date updated information can be specified on the second line
after the “/*!” marker and must be preceded by “** ”. (optional)
d. The preferred editor view mode can be specified on the third line after
the “/*!” marker and must be preceded by “** View: ”. (optional)
(see section VII.E.10)
e. The routine comments are in-between the “/*!” and “!*/”, and must be
preceded by “* ”.
f. The source code is anything after the “!*/” marker.
C. Valid File Extensions are:
1.
2.
3.
4.
filename.c
filename.cpp
filename.cc
filename.h
D. Possible Errors:
1. The editor will not properly parse implementation files that do not meet the
specifications listed.
12
Listing 1: Example C++ file
//! File maintained by Web-based Source Editor
//!
version Unix v1.0 (Jan 10 2001 00:09:14)
//! copyright (c) 2001 Donald Alan Retzlaff
donr@unt.edu
//! Date Updated: Sun Jan 14 00:56:05 2001
#include
#include
#include
#include
<stdio.h>
<stdlib.h>
<string.h>
<fstream.h>
#include "ini.h"
/*! ///////////////////////////////////////////////////
** INI :: freeSectionLines
** Date Updated: Sun Jan 14 00:41:59 2001
** View: B
*
* freeSectionLines() is designed to allow the user to easily free
* the dynamically-allocated space associated with a section array.
*
* INPUT: a pointer to previous section array
* RETURN: nothing
*
!*/
#line 1
void INI :: freeSectionLines (char **section)
{
if (section != NULL) while (*section) free (*section++);
} // INI :: freeSectionLines
/*! ///////////////////////////////////////////////////
** INI :: freeSection
** Date Updated: Sun Jan 14 00:43:41 2001
** View: B
*
* freeSection() is designed to easily free-up the
* space associated with a section array. This function not only
* deletes each individual line with the section, it deletes the
* pointer to the line strings.
!*/
#line 1
void INI :: freeSection (char **section)
{
if (section == NULL) return;
freeSectionLines (section);
free (section);
} // INI :: freeSection
13
VII. INI control files
A. INI control files are used to specify the look and feel of the editor
B. Default INI control file
1. The default INI control file must be placed in the same directory as the
editor application.
2. All default keyword values are to be declared in the default INI control file.
C. Project-specific INI control file (optional)
1. A project-specific INI control file can be placed in the same directory as the
project source files.
2. All keywords in the project INI override the keywords in the default INI
when editing a file in the project INI’s directory.
D. The INI files must be edited in a plain ASCII editor, using the following
guidelines:
1.
2.
3.
4.
5.
6.
7.
Keywords should be in the form of keyword=value.
Keywords must be in the [Configuration Section] of the INI file.
Keywords are case-insensitive.
Spaces in a keyword are significant, even after the last character.
The value of the keyword begins immediately after the equal sign.
Lines that begin with a semicolon are comments.
Lines of text can be placed in the [Lines] section of the INI file (optional).
E. Keywords
1. Background color - color of the background to be used in all project
windows, must be a valid HTML color keyword.
2. Background image - background image to be used in all project windows,
must be a valid, fully qualified URL for the image.
3. Source Code Window Attributes - window attributes for the source code
window (toolbar, scrollbar, menubar, location, status, directories, resizable,
height, width).
4. Filename Base - the base directory for files.
5. Line Width - specifies the width of the Editor windows for the source code,
and documentation.
6. Doc Lines - specifies the vertical size in lines of the display area when
editing documentation.
7. Source Lines - specifies the vertical size in lines of the display area when
editing the routine code.
8. Intro Lines - specifies the vertical size in lines of the module introduction
display area on the module action page.
9. Header Intro Lines - specifies the vertical size in lines of the display area
when editing a header file.
10. View – specifies the default view (Both, Source, Docs, or B,S,D).
11. Project Name – specifies the project name to display on all screens
regarding files within this directory.
14
Listing 2: Example INI control files: Default
[Configuration]
Background Color=color name OR #triplet
Background Image=full or relative URL path of image file
Filename Base=/base_directory_for_references/
Source Code Window Attributes=browser window attributes
; View=Both | Source | Docs
View=Source
[B|S|D]
Line Width=80
Doc Lines=5
Source Lines=30
Intro Lines=10
Header Intro Lines=30
Listing 3: Example INI control files: Project Specific
[Configuration]
Project Name=INI Control File Module
Source Code Window
Attributes=toolbar=no,scrollbars=yes,menubar=no,location=no,s
tatus=no,directories=no,resizable=yes,height=610,width=700
Background Color=cyan
Background Image=http://www.cs.unt.edu/~donr/courses/backg2.jpg
; View=Both | Source | Docs
View=Source
[B|S|D]
Line Width=80
Doc Lines=5
Source Lines=30
Intro Lines=10
Header Intro Lines=30
15
Glossary
ASCII
Stands for American Standard Code for Information
Interchange. ASCII code is used to represent alphanumeric
information.
Comments
Lines in program code that do not affect the program but
serve to explain the code.
Default INI file
INI file that the program refers to by default.
Delimiters
A character that marks the beginning or end of a unit of data
Filename Base
The base directory path specified in an INI file. The Filename
base precedes all specified paths.
Header file
A file that explains what the functions in the implementation
file do. It explains this information to both the user and the
program compiler.
HTML
A markup language that is used to create hypertext and
hypermedia documents on the World Wide Web incorporating
text, graphics, sound, video, and hyperlinks
Implementation file
A file that has the actual code of the functions explained in the
header file.
INI file
Initialization file that allows the administrator to set the initial
values in the application
JavaScript
A scripting language used for the development of WebPages.
Keyword-value pair
This is how values are defined in an INI file.
e.g. color=black
Parse
To analyze or separate into more easily processed components
PHP
A widely used general-purpose scripting language that is
especially suited for Web development and can be embedded
into HTML.
Project Specific INI file INI file the program refers to for project-specific values.
Values in the Project Specific INI file override those in the
default INI file.
Routine
Also referred to as a function. A routine is a set of
programming instructions designed to perform a specific
limited task.
16