DropLyx

Real-time collaborative editing for LyX files via Dropbox

Author: Johannes Emmerling (assisted by Claude)

DropLyx is a lightweight system tray application that enables collaborative editing of LyX documents through Dropbox. It provides file locking, conflict detection, and automatic merging of changes when multiple users edit the same document.

Features

• File Locking: Prevents conflicts by locking files while you're editing them
• Real-time Monitoring: Automatically detects when you open/close LyX files
• Smart Auto-Merge: Automatically merges non-conflicting changes from multiple editors
• Merge on Save (Optional): When enabled, automatically merges remote changes when you save, allowing you to see others' changes in LyX immediately (requires reload)
• Dropbox Conflict Resolution: Automatically detects and merges Dropbox conflict files using three-way merge
• Visual Status Indicators:
  • Dark Blue: Monitoring, no files open
  • Green: You're editing files (all good)
  • Red: Someone else is editing a file
• Desktop Notifications: Get notified when files are locked/unlocked or when remote changes occur
• Recursive Folder Monitoring: Watches entire folder trees including subfolders
• Conflict Resolution: Creates backup files when automatic merging isn't possible

How It Works

1. File Detection: DropLyx monitors LyX processes and detects open files by parsing window titles
2. Lock Creation: When you open a file, DropLyx creates a .lock file and a .baseline copy
3. Change Detection: Uses SHA256 hashing to detect when files are modified remotely (via Dropbox sync)
4. 3-Way Merge: When you close a file with remote changes, it performs a Git-style 3-way merge:
   • Baseline: Original file when you started editing
   • Local: Your changes
   • Remote: Changes from other users
5. Auto-Merge: If changes don't conflict, they're automatically merged. Otherwise, backup files are created for manual resolution.
6. Dropbox Conflict Handling: If Dropbox creates its own conflict files (e.g., "file (conflicted copy 2024-01-15).lyx"), DropLyx automatically detects them, performs a three-way merge with the original file, and removes the conflict file if successful.

Installation

Option 1: Download Pre-built Binary

Windows:

1. Download the DropLyx-windows.zip file from the Releases page.
2. Extract the entire folder to your desired location.
3. Run DropLyx.exe from the extracted folder.

Linux: Download the Linux binary or AppImage from the Releases page.

macOS: Download DropLyx.app from the Releases page. On first launch, you may need to right-click and select "Open" to bypass Gatekeeper.

Option 2: Build from Source

Windows:

Requirements:

• Python 3.8+
• Dependencies listed in requirements.txt

Steps:

1. Clone the repository:

   git clone https://github.com/yourusername/droplyx.git
   cd droplyx

2. Install dependencies:

   pip install -r requirements.txt

3. Run directly:

   python DropLyx.py

4. Or build executable:

   pyinstaller DropLyx.spec

   The executable will be in the dist folder.

Linux:

See BUILD_LINUX.md for detailed Linux compilation instructions including system dependencies and AppImage creation.

macOS:

See BUILD_MACOS.md for detailed macOS compilation instructions including .app bundle creation and notarization.

Usage

1. First Launch:

   • Run DropLyx.exe
   • Select your Dropbox folder (or any folder containing .lyx files)
   • The app will minimize to the system tray

2. Monitor Status:

   • Dark blue icon: Ready, monitoring for LyX files
   • Green icon: You're editing a file
   • Red icon: Someone else has a file locked

3. Work as Normal:

   • Open and edit LyX files as usual
   • DropLyx automatically creates locks
   • If someone else edited the file, you'll get a notification
   • IMPORTANT: If LyX shows "Document externally modified", click "Ignore" or "No" - do NOT reload! DropLyx will merge changes automatically when you close the file.

4. Auto-Merge:

   • When you close a file, DropLyx automatically merges remote changes
   • If conflicts exist, backup files are created:
     • .remote_backup: The other user's version
     • .local_backup: Your version
     • .pre_merge_backup: File state before merge attempt

5. System Tray Menu:

   • Right-click the icon for options
   • Add/remove watched folders
   • Toggle "Merge on Save" feature
   • Check status
   • Quit the application

6. Merge on Save (Optional Feature):

   • Enable this from the system tray menu
   • When enabled, DropLyx detects when you save a file
   • If remote changes exist, they're automatically merged into your file
   • You'll get a notification to reload the file in LyX (File > Revert)
   • This allows you to see collaborators' changes without closing the file
   • Note: You must reload the file in LyX after each save to see the merged changes

Configuration

Settings are stored in ~/.lyx_sync_config.json:

{
  "watch_dirs": [
    "C:\\Users\\YourName\\Dropbox\\LyX"
  ],
  "merge_on_save": false
}

Technical Details

File Lock Format

Lock files contain the username of the person editing:

filename.lyx.lock

Baseline Tracking

Baseline files are created when editing starts:

filename.lyx.baseline

Merge Algorithm

• Line-by-line comparison of baseline, local, and remote versions
• Changes that don't overlap are automatically merged
• Conflicting changes (same line edited differently) trigger manual resolution

Conflict Detection

A conflict occurs when:

1. Baseline ≠ Local (you changed the line)
2. Baseline ≠ Remote (they changed the line)
3. Local ≠ Remote (changes differ)

Limitations

• Platform-Specific File Detection:
  • Windows: Uses Win32 API for window title parsing
  • Linux: Uses /proc filesystem and open file descriptors
• LyX Specific: Designed specifically for LyX files
• Dropbox Sync: Relies on Dropbox (or similar sync service) to sync files between machines
• Line-based Merging: Merge is line-based, not semantic (works well for LaTeX/LyX structure)

Troubleshooting

File detection not working:

• Ensure LyX window titles contain the filename and folder path
• Check that watched folder includes the file location

Merge conflicts:

• Review backup files (.local_backup, .remote_backup)
• Manually resolve differences
• Copy resolved version over main file

Lock files not removed:

• Close DropLyx properly (right-click > Quit)
• Or manually delete .lock files

Dependencies

• Pillow: Icon generation
• pystray: System tray integration
• psutil: Process monitoring
• plyer: Desktop notifications

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

MIT License - See LICENSE file for details

Acknowledgments

• LyX logo courtesy of the LyX project
• Inspired by collaborative editing needs in academic research
• Co-developed with Claude (Anthropic AI assistant) for performance optimization and multi-platform support

Support

For issues, questions, or feature requests, please open an issue on GitHub.

---

Note: DropLyx is a community project and is not officially affiliated with LyX or Dropbox.