vectory 0.8.0 → 0.8.1

data/docs/guides/error-handling.adoc

@@ -0,0 +1,400 @@
+---
+layout: default
+title: Error Handling
+parent: Guides
+nav_order: 1
+---
+= Error Handling
+
+Common errors and how to resolve them.
+
+== Purpose
+
+This guide covers common errors you may encounter when using Vectory and how to resolve them.
+
+== Error Classes
+
+Vectory uses a structured error hierarchy:
+
+[source,ruby]
+----
+Vectory::Error                  # Base error class
+    ├── SystemCallError         # External tool execution failures
+    ├── NotWrittenToDiskError   # Accessing path before write
+    ├── ParsingError           # Content parsing failures
+    ├── InkscapeNotFoundError  # Inkscape not available
+    ├── ConversionError        # Conversion failures with diagnostics
+    └── InkscapeQueryError     # Dimension query failures
+----
+
+== Common Errors
+
+=== Inkscape Not Found
+
+[source,ruby]
+----
+Vectory::InkscapeNotFoundError: Inkscape not found in PATH
+----
+
+**Causes**:
+
+* Inkscape not installed
+* Inkscape not in system PATH
+* Custom path not configured
+
+**Solutions**:
+
+. Install Inkscape:
++
+[source,shell]
+----
+# macOS
+brew install --cask inkscape
+
+# Ubuntu/Debian
+sudo apt install inkscape
+
+# Windows
+# Download from https://inkscape.org/release/
+----
+
+. Verify installation:
++
+[source,shell]
+----
+inkscape --version
+----
+
+. Set custom path:
++
+[source,ruby]
+----
+ENV["INKSCAPE_PATH"] = "/custom/path/to/inkscape"
+----
+
+=== Ghostscript Not Found
+
+[source,ruby]
+----
+Vectory::SystemCallError: Ghostscript conversion failed
+----
+
+**Causes**:
+
+* Ghostscript not installed
+* Ghostscript not in system PATH
+
+**Solutions**:
+
+. Install Ghostscript:
++
+[source,shell]
+----
+# macOS
+brew install ghostscript
+
+# Ubuntu/Debian
+sudo apt install ghostscript
+
+# Windows
+# Download from https://www.ghostscript.com/download/gsdnld.html
+----
+
+. Verify installation:
++
+[source,shell]
+----
+gs --version
+----
+
+=== Conversion Timeout
+
+[source,ruby]
+----
+Vectory::SystemCallError: Command timed out: inkscape
+----
+
+**Causes**:
+
+* Large file being processed
+* Complex vector graphics
+* System resource constraints
+* Inkscape hanging on macOS
+
+**Solutions**:
+
+. Check if file is valid:
++
+[source,ruby]
+----
+# Verify file can be opened
+File.open("diagram.eps", "r") { |f| f.read(100) }
+----
+
+. Increase timeout:
++
+[source,ruby]
+----
+# Default timeout is 60 seconds
+# For larger files, you may need to wait longer
+----
+
+. On macOS, ensure `DISPLAY=""` is set (automatic in Vectory)
+
+=== Not Written to Disk Error
+
+[source,ruby]
+----
+Vectory::NotWrittenToDiskError: File has not been written to disk yet
+----
+
+**Causes**:
+
+* Accessing `path` before calling `write()`
+
+**Solution**:
+
+[source,ruby]
+----
+eps = Vectory::Eps.from_path("diagram.eps")
+
+# WRONG: This raises error
+puts eps.path  # => NotWrittenToDiskError
+
+# CORRECT: Write first, then access path
+eps.write("output.eps")
+puts eps.path  # => "output.eps"
+----
+
+=== Parsing Error
+
+[source,ruby]
+----
+Vectory::ParsingError: Unable to detect file format
+----
+
+**Causes**:
+
+* Invalid file content
+* Corrupted file
+* Unsupported format
+
+**Solutions**:
+
+. Verify file format:
++
+[source,ruby]
+----
+content = File.read("unknown_file", 100)
+puts content  # Check first 100 bytes
+----
+
+. Use explicit format:
++
+[source,ruby]
+----
+# Force format if detection fails
+svg = Vectory::Svg.from_path("diagram")  # Treat as SVG
+----
+
+=== Dimension Query Failed
+
+[source,ruby]
+----
+Vectory::InkscapeQueryError: Failed to query dimensions
+----
+
+**Causes**:
+
+* Invalid input file
+* Inkscape version incompatibility
+
+**Solutions**:
+
+. Verify file is valid:
++
+[source,ruby]
+----
+# Try converting first
+svg = Vectory::Svg.from_path("diagram.svg")
+# If conversion works, file is valid
+----
+
+. Check Inkscape version:
++
+[source,ruby]
+----
+inkscape = Vectory::InkscapeWrapper.instance
+puts inkscape.version  # Should be 0.92 or later
+----
+
+## Error Handling Patterns
+
+=== Rescue Specific Errors
+
+[source,ruby]
+----
+begin
+  svg = Vectory::Eps.from_path("diagram.eps").to_svg
+rescue Vectory::InkscapeNotFoundError => e
+  puts "Inkscape not found: #{e.message}"
+rescue Vectory::ConversionError => e
+  puts "Conversion failed: #{e.message}"
+  puts "Diagnostics: #{e.diagnostics}"
+rescue Vectory::Error => e
+  puts "Vectory error: #{e.message}"
+end
+----
+
+=== Retry Logic
+
+[source,ruby]
+----
+require 'vectory'
+
+def convert_with_retry(input, output, max_retries = 3)
+  retries = 0
+
+  begin
+    svg = Vectory::Eps.from_path(input).to_svg
+    svg.write(output)
+  rescue Vectory::SystemCallError => e
+    retries += 1
+    if retries < max_retries
+      puts "Retry #{retries}/#{max_retries}..."
+      sleep 1
+      retry
+    else
+      raise
+    end
+  end
+end
+----
+
+=== Validation Before Conversion
+
+[source,ruby]
+----
+def validate_file(path)
+  # Check file exists
+  raise "File not found: #{path}" unless File.exist?(path)
+
+  # Check file readable
+  raise "File not readable: #{path}" unless File.readable?(path)
+
+  # Try to detect format
+  content = File.read(path, 100)
+  format = Vectory::FileMagic.detect_format(content)
+
+  if format == :unknown
+    raise "Unable to detect format: #{path}"
+  end
+
+  true
+end
+
+# Usage
+begin
+  validate_file("diagram.eps")
+  svg = Vectory::Eps.from_path("diagram.eps").to_svg
+rescue RuntimeError => e
+  puts "Validation failed: #{e.message}"
+end
+----
+
+## Debugging
+
+=== Enable Debug Logging
+
+[source,ruby]
+----
+# Enable logging
+ENV["VECTORY_LOG"] = "1"
+
+require 'vectory'
+
+# Now all external tool commands are logged
+svg = Vectory::Eps.from_path("diagram.eps").to_svg
+# Logs: [DEBUG] Executing: inkscape ...
+----
+
+=== Check Tool Availability
+
+[source,ruby]
+----
+require 'vectory'
+
+# Check all tools
+inkscape = Vectory::InkscapeWrapper.instance
+puts "Inkscape: #{inkscape.available? ? "OK" : "MISSING"}"
+puts "  Path: #{inkscape.executable}"
+puts "  Version: #{inkscape.version}"
+
+gs = Vectory::GhostscriptWrapper.instance
+puts "Ghostscript: #{gs.available? ? "OK" : "MISSING"}"
+puts "  Path: #{gs.executable}"
+----
+
+### Test Conversion Simple File
+
+[source,ruby]
+----
+# Create simple SVG for testing
+test_svg = '<svg width="100" height="100"><rect width="100" height="100" fill="red"/></svg>'
+
+File.write("test.svg", test_svg)
+
+# Test conversion
+begin
+  svg = Vectory::Svg.from_path("test.svg")
+  eps = svg.to_eps
+  puts "Conversion successful!"
+rescue => e
+  puts "Conversion failed: #{e.message}"
+ensure
+  File.delete("test.svg") if File.exist?("test.svg")
+end
+----
+
+## Platform-Specific Issues
+
+### macOS
+
+**Inkscape timeout**:
+
+[source,ruby]
+----
+# Vectory automatically sets this, but you can also set manually
+ENV["DISPLAY"] = ""
+----
+
+### Windows
+
+**Inkscape 1.3.1+ EPS issues**:
+
+* Use Inkscape 1.3.0 instead
+* Download from: https://inkscape.org/gallery/item/inkscape-1.3.0/
+
+**Process management**:
+
+[source,ruby]
+----
+# Windows uses taskkill instead of Process.kill
+# This is handled automatically by Vectory
+----
+
+### Linux
+
+**Permission errors**:
+
+[source,shell]
+----
+# Ensure proper permissions
+chmod +x diagrams/*
+----
+
+## See Also
+
+* link:../features/external-dependencies/[External Dependencies] - Tool requirements
+* link:../understanding/error-classes/[Error Classes] - Error hierarchy
+* link:../reference/api/[API Reference] - Method documentation

data/docs/guides/index.adoc

@@ -0,0 +1,197 @@
+---
+layout: default
+title: Guides
+nav_order: 6
+has_children: true
+---
+= Guides
+
+Step-by-step guides for common Vectory tasks.
+
+== Overview
+
+This section provides practical, task-oriented guides for using Vectory. Each guide focuses on a specific use case with detailed examples.
+
+== Getting Started Guides
+
+link:batch-processing[**Batch Processing Images**]::
+Convert multiple images in a directory.
++
+Iterate through files, convert formats, handle errors.
+
+link:error-handling[**Error Handling**]::
+Common errors and how to resolve them.
++
+Missing tools, conversion failures, timeout issues.
+
+link:dimension-query[**Querying Image Dimensions**]::
+Get image dimensions without full conversion.
++
+Fast dimension retrieval for validation.
+
+== Conversion Guides
+
+link:eps-to-svg[**Converting EPS to SVG**]::
+Complete EPS to SVG conversion workflow.
++
+Ghostscript + Inkscape pipeline, bounding box preservation.
+
+link:svg-to-emf[**Converting SVG to EMF**]::
+SVG to EMF conversion for Windows compatibility.
++
+Inkscape conversion, quality considerations.
+
+link:emf-to-svg[**Converting EMF to SVG**]::
+EMF to SVG conversion workflow.
++
+emf2svg integration, output validation.
+
+== Integration Guides
+
+link:metanorma-integration[**Metanorma Integration**]::
+Using Vectory with Metanorma documents.
++
+SVG mapping, link rewriting, XML processing.
+
+link:rails-integration[**Rails Integration**]::
+Using Vectory in Ruby on Rails applications.
++
+Active Storage integration, background jobs.
+
+link:cli-integration[**Command-Line Integration**]::
+Using Vectory in shell scripts and CI/CD.
++
+One-liners, batch processing, error handling.
+
+== Advanced Guides
+
+link:custom-configuration[**Custom Configuration**]::
+Configuring Vectory for specific needs.
++
+Environment variables, tool paths, timeout settings.
+
+link:performance-optimization[**Performance Optimization**]::
+Tips for faster conversions.
++
+Caching, batch processing, parallel execution.
+
+link:debugging[**Debugging Conversion Issues**]::
+Troubleshooting failed conversions.
++
+Verbose logging, intermediate file inspection.
+
+== Quick Reference Guides
+
+=== Common Conversions
+
+[cols="1,1,1a"]
+|===
+|Input Format|Output Format|Method
+
+|EPS
+|SVG
+|`Vectory::Eps.from_path(file).to_svg`
+
+|PS
+|SVG
+|`Vectory::Ps.from_path(file).to_svg`
+
+|EMF
+|SVG
+|`Vectory::Emf.from_path(file).to_svg`
+
+|SVG
+|EPS
+|`Vectory::Svg.from_path(file).to_eps`
+
+|SVG
+|PDF
+|`Vectory::Svg.from_path(file).to_pdf`
+|===
+
+=== Error Resolution
+
+[cols="1,2a"]
+|===
+|Error|Solution
+
+|`InkscapeNotFoundError`
+|Install Inkscape and ensure it's in PATH
+
+|`SystemCallError` (timeout)
+|Increase timeout or check input file
+
+|`ParsingError`
+|Verify file format and content
+
+|`NotWrittenToDiskError`
+|Call `write()` before accessing `path`
+|===
+
+== Example Workflows
+
+=== Basic Conversion Workflow
+
+. Load image from file
+. Convert to desired format
+. Write to output location
+
+[source,ruby]
+----
+require 'vectory'
+
+# Load EPS file
+eps = Vectory::Eps.from_path("input.eps")
+
+# Convert to SVG
+svg = eps.to_svg
+
+# Write to file
+svg.write("output.svg")
+----
+
+=== Batch Conversion Workflow
+
+. Iterate through input directory
+. Detect file format
+. Convert to target format
+. Handle errors gracefully
+
+[source,ruby]
+----
+require 'vectory'
+
+Dir["input/*.eps"].each do |file|
+  begin
+    svg = Vectory::Eps.from_path(file).to_svg
+    svg.write(File.join("output", File.basename(file, ".eps") + ".svg"))
+    puts "Converted: #{file}"
+  rescue Vectory::Error => e
+    warn "Failed to convert #{file}: #{e.message}"
+  end
+end
+----
+
+=== Dimension Query Workflow
+
+. Load image
+. Query dimensions
+. Use dimensions for validation or layout
+
+[source,ruby]
+----
+require 'vectory'
+
+eps = Vectory::Eps.from_path("diagram.eps")
+width, height = eps.dimensions
+
+if width > 1000 || height > 1000
+  puts "Warning: Image dimensions are large"
+end
+----
+
+== See Also
+
+* link:../features/[Features] - Feature documentation
+* link:../understanding/[Understanding] - Internal architecture
+* link:../reference/[Reference] - Complete API documentation