Added additional scripts and docs.

2025-12-14 00:13:08 -05:00
parent f0bad62bc1
commit f9913eeee7
7 changed files with 1365 additions and 4 deletions
--- a/docs/ESPANSO.md
+++ b/docs/ESPANSO.md
@@ -0,0 +1,454 @@
+# Espanso Quick Reference Guide
+
+A comprehensive guide to using espanso text expansion in your dotfiles setup.
+
+## 🚀 Getting Started
+
+### Installation
+
+Espanso is automatically installed when you run the main install script:
+
+```bash
+./install.sh
+```
+
+Or install it separately:
+
+```bash
+# Ubuntu/Debian
+wget https://github.com/espanso/espanso/releases/latest/download/espanso-debian-x11-amd64.deb
+sudo apt install ./espanso-debian-x11-amd64.deb
+espanso service register
+
+# macOS
+brew tap espanso/espanso
+brew install espanso
+espanso service register
+
+# Fedora
+# See: https://espanso.org/install/
+```
+
+### Initial Setup
+
+Run the setup wizard to personalize your configuration:
+
+```bash
+./bin/setup-espanso.sh
+```
+
+This will:
+- Personalize your snippets with your information
+- Install optional espanso packages
+- Show you useful triggers and tips
+
+## ⌨️ Basic Controls
+
+| Action | Shortcut |
+|--------|----------|
+| Toggle espanso on/off | `ALT+SHIFT+E` |
+| Open search menu | `ALT+SPACE` |
+| Restart espanso | `espanso restart` |
+| Check status | `espanso status` |
+
+## 📝 Built-in Snippets
+
+### Date & Time
+
+| Trigger | Output | Example |
+|---------|--------|---------|
+| `:date` | Current date | 2024-12-13 |
+| `:time` | Current time | 14:30:45 |
+| `:datetime` | Date and time | 2024-12-13 14:30:45 |
+| `:now` | Formatted datetime | December 13, 2024 at 02:30 PM |
+
+### Emoticons & Symbols
+
+| Trigger | Output |
+|---------|--------|
+| `:shrug` | ¯\\\_(ツ)_/¯ |
+| `:flip` | (╯°□°)╯︵ ┻━┻ |
+| `:unflip` | ┬─┬ ノ( ゜-゜ノ) |
+| `:lenny` | ( ͡° ͜ʖ ͡°) |
+| `:arrow` | → |
+| `:larrow` | ← |
+| `:check` | ✓ |
+| `:cross` | ✗ |
+| `:star` | ★ |
+| `:heart` | ♥ |
+
+### Code Templates
+
+| Trigger | Output |
+|---------|--------|
+| `:bash` | Bash script template with shebang |
+| `:python` | Python script template |
+| `:shebang` | `#!/usr/bin/env bash` |
+| `:gitignore` | Complete .gitignore template |
+| `:mdcode` | Markdown code block |
+| `:mdtable` | Markdown table template |
+
+### Git Shortcuts
+
+| Trigger | Output |
+|---------|--------|
+| `:gst` | `git status` |
+| `:gco` | `git checkout ` |
+| `:gcm` | `git commit -m ""` |
+| `:glog` | `git log --oneline --graph --decorate --all` |
+
+### Docker Shortcuts
+
+| Trigger | Output |
+|---------|--------|
+| `:dps` | `docker ps` |
+| `:dcup` | `docker-compose up -d` |
+| `:dcdown` | `docker-compose down` |
+
+### Personal Information (Customizable)
+
+| Trigger | Output |
+|---------|--------|
+| `:myemail` | Your email address |
+| `:myname` | Your full name |
+| `:myphone` | Your phone number |
+| `:mywebsite` | Your website URL |
+| `:mygithub` | Your GitHub profile |
+| `:sig` | Your email signature |
+
+### Text Templates
+
+| Trigger | Output |
+|---------|--------|
+| `:lorem` | Lorem ipsum paragraph |
+| `:loremlong` | Extended lorem ipsum |
+| `:emailhi` | Email greeting template |
+| `:emailthanks` | Thank you email template |
+| `:mdheader` | Markdown document header |
+| `:meeting` | Meeting notes template |
+
+## 🎨 Creating Custom Snippets
+
+Edit your snippet files:
+
+```bash
+# Base snippets (general use)
+vim ~/.config/espanso/match/base.yml
+
+# Personal snippets (your info)
+vim ~/.config/espanso/match/personal.yml
+```
+
+### Simple Text Replacement
+
+```yaml
+matches:
+  - trigger: ":hw"
+    replace: "Hello, World!"
+```
+
+### With Variables (Dynamic Content)
+
+```yaml
+matches:
+  - trigger: ":mydate"
+    replace: "Today is {{mydate}}"
+    vars:
+      - name: mydate
+        type: date
+        params:
+          format: "%B %d, %Y"
+```
+
+### Multi-line Templates
+
+```yaml
+matches:
+  - trigger: ":email"
+    replace: |
+      Dear {{name}},
+      
+      
+      
+      Best regards,
+      Your Name
+    vars:
+      - name: name
+        type: form
+        params:
+          layout: "Recipient name: {{name}}"
+```
+
+### With Shell Commands
+
+```yaml
+matches:
+  - trigger: ":myip"
+    replace: "{{output}}"
+    vars:
+      - name: output
+        type: shell
+        params:
+          cmd: "curl -s ifconfig.me"
+```
+
+### Cursor Positioning
+
+```yaml
+matches:
+  - trigger: ":func"
+    replace: "function {{name}}() {\n    {{cursor}}\n}"
+    vars:
+      - name: name
+        type: form
+        params:
+          layout: "Function name: {{name}}"
+```
+
+## 📦 Package Management
+
+### List Installed Packages
+
+```bash
+espanso package list
+```
+
+### Install Packages
+
+```bash
+# Emoji support
+espanso install emoji --force
+
+# Greek letters
+espanso install greek-letters --force
+
+# Math symbols
+espanso install math --force
+
+# All emojis
+espanso install all-emojis --force
+```
+
+### Browse Available Packages
+
+Visit: https://hub.espanso.org/
+
+## 🔧 Configuration
+
+### Main Configuration File
+
+Location: `~/.config/espanso/config/default.yml`
+
+Key settings:
+
+```yaml
+# Toggle key
+toggle_key: ALT+SHIFT+E
+
+# Search shortcut
+search_shortcut: ALT+SPACE
+
+# Backend (Auto, Clipboard, or Inject)
+backend: Auto
+
+# Show notifications
+show_notifications: true
+
+# Auto-restart on config changes
+auto_restart: true
+```
+
+### Application-Specific Configs
+
+Create configs for specific applications:
+
+```bash
+# Only in terminal
+vim ~/.config/espanso/match/terminal.yml
+```
+
+```yaml
+filter_title: "Terminal|Konsole|iTerm"
+
+matches:
+  - trigger: ":ll"
+    replace: "ls -lah"
+```
+
+## 🛠️ Troubleshooting
+
+### Espanso Not Working
+
+1. Check if running:
+   ```bash
+   espanso status
+   ```
+
+2. Restart the service:
+   ```bash
+   espanso restart
+   ```
+
+3. Check logs:
+   ```bash
+   espanso log
+   ```
+
+### Snippets Not Expanding
+
+1. Verify the trigger syntax in your YAML files
+2. Check for YAML syntax errors:
+   ```bash
+   espanso match list
+   ```
+3. Ensure espanso is enabled (not toggled off with ALT+SHIFT+E)
+
+### Conflicts with Other Apps
+
+Some applications may conflict with espanso. Add them to the filter:
+
+```yaml
+# In config/default.yml
+filter_exec: "application_name"
+```
+
+### Clipboard Issues
+
+Try changing the backend:
+
+```yaml
+# In config/default.yml
+backend: Clipboard
+```
+
+## 📚 Advanced Features
+
+### Forms (Interactive Inputs)
+
+```yaml
+matches:
+  - trigger: ":invoice"
+    replace: |
+      Invoice #{{number}}
+      Client: {{client}}
+      Amount: ${{amount}}
+      Due: {{date}}
+    vars:
+      - name: number
+        type: form
+        params:
+          layout: |
+            Invoice Number: {{number}}
+            Client Name: {{client}}
+            Amount: {{amount}}
+            Due Date: {{date}}
+```
+
+### Choice Variables
+
+```yaml
+matches:
+  - trigger: ":env"
+    replace: "{{env}}"
+    vars:
+      - name: env
+        type: choice
+        params:
+          values:
+            - development
+            - staging
+            - production
+```
+
+### Script Variables
+
+```yaml
+matches:
+  - trigger: ":weather"
+    replace: "{{output}}"
+    vars:
+      - name: output
+        type: script
+        params:
+          args:
+            - python
+            - /path/to/weather_script.py
+```
+
+## 🔄 Backup and Sync
+
+### Backup Your Config
+
+```bash
+# Using the dotfiles system
+cd ~/.dotfiles
+git add espanso/
+git commit -m "Update espanso config"
+git push
+```
+
+### Restore on New System
+
+```bash
+# Clone dotfiles
+git clone https://github.com/YOUR_USERNAME/dotfiles.git ~/.dotfiles
+cd ~/.dotfiles
+
+# Install
+./install.sh
+
+# Personalize
+./bin/setup-espanso.sh
+```
+
+## 📖 Resources
+
+- [Official Documentation](https://espanso.org/docs/)
+- [Package Hub](https://hub.espanso.org/)
+- [GitHub Repository](https://github.com/espanso/espanso)
+- [Community Forum](https://github.com/espanso/espanso/discussions)
+
+## 💡 Tips & Best Practices
+
+1. **Use consistent prefixes**: Start all triggers with `:` to avoid accidents
+2. **Keep it organized**: Separate snippets by category in different files
+3. **Test before committing**: Verify new snippets work before adding to git
+4. **Use descriptive triggers**: Make triggers memorable and logical
+5. **Leverage forms**: Use forms for snippets that need customization
+6. **Back up regularly**: Keep your config in version control
+7. **Share useful snippets**: Contribute to the community hub
+
+## 🎯 Common Use Cases
+
+### Developer Workflow
+
+```yaml
+:fixme    → // FIXME: 
+:todo     → // TODO: 
+:note     → // NOTE: 
+:debug    → console.log('DEBUG:', );
+```
+
+### Writing & Documentation
+
+```yaml
+:doc      → Documentation template
+:readme   → README.md template
+:license  → MIT License text
+:quote    → > Blockquote
+```
+
+### Communication
+
+```yaml
+:ty       → Thank you
+:yw       → You're welcome
+:lgtm     → Looks good to me
+:wip      → Work in progress
+```
+
+---
+
+**Happy expanding!** 🚀
+
+For questions or issues, check the [espanso documentation](https://espanso.org/docs/) or open an issue in your dotfiles repository.
--- a/docs/SETUP_GUIDE.md
+++ b/docs/SETUP_GUIDE.md
@@ -0,0 +1,278 @@
+# Dotfiles Repository Setup Checklist
+
+Use this checklist to ensure your dotfiles repository is complete and ready to use.
+
+## 📋 File Structure
+
+### Core Files
+- [ ] `README.md` - Main documentation (use the artifact provided)
+- [ ] `LICENSE` - MIT License file
+- [ ] `.gitignore` - Git ignore rules
+- [ ] `install.sh` - Main installation script
+
+### Zsh Configuration
+- [ ] `zsh/.zshrc` - Main zsh config
+- [ ] `zsh/themes/adlee.zsh-theme` - Custom theme
+- [ ] `zsh/.zshrc.local.example` - Template for local settings (optional)
+
+### Espanso Configuration
+- [ ] `espanso/config/default.yml` - Espanso settings
+- [ ] `espanso/match/base.yml` - Base snippets
+- [ ] `espanso/match/personal.yml` - Personal snippets
+
+### Git Configuration
+- [ ] `git/.gitconfig` - Git settings
+- [ ] `git/.gitignore_global` - Global gitignore (optional)
+
+### Other Configs
+- [ ] `vim/.vimrc` - Vim config (if you use vim)
+- [ ] `tmux/.tmux.conf` - Tmux config (if you use tmux)
+
+### Utility Scripts
+- [ ] `bin/update-dotfiles` - Update script
+- [ ] `bin/setup-espanso.sh` - Espanso wizard
+- [ ] `bin/deploy-zshtheme-systemwide.sh` - System-wide deployment
+
+### Documentation
+- [ ] `docs/SETUP_GUIDE.md` - Detailed setup guide
+- [ ] `docs/ESPANSO.md` - Espanso reference
+- [ ] `CHECKLIST.md` - This file
+
+## 🔧 Setup Steps
+
+### 1. Create Directory Structure
+```bash
+cd ~/.dotfiles
+mkdir -p zsh/themes
+mkdir -p espanso/config espanso/match
+mkdir -p git
+mkdir -p vim
+mkdir -p tmux
+mkdir -p bin
+mkdir -p docs
+```
+
+### 2. Create/Copy Configuration Files
+
+- [ ] Copy your existing `.zshrc` to `zsh/.zshrc`
+- [ ] Copy your theme to `zsh/themes/adlee.zsh-theme`
+- [ ] Copy espanso configs from `~/.config/espanso/` to `espanso/`
+- [ ] Copy `.gitconfig` to `git/.gitconfig`
+- [ ] Copy `.vimrc` to `vim/.vimrc` (if exists)
+- [ ] Copy `.tmux.conf` to `tmux/.tmux.conf` (if exists)
+
+### 3. Create Scripts
+
+Download or create these scripts from the artifacts:
+- [ ] `install.sh`
+- [ ] `bin/update-dotfiles`
+- [ ] `bin/setup-espanso.sh`
+- [ ] `bin/deploy-zshtheme-systemwide.sh`
+
+Make them executable:
+```bash
+chmod +x install.sh
+chmod +x bin/*
+```
+
+### 4. Create Documentation
+
+- [ ] Create `README.md` (use artifact provided)
+- [ ] Create `docs/SETUP_GUIDE.md` (artifact provided earlier)
+- [ ] Create `docs/ESPANSO.md` (artifact provided earlier)
+
+### 5. Create .gitignore
+
+```bash
+cat > .gitignore << 'EOF'
+# OS files
+.DS_Store
+Thumbs.db
+
+# Backup files
+*.backup
+*.bak
+*~
+
+# Local machine-specific configs
+*.local
+.zshrc.local
+
+# Sensitive information
+.env
+.env.*
+secrets/
+
+# Optional: Uncomment if personal espanso info is sensitive
+# espanso/match/personal.yml
+
+# Espanso backup files
+espanso/match/*.backup
+EOF
+```
+
+### 6. Create LICENSE
+
+```bash
+cat > LICENSE << 'EOF'
+MIT License
+
+Copyright (c) 2024 Aaron D. Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+EOF
+```
+
+## 🐙 GitHub Setup
+
+### 1. Create Repository
+- [ ] Go to https://github.com/new
+- [ ] Name: `dotfiles`
+- [ ] Description: "Personal configuration files and automation scripts"
+- [ ] Visibility: Public or Private
+- [ ] Don't initialize with README (you already have one)
+- [ ] Click "Create repository"
+
+### 2. Initialize Git
+```bash
+cd ~/.dotfiles
+git init
+git add .
+git commit -m "Initial commit: Add dotfiles and custom zsh theme"
+```
+
+### 3. Add Remote and Push
+```bash
+# Replace adlee-was-taken with your GitHub username
+git remote add origin https://github.com/adlee-was-taken/dotfiles.git
+git branch -M main
+git push -u origin main
+```
+
+### 4. Update URLs in Files
+- [ ] Update `install.sh` - Replace `adlee-was-taken` in `DOTFILES_REPO`
+- [ ] Update `README.md` - Replace all `adlee-was-taken` references
+- [ ] Update `docs/SETUP_GUIDE.md` - Replace `adlee-was-taken`
+
+```bash
+# Quick find all instances
+grep -r "adlee-was-taken" .
+```
+
+## ✅ Verification
+
+### Test Local Installation
+- [ ] Test install script on local machine
+  ```bash
+  # Dry run first
+  bash -n install.sh  # Check for syntax errors
+  
+  # Then test (will backup existing configs)
+  ./install.sh
+  ```
+
+- [ ] Verify symlinks were created correctly
+  ```bash
+  ls -la ~ | grep "^l"  # Show all symlinks in home
+  ```
+
+- [ ] Test zsh theme
+  ```bash
+  source ~/.zshrc
+  # Check if prompt looks correct
+  ```
+
+- [ ] Test espanso
+  ```bash
+  espanso status
+  # Try typing: ..date
+  ```
+
+### Test GitHub Setup
+- [ ] Clone on a test directory
+  ```bash
+  cd /tmp
+  git clone https://github.com/adlee-was-taken/dotfiles.git test-dotfiles
+  cd test-dotfiles
+  ./install.sh
+  ```
+
+### Test System-wide Deployment
+- [ ] Check current status
+  ```bash
+  sudo ./bin/deploy-zshtheme-systemwide.sh --status
+  ```
+
+- [ ] Test deployment
+  ```bash
+  sudo ./bin/deploy-zshtheme-systemwide.sh --current
+  ```
+
+## 📝 Final Touches
+
+### Customize Personal Info
+- [ ] Edit `espanso/match/personal.yml` with your info
+- [ ] Edit `git/.gitconfig` with your name and email
+- [ ] Update `README.md` with your GitHub username
+- [ ] Update any other personal references
+
+### Optional Enhancements
+- [ ] Add GitHub Actions for linting (optional)
+- [ ] Add screenshots to README
+- [ ] Create a demo GIF of the theme
+- [ ] Add more espanso snippets for your workflow
+- [ ] Create shell aliases in `.zshrc`
+
+### Security Check
+- [ ] Ensure no sensitive info in committed files
+  ```bash
+  # Search for potential secrets
+  grep -rE '(password|secret|token|key)' . --exclude-dir=.git
+  ```
+
+- [ ] Verify `.gitignore` is working
+  ```bash
+  git status  # Should not show .local files or sensitive data
+  ```
+
+## 🎉 You're Done!
+
+Once all items are checked:
+- [ ] Commit any final changes
+  ```bash
+  git add .
+  git commit -m "Complete repository setup"
+  git push
+  ```
+
+- [ ] Test on a second machine (if available)
+- [ ] Star your own repo (you deserve it! 😄)
+- [ ] Share with others who might find it useful
+
+## 📚 Next Steps
+
+- Read through `docs/SETUP_GUIDE.md` for detailed usage
+- Explore `docs/ESPANSO.md` for all available snippets
+- Customize the theme colors in `zsh/themes/adlee.zsh-theme`
+- Add more aliases to `.zshrc`
+- Consider contributing to the espanso community hub
+
+---
+
+**Need help?** Open an issue in your repository or check the documentation files.