omnizip 0.3.1

data/docs/guides/extracting-archives.adoc

@@ -0,0 +1,53 @@
+---
+title: Extracting Archives
+nav_order: 2
+parent: Guides
+---
+
+== Extracting Archives
+
+Guide to extracting files from archives.
+
+== Quick Examples
+
+=== Extract All Files
+
+[source,ruby]
+----
+require 'omnizip'
+
+Omnizip::Archive.open('backup.zip') do |archive|
+  archive.extract_all('output/')
+end
+----
+
+=== Extract Specific Files
+
+[source,ruby]
+----
+Omnizip::Archive.open('backup.zip') do |archive|
+  archive.extract('document.pdf', 'restored/document.pdf')
+end
+----
+
+=== List Contents
+
+[source,ruby]
+----
+entries = Omnizip.list_archive('backup.zip')
+entries.each do |entry|
+  puts "#{entry.name}: #{entry.size} bytes"
+end
+----
+
+== Pattern Matching
+
+[source,ruby]
+----
+archive.extract_matching('*.txt', 'output/')
+----
+
+== See Also
+
+* link:creating-archives.html[Creating Archives]
+* link:../reference/api/overview.html[Ruby API]

data/docs/guides/format-conversion.adoc

@@ -0,0 +1,64 @@
+---
+title: Format Conversion
+nav_order: 3
+parent: Guides
+---
+
+== Format Conversion
+
+Converting archives between different formats.
+
+== ZIP to 7z
+
+[source,ruby]
+----
+require 'omnizip'
+
+Omnizip::Archive.open('input.zip') do |zip_archive|
+  Omnizip::Archive.create('output.7z', format: :seven_zip) do |sevenz_archive|
+    zip_archive.entries.each do |entry|
+      next if entry.directory?
+      data = zip_archive.read(entry.name)
+      sevenz_archive.add_data(entry.name, data)
+    end
+  end
+end
+----
+
+== 7z to ZIP
+
+[source,ruby]
+----
+Omnizip::Archive.open('input.7z') do |sevenz_archive|
+  Omnizip::Archive.create('output.zip', format: :zip) do |zip_archive|
+    sevenz_archive.entries.each do |entry|
+      next if entry.directory?
+      data = sevenz_archive.read(entry.name)
+      zip_archive.add_data(entry.name, data)
+    end
+  end
+end
+----
+
+== Batch Conversion
+
+[source,ruby]
+----
+Dir.glob('*.zip').each do |zip_file|
+  sevenz_file = zip_file.sub('.zip', '.7z')
+
+  Omnizip::Archive.open(zip_file) do |src|
+    Omnizip::Archive.create(sevenz_file, format: :seven_zip, level: 9) do |dest|
+      src.entries.each do |entry|
+        next if entry.directory?
+        dest.add_data(entry.name, src.read(entry.name))
+      end
+    end
+  end
+end
+----
+
+== See Also
+
+* link:creating-archives.html[Creating Archives]
+* link:../comparison/feature-matrix.html[Format Comparison]

data/docs/guides/index.adoc

@@ -0,0 +1,49 @@
+---
+title: Guides
+nav_order: 10
+has_children: true
+---
+
+== Guides
+
+Comprehensive guides for all Omnizip features and formats.
+
+=== Core Operations
+
+* link:creating-archives.html[Creating Archives] - Build new archives with comprehensive examples
+* link:extracting-archives.html[Extracting Archives] - Extract files from archives
+* link:format-conversion.html[Format Conversion] - Convert between archive formats
+
+=== Compression Algorithms
+
+* link:compression-algorithms/[Compression Algorithms Overview] - Algorithm comparison and selection guide
+* link:compression-algorithms/lzma.html[LZMA] - High compression ratio algorithm
+* link:compression-algorithms/lzma2.html[LZMA2] - Enhanced LZMA with multi-threading
+* link:compression-algorithms/bzip2.html[BZip2] - Text file compression
+* link:compression-algorithms/ppmd.html[PPMd] - Prediction by Partial Matching for text
+* link:compression-algorithms/deflate.html[Deflate] - ZIP-compatible compression
+* link:compression-algorithms/zstandard.html[Zstandard] - Modern fast compression
+
+=== Archive Formats
+
+* link:archive-formats/[Archive Formats Overview] - Format comparison and selection guide
+* link:archive-formats/seven-zip-format.html[7z Format] - 7-Zip archives with solid compression
+* link:archive-formats/zip-format.html[ZIP Format] - ZIP archives with ZIP64 support
+* link:archive-formats/rar-format.html[RAR Format] - RAR4/RAR5 archives (read-only)
+* link:archive-formats/tar-format.html[TAR Format] - TAR archives with POSIX extensions
+* link:archive-formats/gzip-format.html[GZIP Format] - GZIP single file compression
+* link:archive-formats/xz-format.html[XZ Format] - XZ compressed files with LZMA2
+
+=== Advanced Features
+
+* link:advanced-features/[Advanced Features Overview] - Power user features
+* link:advanced-features/streaming.html[Streaming Operations] - Memory-efficient processing
+* link:advanced-features/parallel-processing.html[Parallel Processing] - Multi-threaded compression
+* link:advanced-features/progress-tracking.html[Progress Tracking] - Real-time progress monitoring
+* link:advanced-features/encryption.html[Encryption] - AES-256 password protection
+
+=== Migration & Optimization
+
+* link:migration-rubyzip.html[Migrating from Rubyzip] - Migration guide for rubyzip users
+* link:performance-tuning.html[Performance Tuning] - Optimize compression performance
+* link:parity-archives.html[PAR2 Parity Archives] - Error correction and recovery

data/docs/guides/migration-rubyzip.adoc

@@ -0,0 +1,217 @@
+---
+title: Migrating from Rubyzip
+nav_order: 4
+parent: Guides
+---
+
+== Migrating from Rubyzip
+
+Complete guide to migrating from the rubyzip gem to Omnizip.
+
+== Quick Migration
+
+=== Step 1: Install Omnizip
+
+[source,ruby]
+----
+# Gemfile
+gem 'omnizip', '~> 1.0'
+----
+
+=== Step 2: Use Compatibility Layer
+
+[source,ruby]
+----
+# Before (rubyzip)
+require 'zip'
+
+# After (Omnizip with compatibility)
+require 'omnizip/rubyzip_compat'
+
+# All existing Zip::* code works unchanged!
+----
+
+== Why Migrate?
+
+✅ **Format Flexibility** - Support both ZIP and 7z formats
+
+✅ **Better Compression** - LZMA2, BZip2, PPMd, Deflate64
+
+✅ **Pure Ruby** - No external dependencies
+
+✅ **Backward Compatible** - Drop-in replacement
+
+✅ **Better Architecture** - Clean OOP design
+
+== Code Examples
+
+=== Creating Archives
+
+**Before (rubyzip):**
+
+[source,ruby]
+----
+Zip::File.open('archive.zip', create: true) do |zip|
+  zip.add('file.txt', 'path/to/file.txt')
+end
+----
+
+**After (with compatibility layer):**
+
+[source,ruby]
+----
+require 'omnizip/rubyzip_compat'
+
+Zip::File.open('archive.zip', create: true) do |zip|
+  zip.add('file.txt', 'path/to/file.txt')
+end
+----
+
+**After (enhanced API):**
+
+[source,ruby]
+----
+require 'omnizip'
+
+Omnizip::Archive.create('archive.zip') do |archive|
+  archive.add_file('path/to/file.txt', 'file.txt')
+end
+----
+
+=== Extracting Archives
+
+**Before (rubyzip):**
+
+[source,ruby]
+----
+Zip::File.open('archive.zip') do |zip|
+  zip.each do |entry|
+    entry.extract("output/#{entry.name}")
+  end
+end
+----
+
+**After (enhanced API):**
+
+[source,ruby]
+----
+Omnizip::Archive.open('archive.zip') do |archive|
+  archive.extract_all('output/')
+end
+----
+
+== Migration Strategies
+
+=== Strategy 1: Drop-in Replacement
+
+For simple codebases - just change the require:
+
+[source,ruby]
+----
+# config/initializers/omnizip.rb
+require 'omnizip/rubyzip_compat'
+----
+
+All existing `Zip::*` code works unchanged!
+
+=== Strategy 2: Gradual Migration
+
+Keep both gems during transition:
+
+[source,ruby]
+----
+# Gemfile
+gem 'rubyzip', '~> 3.0'
+gem 'omnizip', '~> 1.0'
+
+# Migrate file by file
+require 'zip'        # Old code
+require 'omnizip'    # New code
+----
+
+=== Strategy 3: Full Migration
+
+New projects - use enhanced API:
+
+[source,ruby]
+----
+require 'omnizip'
+
+# Use Omnizip's improved API from the start
+Omnizip::Archive.create('backup.7z', format: :seven_zip) do |archive|
+  archive.add_directory('data/')
+end
+----
+
+== Common Patterns
+
+=== Reading Archive Contents
+
+[source,ruby]
+----
+Omnizip::Zip::File.open('archive.zip') do |zip|
+  zip.each do |entry|
+    next unless entry.file?
+    content = entry.get_input_stream.read
+    process(entry.name, content)
+  end
+end
+----
+
+=== Streaming Operations
+
+[source,ruby]
+----
+Omnizip::Zip::OutputStream.open('archive.zip') do |zos|
+  files.each do |file|
+    zos.put_next_entry(file[:name])
+    zos.write file[:data]
+  end
+end
+----
+
+=== Encrypted Archives
+
+[source,ruby]
+----
+# Use 7z for AES-256 encryption
+Omnizip::Archive.create('secure.7z',
+                        format: :seven_zip,
+                        password: 'secret') do |archive|
+  archive.add_file('sensitive.txt')
+end
+----
+
+== Migration Checklist
+
+- [ ] Install Omnizip gem
+- [ ] Choose migration strategy
+- [ ] Update require statements
+- [ ] Run tests
+- [ ] Verify compatibility
+- [ ] Deploy to staging
+- [ ] Monitor performance
+- [ ] Deploy to production
+
+== Complete Migration Guide
+
+For the complete migration guide with advanced topics, see:
+
+* link:https://github.com/metanorma/omnizip/blob/main/MIGRATION_GUIDE.md[Full Migration Guide] (GitHub)
+
+Topics covered in full guide:
+
+* Advanced migration patterns
+* Handling large files
+* Using both libraries together
+* Converting ZIP to 7z
+* Integration testing
+* Performance optimization
+* Troubleshooting
+* Rollback plan
+
+== See Also
+
+* link:../comparison/vs-rubyzip.html[Omnizip vs rubyzip Comparison]
+* link:../getting-started/quick-start.html[Quick Start Guide]
+* link:../reference/api/overview.html[Ruby API Reference]