Create ECMA-55 conformance reference manual

[treytomes]

Description

ECMA-55 requires implementations to provide a reference manual documenting all implementation-defined behavior.

ECMA-55 Requirement

• ECMA55-CNF-007: "A conforming implementation shall be accompanied by a reference manual that defines all undefined and implementation-defined behavior." (Appendix 3, PDF p. 39)

Required Documentation (Appendix 4)

The reference manual must define 14 implementation-specific features:

Numeric Behavior

• ECMA55-DOC-001: Numeric-expression evaluation accuracy
• ECMA55-DOC-007: Machine infinitesimal (smallest positive value)
• ECMA55-DOC-008: Machine infinity (largest value)
• ECMA55-DOC-010: Numeric precision (significant digits)

I/O Formatting

• ECMA55-DOC-002: End-of-line handling
• ECMA55-DOC-003: Print numeric exrad-width (exponent width)
• ECMA55-DOC-009: Output margin (line width)
• ECMA55-DOC-011: Print-zone length (TAB zones)
• ECMA55-DOC-013: Print numeric significance-width

Input Behavior

• ECMA55-DOC-005: Input prompt format
• ECMA55-DOC-014: Batch-mode input reply mechanism

Variable Behavior

• ECMA55-DOC-004: Initial variable values
• ECMA55-DOC-006: Maximum retained string length

Random Numbers

• ECMA55-DOC-012: Pseudo-random sequence definition (without RANDOMIZE)

Current State

Configuration exists in appsettings.json but lacks formal documentation:

{
  "MaxLineLength": 72,
  "MaxStringLength": 18,
  "TerminalWidth": 80,
  "NumTerminalColumns": 5,
  ...
}

Implementation Plan

1. Create Reference Manual

File: docs/ECMA55_REFERENCE_MANUAL.md

Structure:

# ECMA-55 Implementation Reference Manual

## 1. Introduction
- Implementation name and version
- ECMA-55 conformance statement

## 2. Numeric Representation
- Precision: Double-precision IEEE 754 (15-16 significant decimal digits)
- Range: ±5.0 × 10^-324 to ±1.7 × 10^308
- Machine infinitesimal: 5.0 × 10^-324
- Machine infinity: 1.7 × 10^308
- Evaluation accuracy: IEEE 754 rounding rules

## 3. String Handling
- Maximum string length: 18 characters
- Initial string values: Empty string ""

## 4. Print Formatting
- Output margin: 80 characters
- Print zones: 5 zones of 16 characters each
- Significance width: 6 decimal digits minimum
- Exrad width: 2 digits (E+00)
- End-of-line: Platform-specific (CRLF on Windows, LF on Unix)

## 5. Input Handling
- Interactive prompt: "? "
- Batch mode: Read from stdin with no prompt
- Initial numeric values: 0

## 6. Random Numbers
- Algorithm: .NET System.Random (Knuth subtractive)
- Seed: Fixed initial seed (42) for repeatability
- Sequence: Deterministic without RANDOMIZE

## 7. Error Handling
- Fatal exceptions: Program terminates immediately
- Nonfatal exceptions: Program continues with recovery value

## 8. Extensions
- Non-ECMA-55 features (if any): ASC, MID$, POS, SLEEP

2. Document Current Behavior

Extract values from:

• MinimalBasicConfiguration.cs
• appsettings.json
• .NET double precision specs
• Test actual RND sequence behavior

3. Link from README

Add "Conformance" section referencing the manual

Acceptance Criteria

• Reference manual created in docs/
• All 14 implementation-defined features documented
• Numeric precision/range specified
• I/O formatting rules defined
• Random number behavior documented
• Error handling described
• Non-standard extensions listed (if any)
• Linked from main README

Related

• Spec: docs/specifications/ecma-55/requirements.md (ECMA55-CNF-007, DOC-001 to DOC-014)
• Config: src/ECMABasic.Application/Configuration/MinimalBasicConfiguration.cs
• Gap Analysis: .claude/audits/ecma55-gap-analysis-2026-06-24.md

Estimated Effort: 8-10 hours (research + documentation + verification)