QWK.NET ‐ Console Encoding Advice

Console Encoding Advice

This document provides platform-specific advice for configuring console/terminal environments to properly display CP437 box-drawing characters and extended ASCII used in QWK packets.

---

Overview

QWK packets use CP437 (DOS Latin US) encoding, which includes:

• Box-drawing characters (single and double lines)
• Block graphics (shading characters)
• Extended ASCII (accented letters, symbols)

Modern terminals use UTF-8 encoding, which can display all CP437 characters when properly configured.

---

Quick Verification

Run the QWK.NET diagnostics render test to verify your setup:

QwkNet.Diagnostics rendertest

You should see clean box-drawing characters, block graphics, and international characters.

If characters appear as question marks (?) or boxes, your console encoding needs adjustment.

---

Windows Configuration

Windows Terminal (Recommended)

Windows Terminal provides the best CP437 rendering support.

1. Install/Open Windows Terminal

   • Windows 11: Pre-installed
   • Windows 10: Install from Microsoft Store

2. Verify UTF-8 Support

   • Windows Terminal uses UTF-8 by default
   • No additional configuration needed

3. Set Code Page (if needed)

   chcp 65001

4. Verify Rendering

   QwkNet.Diagnostics rendertest

Command Prompt (Legacy)

If using the legacy Windows Command Prompt:

1. Set UTF-8 Code Page

   chcp 65001

2. Use TrueType Font

   • Right-click title bar - Properties - Font
   • Select "Consolas" or "Lucida Console"
   • Click OK

3. Test Rendering

   QwkNet.Diagnostics rendertest

Known Limitations:

• Legacy console may show boxes for some characters
• Consider upgrading to Windows Terminal

PowerShell

PowerShell 7+ uses UTF-8 by default:

1. Verify Encoding

   [Console]::OutputEncoding

2. Set UTF-8 (if needed)

   [Console]::OutputEncoding = [System.Text.Encoding]::UTF8

3. Verify Rendering

   dotnet run --project QwkNet.Diagnostics rendertest

---

Linux Configuration

Most modern Linux distributions use UTF-8 by default. Verify and configure as needed:

1. Check Current Locale

locale

Expected output should include:

LANG=en_GB.UTF-8
LC_ALL=en_GB.UTF-8

2. Set UTF-8 Locale (if needed)

For British English:

export LANG=en_GB.UTF-8
export LC_ALL=en_GB.UTF-8

For US English:

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

Make Permanent (add to ~/.bashrc or ~/.zshrc):

echo 'export LANG=en_GB.UTF-8' >> ~/.bashrc
echo 'export LC_ALL=en_GB.UTF-8' >> ~/.bashrc
source ~/.bashrc

3. Verify Terminal Font

Ensure your terminal uses a font with Unicode support:

• GNOME Terminal: Edit - Preferences - Text - Custom font
• Konsole: Settings - Edit Current Profile - Appearance - Font
• xterm: Add to ~/.Xresources:

  xterm*faceName: DejaVu Sans Mono
  xterm*faceSize: 10
  

Recommended fonts:

• DejaVu Sans Mono
• Liberation Mono
• Ubuntu Mono
• Fira Code

4. Test Rendering

dotnet run --project tools/QwkNet.Diagnostics rendertest

---

macOS Configuration

macOS Terminal.app and iTerm2 both support UTF-8 by default.

Terminal.app (Built-in)

1. Verify UTF-8 Encoding

   • Terminal - Preferences - Profiles - Advanced
   • Check "Set locale environment variables on startup"
   • Character encoding should be "Unicode (UTF-8)"

2. Select Unicode Font

   • Terminal - Preferences - Profiles - Text
   • Font: Select "Menlo" or "Monaco"

3. Test Rendering

   dotnet run --project tools/QwkNet.Diagnostics rendertest

iTerm2 (Recommended)

iTerm2 provides superior Unicode rendering:

1. Install iTerm2

   brew install --cask iterm2

2. Configure Profile

   • iTerm2 - Preferences - Profiles - Terminal
   • Character Encoding: Unicode (UTF-8)
   • Report Terminal Type: xterm-256color

3. Select Font

   • Preferences - Profiles - Text
   • Font: "Menlo Regular" or "Fira Code"

4. Test Rendering

   dotnet run --project tools/QwkNet.Diagnostics rendertest

---

Common Issues and Solutions

Issue: Box Characters Show as Question Marks (?)

Cause: Console not using UTF-8 encoding.

Solution:

• Windows: Run chcp 65001
• Linux/macOS: Set LANG=en_GB.UTF-8

Issue: Box Characters Show as Empty Boxes

Cause: Font doesn't support Unicode box-drawing.

Solution:

• Windows: Change font to Consolas or use Windows Terminal
• Linux: Use DejaVu Sans Mono or Liberation Mono
• macOS: Use Menlo or Monaco

Issue: Characters Overlap or Don't Align

Cause: Proportional font or incorrect character width.

Solution:

• Use a monospaced (fixed-width) font
• Recommended: Consolas (Windows), DejaVu Sans Mono (Linux), Menlo (macOS)

Issue: ANSI Colours Don't Display

Cause: Terminal doesn't support ANSI escape codes.

Solution:

• Windows: Use Windows Terminal or PowerShell 7+
• Linux: Most terminals support ANSI; verify with: echo -e "\e[31mRed\e[0m"
• macOS: Both Terminal.app and iTerm2 support ANSI

Issue: Rendering Works in One Terminal But Not Another

Cause: Different terminal emulators have different capabilities.

Solution:

• Use recommended terminals: Windows Terminal, iTerm2, GNOME Terminal
• Verify encoding settings in each terminal separately

---

Testing Your Configuration

Test 1: Basic Box Drawing

Run the render test command:

QwkNet.Diagnostics rendertest

Expected output should show clean boxes.

Test 2: With Real QWK Packet

Test rendering from an actual packet:

QwkNet.Diagnostics rendertest --packet starol.qwk

This shows box-drawing as it appears in real BBS packets.

Test 3: Manual Character Test

In your terminal, type:

echo "Box drawing test"

You should see proper rendering of any special characters.

---

Recommended Terminal Configurations

Windows

• Best: Windows Terminal
• Alternative: PowerShell 7+
• Avoid: Legacy cmd.exe

Linux

• Best: GNOME Terminal, Konsole
• Alternative: Alacritty, Terminator
• Font: DejaVu Sans Mono

macOS

• Best: iTerm2
• Alternative: Terminal.app
• Font: Menlo, Fira Code

---

.NET Code Examples

Setting Console Encoding Programmatically

using System;
using System.Text;

// Set console to UTF-8 for CP437 character display
try
{
  Console.OutputEncoding = Encoding.UTF8;
  Console.InputEncoding = Encoding.UTF8;
}
catch (IOException)
{
  // Some environments don't support changing encoding
  // The application will still work, but characters may not display correctly
}

Testing Character Display

using QwkNet.Encoding;

// Decode CP437 box-drawing bytes
byte[] boxBytes = new byte[] { 0xDA, 0xC4, 0xBF }; // top-left, horizontal, top-right
string decoded = Cp437Encoding.Decode(boxBytes, DecoderFallbackPolicy.Strict);

// Display to console
Console.WriteLine(decoded);

---

Troubleshooting Checklist

• Console encoding set to UTF-8
• Using a monospaced font
• Font supports Unicode box-drawing (U+2500-U+257F range)
• Locale set to UTF-8 (Linux/macOS)
• Using recommended terminal emulator
• .NET 10 runtime installed
• QwkNet.Diagnostics rendertest produces clean output

---

Summary

Quick Setup:

1. Use a modern terminal (Windows Terminal, iTerm2, GNOME Terminal)
2. Ensure UTF-8 encoding is enabled
3. Use a monospaced Unicode font
4. Run QwkNet.Diagnostics rendertest to verify

If rendering fails:

1. Check console encoding (chcp 65001 on Windows, locale on Unix)
2. Verify font supports box-drawing characters
3. Try a different terminal emulator
4. Review platform-specific section above

The QWK.NET library correctly encodes and decodes all CP437 characters. Rendering issues are typically environmental and can be resolved with proper terminal configuration.