Software Manual

The Burn Project

by Kyle Gossman

Documentation, Standards and Conventions
Source Code Files
Software Installation
Design Issues List
Cross-Reference Table
To Do List
Revision History

Documentation, Standards and Conventions

Internal Documentation

Each file has a comment with the filename, author name, creation date, and a short description of the file at the top. For example, the comment for the file add_course.php would look like this:

/*
** add_course.php
** by Andy Cooper
**
** Created: May 05, 2003
**
** This script displays the form to add a course
** to a student plan.
*/

Each function also has a comment with the function name and a description of the function, for example:

/*
** get_student_plan
**
** Returns the student plan given a username.
*/

Coding Standards

The coding standards followed included having opening semicolons on the same line as a function header or control statement.

function get_student_plan() {

/* .... */

}

Variable names were to be clear and indicate what they were used for. They should be longer than 2 characters, with the exception of counter variables, which were usually named $i and $j. In general we would put the <? and ?>s that signified blocks of php code instead of html on their own lines to clearly separate the two. The only exception is when this new line caused an error in the software. For example, if we had an html tag like the following:

<option name="

/* ... */

The new lines would be included in the name parameter.

File Naming Conventions

All files have either the extension php or txt depending on whether they are web content or data files. Each file is named clearly and suggests what its function is, and files are placed in directories based on what module they belong in as described in the design document.

Source Code Files

1.1 authentication_utils.php

Purpose: To authenticate the user and allow other modules to determine whether a user is properly authenticated for a specific resource, and what the username is.
Contains:

function get_auth_level() - Returns the current authentication level.
function get_username() - Returns the user's kerberos username.

Programming Language:
- PHP
- HTML

1.2 index.php

Purpose: The main index page.
Contains:
Programming Language:
- PHP
- HTML

1.3 admin/add_course.php

Purpose: Displays the form to add a course to the course catalog.
Contains:
Programming Language:
- PHP
- HTML

1.4 admin/admin_main.php

Purpose: Decides which sub-page of the administration section to display. Pages are 'included' as needed.
Contains:
Programming Language:
- PHP
- HTML

1.5 admin/catalog.php

Purpose: Displays the form to edit the course catalog.
Contains:
Programming Language:
- PHP
- HTML

1.6 admin/change_course.php

Purpose: Displays the form to choose which course to change in the course catalog
Contains:
Programming Language:
- PHP
- HTML

1.7 admin/change_course2.php

Purpose: Displays the form to change the course that is chosen by the change_course.php script.
Contains:
Programming Language:
- PHP
- HTML

1.8 admin/remove_course.php

Purpose: Displays the form to remove a course from the course catalog
Contains:
Programming Language:
- PHP
- HTML

1.9 admin/statistics.php

Purpose: Displays a table of the course statistics
Contains:
Programming Language:
- PHP
- HTML

1.10 admin/view_catalog.php

Purpose: Displays the current catalog
Contains:
Programming Language:
- PHP
- HTML

1.11 datamod/admin_config.php

Purpose: Provides functions for reading in and writing to the administration configuration flat file.
Contains:

function is_admin($username) - Checks if a user is an administrator.
function is_super_admin($username) - Checks if a user is the super administrator.
function add_admin($username) - Adds an administrator
function remove_admin($username) - Removes an administrator

Programming Language:
- PHP
- HTML

1.12 datamod/advisee_list.php

Purpose: Provides functions for reading in and writing to the advisee list flat files.
Contains:

function get_advisees($advisor) - Returns an array of advisees for a given advisor.
function get_advisee_file() - Returns an array of the entire advisee file.
function set_advisee_file($advisees) - Writes an array representation of the advisee file to disk
function add_advisor($advisor) - Adds an advisor to the advisee file
function add_advisees($advisor, $students) - Adds advisees to a given advisor
function remove_advisee($advisor, $advisee) - Removes a student from being an advisee of the given advisor
function set_advisees($new_advisees) - Replaces the array of an advisor and advisees with a new array

Programming Language:
- PHP
- HTML

1.13 datamod/course_cat.php

Purpose: Provides functions for reading in and writing to the course catalog flat files.
Contains:

function get_catalog() - Returns the entire catalog in an array
function set_catalog($catalog) - Writes an array representation of the catalog to disk
function write_course_line($file, $course) - Writes an array representation of a course to file
function catalog_add_course($course) - Adds a course to the catalog
function catalog_remove_course($course) - Removes a course from the catalog
function get_course($course_id) - Returns an array representation of a course given the course id
function set_course($course) - Writes a course to the catalog. If the course id exists, the old course will be overwritten.
function course_exists($course_id) - Returns 1 if a course exists given the course id, or 0 otherwise
function get_dependencies($course_id) - Returns an array of the dependencies for a course

Programming Language:
- PHP
- HTML

1.14 datamod/data_module.php

Purpose: Provides the public interface of the data module to other modules. Other modules can 'include' this file and get all the functionality of the entire data module through its functions.
Contains:
Programming Language:
- PHP
- HTML

1.15 datamod/skeleton.php

Purpose: Provides functions for reading in and writing to the course plan skeleton flat files.
Contains:

function get_skeleton_file() - Returns an array representation of the skeleton file
function set_skeleton_file($skeletons) - Writes an array representation of the skeleton file to disk
function get_skeleton($name) - Returns an array representation of the specified skeleton plan
function set_skeleton($name, $new_skeleton) - Writes an array representation of the specified skeleton plan to disk

Programming Language:
- PHP
- HTML

1.16 datamod/stud_sched.php

Purpose: Provides functions for reading in and writing to the student schedule flat files.
Contains:

function get_student_plan($username) - Returns the student plan given a username.
function set_student_plan($username, $stud_info, $plan) - Writes the student plan for the given username to disk
function get_student_info($username) - Returns an array of information about a student
function set_student_info($username, $info) - Writes an array representation of student information for the given username to disk
function remove_course($username, $quarter, $slot) - Removes a course specified by quarter and slot from a given username's plan
function add_course($username, $quarter, $slot, $course) - Adds a course into the specified quarter and slot for the given username's plan
function dependencies_met($username, $dependencies, $quarter) - Checks to see if a students dependencies are met up until a given quarter
function generate_stats() - Returns an array representation of how many students are signed up for the courses in the catalog

Programming Language:
- PHP
- HTML

1.17 faculty/faculty_main.php

Purpose: Decides which sub-page of the faculty section to display. Pages are 'included' as needed.
Contains:
Programming Language:
- PHP
- HTML

1.18 student/add_course.php

Purpose: Displays the form to add a course to a student plan.
Contains:
Programming Language:
- PHP
- HTML

1.19 student/confirm_delete.php

Purpose: Displays the form to confirm deletion of a course from a student plan.
Contains:
Programming Language:
- PHP
- HTML

1.20 student/move_course.php

Purpose: Displays the form to move a course in a student plan.
Contains:
Programming Language:
- PHP
- HTML

1.21 student/show_plan.php

Purpose: Displays the course plan on the default student page.
Contains:
Programming Language:
- PHP
- HTML

1.22 student/student_main.php

Purpose: Decides which sub-page of the student section to display. Pages are 'included' as needed.
Contains:
Programming Language:
- PHP
- HTML

Software Installation

2.1 Development Platform

Hardware

Intel Celeron 533 Mhz
384 MB RAM
200 GB Hard Drive

Software

Debian/GNU Linux 2.4.18
Apache 1.3.27
PHP4
Emacs and vi for editing

2.2 Client Delivery Platform

2.2.1 Web server

Hardware
Nearly identical to the development platform
Software
Solaris 8

Apache

PHP4

2.2.2 Users
- Hardware
  
  Computer with a 486/66-MHz processor or higher (Pentium processor recommended).
  16 MB RAM for Windows 98
  32 MB RAM for Windows 2000/XP
- Software
  
  Windows XP
  Internet Explorer 6 or Netscape Navigator 6

Design Issues List

Items

Cross-Reference Table

Table Key:

RE – Requirements Document, Requirements section.
UI – Design Document, User Interface section.
IP – Design Document, Implementation Platform section.
DD – Design Document, Detailed Design section.
DS – Design Document, Data Storage section.

Design ID and Heading Name	Software ID and Heading Name
UI / 2.1	1.1
UI / 2.2	1.22
UI / 2.2.3	1.18
UI / 2.3	1.17
DS / 1.1	1.13
DS / 1.2	1.16
DS / 2.1	1.11
DS / 2.2	1.12
DS / 2.3	1.13
DS / 2.4	1.16
DS / 2.5	1.15
IP / 1	2.1
IP / 2	2.2

To Do List