# Tralegraffe ROM Extractor — User Manual
# Version 26.04 — Copyright (c) 2026 Tralegraffe Software Solution
# Platforms: macOS, Linux, Windows

═══════════════════════════════════════════════════════════════
                         ENGLISH
═══════════════════════════════════════════════════════════════

## Description

Tralegraffe ROM Extractor is a cross-platform utility for recursively
extracting large collections of ZIP archives. It is designed for
retrocomputing enthusiasts who need to decompress massive ROM collections
(e.g., No-Intro, TOSEC, MAME) containing thousands of nested ZIP files.

Features:
  - Graphical folder picker (native on macOS/Windows, zenity/kdialog on Linux)
  - Progress bar with elapsed and estimated remaining time
  - Automatic deletion of successfully extracted archives
  - Extraction summary (files extracted, errors, space freed, duration)
  - Color-coded console output
  - Free one-time lifetime activation per device

## Activation

On first launch, the software requires a free one-time activation:
  1. Enter your full name
  2. Enter your email address
  3. An internet connection is required only for this step
  4. Once activated, the license is permanent — no further activation needed

License data is stored locally:
  - macOS:   ~/.unzip_license
  - Linux:   ~/.unzip_license
  - Windows: %USERPROFILE%\.unzip_license

## Platform-Specific Instructions

### macOS (unzip.sh)

Requirements:
  - macOS 10.13+ (High Sierra or later)
  - unzip, curl (preinstalled)

Usage:
  chmod +x unzip.sh
  ./unzip.sh

Folder selection uses the native macOS dialog (osascript).

### Linux (unzip_linux.sh)

Requirements:
  - Bash 4+
  - unzip, curl (install via your package manager)
  - Optional: zenity (GNOME) or kdialog (KDE) for graphical folder picker

Usage:
  chmod +x unzip_linux.sh
  ./unzip_linux.sh

If zenity/kdialog is not available, the script will ask for the folder path
directly in the terminal. Tilde (~) expansion is supported.

### Windows (unzip_windows.ps1)

Requirements:
  - Windows 10/11
  - PowerShell 5.1+
  - Internet connection for first activation

Usage:
  Right-click the file → "Run with PowerShell"
  Or from PowerShell:
    Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
    .\unzip_windows.ps1

Folder selection uses the Windows native FolderBrowserDialog.
ZIP extraction uses Expand-Archive (built-in).

## Menu Options

  1) Select folder and extract all ZIP files
     Scans all subdirectories, extracts each ZIP in place, removes the
     archive on success, and shows a summary at the end.

  2) Show software info
     Displays version, copyright, license type, and device ID.

  3) Exit

## Tips for ROM Collections

  - Point the tool at the top-level folder of your ROM collection
  - It will recurse into all subfolders automatically
  - Ensure sufficient disk space — extracted ROMs typically take 2-3x
    the size of compressed archives
  - For very large collections (100,000+ files), the initial scan may
    take a moment

═══════════════════════════════════════════════════════════════
                        ITALIANO
═══════════════════════════════════════════════════════════════

## Descrizione

Tralegraffe ROM Extractor è un'utilità multipiattaforma per l'estrazione
ricorsiva di grandi collezioni di archivi ZIP. È progettata per gli
appassionati di retrocomputing che devono decomprimere enormi collezioni
di ROM (es. No-Intro, TOSEC, MAME) contenenti migliaia di file ZIP.

Funzionalità:
  - Selettore grafico cartelle (nativo su macOS/Windows, zenity/kdialog su Linux)
  - Barra di avanzamento con tempo trascorso e stima del tempo residuo
  - Cancellazione automatica degli archivi estratti con successo
  - Riepilogo estrazione (file estratti, errori, spazio liberato, durata)
  - Output console colorato
  - Attivazione gratuita una tantum lifetime per dispositivo

## Attivazione

Al primo avvio il software richiede un'attivazione gratuita una tantum:
  1. Inserisci nome e cognome
  2. Inserisci la tua email
  3. È necessaria una connessione internet solo per questo passaggio
  4. Una volta attivato, la licenza è permanente — nessuna ulteriore
     attivazione necessaria

I dati della licenza sono salvati localmente:
  - macOS:   ~/.unzip_license
  - Linux:   ~/.unzip_license
  - Windows: %USERPROFILE%\.unzip_license

## Istruzioni per Piattaforma

### macOS (unzip.sh)

Requisiti:
  - macOS 10.13+ (High Sierra o successivo)
  - unzip, curl (preinstallati)

Utilizzo:
  chmod +x unzip.sh
  ./unzip.sh

La selezione cartella usa il dialogo nativo macOS (osascript).

### Linux (unzip_linux.sh)

Requisiti:
  - Bash 4+
  - unzip, curl (installabili col gestore pacchetti)
  - Opzionale: zenity (GNOME) o kdialog (KDE) per selettore grafico

Utilizzo:
  chmod +x unzip_linux.sh
  ./unzip_linux.sh

Se zenity/kdialog non è disponibile, lo script chiederà il percorso
direttamente nel terminale. L'espansione della tilde (~) è supportata.

### Windows (unzip_windows.ps1)

Requisiti:
  - Windows 10/11
  - PowerShell 5.1+
  - Connessione internet per la prima attivazione

Utilizzo:
  Tasto destro sul file → "Esegui con PowerShell"
  Oppure da PowerShell:
    Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
    .\unzip_windows.ps1

La selezione cartella usa il FolderBrowserDialog nativo di Windows.
L'estrazione ZIP usa Expand-Archive (integrato).

## Opzioni del Menu

  1) Seleziona cartella e decomprimi tutti i file ZIP
     Scansiona tutte le sottocartelle, estrae ogni ZIP sul posto,
     rimuove l'archivio in caso di successo e mostra un riepilogo finale.

  2) Mostra info sul software
     Mostra versione, copyright, tipo di licenza e device ID.

  3) Esci

## Consigli per le Collezioni ROM

  - Punta il tool alla cartella principale della tua collezione ROM
  - Ricorrerà automaticamente in tutte le sottocartelle
  - Assicurati di avere spazio disco sufficiente — le ROM estratte
    occupano tipicamente 2-3x lo spazio degli archivi compressi
  - Per collezioni molto grandi (100.000+ file), la scansione iniziale
    potrebbe richiedere un momento

═══════════════════════════════════════════════════════════════

License: MIT — Copyright (c) 2026 Tralegraffe Software Solution
See the LICENSE file for full terms.
For support, contact: castle.ox@icloud.com