omnizip 0.3.1

data/docs/reference/index.adoc

@@ -0,0 +1,26 @@
+---
+title: Reference
+nav_order: 50
+has_children: true
+---
+
+== Reference
+
+Complete technical reference for Omnizip CLI and Ruby API.
+
+=== Command-Line Interface
+
+* link:cli/overview.html[CLI Overview] - Command-line interface introduction
+* link:cli/compress-command.html[compress] - Compress files command reference
+
+=== Ruby API
+
+* link:api/overview.html[API Overview] - Ruby API introduction and examples
+
+== Additional Resources
+
+For more detailed guides, see:
+
+* link:../guides/[How-To Guides] - Step-by-step guides for common tasks
+* link:../getting-started/[Getting Started] - Installation and quick start
+* link:../comparison/[Comparison] - Compare with other tools

data/docs/resources/faq.adoc

@@ -0,0 +1,185 @@
+---
+title: FAQ
+nav_order: 71
+---
+
+== Frequently Asked Questions
+
+=== General Questions
+
+==== What is Omnizip?
+
+Omnizip is a pure Ruby compression library supporting multiple compression algorithms (LZMA, LZMA2, BZip2, PPMd, Deflate, Zstandard) and archive formats (7z, ZIP, RAR, TAR, etc.) with zero external dependencies.
+
+==== Why use Omnizip?
+
+* **Portability** - Works on all Ruby platforms (MRI, JRuby, TruffleRuby)
+* **No Dependencies** - Zero external dependencies or native extensions
+* **Comprehensive** - Support for 10+ archive formats and 6 compression algorithms
+* **Extensible** - Registry-based plugin architecture
+
+==== How fast is Omnizip?
+
+Pure Ruby implementation is 10-60x slower than native implementations:
+
+* LZMA encode: 13-15x slower
+* LZMA decode: 8-10x slower
+* BWT transform: 50-60x slower
+
+This is an acceptable trade-off for maximum portability.
+
+=== Installation
+
+==== What Ruby version is required?
+
+Ruby 3.0 or higher is required.
+
+==== Does Omnizip work on JRuby?
+
+Yes, Omnizip works on JRuby 9.4+.
+
+==== Does Omnizip work on TruffleRuby?
+
+Yes, Omnizip works on TruffleRuby 22+.
+
+=== Usage
+
+==== How do I compress a file?
+
+[source,bash]
+----
+omnizip compress input.txt output.lzma
+----
+
+[source,ruby]
+----
+Omnizip.compress_file('input.txt', 'output.lzma')
+----
+
+==== How do I create an archive?
+
+[source,bash]
+----
+omnizip archive create backup.7z documents/
+----
+
+[source,ruby]
+----
+writer = Omnizip::Formats::SevenZip::Writer.new('backup.7z')
+writer.add_directory('documents/')
+writer.close
+----
+
+==== How do I extract an archive?
+
+[source,bash]
+----
+omnizip archive extract backup.7z output/
+----
+
+[source,ruby]
+----
+reader = Omnizip::Formats::SevenZip::Reader.new('backup.7z')
+reader.extract_all('output/')
+reader.close
+----
+
+==== What compression level should I use?
+
+* **Levels 1-3**: Fast compression for temporary files
+* **Levels 4-6**: Balanced speed/ratio for general use (default: 5)
+* **Levels 7-9**: Maximum compression for storage
+
+=== Compatibility
+
+==== Can Omnizip extract 7-Zip archives?
+
+Yes, Omnizip can extract archives created by 7-Zip.
+
+==== Can Omnizip create ZIP files?
+
+Yes, Omnizip can create ZIP files compatible with all ZIP tools.
+
+==== Can Omnizip create RAR archives?
+
+Yes, Omnizip can create RAR5 archives using pure Ruby implementation.
+
+=== Performance
+
+==== How can I speed up compression?
+
+1. Use lower compression levels (--level 1-3)
+2. Use faster algorithms (zstandard, deflate)
+3. Enable parallel processing (--threads)
+4. Use compression profiles for automatic selection
+
+==== Why is compression slow?
+
+Pure Ruby implementation prioritizes portability over performance. Native implementations are 10-60x faster but require platform-specific compilation.
+
+=== Troubleshooting
+
+==== Compression failed with "Algorithm not found"
+
+Ensure the algorithm name is correct:
+
+[source,bash]
+----
+omnizip list  # See available algorithms
+----
+
+==== Archive extraction failed
+
+Verify the archive is not corrupted:
+
+[source,bash]
+----
+omnizip archive list archive.7z
+----
+
+Try different extraction options or check file integrity.
+
+==== Out of memory error
+
+For large files, consider:
+
+1. Using chunked processing
+2. Reducing compression level
+3. Using faster algorithms
+
+=== Advanced
+
+==== How do I use filters?
+
+[source,bash]
+----
+omnizip archive create binaries.7z app.exe --filters bcj_x86
+----
+
+[source,ruby]
+----
+writer = Omnizip::Formats::SevenZip::Writer.new('binaries.7z',
+  filters: [:bcj_x86]
+)
+----
+
+==== How do I encrypt archives?
+
+[source,bash]
+----
+omnizip archive create secure.7z data/ --password "PASSWORD"
+----
+
+[source,ruby]
+----
+writer = Omnizip::Formats::SevenZip::Writer.new('secure.7z',
+  password: 'PASSWORD'
+)
+----
+
+=== See Also
+
+* link:../getting-started/[Getting Started]
+* link:../guides/[Usage Guides]
+* link:../troubleshooting/[Troubleshooting]
+* link:../resources/quick-reference[Quick Reference]

data/docs/resources/quick-reference.adoc

@@ -0,0 +1,222 @@
+---
+title: Quick Reference
+nav_order: 70
+---
+
+== Quick Reference
+
+Cheat sheet for common Omnizip operations.
+
+=== Command-Line Quick Reference
+
+==== File Compression
+
+[source,bash]
+----
+# Basic compression
+omnizip compress INPUT OUTPUT
+
+# With algorithm and level
+omnizip compress INPUT OUTPUT --algorithm ALGORITHM --level N
+
+# Pipe mode
+cat INPUT | omnizip compress - OUTPUT
+----
+
+==== Archive Operations
+
+[source,bash]
+----
+# Create archive
+omnizip archive create OUTPUT INPUT...
+
+# Extract archive
+omnizip archive extract ARCHIVE [OUTPUT_DIR]
+
+# List contents
+omnizip archive list ARCHIVE
+----
+
+==== Common Options
+
+`--algorithm`:: Compression algorithm (lzma, lzma2, bzip2, ppmd7, deflate, zstandard)
+`--level N`:: Compression level (1-9)
+`--verbose`, `-v`:: Verbose output
+`--help`, `-h`:: Show help
+
+=== Ruby API Quick Reference
+
+==== Convenience Methods
+
+[source,ruby]
+----
+# Compress file
+Omnizip.compress_file('input.txt', 'output.lzma')
+
+# Decompress file
+Omnizip.decompress_file('output.lzma', 'restored.txt')
+
+# Extract archive
+Omnizip.extract_archive('archive.7z', 'output/')
+
+# List archive
+Omnizip.list_archive('archive.7z')
+----
+
+==== Registry Methods
+
+[source,ruby]
+----
+# Get algorithm
+algorithm = Omnizip::AlgorithmRegistry.get(:lzma2).new(level: 9)
+
+# Get format writer
+writer = Omnizip::FormatRegistry.get(:seven_zip).new_writer('archive.7z')
+----
+
+=== Compression Algorithm Quick Reference
+
+[cols="1,1,2,2"]
+|===
+|Algorithm |Option |Speed |Best For
+
+|LZMA
+|--algorithm lzma
+|Slow
+|Maximum compression
+
+|LZMA2
+|--algorithm lzma2 (default)
+|Slow
+|Archives, backups
+
+|BZip2
+|--algorithm bzip2
+|Medium
+|Text files
+
+|PPMd7
+|--algorithm ppmd7
+|Medium
+|Text, documents
+
+|Deflate
+|--algorithm deflate
+|Fast
+|Compatibility
+
+|Zstandard
+|--algorithm zstandard
+|Very Fast
+|Speed-sensitive
+|===
+
+=== Compression Level Quick Reference
+
+[cols="1,1,2"]
+|===
+|Level |Option |Use Case
+
+|1
+|--level 1
+|Fastest, temporary files
+
+|3
+|--level 3
+|Fast, frequent operations
+
+|5
+|--level 5 (default)
+|Balanced, general use
+
+|7
+|--level 7
+|High compression, storage
+
+|9
+|--level 9
+|Maximum compression
+|===
+
+=== Archive Format Quick Reference
+
+[cols="1,2,2"]
+|===
+|Format |Extension |Best For
+
+|7z
+|.7z
+|Maximum compression, solid archives
+
+|ZIP
+|.zip
+|Cross-platform compatibility
+
+|RAR4/RAR5
+|.rar
+|Binary distribution, multi-volume
+
+|TAR
+|.tar
+|Unix backups
+
+|GZIP
+|.gz
+|Single file compression
+
+|XZ
+|.xz
+|System packages
+|===
+
+=== Common Patterns
+
+==== Backup Script
+
+[source,bash]
+----
+#!/bin/bash
+DATE=$(date +%Y%m%d)
+omnizip archive create "backup_${DATE}.7z" \
+  documents/ projects/ \
+  --level 7 --solid
+----
+
+==== Batch Compression
+
+[source,bash]
+----
+for file in *.txt; do
+  omnizip compress "$file" "${file}.lzma" --level 5
+done
+----
+
+==== Ruby Backup Script
+
+[source,ruby]
+----
+require 'omnizip'
+require 'time'
+
+timestamp = Time.now.strftime('%Y%m%d')
+archive_name = "backup_#{timestamp}.7z"
+
+writer = Omnizip::Formats::SevenZip::Writer.new(archive_name,
+  level: 7,
+  solid: true
+)
+
+%w[documents projects].each do |dir|
+  writer.add_directory(dir) if Dir.exist?(dir)
+end
+
+writer.close
+puts "Created #{archive_name}"
+----
+
+=== See Also
+
+* link:../getting-started/quick-start[Quick Start Guide]
+* link:../guides/basic-usage/[Basic Usage Guides]
+* link:../reference/cli/[CLI Reference]
+* link:../reference/api/[API Reference]

data/docs/troubleshooting/index.adoc

@@ -0,0 +1,208 @@
+---
+title: Troubleshooting
+nav_order: 80
+---
+
+== Troubleshooting
+
+Common problems and solutions when using Omnizip.
+
+=== Common Issues
+
+==== "Algorithm not found" Error
+
+**Problem**: Compression fails with algorithm not found error.
+
+**Solution**: Check available algorithms:
+
+[source,bash]
+----
+omnizip list
+----
+
+[source,ruby]
+----
+Omnizip::AlgorithmRegistry.registered.each do |name|
+  puts name
+end
+----
+
+**Causes**:
+* Typo in algorithm name
+* Algorithm not registered
+
+==== "File not found" Error
+
+**Problem**: Cannot read input file.
+
+**Solution**: Verify file paths and permissions:
+
+[source,bash]
+----
+# Check file exists
+ls -la input.txt
+
+# Check permissions
+chmod +r input.txt
+----
+
+==== "Out of memory" Error
+
+**Problem**: Large file compression fails.
+
+**Solutions**:
+
+1. Use lower compression level:
+[source,bash]
+----
+omnizip compress large.txt output.lzma --level 1
+----
+
+2. Use faster algorithm:
+[source,bash]
+----
+omnizip compress large.txt output.zst --algorithm zstandard
+----
+
+3. Use chunked processing:
+[source,ruby]
+----
+Omnizip.compress_file_chunked('large.txt', 'output.lzma',
+  chunk_size: 10 * 1024 * 1024
+)
+----
+
+==== "Archive corrupted" Error
+
+**Problem**: Cannot extract archive.
+
+**Solutions**:
+
+1. Verify archive integrity:
+[source,bash]
+----
+omnizip archive list archive.7z
+----
+
+2. Try recovery mode:
+[source,ruby]
+----
+reader = Omnizip::Formats::SevenZip::Reader.new('archive.7z',
+  salvage_mode: true
+)
+reader.extract_all('output/')
+----
+
+3. Check CRC:
+[source,ruby]
+----
+if Omnizip::Checksums.verify_file('archive.7z', :crc32)
+  puts "Archive is valid"
+else
+  puts "Archive is corrupted"
+end
+----
+
+=== Performance Issues
+
+==== Slow Compression
+
+**Solutions**:
+
+1. Use lower compression level:
+[source,bash]
+----
+omnizip compress input.txt output.lzma --level 3
+----
+
+2. Use faster algorithm:
+[source,bash]
+----
+omnizip compress input.txt output.zst --algorithm zstandard
+----
+
+3. Enable parallel processing:
+[source,ruby]
+----
+Omnizip.compress_file('input.txt', 'output.lzma',
+  parallel: true,
+  threads: 4
+)
+----
+
+==== Slow Decompression
+
+**Solutions**:
+
+1. Use buffered reading:
+[source,ruby]
+----
+reader = Omnizip::Formats::SevenZip::Reader.new('archive.7z',
+  buffer_size: 1024 * 1024
+)
+reader.extract_all('output/')
+----
+
+2. Extract specific files only:
+[source,bash]
+----
+omnizip archive extract archive.7z output/ \
+  --pattern 'important.txt'
+----
+
+=== Format-Specific Issues
+
+==== 7z Issues
+
+**Problem**: 7z archive not compatible with 7-Zip.
+
+**Solution**: Ensure standard options:
+
+[source,ruby]
+----
+writer = Omnizip::Formats::SevenZip::Writer.new('archive.7z',
+  algorithm: :lzma2,
+  level: 5  # Standard level
+)
+----
+
+==== ZIP Issues
+
+**Problem**: ZIP not readable by other tools.
+
+**Solution**: Use Deflate algorithm:
+
+[source,bash]
+----
+omnizip archive create archive.zip files/ \
+  --algorithm deflate --level 5
+----
+
+==== RAR Issues
+
+**Problem**: RAR extraction fails.
+
+**Solution**: Verify RAR version:
+
+[source,ruby]
+----
+# Try RAR4 reader
+reader = Omnizip::Formats::Rar::Reader.new('archive.rar')
+
+# Or RAR5 reader
+reader = Omnizip::Formats::Rar::Rar5::Reader.new('archive.rar')
+----
+
+### Getting Help
+
+If you continue to have issues:
+
+1. Check link:../resources/faq[FAQ]
+2. Review link:../guides/[usage guides]
+3. Search link:https://github.com/metanorma/omnizip/issues[GitHub issues]
+4. Create a new issue with:
+   * Omnizip version
+   * Ruby version
+   * Operating system
+   * Error message
+   * Minimal reproduction code