dbbasic-manx Specification

Version: 0.1.0 Status: Active Development Author: DBBASIC Team Date: 2025-10-22

Links: - GitHub: https://github.com/askrobots/dbbasic-manx - PyPI: (not published yet) - Specification: https://dbbasic.com/manx-spec

Philosophy

Man pages should look like BBS screens from 1995, but with modern syntax highlighting.

Core Principles: 1. Zero dependencies - Uses only Python stdlib 2. Beautiful terminal output - 256-color ANSI with box-drawing characters 3. Syntax highlighting - Code blocks with language-aware coloring 4. Pager integration - Works with less -R for keyboard navigation 5. Single file - Fully self-contained for easy distribution

What Is dbbasic-manx?

A standalone Python script that provides BBS-style, ANSI-colored man pages with syntax highlighting and pager support.

Instead of traditional plain-text man pages, manx gives you: - Beautiful colors and formatting - Syntax-highlighted code examples - Proper box-drawing characters - Keyboard navigation (arrow keys, search, etc.) - Automatic terminal width adaptation

Features

Zero Dependencies

Uses only Python standard library: - os, sys, re for core functionality - textwrap for text wrapping - shutil for terminal size detection - pydoc.pager for paging support

No pip install required beyond Python 3.6+.

ANSI Colors

Beautiful 256-color terminal output: - Bold headers and section names - Dimmed metadata and comments - Syntax-highlighted code blocks - Colored box-drawing characters - Respects NO_COLOR environment variable

Syntax Highlighting

Automatic highlighting for: - Python - Keywords, strings, comments, numbers - Shell - Commands, flags, env vars, quoted args - HTTP - Methods, status codes, headers - TSV - Tab-separated values with header highlighting

Pager Support

Integrates with less -R for full keyboard navigation: - Arrow keys / PageUp / PageDown - Navigate - / - Search for text - n - Next search match - q - Quit pager

Adaptive Width

Automatically adjusts to terminal size: - Min width: 60 columns (narrow terminals) - Max width: 120 columns (readability) - Default: 100 columns (when piped/redirected)

Pipe-Friendly

Detects when output is redirected:

# Outputs plain text when piped
python manx.py dbbasic-tsv > dbbasic-tsv.txt

# Disables colors with NO_COLOR
NO_COLOR=1 python manx.py dbbasic-tsv

Installation

Single File Installation

# Download the script
curl -O https://raw.githubusercontent.com/askrobots/dbbasic-manx/main/manx.py
chmod +x manx.py

# Run it
./manx.py

System-Wide Installation

# Copy to /usr/local/bin
sudo cp manx.py /usr/local/bin/manx
sudo chmod +x /usr/local/bin/manx

# Now use it anywhere
manx dbbasic-tsv

Usage

View Menu

python manx.py

Shows available manual pages with descriptions.

View Specific Page

python manx.py dbbasic-tsv

Displays the man page for dbbasic-tsv with full ANSI colors and pager.

Disable Colors

NO_COLOR=1 python manx.py dbbasic-tsv

Export to Text File

python manx.py dbbasic-tsv > dbbasic-tsv.txt

Automatically disables colors when redirected to file.

Adding New Pages

To add a new manual page, create a function that returns formatted content:

def get_mynew_man():
    """Generate man page for mynew tool."""
    mycode = code_block("""print("Hello, World!")""", "python")

    return f"""{h1("MYNEW(1) — My New Tool")}

{BOLD}NAME{RESET}
  mynew — Description of your tool

{BOLD}SYNOPSIS{RESET}
  mynew [options] <args>

{BOLD}DESCRIPTION{RESET}
  Your tool description here.

{BOLD}EXAMPLES{RESET}
{mycode}

{BOLD}SEE ALSO{RESET}
  other-tool(1), related-tool(1)
"""

# Register it in the PAGES dictionary
PAGES = {
    "dbbasic-tsv": get_dbbasic_tsv_man,
    "mynew": get_mynew_man,
}

Available Formatting Functions

# Headers
h1("TITLE")           # Large header with box
h2("Section Name")    # Section header

# Text styles
BOLD + "text" + RESET        # Bold text
DIM + "text" + RESET         # Dimmed text
ITAL + "text" + RESET        # Italic text
UNDER + "text" + RESET       # Underlined text

# Code blocks
code_block("""code here""", "python")    # Python syntax
code_block("""code here""", "shell")     # Shell syntax
code_block("""code here""", "http")      # HTTP syntax
code_block("""code here""", "tsv")       # TSV syntax

# Colors
FG["green"] + "text" + RESET     # Green text
FG["blue"] + "text" + RESET      # Blue text
FG["yellow"] + "text" + RESET    # Yellow text
FG["red"] + "text" + RESET       # Red text

Syntax Highlighting Details

Python

Highlights: - Keywords: def, class, if, for, while, return, etc. - Built-ins: print, len, str, int, dict, etc. - Strings: Single, double, and triple-quoted - Comments: Lines starting with # - Numbers: Integers and floats - Decorators: @property, @staticmethod, etc.

Shell

Highlights: - Commands: ls, cd, grep, awk, sed, etc. - Flags: -r, --recursive, -avz - Environment variables: $HOME, ${VAR} - Quoted strings: Single and double quotes - Pipes and redirects: |, >, >>

HTTP

Highlights: - Methods: GET, POST, PUT, DELETE - Status codes: 200, 404, 500 - Headers: Content-Type:, Authorization: - URLs: https://example.com

TSV

Highlights: - Header row in bold yellow - Tab separators - Data rows in normal color

Terminal Compatibility

Supported Terminals

✅ iTerm2 (macOS)
✅ Terminal.app (macOS)
✅ Alacritty
✅ GNOME Terminal
✅ Konsole
✅ Windows Terminal
✅ Most modern terminal emulators

Requirements

256-color support (most terminals after 2010)
UTF-8 encoding for box-drawing characters
less installed for pager (optional, falls back to basic pager)

Environment Variables

NO_COLOR

Disable all ANSI color codes:

NO_COLOR=1 python manx.py dbbasic-tsv

Standard supported by many CLI tools: https://no-color.org/

COLORTERM

Detect truecolor support:

COLORTERM=truecolor python manx.py dbbasic-tsv

Currently used for detection, may enable 24-bit color in future.

Examples

Basic Usage

# List available pages
python manx.py

# View a page
python manx.py dbbasic-tsv

# View with custom pager
PAGER=more python manx.py dbbasic-tsv

Integration Examples

Shell Alias

# Add to ~/.bashrc or ~/.zshrc
alias manx='python /path/to/manx.py'

# Now use it
manx dbbasic-tsv

Quick Reference Script

#!/bin/bash
# quickref.sh - Quick reference for dbbasic tools
python manx.py "$1"

Documentation Server

# Serve manx pages over HTTP
from http.server import HTTPServer, BaseHTTPRequestHandler
import subprocess

class ManxHandler(BaseHTTPRequestHandler):
    def do_GET(self):
        page = self.path.strip('/')
        result = subprocess.run(
            ['python', 'manx.py', page],
            capture_output=True,
            text=True,
            env={'NO_COLOR': '1'}
        )
        self.send_response(200)
        self.send_header('Content-Type', 'text/plain; charset=utf-8')
        self.end_headers()
        self.wfile.write(result.stdout.encode())

HTTPServer(('', 8000), ManxHandler).serve_forever()

Philosophy Behind Manx

Why BBS-Style?

The Bulletin Board System (BBS) era (1980s-1990s) had beautiful ANSI art and colorful interfaces that made text mode feel alive. Modern terminals support 256 colors and Unicode, so why settle for plain text?

Why Not HTML?

Terminals are faster to navigate
No browser required
Works over SSH
Can pipe/grep output
Stays in your workflow

Why Not Standard Man Pages?

Traditional man pages (man(1)) are: - Plain text only (no colors) - Fixed format (troff/groff) - Require installation - Hard to customize

Manx gives you the benefits of man pages (keyboard navigation, searchable) with modern aesthetics.

Design Principles

Beautiful by default - Colors make reading easier
Fast navigation - Pager support for large pages
Copy/paste friendly - Plain text when piped
Single file - No installation hassles
Extensible - Easy to add new pages

Comparison

vs Traditional Man Pages

man(1):          Plain text, no colors, system-installed
manx:            256-color ANSI, syntax highlighting, single file

vs HTML Documentation

HTML:            Requires browser, not terminal-native
manx:            Works over SSH, stays in terminal

vs README.md

README:          GitHub rendering only, no colors in terminal
manx:            Beautiful in terminal, syntax-highlighted code

Current Pages

dbbasic-tsv

Complete manual for the TSV database module: - Installation and setup - API reference - Code examples with syntax highlighting - Query examples - Transaction examples

More pages coming soon for other dbbasic modules.

Roadmap

Short-term

[ ] Add pages for all dbbasic modules
[ ] Add table rendering support
[ ] Add image placeholders (ASCII art)
[ ] Package for PyPI

Long-term

[ ] Interactive mode (choose page from menu)
[ ] Search across all pages
[ ] Generate pages from docstrings
[ ] Plugin system for custom formatters

License

MIT License - Feel free to use and modify!