vectory 0.7.8 → 0.8.1

data/docs/features/format-detection.adoc

@@ -0,0 +1,173 @@
+---
+layout: default
+title: Format Detection
+parent: Features
+nav_order: 2
+---
+= Format Detection
+
+How Vectory automatically detects vector image formats.
+
+== Overview
+
+Vectory can automatically detect image formats from file content, not just file extensions. This ensures reliable format identification even when files have incorrect or missing extensions.
+
+== Detection Methods
+
+=== Magic Number Detection
+
+Vectory uses file signatures (magic numbers) to identify binary formats:
+
+[cols="1,2a"]
+|===
+|Format|Magic Number
+
+|EPS
+|%!PS-Adobe-3.0 EPSF-3.0
+
+|PS
+|%!PS-Adobe-3.0 (without EPSF)
+
+|EMF
+|\x01\x00\x00\x00 (EMF header signature)
+|===
+
+[source,ruby]
+----
+# Automatic detection from file
+image = Vectory::Image.from_path("unknown_file")
+puts image.class  # => Vectory::Eps, Vectory::Ps, Vectory::Emf, etc.
+----
+
+=== Content Inspection
+
+SVG files are detected by XML content inspection:
+
+[source,ruby]
+----
+# Detects <svg> tag in XML content
+svg = Vectory::Image.from_path("no_extension_file")
+puts svg.class  # => Vectory::Svg
+----
+
+=== Explicit Factory Methods
+
+You can also explicitly specify the format:
+
+[source,ruby]
+----
+# Explicit format selection
+eps = Vectory::Eps.from_path("diagram")
+svg = Vectory::Svg.from_path("diagram")
+----
+
+== Format Detection API
+
+=== FileMagic.detect_format
+
+Detect format from content string:
+
+[source,ruby]
+----
+content = File.read("unknown_file")
+format = Vectory::FileMagic.detect_format(content)
+
+case format
+when :eps
+  puts "This is an EPS file"
+when :ps
+  puts "This is a PS file"
+when :emf
+  puts "This is an EMF file"
+when :svg
+  puts "This is an SVG file"
+else
+  puts "Unknown format"
+end
+----
+
+=== from_path Auto-Detection
+
+[source,ruby]
+----
+# Auto-detects format from file path and content
+image = Vectory::Image.from_path("diagram")
+
+if image.is_a?(Vectory::Eps)
+  puts "Detected EPS format"
+elsif image.is_a?(Vectory::Svg)
+  puts "Detected SVG format"
+end
+----
+
+== Detection Priority
+
+Vectory uses a cascading detection strategy:
+
+. **Magic numbers** for EPS, PS, EMF (most reliable)
+. **XML content inspection** for SVG (looks for `<svg>` tag)
+. **File extension** as fallback (`.eps`, `.ps`, `.emf`, `.svg`)
+
+[source,ruby]
+----
+# Detection priority example
+content = "%!PS-Adobe-3.0 EPSF-3.0"
+format = Vectory::FileMagic.detect_format(content)
+puts format  # => :eps (magic number detected)
+----
+
+== Edge Cases
+
+=== EPS vs PS Detection
+
+The presence of `EPSF-3.0` distinguishes EPS from PS:
+
+[source,ruby]
+----
+eps_content = "%!PS-Adobe-3.0 EPSF-3.0"
+ps_content = "%!PS-Adobe-3.0"
+
+Vectory::FileMagic.detect_format(eps_content)  # => :eps
+Vectory::FileMagic.detect_format(ps_content)    # => :ps
+----
+
+=== Invalid Files
+
+[source,ruby]
+----
+begin
+  image = Vectory::Image.from_path("corrupt_file")
+rescue Vectory::ParsingError => e
+  puts "Failed to detect format: #{e.message}"
+end
+----
+
+=== Empty Files
+
+[source,ruby]
+----
+empty_content = ""
+format = Vectory::FileMagic.detect_format(empty_content)
+puts format  # => :unknown
+----
+
+== Performance
+
+Format detection is fast and efficient:
+
+* **Magic number check**: First few bytes only
+* **XML inspection**: Checks for `<svg>` tag
+* **No full file parsing**: Detection is separate from conversion
+
+[source,ruby]
+----
+# Detection is fast even for large files
+large_eps = Vectory::Image.from_path("100mb_diagram.eps")
+# Detection completes in milliseconds
+----
+
+== See Also
+
+* link:conversion/[Conversion Features] - What happens after detection
+* link:../understanding/magic-numbers/[Magic Numbers] - Technical details
+* link:../reference/api/[API Reference] - Detection methods

data/docs/features/index.adoc

@@ -0,0 +1,205 @@
+---
+layout: default
+title: Features
+nav_order: 4
+has_children: true
+---
+= Features
+
+Explore Vectory's conversion capabilities and format support.
+
+== Overview
+
+Vectory provides pairwise vector image conversion between EPS, PS, EMF, SVG, and PDF formats. This section covers all supported formats, conversion methods, and special features.
+
+== Supported Formats
+
+=== Input Formats
+
+link:formats/eps[**EPS (Encapsulated PostScript)**]::
+PostScript-based vector format with bounding box support.
+
+link:formats/ps[**PS (PostScript)**]::
+Full PostScript document format.
+
+link:formats/emf[**EMF (Enhanced Metafile)**]::
+Windows vector metafile format.
+
+link:formats/svg[**SVG (Scalable Vector Graphics)**]::
+XML-based vector format for web graphics.
+
+=== Output Formats
+
+All input formats can be converted to:
+* link:formats/eps[EPS]
+* link:formats/ps[PS]
+* link:formats/emf[EMF]
+* link:formats/svg[SVG]
+* link:formats/pdf[PDF] (intermediate format)
+
+== Key Features
+
+link:conversion/[**Pairwise Conversion**]::
+Convert any supported format to any other format.
++
+Transparent conversion through PDF intermediate format when needed.
+
+link:format-detection/[**Automatic Format Detection**]::
+Detect image format from file content, not just extension.
++
+Uses magic numbers for EPS, PS, EMF; content inspection for SVG.
+
+link:dimension-query/[**Dimension Queries**]::
+Query image dimensions without full rendering.
++
+Fast dimension retrieval using external tools.
+
+link:content-sources/[**Multiple Input Sources**]::
+Load images from files, content strings, or data URIs.
+
+link:speed/[**Performance**]::
+Efficient caching and external tool management.
++
+Singleton pattern for Inkscape wrapper, version detection.
+
+== Conversion Paths
+
+Vectory uses different external tools depending on the source and target formats.
+
+=== Direct Conversions (via Inkscape)
+
+* **SVG → EPS/PS/EMF/PDF** (via Inkscape export)
+* **EPS/PS/EMF/PDF → SVG** (via Inkscape import)
+
+Inkscape handles direct conversions to and from SVG format.
+
+=== Direct Conversions (via emf2svg)
+
+* **EMF → SVG** (via emf2svg gem)
+
+The emf2svg gem provides native EMF to SVG conversion without external tool dependencies.
+
+=== Two-Step Conversions (via Ghostscript + Inkscape)
+
+* **EPS → PDF → SVG** (Ghostscript for EPS→PDF, Inkscape for PDF→SVG)
+* **PS → PDF → SVG** (Ghostscript for PS→PDF, Inkscape for PDF→SVG)
+
+This two-step process preserves BoundingBox information from EPS/PS files.
+
+=== Conversion Tool Matrix
+
+[cols="2,2a"]
+|===
+|Conversion|Tool Used
+
+|SVG ↔ EPS
+|Inkscape
+
+|SVG ↔ PS
+|Inkscape
+
+|SVG ↔ EMF
+|Inkscape (SVG→EMF), emf2svg (EMF→SVG)
+
+|SVG ↔ PDF
+|Inkscape
+
+|EPS → PDF
+|Ghostscript (preserves BoundingBox)
+
+|PS → PDF
+|Ghostscript (preserves BoundingBox)
+
+|EPS/PS → SVG
+|Ghostscript + Inkscape (two-step)
+
+|EMF → SVG
+|emf2svg gem
+|===
+
+See link:conversion/[Conversion Features] for detailed conversion paths and options.
+
+== External Tool Integration
+
+Vectory relies on external tools for actual conversion operations. The library provides a unified Ruby interface while delegating the heavy lifting to specialized tools.
+
+link:inkscape-version/[**Inkscape Version Handling**]::
+Automatic version detection for 0.x vs 1.x+ syntax differences.
++
+Vectory detects the installed Inkscape version and uses appropriate command-line syntax.
+
+link:external-dependencies/[**External Dependencies**]::
+Comprehensive guide to all external tools and gems.
++
+* **Inkscape** - Primary conversion engine for SVG, EPS, PS, EMF, PDF
+* **Ghostscript** - EPS/PS to PDF conversion with BoundingBox preservation
+* **emf2svg** - EMF format support via Ruby gem
+* **moxml** - XML/HTML parsing for Metanorma integration
+
+link:timeout-handling/[**Timeout and Error Handling**]::
+Robust error handling for external tool failures.
++
+Automatic tool discovery, timeout management, platform-specific process handling.
+
+== Special Features
+
+link:metadata/[**Metadata Preservation**]::
+Preserves document metadata during conversions.
+
+link:bounding-box/[**Bounding Box Handling**]::
+Maintains EPS/PS bounding box information through conversion pipeline.
+
+link:metanorma-integration/[**Metanorma Integration**]::
+SVG mapping features for XML/HTML document processing.
++
+Link rewriting, ID preservation, namespace handling.
+
+== Quick Examples
+
+=== Convert EPS to SVG
+
+[source,ruby]
+----
+require 'vectory'
+
+svg = Vectory::Eps.from_path("diagram.eps").to_svg
+svg.write("diagram.svg")
+----
+
+=== Detect Format from Content
+
+[source,ruby]
+----
+content = File.read("unknown_file")
+format = Vectory::FileMagic.detect_format(content)
+# => :eps, :ps, :emf, :svg, or :unknown
+----
+
+=== Query Dimensions
+
+[source,ruby]
+----
+eps = Vectory::Eps.from_path("diagram.eps")
+width, height = eps.dimensions
+puts "Size: #{width}x#{height}"
+----
+
+== Common Use Cases
+
+**Batch conversion**::
+Use link:guides/batch-processing[batch processing guide] for multiple files.
+
+**Format validation**::
+Use link:format-detection[format detection] to verify file types.
+
+**Dimension extraction**::
+Use link:dimension-query[dimension queries] for fast size retrieval.
+
+**Metanorma documents**::
+Use link:metanorma-integration[SVG mapping] for XML integration.
+
+== See Also
+
+* link:../understanding/[Understanding Vectory] - How features work internally
+* link:../guides/[Guides] - Practical how-to guides
+* link:../reference/[Reference] - Complete API documentation

data/docs/getting-started/core-concepts.adoc

@@ -0,0 +1,214 @@
+---
+layout: default
+title: Core Concepts
+parent: Getting Started
+nav_order: 3
+---
+
+Understanding Vectory's architecture and design principles.
+
+== Purpose
+
+This section explains Vectory's core concepts including its class hierarchy, conversion pipeline, and design patterns. Understanding these concepts will help you use Vectory effectively.
+
+== Class Hierarchy
+
+Vectory uses an object-oriented, inheritance-based architecture:
+
+[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`, which provides common functionality for vector image manipulation.
+
+== Factory Methods
+
+All format classes support four factory methods for creating image objects:
+
+=== from_path
+
+Load from a file path:
+
+[source,ruby]
+----
+eps = Vectory::Eps.from_path("diagram.eps")
+----
+
+=== from_content
+
+Load from a content string:
+
+[source,ruby]
+----
+content = File.read("diagram.eps")
+eps = Vectory::Eps.from_content(content)
+----
+
+=== from_datauri
+
+Load from a data URI:
+
+[source,ruby]
+----
+uri = "data:image/svg+xml;base64,PHN2Zy..."
+svg = Vectory::Svg.from_datauri(uri)
+----
+
+=== from_node
+
+Load from an XML node (Metanorma integration):
+
+[source,ruby]
+----
+# Used internally by Metanorma's SVG mapping
+----
+
+== Conversion Methods
+
+Each format class can convert to any other format:
+
+[source,ruby]
+----
+# Convert EPS to SVG
+svg = Vectory::Eps.from_path("diagram.eps").to_svg
+
+# Convert SVG to EMF
+emf = Vectory::Svg.from_path("drawing.svg").to_emf
+
+# Convert EMF to PDF
+pdf = Vectory::Emf.from_path("chart.emf").to_pdf
+----
+
+== Conversion Pipeline
+
+Vectory uses a flexible conversion pipeline:
+
+=== Direct Conversions
+
+Some conversions are direct:
+* **SVG → EPS/PS/EMF/PDF**: Via Inkscape
+* **EMF → SVG**: Via emf2svg
+
+=== Two-Step Conversions
+
+Other conversions use an intermediate PDF format:
+* **EPS/PS → PDF → SVG**: Via Ghostscript + Inkscape
+
+This two-step conversion ensures:
+* BoundingBox preservation from EPS/PS
+* High-quality output from Inkscape
+
+== Properties
+
+All image objects have these properties:
+
+[source,ruby]
+----
+eps = Vectory::Eps.from_path("diagram.eps")
+
+# Raw content
+content = eps.content
+
+# Original file location
+original_path = eps.initial_path
+
+# Current file location (raises error if not written)
+current_path = eps.path  # => NotWrittenToDiskError
+
+# Image dimensions
+width, height = eps.dimensions
+
+# Write to file
+output_path = eps.write("output.eps")
+----
+
+== File System Operations
+
+Vectory distinguishes between two file paths:
+
+* **`initial_path`**: Where the file was originally loaded from (read-only)
+* **`path`**: Where the file is currently written (raises error if not yet written)
+
+[source,ruby]
+----
+eps = Vectory::Eps.from_path("input.eps")
+puts eps.initial_path  # => "input.eps"
+
+puts eps.path  # => raises NotWrittenToDiskError
+
+eps.write("output.eps")
+puts eps.path  # => "output.eps"
+----
+
+Writing without arguments uses a temporary directory:
+
+[source,ruby]
+----
+eps = Vectory::Eps.from_path("input.eps")
+temp_path = eps.write  # => "/tmp/vectory_20250119..."
+----
+
+== Format Detection
+
+Vectory detects formats using:
+* **Magic numbers** for EPS, PS, EMF (file signatures)
+* **Content inspection** for SVG (XML structure)
+* **File extension** as fallback
+
+[source,ruby]
+----
+# Auto-detect from file
+image = Vectory::Image.from_path("unknown_file")
+puts image.class  # => Vectory::Eps, Vectory::Svg, etc.
+
+# Detect format from content
+content = File.read("unknown_file")
+format = Vectory::FileMagic.detect_format(content)
+puts format  # => :eps, :ps, :emf, :svg, or :unknown
+----
+
+== Error Handling
+
+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
+----
+
+== External Tool Integration
+
+Vectory uses the https://en.wikipedia.org/wiki/Singleton_pattern[Singleton pattern] for external tool wrappers:
+
+[source,ruby]
+----
+# Shared Inkscape instance across conversions
+inkscape = Vectory::InkscapeWrapper.instance
+
+# Version is cached
+puts inkscape.version  # => "1.3.0" (cached)
+
+# Tool discovery is done once
+puts inkscape.executable  # => "/usr/bin/inkscape"
+----
+
+This design improves performance and ensures consistent behavior.
+
+== Next Steps
+
+. Explore link:../features/[Features] for supported formats and conversions
+. Check link:../guides/[Guides] for practical examples
+. See link:../understanding/[Understanding] for internal architecture details

data/docs/getting-started/index.adoc

@@ -0,0 +1,37 @@
+---
+layout: default
+title: Getting Started
+nav_order: 2
+has_children: true
+---
+= Getting Started
+
+Get up and running with Vectory quickly.
+
+== Overview
+
+This section will help you install Vectory and perform your first vector image conversions.
+
+== Prerequisites
+
+Before installing Vectory, ensure you have the following:
+
+* **Ruby** 3.1 or later
+* **Inkscape** 0.92 or later (recommended: 1.x)
+* **Ghostscript** (for EPS/PS conversions)
+
+See link:installation[Installation] for detailed setup instructions.
+
+== Quick Start Path
+
+. link:installation[Install Vectory]
+. link:quick-start[Try basic conversions]
+. link:core-concepts[Understand core concepts]
+
+== Next Steps
+
+After getting started, explore:
+
+* link:../features/[Features] - All supported formats and conversions
+* link:../guides/[Guides] - Practical how-to guides
+* link:../reference/[Reference] - Complete API documentation