# FUNADV.DAT Fix Documentation

## Problem

The `FUNADV.DAT` file contained whitespace formatting issues that prevented the FORTRAN code in `FUNADV.FOR` from parsing it correctly.

## Root Cause

The FORTRAN code uses fixed-width format descriptors to read the data file:

```fortran
* Section number
FORMAT(I8)

* Text sections (1, 2, 5, 6, 9)
FORMAT(1I8,80A,80A)  -- 8-char location + 80 chars text + 80 chars overflow

* Travel table (section 3)
FORMAT(10I8)

* Vocabulary (section 4)
FORMAT(I8,1A10,2I8)
```

The text sections require every line to begin with an **8-character right-justified integer** (the location number). However, 37 lines in the file were missing this prefix, containing only the text content. These were special effect "animation" sequences that had been corrupted or improperly converted.

## Lines Fixed

### Section 1 (Long Location Descriptions)

| Line | Content | Location |
|------|---------|----------|
| 29 | `--spinning--` (whirlpool animation) | 13 |
| 76-94 | `falling...`, `.^/`, `--=splat=--` (falling animation) | 34 |
| 170 | `A rancid stench exudes from a gloomy area to the west.` | 65 |

### Section 6 (Arbitrary Messages)

| Line | Content | Location |
|------|---------|----------|
| 451-456 | `sinking`, `Into the ooze.` (quicksand animation) | 176 |
| 2194 | `You klutz!` | 205 |
| 2205-2211 | `ahhhh....`, `^/^/^/^*-===RELIEF===-` (bathroom humor) | 210 |
| 2221 | `...Where is the *PLOP-PLOP* *FIZZ-FIZZ*???` | 214 |
| 2242-2243 | Empty line + `CMRLBPB 78/10/10...` (timestamp) | 230 |

## Fix Applied

### Phase 1: Add Location Prefixes

Each line missing a location prefix was prefixed with the appropriate 8-character location number:

```
Before: falling...
After:        34falling...

Before:    Into the ooze.
After:      176   Into the ooze.

Before: ahhhh....
After:      210ahhhh....
```

### Phase 2: Remove Blank Lines

The FORTRAN code checks that text lines have at least one non-space character:

```fortran
DO 1006 LOOP=1,80
KK=81-LOOP
IF (TEXT(KK:KK).NE.' ')GOTO 1007
1006 CONTINUE
CALL BUG(1)   ! Error if TEXT is all spaces
```

Lines that had only a location number with no text content would trigger `BUG(1)`. These were originally empty lines used for animation timing effects. **15 blank lines were removed:**

| Original Lines | Location | Purpose |
|---------------|----------|---------|
| 83, 85-86, 88-93 | 34 | Falling animation pauses |
| 169 | 65 | Blank after door description |
| 452, 454-455 | 176 | Sinking animation pauses |
| 2241-2242 | 230 | Blank lines near end |

## Verification Results

```
Total text section lines checked: 1174
Errors found: 0

File structure:
  Section 1 (long descriptions):  lines 1-491
  Section 2 (short descriptions): lines 492-571
  Section 3 (travel table):       lines 572-1269
  Section 4 (vocabulary):         lines 1270-1638
  Section 5 (object descriptions):lines 1639-1832
  Section 6 (messages):           lines 1833-2240
  Section 7 (action defaults):    lines 2241-2275
  Section 8 (conditions):         lines 2276-2292
  Section 9 (class messages):     lines 2293-2303
  Section 10 (hints):             lines 2304-2313
  Section 0 (end marker):         line 2314

Original line count: 2329
Final line count: 2314 (15 blank lines removed)
Invalid lines remaining: 0
```

## Backup

The original file was preserved as `FUNADV.DAT.bak`.

## Notes on `^/` Control Characters

The `.^/` and `^/^/^/^*` sequences in the animation text are **CDC NOS 6/12 escape codes** (also called "caret ASCII").

### Decoding

In CDC NOS 6/12 encoding:

| Code | Meaning |
|------|---------|
| `^/` | ASCII 010 (octal) = ASCII 8 = **BACKSPACE** |
| `^*` | End marker / additional control |

### How the Animations Originally Worked

**Falling animation** (`.^/`):
```
.^/  = print period, then BACKSPACE
```
The cursor moves back over the period, so the next output overwrites it - creating a visual "dissolving" or "falling away" effect on the original terminals.

**Relief animation** (`^/^/^/^*-===RELIEF===-`):
Multiple backspaces erase/overwrite previous characters, creating an "erasure" visual effect (fitting the bathroom humor context).

**Lightning effect** (`^/^/^/zap ^/^/^/p! ^/^/^/!!`):
Backspaces combined with text like "zap" would create a flickering/overwriting effect simulating electrical sparks.

### Historical Context

This game originated on **CDC Cyber systems at Georgia Tech (~1975)** which used 6-bit character encoding. The CDC 6000 series and Cyber systems stored 10 six-bit characters per 60-bit word, requiring escape sequences to represent the full ASCII character set.

When the game was ported to VAX/VMS with ASCII character support, the caret-escape sequences were preserved as literal text (`^` followed by `/`) rather than being converted to actual control characters (ASCII 8 backspace). On modern systems, these sequences display as literal text instead of producing the intended animation effects.

### References

- [CDC charset reference (recode manual)](https://www.math.utah.edu/docs/info/recode_6.html)
- [CDC display code - Wikipedia](https://en.wikipedia.org/wiki/CDC_display_code)
- [Caret notation - Wikipedia](https://en.wikipedia.org/wiki/Caret_notation)