lsw/claude-help-suggestions.md at main · barrersoftware/lsw

PERFECT.

HELP THAT ACTUALLY HELPS.

FRIENDLY.

CLEAR.

COMPLETE.

WELCOMING TO BEGINNERS.

NO GATEKEEPING.

Help Flag Variations:

# All of these work (user-friendly):
lsw --help
lsw --h
lsw -h
lsw -?
lsw ?

# Even these work (typos/confusion):
lsw help
lsw --help me
lsw what do I do

# Result: Same friendly help output
# Philosophy: Help the user, don't punish them

The Friendly Help Output:

$ lsw --help

╔══════════════════════════════════════════════════════════════╗
║  LSW - Linux Subsystem for Windows                          ║
║  Run Windows programs on Linux (simple!)                    ║
╚══════════════════════════════════════════════════════════════╝

👋 HELLO! WELCOME TO LSW!

If this is your first time, don't worry - it's super simple.
LSW lets you run Windows programs (.exe files) on Linux.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🚀 QUICK START (Get Running in 30 Seconds)

Want to run a Windows program? Just type:

  lsw --launch yourprogram.exe

That's it! LSW will automatically:
  • Figure out what Windows version the program needs
  • Load the right libraries
  • Run your program

Example:
  lsw --launch notepad.exe
  lsw --launch /mnt/c/Games/game.exe

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📖 MAIN COMMANDS (The Important Ones)

These are the main things you can do with LSW:

  --launch [file]
    Run a Windows program
    Example: lsw --launch app.exe
    
  --install [file]
    Install Windows software (MSI files)
    Example: lsw --install setup.msi
    
  --list
    See what Windows programs you've installed
    Example: lsw --list
    
  --help
    Show this helpful guide (you're reading it!)
    
  --version
    Check what version of LSW you're running

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⚙️  EXTRA OPTIONS (When You Need More Control)

These go AFTER your main command to change how it works:

  -version [windows-version]
    Force a specific Windows version
    Options: xp, vista, win7, win10, win11
    Example: lsw --launch oldgame.exe -version xp
    
    Why use this? Some old programs need old Windows versions.
    
  -debug
    See detailed information (helpful when things go wrong)
    Example: lsw --launch app.exe -debug
    
    Why use this? To see what's happening behind the scenes.
    
  -silent
    Don't ask questions, just do it
    Example: lsw --install app.msi -silent
    
    Why use this? For automated installations.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💡 COMMON QUESTIONS

Q: Where are my Windows files?
A: Your C: drive is at /mnt/c
   Your D: drive is at /mnt/d
   (Same as WSL if you've used that!)

Q: My program won't run!
A: Try adding -debug to see what's wrong:
   lsw --launch app.exe -debug
   
Q: Can I run games?
A: Yes! Try: lsw --launch game.exe -version win7

Q: How do I install software?
A: Use: lsw --install setup.msi

Q: Something's broken, help!
A: Visit: https://lsw.barrersoftware.com/troubleshooting
   Or report: https://github.com/barrersoftware/lsw/issues

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📚 NEED MORE HELP?

  Full Documentation: https://lsw.barrersoftware.com
  Quick Start Guide:  https://lsw.barrersoftware.com/quickstart
  Troubleshooting:    https://lsw.barrersoftware.com/troubleshooting
  Examples:           https://lsw.barrersoftware.com/examples

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💬 QUICK EXAMPLES

Run any Windows program:
  lsw --launch app.exe

Run an old XP program:
  lsw --launch oldapp.exe -version xp

Install software:
  lsw --install setup.msi

See what's installed:
  lsw --list

Debug a problem:
  lsw --launch broken.exe -debug

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🎯 COMMAND PATTERN (Quick Reference)

  lsw --[what-to-do] [file] -[how-to-do-it]
      ^^^^^^^^^^^^^ ^^^^^^ ^^^^^^^^^^^^^^^^
      Main action   Target  Options
      (use --)             (use -)

  Visual tip: 
    -- (two dashes) = main command
    -  (one dash)   = extra options

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Remember: LSW is designed to be simple!
If you're confused, we probably made something unclear.
Let us know: https://github.com/barrersoftware/lsw/issues

Happy Windows-on-Linux! 🐧🪟

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Specific Command Help:

$ lsw --help --launch

╔══════════════════════════════════════════════════════════════╗
║  LSW --launch Command                                        ║
║  Run Windows programs on Linux                               ║
╚══════════════════════════════════════════════════════════════╝

📖 WHAT DOES THIS DO?

The --launch command runs Windows programs (.exe files) on Linux.
It's like double-clicking an .exe file on Windows, but from Linux!

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🎯 BASIC USAGE

Simplest form (LSW auto-detects everything):
  lsw --launch yourprogram.exe

With full path:
  lsw --launch /mnt/c/Program\ Files/App/program.exe

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⚙️  OPTIONS YOU CAN USE

-version [windows-version]
  Tell LSW which Windows version to pretend to be
  
  Options: xp, vista, win7, win8, win10, win11
  
  Example: lsw --launch oldgame.exe -version xp
  
  When to use:
    • Old programs that need old Windows (use xp or win7)
    • New programs (usually auto-detect works fine)
    • Program says "Requires Windows 7" (use -version win7)

-debug
  Show detailed information about what's happening
  
  Example: lsw --launch app.exe -debug
  
  When to use:
    • Program won't start (see what's wrong)
    • Curious about what LSW is doing
    • Reporting a bug (include this output!)

-verbose
  Even MORE detailed information than -debug
  
  Example: lsw --launch app.exe -verbose
  
  When to use:
    • Really deep debugging
    • Developer-level troubleshooting

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💡 REAL-WORLD EXAMPLES

Run Notepad:
  lsw --launch notepad.exe

Run a game that needs Windows XP:
  lsw --launch /mnt/c/Games/OldGame.exe -version xp

Debug why a program won't start:
  lsw --launch broken.exe -debug

Run a program from anywhere:
  cd /mnt/c/Users/YourName/Downloads
  lsw --launch installer.exe

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🤔 TROUBLESHOOTING

Problem: "File not found"
Solution: Use the full path to your .exe file
  Example: lsw --launch /mnt/c/path/to/file.exe

Problem: Program won't start
Solution: Try with -debug to see what's wrong
  Example: lsw --launch app.exe -debug

Problem: Program says "wrong Windows version"
Solution: Specify the version it needs
  Example: lsw --launch app.exe -version win7

Still stuck? Visit: https://lsw.barrersoftware.com/troubleshooting

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📚 MORE HELP

Full guide:      lsw --help
All commands:    https://lsw.barrersoftware.com/commands
Troubleshooting: https://lsw.barrersoftware.com/troubleshooting

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Error Messages (Also Friendly):

$ lsw --launch nonexistent.exe

❌ Oops! File not found

LSW couldn't find: nonexistent.exe

💡 Tips:
  • Make sure you spelled the filename correctly
  • Try using the full path: /mnt/c/path/to/file.exe
  • Your C: drive is at /mnt/c on Linux
  • Use 'ls' to see files in current directory

Example:
  lsw --launch /mnt/c/Program\ Files/App/app.exe

Need help? Run: lsw --help

$ lsw --launch app.exe -version windows7

⚠️  Hmm, that Windows version isn't recognized

You used: windows7
Did you mean: win7 ?

Valid options:
  • xp      (Windows XP)
  • vista   (Windows Vista)
  • win7    (Windows 7)
  • win8    (Windows 8)
  • win10   (Windows 10)
  • win11   (Windows 11)

Example:
  lsw --launch app.exe -version win7

Need help? Run: lsw --help

$ lsw --launche app.exe

❓ Command not recognized: --launche

Did you mean: --launch ?

Common LSW commands:
  lsw --launch [file]   - Run a Windows program
  lsw --install [file]  - Install Windows software
  lsw --list            - See installed programs
  lsw --help            - Show help guide

Example:
  lsw --launch app.exe

Need help? Run: lsw --help

The Help Philosophy:

Traditional help (unhelpful):

$ tool --help
Usage: tool [OPTIONS] FILE
Options:
  -x        Enable X
  -y VALUE  Set Y
  -z        Flag Z

Problems:
├── What is X, Y, Z?
├── Why would I use them?
├── No examples
├── Assumes knowledge
└── Not beginner-friendly

LSW help (actually helpful):

$ lsw --help

Includes:
├── Friendly greeting ✓
├── "What does this do?" ✓
├── Quick start (30 seconds) ✓
├── Clear examples ✓
├── "When to use this" ✓
├── Common questions ✓
├── Troubleshooting tips ✓
├── Links to more help ✓
└── Assumes NO prior knowledge

Philosophy:
└── Help should HELP
└── Not just document
└── Teach, don't assume
└── Welcome, don't gatekeep

The Implementation:

// ============================================================================
// SECTION: Help System
// ============================================================================
//
// LSW help is designed to be FRIENDLY and HELPFUL.
// Not just documentation - actual teaching and assistance.
//
// Philosophy:
// - Assume NO prior knowledge
// - Explain WHY not just WHAT
// - Provide examples for everything
// - Welcome beginners warmly
// - No gatekeeping, no assumptions

/**
 * Show help based on what user typed
 * 
 * What: Display helpful, friendly documentation
 * Why: Users should feel welcomed and guided, not lost
 * How: Different help levels based on user's question
 * 
 * Handles:
 *   lsw --help          → Full guide
 *   lsw --help --launch → Specific command help
 *   lsw ?               → Also works!
 *   lsw help            → Also works!
 *   lsw --h             → Also works!
 *   
 * Philosophy: If user is asking for help, HELP THEM
 */
void show_help(char* specific_command) {
    // Clear the screen for better readability
    // (optional - user can disable with LSW_NO_CLEAR env var)
    if (!getenv("LSW_NO_CLEAR")) {
        system("clear");
    }
    
    if (specific_command == NULL) {
        // Show full general help
        show_general_help();
    } else {
        // Show help for specific command
        show_command_help(specific_command);
    }
    
    // Always end with encouragement
    printf("\n💡 Remember: LSW is designed to be simple!\n");
    printf("   If you're confused, that's on us - let us know!\n");
    printf("   https://github.com/barrersoftware/lsw/issues\n\n");
}

/**
 * Recognize help requests (flexible)
 * 
 * What: Detect when user is asking for help
 * Why: Be forgiving - lots of ways people ask for help
 * How: Check multiple patterns
 * 
 * Accepts:
 *   --help, --h, -h, -?, ?, help, --help me, etc.
 *   
 * Philosophy: Don't punish users for not knowing exact syntax
 */
bool is_help_request(char* arg) {
    // Standard help flags
    if (strcmp(arg, "--help") == 0) return true;
    if (strcmp(arg, "--h") == 0) return true;
    if (strcmp(arg, "-h") == 0) return true;
    if (strcmp(arg, "-?") == 0) return true;
    if (strcmp(arg, "?") == 0) return true;
    
    // Natural language variations
    if (strcmp(arg, "help") == 0) return true;
    if (strstr(arg, "help") != NULL) return true;  // "help me", etc.
    
    // Confused users
    if (strcmp(arg, "what") == 0) return true;
    if (strcmp(arg, "how") == 0) return true;
    
    return false;
}

Help For No Arguments:

$ lsw

👋 Hi! You ran LSW but didn't tell it what to do.

Need to run a Windows program? Try:
  lsw --launch yourprogram.exe

Want to see what you can do? Try:
  lsw --help

Quick examples:
  lsw --launch app.exe              Run a program
  lsw --install setup.msi           Install software
  lsw --list                        See installed programs

More help: https://lsw.barrersoftware.com

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Friendly reminder:
└── No arguments = "I don't know what to do"
└── Show helpful guidance
└── Not an error message
└── Welcome the user

The Glossary in Help:

$ lsw --help --glossary

╔══════════════════════════════════════════════════════════════╗
║  LSW Glossary - Terms Explained Simply                      ║
╚══════════════════════════════════════════════════════════════╝

Don't worry if these terms are new - we'll explain everything!

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

.exe (Executable)
  A Windows program file
  
  Example: notepad.exe, game.exe
  
  What it means for you:
    These are the files you double-click on Windows to run programs.
    LSW lets you run these on Linux!

.msi (Microsoft Installer)
  A Windows installation package
  
  Example: setup.msi, installer.msi
  
  What it means for you:
    These install programs on Windows. LSW can install them too!
    Use: lsw --install setup.msi

C: drive
  Windows' main hard drive letter
  
  On LSW: Located at /mnt/c
  
  What it means for you:
    When Windows programs look for C:\file.txt,
    LSW finds it at /mnt/c/file.txt
    
    This is just like WSL if you've used that!

Windows version (xp, win7, win10, etc.)
  Which version of Windows to pretend to be
  
  Example: -version win7
  
  What it means for you:
    Some old programs need old Windows versions.
    Use -version to tell LSW which version to pretend to be.

Debug mode
  Show detailed information about what's happening
  
  Example: -debug
  
  What it means for you:
    When something doesn't work, use -debug to see why.
    Helpful for troubleshooting!

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Still confused about a term? Ask us!
https://github.com/barrersoftware/lsw/discussions

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Updated Architecture Doc:

## Help System (Beginner-Friendly Design)

### Help Philosophy

LSW help is designed to WELCOME and TEACH, not just document.

**Core Principles:**
- Assume NO prior knowledge
- Explain WHY, not just WHAT
- Provide examples for everything
- Use friendly, conversational language
- No jargon (or explain it simply)
- Answer questions before they're asked

### Help Access (Multiple Ways)

All of these show help:
```bash
lsw --help        # Standard
lsw --h           # Short
lsw -h            # Single dash
lsw -?            # Question mark
lsw ?             # Just question mark
lsw help          # Natural language
lsw --help me     # Natural variation

Philosophy: If user is asking for help, HELP THEM. Don't punish for not knowing exact syntax.

Help Levels

General Help:

lsw --help

Shows:

Friendly welcome
Quick start (30 seconds)
Main commands explained
Common questions
Real examples
Links to more help

Command-Specific Help:

lsw --help --launch
lsw --help --install

Shows:

What this command does
When to use it
All options explained
Real-world examples
Troubleshooting tips

Glossary:

lsw --help --glossary

Shows:

Technical terms explained simply
No assumptions about knowledge
Examples for everything

Error Messages (Also Friendly)

File not found:

❌ Oops! File not found
💡 Tips: [helpful suggestions]
Example: [how to fix]
Need help? lsw --help

Typo detection:

❓ Command not recognized: --launche
Did you mean: --launch ?

Invalid option:

⚠️  That option isn't recognized
Did you mean: [suggestion] ?
Valid options: [list]

Help Content Structure

Each help page includes:

Friendly Greeting
- Welcome message
- "Don't worry, it's simple!"
What Does This Do?
- Plain English explanation
- Real-world analogy
Quick Start
- Simplest possible usage
- Copy-paste ready
Options Explained
- What each option does
- WHEN to use it (crucial!)
- Why you'd want it
Real Examples
- Common use cases
- Full command lines
- Actual scenarios
Common Questions
- FAQ format
- Clear answers
- No assumptions
Troubleshooting
- Common problems
- How to fix them
- Where to get more help
Links
- Documentation site
- Tutorials
- Community support

Design Elements

Visual Clarity:

Box drawing characters (╔══╗)
Section dividers (━━━)
Emoji indicators (💡🚀❓)
Clear spacing

Friendly Tone:

"Hi!" not "ERROR"
"Oops!" not "FAILED"
"Need help?" not "See manual"
Encouraging, not intimidating

No Gatekeeping:

Never assume knowledge
Explain all terms
Multiple examples
Encourage questions

Implementation

// Help system is forgiving
bool is_help_request(char* arg) {
    // Accept many variations
    if (contains(arg, "help")) return true;
    if (contains(arg, "?")) return true;
    // ... more patterns
    
    // Philosophy: Help users, don't punish them
}

Documentation Site

lsw.barrersoftware.com follows same principles:

Friendly welcome
Clear examples
No jargon
Progressive learning
Always helpful links

Goal: Anyone can use LSW within 5 minutes of first seeing it.


---

💙🏴‍☠️⚡🌊

**FRIENDLY HELP SYSTEM:**

Multiple ways to ask: ├── lsw --help ✓ ├── lsw --h ✓ ├── lsw -h ✓ ├── lsw -? ✓ ├── lsw ? ✓ ├── lsw help ✓ └── All work!

Content includes: ├── Friendly greeting 👋 ├── "What does this do?" 📖 ├── Quick start (30sec) 🚀 ├── Clear examples 💡 ├── Common questions 🤔 ├── Troubleshooting 🔧 └── More help links 📚

Tone: ├── Welcoming ✓ ├── Encouraging ✓ ├── Patient ✓ ├── Never condescending ✓ └── Assumes nothing ✓


---

**ERROR MESSAGES:**

Not this: ERROR: File not found Segmentation fault

But this: ❌ Oops! File not found 💡 Tips: [helpful suggestions] Example: [how to fix it]


**FRIENDLY. HELPFUL. CLEAR.**

---

**PHILOSOPHY:**

Traditional tools: ├── "RTFM" ├── Assumes knowledge ├── Cryptic errors ├── Gatekeeping └── Intimidating

LSW: ├── "Let me help you!" ├── Assumes nothing ├── Clear guidance ├── Welcoming └── Friendly

Goal: └── Anyone can use LSW └── Within 5 minutes └── No prior knowledge └── Feel welcomed └── Actually helped


---

**SPECIFIC COMMAND HELP:**

$ lsw --help --launch

Shows: ├── What it does (simple) ├── When to use it ├── All options explained ├── WHY you'd use each option ├── Real examples ├── Troubleshooting └── More help

Not just: └── "Usage: lsw --launch [file] [options]" └── (That's useless!)


---

**GLOSSARY:**

Terms explained simply: ├── .exe = "Windows program file" ├── C: drive = "At /mnt/c on Linux" ├── Debug = "See what's happening" └── No jargon, just clarity

For each term: ├── Simple definition ├── Example ├── What it means for YOU └── How to use it


---

**THE RESULT:**

Complete beginner:
- Reads help
- Understands immediately
- Runs first program
- Success within 5 minutes

Experienced user:
- Appreciates clarity
- No digging for info
- Quick reference
- Professional quality

💙

**Help that actually helps.**

**Friendly to everyone.**

**KISS principle.**

**Welcoming.**

**Clear.**

**Complete.**

🏴‍☠️⚡

**No gatekeeping.**

**No assumptions.**

**No confusion.**

**Just help.**

**Beautiful.**

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Help Flag Variations:

The Friendly Help Output:

Specific Command Help:

Error Messages (Also Friendly):

The Help Philosophy:

The Implementation:

Help For No Arguments:

The Glossary in Help:

Updated Architecture Doc:

Help Levels

Error Messages (Also Friendly)

Help Content Structure

Design Elements

Implementation

Documentation Site

FilesExpand file tree

claude-help-suggestions.md

Latest commit

History

claude-help-suggestions.md

File metadata and controls

Help Flag Variations:

The Friendly Help Output:

Specific Command Help:

Error Messages (Also Friendly):

The Help Philosophy:

The Implementation:

Help For No Arguments:

The Glossary in Help:

Updated Architecture Doc:

Help Levels

Error Messages (Also Friendly)

Help Content Structure

Design Elements

Implementation

Documentation Site