πŸ“ EduMerge Docs

EduMerge Documentation

Complete guide to using EduMerge's text editor and mail merge features

Getting Started

What is EduMerge?

EduMerge is a powerful, student-focused text editor with integrated mail merge capabilities. Built with Python and ttkbootstrap, it provides:

✍️ Rich Text Editing

Full formatting support with bold, italic, underline, and custom fonts

πŸ”„ Mail Merge

Automate personalized document creation for multiple recipients

πŸ“€ Multiple Formats

Support for TXT, CSV, DOCX, and PDF files

πŸ”’ Privacy First

All processing happens locallyβ€”no cloud, no tracking

Requirements

Installation

Step 1: Clone the Repository

git clone https://github.com/aksgamigg/EduMerge.git
cd EduMerge

Step 2: Install Dependencies

Run the automatic dependency installer:

python dependency-installer.py

This will install all required libraries:

⚠️ Important: After installation, restart your terminal to ensure all dependencies are recognized.

Step 3: Verify Installation

Run the diagnostics tool to check if everything is properly installed:

python diagnostics.py

Step 4: Launch EduMerge

python EduMerge.py
βœ… Success! You should now see the EduMerge starting window.

Text Editor

Interface Overview

The text editor features a modern three-panel layout:

Basic Operations

Creating a New Document

  1. Click πŸ“„ New Document in the sidebar
  2. If you have unsaved changes, you'll be prompted to save
  3. Start typing in the text area

Opening Files

EduMerge supports multiple file formats:

Saving Files

Text Formatting

Basic Styles

Style Button Shortcut Usage
Bold 𝐁 Ctrl+B Emphasis, headings
Italic 𝐼 Ctrl+I Emphasis, quotes
Underline UΜ² Ctrl+U Important text

Headings

πŸ’‘ Tip: Select text first, then click the formatting button. To remove formatting, select the text and click the button again.

Fonts

Change font family and size using the toolbar:

Colors

Inserting Content

Images

  1. Click πŸ–ΌοΈ Insert Image in sidebar
  2. Select image file (PNG, JPG, GIF, BMP supported)
  3. Image is automatically resized if wider than 700px
⚠️ Note: Images are embedded in the document but lost when saving as .txt. Use DOCX export to preserve images.

CSV Tables

  1. Click πŸ“Š CSV Table in sidebar
  2. Open a CSV file
  3. View data in searchable, paginated table format

Exporting Documents

Export to DOCX

Creates a Microsoft Word document:

# Click "πŸ“„ Export DOCX" in sidebar
# Choose save location
# Each paragraph becomes a separate Word paragraph

Export to PDF

For PDF export, use one of these methods:

  1. Export to DOCX first, then convert using Word/LibreOffice
  2. Use your browser's "Print to PDF" feature

Mail Merge

What is Mail Merge?

Mail Merge automates the creation of personalized documents for multiple recipients. Perfect for:

Step-by-Step Guide

Step 1: Launch Mail Merge

  1. Run python EduMerge.py
  2. Click πŸ“§ Mail Merge on the starting screen

Step 2: Enter Recipient Names

You have two options:

Option A: Manual Insert
  1. Choose "Manual Insert"
  2. Enter the number of recipients (minimum 2)
  3. Enter each name when prompted
  4. Names are automatically converted to Title Case
πŸ’‘ Valid Names: Names can only contain letters, spaces, and hyphens (e.g., "John Smith", "Mary-Jane")
Option B: Text File
  1. Choose "Text File"
  2. Prepare a .txt file with names in this format:
Alice Johnson, Bob Williams, Charlie Brown, Diana Prince

Step 3: Create Letter Content

Use the special placeholder [name] where you want the recipient's name to appear:

Dear [name],

Congratulations on your excellent performance this semester!

We are pleased to inform you, [name], that you have been selected
for the Academic Excellence Award.

Best regards,
Principal's Office

You can provide the letter in two ways:

⚠️ Important: The [name] placeholder is case-sensitive. Use exactly [name], not [Name] or [NAME].

Step 4: Choose Output Folder

  1. Select where you want to save the generated letters
  2. Each letter will be saved as RecipientName's Mail.txt

Step 5: Success!

When complete:

Example Workflow

# Names entered: Alice, Bob, Charlie
# Letter template:
"Dear [name], Welcome to our program!"

# Generated files:
Alice's Mail.txt β†’ "Dear Alice, Welcome to our program!"
Bob's Mail.txt β†’ "Dear Bob, Welcome to our program!"
Charlie's Mail.txt β†’ "Dear Charlie, Welcome to our program!"

Advanced Tips

Supported File Formats

.TXT (Plain Text)

.CSV (Comma-Separated Values)

.DOCX (Microsoft Word)

.PDF (Portable Document Format)

⚠️ PDF Loading: When opening PDFs, the editor may freeze briefly. A progress bar indicates loading is in progress.

Keyboard Shortcuts

Action Shortcut Description
New Document Ctrl+N Create a new blank document
Open File Ctrl+O Open file dialog
Save Ctrl+S Save current document
Bold Ctrl+B Toggle bold on selected text
Italic Ctrl+I Toggle italic on selected text
Underline Ctrl+U Toggle underline on selected text
πŸ’‘ Pro Tip: You can select text and use multiple shortcuts in succession (e.g., Ctrl+B then Ctrl+I for bold italic text).

Troubleshooting

Installation Issues

Dependencies Not Installing

Problem: dependency-installer.py fails

Solution:

  1. Ensure you're using Python 3.8+: python --version
  2. Try manual installation: pip install ttkbootstrap Pillow python-docx pdf2image pypdf
  3. Restart terminal after installation

PDF Support Not Working

Problem: Can't open PDF files

Solution:

  1. Install Poppler (required for PDF viewing)
  2. Windows: Download from https://blog.alivate.com.au/poppler-windows/
  3. Linux: sudo apt-get install poppler-utils
  4. macOS: brew install poppler
  5. Run python diagnostics.py to verify

Runtime Issues

Application Won't Start

Problem: Error when running EduMerge.py

Solution:

# Run diagnostics first
python diagnostics.py

# Check for missing dependencies
# Reinstall if needed
python dependency-installer.py

Logo/Images Not Showing

Problem: Logo or UI images missing

Solution: Ensure these files exist in the EduMerge directory:

Unsaved Changes Not Detected

Problem: Document shows as saved when it shouldn't

Solution: This is a known limitation. Always manually save (Ctrl+S) before closing.

Mail Merge Issues

[name] Not Replaced

Problem: Generated letters still show [name]

Solution:

Names File Not Accepted

Problem: Text file rejected when importing names

Solution: Ensure format is correct:

John Smith, Jane Doe, Bob Johnson

Performance Issues

PDF Loading is Slow

Problem: Application freezes when opening large PDFs

Solution: This is normal for large PDFs. Wait for the loading window to close. For very large PDFs, consider:

Getting Help

If you encounter issues not covered here:

  1. Check the GitHub Issues page
  2. Run python diagnostics.py and share the output
  3. Open a new issue with details about your problem
  4. Email: akshajgoel@bnpsramvihar.edu.in

Advanced Features

Custom Text Formatting

Beyond the basic formatting buttons, you can create complex formatting combinations:

CSV Table Features

The CSV Table view includes:

Window Dragging

Custom dialogs in EduMerge are frameless but draggable:

Status Bar Information

The bottom status bar shows:

API Reference

Main Classes

ModernEditorApp

Main text editor application class.

class ModernEditorApp:
    def __init__(self, root)

    # File operations
    def new_file(self)
    def open_file(self)
    def save_file(self)
    def save_as_file(self)

    # Text formatting
    def apply_bold(self)
    def apply_italic(self)
    def apply_underline(self)
    def apply_heading(self, heading_tag)
    def change_font(self)
    def change_text_color(self)
    def change_bg_color(self)

    # Content insertion
    def insert_image(self)
    def create_csv_table(self)

    # Export methods
    def export_to_docx(self)
    def export_to_pdf(self)

    # File format handlers
    def open_csv(self, filepath)
    def open_docx(self, filepath)
    def open_pdf(self, filepath)

Letter

Handles mail merge letter generation.

class Letter:
    def __init__(self)

    # Core methods
    def process_letter_content(self)
    def generate_personalized_letters(self)
    def show_placeholder_instructions(self)

NameManager

Manages recipient name collection.

class NameManager:
    def __init__(self)

    # Collection methods
    def name_collection(self)
    def collect_names_manually(self)
    def names_text_file_processing(self)
    def confirm_names_proceed(self)

Custom Dialogs

CustomBox

General-purpose message box with custom buttons.

CustomBox(buttons=["OK", "Cancel"], message="Your message", image_y=40)

IntBox

Dialog for integer input (spinbox).

dialog = IntBox(buttons=["Continue", "Exit"], message="Enter number:")
value = dialog.result  # Returns integer
choice = dialog.choice  # Returns button clicked

StringBox

Dialog for single-line text input.

dialog = StringBox(buttons=["OK", "Cancel"], message="Enter text:")
text = dialog.result  # Returns string
choice = dialog.choice  # Returns button clicked

TextBox

Dialog for multi-line text input.

dialog = TextBox(buttons=["Save", "Cancel"], message="Enter content:")
content = dialog.result  # Returns text content
choice = dialog.choice  # Returns button clicked

Utility Functions

# Center a window on screen
center_window(window)

# Show exit confirmation
exit_confirmation()
show_exit_confirmation(callback_function)