vectory 0.8.0 → 0.8.1

data/docs/understanding/architecture.adoc

@@ -0,0 +1,277 @@
+---
+layout: default
+title: Architecture
+parent: Understanding
+nav_order: 1
+---
+= Architecture Overview
+
+Vectory's design principles and architecture.
+
+== Purpose
+
+This section explains Vectory's architecture, design decisions, and implementation patterns.
+
+== Design Philosophy
+
+Vectory follows these core principles:
+
+* **Object-Oriented Design**: Clear class hierarchy with inheritance
+* **Wrapper Pattern**: External tools abstracted behind clean interfaces
+* **Singleton Pattern**: Shared tool instances for efficiency
+* **Model-Based**: Object representation rather than serialization manipulation
+* **Separation of Concerns**: Each class has a single responsibility
+
+== Class Hierarchy
+
+[source,ruby]
+----
+Vectory::Image          # Base class for all images
+    │
+    └── Vectory::Vector  # Abstract base for vector formats
+            │
+            ├── Vectory::Eps      # Encapsulated PostScript
+            ├── Vectory::Ps       # PostScript
+            ├── Vectory::Emf      # Enhanced Metafile
+            ├── Vectory::Svg      # Scalable Vector Graphics
+            └── Vectory::Pdf      # PDF (intermediate format)
+----
+
+Each format class inherits from `Vectory::Vector` and shares common functionality.
+
+== Design Patterns
+
+=== Wrapper Pattern
+
+External tools are wrapped in singleton classes:
+
+[source,ruby]
+----
+# Inkscape wrapper
+class InkscapeWrapper
+  include Singleton
+
+  def executable
+    @executable ||= find_inkscape
+  end
+
+  def version
+    @version ||= detect_version
+  end
+end
+----
+
+**Benefits**:
+
+* Clean interface to external tools
+* Centralized tool discovery
+* Version detection and caching
+* Error handling
+
+=== Singleton Pattern
+
+Tool wrappers use singleton pattern:
+
+[source,ruby]
+----
+# Single instance shared across conversions
+inkscape = Vectory::InkscapeWrapper.instance
+
+# Version detected once, cached
+puts inkscape.version  # Cached result
+----
+
+**Benefits**:
+
+* Efficient resource usage
+* Version detection happens once
+* Consistent behavior across conversions
+
+=== Factory Methods
+
+Each format class provides factory methods:
+
+[source,ruby]
+----
+Vectory::Eps.from_path(path)      # Load from file
+Vectory::Eps.from_content(content) # Load from string
+Vectory::Eps.from_datauri(uri)     # Load from data URI
+Vectory::Eps.from_node(node)       # Load from XML node
+----
+
+**Benefits**:
+
+* Flexible input sources
+* Consistent API across formats
+* Easy testing and mocking
+
+== Conversion Pipeline
+
+=== Direct Conversions
+
+Some conversions are direct:
+
+[source,text]
+----
+SVG → Inkscape → EPS/PS/EMF/PDF
+EMF → emf2svg → SVG
+----
+
+=== Two-Step Conversions
+
+Other conversions use intermediate formats:
+
+[source,text]
+----
+EPS/PS → Ghostscript → PDF → Inkscape → SVG
+----
+
+This preserves BoundingBox information from EPS/PS files.
+
+== Component Interaction
+
+[.flowchart]
+----
+User Code
+    │
+    ├─→ Vectory::Eps.from_path()
+    │       │
+    │       ├─→ Vectory::FileMagic.detect_format()
+    │       │
+    │       └─→ Vectory::Eps.new()
+    │
+    └─→ Vectory::Eps#to_svg()
+            │
+            ├─→ Vectory::Pdf#to_pdf() ──→ GhostscriptWrapper
+            │
+            └─→ Vectory::Pdf#to_svg() ──→ InkscapeWrapper
+----
+
+== File System Operations
+
+=== Path Tracking
+
+Each image tracks two paths:
+
+[source,ruby]
+----
+eps = Vectory::Eps.from_path("input.eps")
+
+# Where it was loaded from (read-only)
+eps.initial_path  # => "input.eps"
+
+# Where it's currently written
+eps.path  # Raises NotWrittenToDiskError if not written
+
+eps.write("output.eps")
+eps.path  # => "output.eps"
+----
+
+=== Temporary Files
+
+Vectory manages temporary files for conversions:
+
+[source,ruby]
+----
+# Temporary files created automatically
+eps = Vectory::Eps.from_path("diagram.eps")
+svg = eps.to_svg  # Creates temp PDF, then temp SVG
+
+# Write to final location
+svg.write("diagram.svg")
+----
+
+Temp files are cleaned up automatically.
+
+== Error Handling
+
+Structured error hierarchy:
+
+[source,ruby]
+----
+Vectory::Error                  # Base error
+    ├── SystemCallError         # External tool failures
+    ├── NotWrittenToDiskError   # Path access before write
+    ├── ParsingError           # Content parsing failures
+    ├── InkscapeNotFoundError  # Inkscape unavailable
+    ├── ConversionError        # Conversion failures
+    └── InkscapeQueryError     # Dimension query failures
+----
+
+== Performance Considerations
+
+=== Caching
+
+[source,ruby]
+----
+# Tool version cached
+inkscape = Vectory::InkscapeWrapper.instance
+inkscape.version  # Detected once, cached
+
+# Tool path cached
+inkscape.executable  # Discovered once, cached
+----
+
+=== Lazy Evaluation
+
+[source,ruby]
+----
+# Version detected only when needed
+inkscape = Vectory::InkscapeWrapper.instance
+# Version not detected until first use
+puts inkscape.version  # Detection happens here
+----
+
+=== Process Management
+
+[source,ruby]
+----
+# Non-blocking timeout on Windows
+spawn("taskkill", "/pid", pid, "/f",
+      %i[out err] => File::NULL)
+
+# Blocking timeout on Unix
+Process.kill(:TERM, pid)
+----
+
+== Extensibility
+
+=== Adding New Formats
+
+To add a new format:
+
+. Create format class inheriting from `Vectory::Vector`
+. Implement `#to_*` conversion methods
+. Add format detection to `FileMagic`
+
+[source,ruby]
+----
+class Vectory::NewFormat < Vectory::Vector
+  def to_svg
+    # Convert to SVG
+  end
+
+  def self.from_path(path)
+    # Load from file
+  end
+end
+----
+
+=== Adding New Conversions
+
+Add conversion methods to existing format classes:
+
+[source,ruby]
+----
+class Vectory::Eps < Vectory::Vector
+  def to_new_format
+    # Convert to new format
+  end
+end
+----
+
+== See Also
+
+* link:class-hierarchy/[Class Hierarchy] - Detailed class structure
+* link:conversion-pipeline/[Conversion Pipeline] - How conversions work
+* link:wrapper-pattern/[Wrapper Pattern] - Tool abstraction details

data/docs/understanding/index.adoc

@@ -0,0 +1,148 @@
+---
+layout: default
+title: Understanding
+nav_order: 5
+has_children: true
+---
+
+Learn how Vectory works internally.
+
+== Overview
+
+This section explains Vectory's internal architecture, design decisions, and implementation details. Understanding these concepts will help you use Vectory effectively and troubleshoot issues.
+
+== Architecture
+
+link:architecture[**Architecture Overview**]::
+Class hierarchy and design patterns used in Vectory.
++
+Object-oriented design with inheritance, singleton pattern for tool wrappers, and model-based architecture.
+
+link:class-hierarchy[**Class Hierarchy**]::
+Detailed explanation of the `Vectory::Image` inheritance tree.
++
+`Vectory::Image` → `Vectory::Vector` → Format-specific classes.
+
+link:conversion-pipeline[**Conversion Pipeline**]::
+How conversions flow through intermediate formats.
++
+Direct conversions vs. two-step conversions through PDF.
+
+== External Tools
+
+link:external-dependencies[**External Dependencies Overview**]::
+Comprehensive guide to all external tools and gems.
++
+Inkscape, Ghostscript, emf2svg, moxml - their purposes and how Vectory integrates with them.
+
+link:inkscape-wrapper[**Inkscape Wrapper**]::
+Singleton pattern implementation for Inkscape integration.
++
+Version detection, command generation, timeout management, 0.x vs 1.x+ syntax differences.
+
+link:ghostscript-wrapper[**Ghostscript Wrapper**]::
+Ghostscript integration for EPS/PS to PDF conversion.
++
+BoundingBox preservation, PDF generation, command-line options.
+
+link:emf2svg-integration[**emf2svg Integration**]::
+EMF format support via the emf2svg gem.
++
+Windows EMF conversion, cross-platform compatibility.
+
+link:moxml-integration[**moxml Integration**]::
+XML/HTML parsing for Metanorma SVG mapping.
++
+Link rewriting, ID preservation, namespace handling.
+
+== Design Patterns
+
+link:wrapper-pattern[**Wrapper Pattern**]::
+Abstracting external tool dependencies.
++
+`InkscapeWrapper` and `GhostscriptWrapper` provide clean interfaces.
+
+link:singleton[**Singleton Pattern**]::
+Shared Inkscape instance across conversions.
++
+Version detection caching, resource efficiency.
+
+link:factory-methods[**Factory Methods**]::
+Class methods for creating image objects.
++
+`from_path`, `from_content`, `from_datauri`, `from_node`.
+
+== File System Operations
+
+link:file-paths[**Path Management**]::
+`initial_path` vs `path` distinction.
++
+Original file location vs. current write location.
+
+link:temp-files[**Temporary File Handling**]::
+How Vectory manages intermediate files.
++
+Automatic cleanup, temp directory usage.
+
+== Error Handling
+
+link:error-classes[**Error Class Hierarchy**]::
+Exception types and when they're raised.
++
+`SystemCallError`, `NotWrittenToDiskError`, `ParsingError`, etc.
+
+link:timeout-handling[**Timeout Management**]::
+How Vectory handles hung external processes.
++
+Platform-specific timeout implementation (Unix vs Windows).
+
+== Format Detection
+
+link:magic-numbers[**Magic Number Detection**]::
+How file formats are detected from content.
++
+EPS, PS, EMF magic numbers; SVG content inspection.
+
+link:file-type-heuristics[**File Type Heuristics**]::
+Fallback strategies when magic numbers aren't enough.
+
+== Performance
+
+link:caching[**Caching Strategies**]::
+Version detection caching, tool discovery caching.
+
+link:batch-optimization[**Batch Processing**]::
+Optimizations for processing multiple files.
+
+== Platform-Specific Behavior
+
+link:windows-support[**Windows Support**]::
+Special considerations for Windows platforms.
++
+Path handling, process management, Inkscape version compatibility.
+
+link:macos-support[**macOS Support**]::
+Display environment configuration for headless operation.
++
+`DISPLAY=""` for Inkscape timeout prevention.
+
+link:linux-support[**Linux Support**]::
+Standard Unix behavior for Vectory.
+
+== Technical Constraints
+
+link:format-limitations[**Format Limitations**]::
+Known limitations of each supported format.
++
+Conversion artifacts, precision issues.
+
+link:tool-versions[**Tool Version Requirements**]::
+Inkscape and Ghostscript version compatibility.
++
+Inkscape 0.x vs 1.x+ syntax differences, known issues.
+
+== See Also
+
+* link:../features/[Features] - What Vectory can do
+* link:../guides/[Guides] - How to use Vectory
+* link:../reference/[Reference] - Complete API documentation

data/docs/understanding/inkscape-wrapper.adoc

@@ -0,0 +1,270 @@
+---
+layout: default
+title: Inkscape Wrapper
+parent: Understanding
+nav_order: 2
+---
+= Inkscape Wrapper
+
+Singleton pattern implementation for Inkscape integration.
+
+== Overview
+
+The `InkscapeWrapper` class provides a clean interface to Inkscape's command-line tools. It uses the singleton pattern to share a single instance across all conversions.
+
+== Singleton Pattern
+
+[source,ruby]
+----
+class InkscapeWrapper
+  include Singleton
+
+  def initialize
+    @executable = nil
+    @version = nil
+  end
+end
+----
+
+[source,ruby]
+----
+# Get singleton instance
+inkscape = Vectory::InkscapeWrapper.instance
+
+# Same instance returned on subsequent calls
+inkscape2 = Vectory::InkscapeWrapper.instance
+puts inkscape.equal?(inkscape2)  # => true
+----
+
+== Version Detection
+
+=== Automatic Detection
+
+Inkscape version is detected on first access:
+
+[source,ruby]
+----
+inkscape = Vectory::InkscapeWrapper.instance
+
+# Version detected automatically
+puts inkscape.version  # => "1.3.0"
+----
+
+=== Version Caching
+
+Version is cached after first detection:
+
+[source,ruby]
+----
+# First call: detects version
+version1 = inkscape.version
+
+# Subsequent calls: returns cached value
+version2 = inkscape.version
+
+puts version1.equal?(version2)  # => true
+----
+
+=== Version Checking
+
+[source,ruby]
+----
+inkscape = Vectory::InkscapeWrapper.instance
+
+# Check if modern version (1.x)
+if inkscape.modern?
+  puts "Using Inkscape 1.x syntax"
+else
+  puts "Using Inkscape 0.x syntax"
+end
+----
+
+== Command Generation
+
+=== Version-Specific Syntax
+
+Inkscape 0.x and 1.x use different command-line syntax:
+
+[source,ruby]
+----
+# Inkscape 0.x syntax
+inkscape --file=input.svg --export-eps=output.eps
+
+# Inkscape 1.x syntax
+inkscape input.svg --export-type=eps --output-file=output.eps
+----
+
+Vectory generates appropriate commands automatically:
+
+[source,ruby]
+----
+class InkscapeWrapper
+  def command(input, output, format)
+    if modern?
+      # Inkscape 1.x syntax
+      [executable, input, "--export-type=#{format}",
+       "--output-file=#{output}"]
+    else
+      # Inkscape 0.x syntax
+      [executable, "--file=#{input}",
+       "--export-#{format}=#{output}"]
+    end
+  end
+end
+----
+
+== Conversion Methods
+
+=== SVG to Other Formats
+
+[source,ruby]
+----
+inkscape = Vectory::InkscapeWrapper.instance
+
+# SVG to PDF
+inkscape.svg_to_pdf("input.svg", "output.pdf")
+
+# SVG to EPS
+inkscape.svg_to_eps("input.svg", "output.eps")
+
+# SVG to PS
+inkscape.svg_to_ps("input.svg", "output.ps")
+
+# SVG to EMF
+inkscape.svg_to_emf("input.svg", "output.emf")
+----
+
+=== Other Formats to SVG
+
+[source,ruby]
+----
+# PDF to SVG
+inkscape.pdf_to_svg("input.pdf", "output.svg")
+
+# EPS to SVG
+inkscape.eps_to_svg("input.eps", "output.svg")
+
+# PS to SVG
+inkscape.ps_to_svg("input.ps", "output.svg")
+----
+
+== Dimension Queries
+
+=== Query Without Rendering
+
+[source,ruby]
+----
+inkscape = Vectory::InkscapeWrapper.instance
+
+# Query dimensions without full conversion
+width, height = inkscape.query_dimensions("diagram.svg")
+puts "Size: #{width}x#{height}"
+----
+
+=== Implementation
+
+Uses Inkscape's `--query-width` and `--query-height` options:
+
+[source,ruby]
+----
+def query_dimensions(input)
+  output = `#{executable} --query-width --query-height #{input}`
+  # Parse output to extract dimensions
+  parse_dimensions(output)
+end
+----
+
+== Error Handling
+
+=== Tool Not Found
+
+[source,ruby]
+----
+begin
+  inkscape = Vectory::InkscapeWrapper.instance
+  inkscape.version
+rescue Vectory::InkscapeNotFoundError => e
+  puts "Inkscape not found: #{e.message}"
+  puts "Install Inkscape or set INKSCAPE_PATH"
+end
+----
+
+=== Execution Failures
+
+[source,ruby]
+----
+begin
+  inkscape.svg_to_pdf("input.svg", "output.pdf")
+rescue Vectory::SystemCallError => e
+  puts "Conversion failed: #{e.message}"
+  puts "Exit code: #{e.exit_code}"
+end
+----
+
+== Platform-Specific Behavior
+
+=== macOS
+
+Vectory automatically sets `DISPLAY=""` to prevent timeouts:
+
+[source,ruby]
+----
+# Automatic on macOS
+ENV["DISPLAY"] = "" if RUBY_PLATFORM =~ /darwin/
+----
+
+=== Windows
+
+* Inkscape 1.3.1+ has EPS/PS issues
+* Use Inkscape 1.3.0 for best compatibility
+
+=== Linux
+
+Standard Unix behavior applies.
+
+== Configuration
+
+=== Custom Inkscape Path
+
+[source,bash]
+----
+# Set environment variable
+export INKSCAPE_PATH="/custom/path/to/inkscape"
+----
+
+[source,ruby]
+----
+# Or set in code
+ENV["INKSCAPE_PATH"] = "/custom/path/to/inkscape"
+inkscape = Vectory::InkscapeWrapper.instance
+puts inkscape.executable  # => "/custom/path/to/inkscape"
+----
+
+## Performance
+
+=== Singleton Efficiency
+
+[source,ruby]
+----
+# Single instance shared across conversions
+1000.times do
+  svg = Vectory::Eps.from_path("file#{i}.eps").to_svg
+end
+# InkscapeWrapper.instance created once, reused 1000 times
+----
+
+=== Version Detection Cost
+
+[source,ruby]
+----
+# Version detected once
+inkscape = Vectory::InkscapeWrapper.instance
+version1 = inkscape.version  # Detects: ~50ms
+version2 = inkscape.version  # Cached: ~0ms
+----
+
+== See Also
+
+* link:../architecture/[Architecture Overview] - Design patterns
+* link:ghostscript-wrapper/[Ghostscript Wrapper] - Other tool wrapper
+* link:../features/external-dependencies/[External Dependencies] - Tool requirements