rtfm-filemanager 7.3.6 → 7.4.0

data/docs/faq.md

@@ -0,0 +1,436 @@
+# RTFM Frequently Asked Questions
+
+Quick answers to common questions.
+
+## General
+
+### What does RTFM stand for?
+
+**Ruby Terminal File Manager**
+
+(Not the other thing... well, maybe also that if you need to Read The Fine Manual!)
+
+### Is RTFM better than ranger?
+
+**Different, not better.**
+
+- **RTFM**: More features, SSH browsing, undo system, AI integration, trash bin
+- **Ranger**: More mature, better documentation, larger community, cleaner design
+
+Choose based on your needs. See [RTFM vs Ranger comparison](../README.md#rtfm-vs-ranger).
+
+### Can I use RTFM on Windows?
+
+**Limited support.**
+
+Core functionality works on Windows, but:
+- ✗ No image display
+- ✗ No w3m/xdotool features
+- ✓ File operations work
+- ✓ Remote SSH works
+
+**Recommended:** Use WSL (Windows Subsystem for Linux) for full features.
+
+### Does RTFM work on macOS?
+
+**Yes!** Fully supported.
+
+Install with:
+```bash
+brew install ruby imagemagick w3m bat pandoc
+gem install rtfm-filemanager
+```
+
+### What terminals work best?
+
+**Best image support:**
+- urxvt (w3m protocol) - Perfect
+- xterm (Sixel protocol) - Perfect
+- mlterm (Sixel protocol) - Perfect
+- Eterm (w3m protocol) - Perfect
+
+**Good:**
+- kitty (w3m with brief flash)
+- foot (Sixel)
+- alacritty (no persistent images)
+
+## Installation & Setup
+
+### Do I need to install dependencies manually?
+
+**Core:** No, gems auto-install (rcurses, termpix)
+
+**Optional features:** Yes, install as needed:
+- ImageMagick (images)
+- bat (syntax highlighting)
+- pandoc (markdown)
+- fzf (fuzzy find)
+
+See [Installation Guide](getting-started.md#installation).
+
+### How do I update RTFM?
+
+```bash
+gem update rtfm-filemanager
+```
+
+This also updates dependencies (rcurses, termpix).
+
+### Can I install from source?
+
+**Yes:**
+```bash
+git clone https://github.com/isene/RTFM
+cd RTFM
+gem install rcurses termpix
+sudo cp bin/rtfm /usr/bin/
+```
+
+### Where are config files stored?
+
+```
+~/.rtfm/
+├── conf              # Main configuration
+├── trash/            # Deleted items (if trash enabled)
+├── bootsnap-cache/   # Performance cache
+└── plugins/
+    ├── preview.rb    # Custom preview handlers
+    └── keys.rb       # Custom key bindings
+```
+
+## Features
+
+### How do I enable the trash bin?
+
+**In RTFM:** Press `Ctrl-d` to toggle
+
+**In config:**
+```ruby
+# ~/.rtfm/conf
+@trash = true
+```
+
+**Restore deleted items:** Press `U` (undo)
+
+**Empty trash:** Press `D`
+
+### Can I undo file operations?
+
+**Yes!** Press `U` to undo:
+- Delete (from trash)
+- Move
+- Rename
+- Copy
+- Symlink
+- Bulk rename
+- Permission changes
+- Ownership changes
+
+**Cannot undo:**
+- Permanent deletion (trash disabled)
+- Failed operations
+
+### How do I use the AI features?
+
+**Setup:**
+1. Get OpenAI API key: https://platform.openai.com/api-keys
+2. Add to config:
+   ```ruby
+   @ai = "sk-your-api-key-here"
+   ```
+3. Install gem: `gem install ruby-openai`
+
+**Usage:**
+- Press `I` on file for AI description
+- Press `Ctrl-a` for AI chat
+
+### Does RTFM support tabs?
+
+**Yes!** Enhanced tab system:
+- `]` - New tab
+- `[` - Close tab
+- `J/K` - Switch tabs
+- `}` - Duplicate tab
+- `{` - Rename tab
+- `1-9` - Jump to tab number
+
+### Can I browse remote servers?
+
+**Absolutely!** Press `Ctrl-e`:
+
+```
+user@server.com:/path/to/directory
+```
+
+Then:
+- `d` - Download files
+- `u` - Upload files
+- `s` - Open SSH shell
+
+See [Remote Browsing Guide](remote-browsing.md).
+
+### How do I copy images to clipboard?
+
+**Press `Ctrl-y` when viewing an image.**
+
+Then paste into:
+- GIMP
+- Inkscape
+- Image editors
+- Browsers
+
+Works with PNG, JPEG, GIF, BMP, WebP.
+
+### Can I customize key bindings?
+
+**Yes!** Edit `~/.rtfm/plugins/keys.rb`:
+
+```ruby
+KEYMAP['X'] = :my_custom_action
+
+def my_custom_action(_chr)
+  @pB.say("Custom action!")
+end
+```
+
+See [Plugin Guide](plugins.md).
+
+## Usage
+
+### How do I exit to current directory?
+
+**Use the `r` command** (set up automatically on first run).
+
+Workflow:
+```bash
+r              # Launch RTFM
+# Navigate to ~/Documents/projects
+q              # Quit
+pwd            # Now in ~/Documents/projects
+```
+
+### How do I copy multiple files?
+
+1. Tag files: Press `t` on each file
+2. Navigate to destination
+3. Press `p` to copy
+
+**Or:** Tag with pattern:
+- `Ctrl-t` then `*.txt` (tag all .txt files)
+
+### How do I rename multiple files?
+
+1. Tag files with `t`
+2. Press `E` (bulk rename)
+3. Enter pattern:
+   - `s/old/new/` - Replace text
+   - `PREFIX_#` - Add prefix with numbers
+   - `upper` / `lower` - Change case
+
+### How do I change permissions on multiple files?
+
+1. Tag files with `t`
+2. Press `Ctrl-p`
+3. Enter permissions:
+   - `755`
+   - `rwxr-xr-x`
+   - `+x` (add execute)
+   - `-w` (remove write)
+
+**v7.2+ Note:** Only tagged files affected (not selected unless tagged)
+
+### What's the difference between `p` and `P`?
+
+- `p` - **Copy** tagged items (original stays)
+- `P` - **Move** tagged items (original removed)
+
+Both preserve selection after operation (v7.2+).
+
+### How do I preview without opening?
+
+Files auto-preview in right pane when selected.
+
+**Toggle preview:** Press `-`
+
+**Scroll preview:**
+- `Shift-↓/↑` - Line by line
+- `TAB` - Page down
+- `Shift-TAB` - Page up
+
+### Can I execute shell commands?
+
+**Yes!** Press `:` then enter command:
+```
+:ls -la
+:git status
+:grep -r pattern .
+```
+
+Output shows in right pane.
+
+**History:** Press `;` to see command history
+
+## Comparison Questions
+
+### RTFM vs ranger?
+
+**RTFM advantages:**
+- SSH/SFTP browsing built-in
+- Comprehensive undo system
+- Trash bin with restore
+- OpenAI integration
+- Permission/ownership undo
+- Smaller codebase
+
+**Ranger advantages:**
+- Larger community
+- Better documentation (working on it!)
+- More mature/stable
+- Multi-column view
+
+### RTFM vs mc (Midnight Commander)?
+
+**RTFM advantages:**
+- Modern design
+- Better image support
+- Git integration
+- AI features
+- Undo system
+
+**mc advantages:**
+- More established (since 1994)
+- Built-in editor (mcedit)
+- FTP support
+- Virtual file systems
+
+### Why not use GUI file manager?
+
+**Benefits of terminal file managers:**
+- ⚡ Faster (keyboard-driven)
+- 🖥️ Works over SSH
+- 🎯 Precision control
+- 🔧 Scriptable/extensible
+- 💻 No X server needed
+- ⌨️ Never leave terminal
+
+**RTFM specifically:**
+- Parses LS_COLORS (consistent theming)
+- Inline images
+- Command execution with output
+- Ruby extensibility
+
+## Technical Questions
+
+### What is rcurses?
+
+**rcurses** is a pure Ruby curses library created specifically for RTFM.
+
+- No C bindings
+- Ruby 3.4+ compatible
+- Modern design
+- Easy to maintain
+
+See: https://github.com/isene/rcurses
+
+### What is termpix?
+
+**termpix** is a terminal image display library extracted from RTFM.
+
+- Multi-protocol support (Sixel, w3m)
+- EXIF auto-orient
+- Used by RTFM, AstroPanel, IMDB
+
+See: https://github.com/isene/termpix
+
+### Why single-file architecture?
+
+**Benefits:**
+- Easy to understand (all code in one place)
+- Simple deployment (one file)
+- No require complexity
+- Easier debugging
+
+**Trade-offs:**
+- Large file (~6K lines)
+- Not modular
+- But: Organized with vim folds
+
+### Can I contribute?
+
+**Yes!**
+
+- Bug reports: https://github.com/isene/RTFM/issues
+- Feature requests: Open issue with detailed description
+- Pull requests: Welcome!
+- Plugins: Share in issues/discussions
+
+### Is RTFM actively maintained?
+
+**Yes!** Regular updates and releases.
+
+Recent activity:
+- v7.3 (Nov 2025) - Image display improvements
+- v7.2 (Oct 2025) - Batch operation consistency
+- v7.1 (Oct 2025) - Archive preview
+
+Check: https://github.com/isene/RTFM/releases
+
+## Workflow Questions
+
+### Best workflow for organizing photos?
+
+```
+r                    # Launch RTFM
+@lsorder = "-t"     # Sort by time (newest first)
+@showimage = true   # Show images
+# Tag keepers with 't'
+P                   # Move to organized folder
+```
+
+### Best workflow for code projects?
+
+```
+r                # Launch
+m p             # Bookmark project directory
+@batuse = true  # Syntax highlighting
+@lsall = "-a"   # Show hidden (.git, etc.)
+G               # Check git status
+```
+
+### How to quickly check server logs?
+
+```
+r
+Ctrl-e                        # Remote mode
+admin@server:/var/log        # Connect
+# Navigate to log file
+# Content shows in right pane
+s                             # Open shell if needed
+```
+
+### Bulk file organization?
+
+```
+r
+Ctrl-t           # Tag by pattern
+*.jpg           # Tag all JPEGs
+P               # Move to new folder
+```
+
+## Still Have Questions?
+
+1. **Check documentation:**
+   - `man rtfm`
+   - Press `?` in RTFM
+   - Read [guides](../README.md#documentation)
+
+2. **Search issues:**
+   https://github.com/isene/RTFM/issues
+
+3. **Ask:**
+   - Open new issue
+   - Email: g@isene.com
+
+---
+
+[← Troubleshooting](troubleshooting.md) | [Back to README](../README.md)

data/docs/getting-started.md

@@ -0,0 +1,276 @@
+# Getting Started with RTFM
+
+This guide will get you up and running with RTFM in minutes.
+
+## Installation
+
+### Quick Install (Recommended)
+
+```bash
+gem install rtfm-filemanager
+```
+
+### With Full Features (Ubuntu/Debian)
+
+```bash
+sudo apt update
+sudo apt install ruby-full x11-utils xdotool bat pandoc poppler-utils \
+  odt2txt docx2txt unzip gnumeric catdoc w3m imagemagick \
+  ffmpegthumbnailer tar gzip bzip2 xz-utils unrar p7zip-full
+
+gem install rtfm-filemanager
+```
+
+### macOS
+
+```bash
+brew install ruby imagemagick w3m bat pandoc poppler
+gem install rtfm-filemanager
+```
+
+## First Launch
+
+```bash
+rtfm
+```
+
+On first run, RTFM will:
+1. Show a welcome message
+2. Add `r` function to your shell config (~/.bashrc or ~/.zshrc)
+3. Create `~/.rtfm/` directory with plugins and config
+
+Press `q` to accept and continue.
+
+## The `r` Command
+
+After installation, you can launch RTFM with just:
+
+```bash
+r
+```
+
+The magic: When you quit RTFM (press `q`), you'll be in RTFM's current directory, not where you launched it.
+
+**Example workflow:**
+```bash
+r                    # Launch RTFM
+# Navigate to ~/Documents/projects
+q                    # Quit RTFM
+pwd                  # You're in ~/Documents/projects
+r                    # Launch RTFM again (remembers location)
+```
+
+## Basic Navigation
+
+### Moving Around
+
+| Key | Action |
+|-----|--------|
+| `↓` or `j` | Move down |
+| `↑` or `k` | Move up |
+| `→` or `l` or `ENTER` | Enter directory / open file |
+| `←` or `h` | Go to parent directory |
+| `HOME` | Jump to first item |
+| `END` | Jump to last item |
+| `PgDn` | Page down |
+| `PgUp` | Page up |
+
+### Understanding the Interface
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Path: /home/user/Documents (drwxr-xr-x...) [Tab: 1/3]  │ ← Top bar (path + metadata)
+├──────────────┬──────────────────────────────────────────┤
+│ projects/    │ # My Projects                            │
+│ photos/      │                                          │
+│ > notes.txt  │ This is the content of notes.txt         │ ← Right pane (preview)
+│ todo.md      │ shown with syntax highlighting...        │
+│ report.pdf   │                                          │
+│              │                                          │
+└──────────────┴──────────────────────────────────────────┘
+│ Status: 5 items                                         │ ← Bottom bar (status)
+└─────────────────────────────────────────────────────────┘
+  Left pane ↑        Right pane ↑
+  (navigate)         (preview)
+```
+
+## Essential Operations
+
+### Viewing Files
+
+- **Preview**: Content shows in right pane automatically
+- **Open in editor**: Press `ENTER` on text files
+- **Open with default app**: Press `x` on files (xdg-open)
+- **Toggle preview**: Press `-` to turn preview on/off
+- **Toggle images**: Press `_` to toggle image display
+
+### Working with Files
+
+#### Copy
+1. Tag files with `t` (toggle tag on/off)
+2. Navigate to destination directory
+3. Press `p` to copy tagged items
+
+#### Move
+1. Tag files with `t`
+2. Navigate to destination
+3. Press `P` to move tagged items
+
+#### Delete
+1. Press `d` on item (or tag multiple with `t` first)
+2. Press `y` to confirm
+
+**Trash bin:** Press `Ctrl-d` to enable trash bin. Deleted items go to `~/.rtfm/trash/` and can be restored with `U` (undo).
+
+#### Rename
+- **Single file**: Press `c`, edit name, press ENTER
+- **Bulk rename**: Tag files with `t`, press `E`, use pattern
+
+### Bookmarks
+
+**Set bookmark:**
+1. Navigate to directory
+2. Press `m`
+3. Press letter (a-z)
+
+**Jump to bookmark:**
+1. Press `'` (apostrophe)
+2. Press bookmark letter
+
+**Special bookmarks:**
+- `'` - Last directory (for quick toggling)
+- `0` - Directory where RTFM started
+- `1-5` - Last 5 visited directories
+
+## Getting Help
+
+### In RTFM
+
+Press `?` to show complete keyboard reference
+
+### Man Page
+
+```bash
+man rtfm
+```
+
+### Version Info
+
+Press `v` to see:
+- RTFM version
+- Image protocol in use
+- Latest available version
+
+## Common Tasks
+
+### Browse Directory Tree
+
+```bash
+r                # Launch RTFM
+h h h           # Go up 3 levels
+' h             # Jump to home bookmark
+l               # Enter directory
+```
+
+### Find and Open File
+
+```bash
+r                # Launch
+/pattern        # Search for pattern
+n               # Next match
+ENTER           # Open file
+```
+
+### Copy Files Between Directories
+
+```bash
+r                # Launch
+m s             # Bookmark source as 's'
+' s             # Jump to source
+t t t           # Tag 3 files
+m d             # Bookmark destination as 'd'
+' d             # Jump to destination
+p               # Copy tagged files here
+```
+
+### Remote File Management
+
+```bash
+r                          # Launch
+Ctrl-e                     # Enter remote mode
+user@server.com:/path     # Enter connection
+# Navigate with arrow keys
+d                          # Download file
+Ctrl-e                     # Exit remote mode
+```
+
+## Tips & Tricks
+
+### Speed Tips
+
+1. **Turn off preview** (`-`) for faster directory traversal
+2. **Use bookmarks** (`m` + letter) for frequent locations
+3. **Use tabs** (`]` to create) for multi-directory work
+4. **Recent files** (`Ctrl-r`) to jump to recently accessed files
+
+### Power User Tips
+
+1. **Undo system** - `U` undoes: delete, move, rename, copy, symlink, permissions, ownership
+2. **Pattern rename** - `E` for bulk rename with regex
+3. **Command mode** - `:` to run any shell command, output in right pane
+4. **Ruby mode** - `@` to execute Ruby code (for debugging or scripting)
+5. **Git workflow** - `G` shows git status, perfect for checking changes
+
+### Workflow Examples
+
+#### Photo Organization
+```
+r → Navigate to photos → t t t (tag) → P (move to new folder)
+```
+
+#### Code Review
+```
+r → / .rb (search) → G (git status) → ENTER (open in editor)
+```
+
+#### Remote Backup
+```
+r → Ctrl-e → server:/backup → u (upload tagged files)
+```
+
+## Next Steps
+
+- Read [Configuration Guide](configuration.md) to customize RTFM
+- Learn [Remote Browsing](remote-browsing.md) for SSH workflows
+- Explore [Plugins](plugins.md) to extend functionality
+- Check [Keyboard Reference](keyboard-reference.md) for all keys
+
+## Troubleshooting
+
+### Images Don't Show
+
+1. Check if w3m is installed: `which w3mimgdisplay`
+2. Check if xdotool is installed: `which xdotool`
+3. Press `v` to see image protocol (should show `w3m` or `sixel`)
+4. Try toggling image preview: `_`
+
+### Commands Don't Work in Command Mode
+
+Some commands need to be whitelisted as "interactive":
+1. Press `+` in RTFM
+2. Type program name (e.g., `htop`)
+3. Or prefix command with `§`: `:§htop`
+
+### Terminal Resize Issues
+
+Press `r` to manually refresh RTFM layout
+
+### General Issues
+
+1. Press `r` to refresh
+2. Check `~/.rtfm/conf` for misconfigurations
+3. Report bugs: https://github.com/isene/RTFM/issues
+
+---
+
+[← Back to README](../README.md) | [Next: Configuration →](configuration.md)