Skip to content

QWK.NET ‐ Console Encoding Advice

Jump to bottom
Agent 57951 edited this page Jan 19, 2026 · 1 revision

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.

Clone this wiki locally