vectory 0.8.0 → 0.8.1

data/docs/index.adoc

@@ -0,0 +1,146 @@
+---
+layout: default
+title: Home
+nav_order: 1
+description: "Vectory: Vector image conversion library for Ruby"
+permalink: /
+---
+= Vectory Documentation
+:toc: macro
+:toclevels: 2
+
+[.lead]
+Vectory provides pairwise vector image conversion for Ruby applications, supporting EPS, PS, EMF, SVG, and PDF formats through integration with external conversion tools.
+
+toc::[]
+
+== Welcome
+
+Vectory helps you:
+
+* **Convert** between vector image formats (EPS, PS, EMF, SVG, PDF)
+* **Preserve** document metadata and bounding boxes
+* **Leverage** external tools (Inkscape, Ghostscript, emf2svg) for reliable conversions
+* **Process** images from files, content, or data URIs
+* **Query** image dimensions without full rendering
+
+== Quick Navigation
+
+=== By Your Role
+
+**Application Developer**::
+Start with link:features/ruby-api/[Ruby API] to integrate Vectory into your applications.
+
+**Metanorma User**::
+Start with link:guides/metanorma-integration[Metanorma Integration] for SVG mapping in XML documents.
+
+**Library Maintainer**::
+Start with link:understanding/architecture[Architecture] to understand Vectory's design.
+
+=== By Task
+
+**Convert EPS to SVG**::
+* link:getting-started/quick-start#converting-eps-to-svg[Quick Start: EPS to SVG]
+* link:features/conversion/[Conversion Features]
+
+**Batch process images**::
+* link:guides/batch-processing[Guide: Batch Processing]
+* link:reference/api[API Reference]
+
+**Handle format detection**::
+* link:features/format-detection[Format Detection]
+* link:guides/error-handling[Guide: Error Handling]
+
+**Query image dimensions**::
+* link:guides/dimension-query[Guide: Dimension Query]
+
+=== By Format
+
+link:features/formats/eps[**EPS (Encapsulated PostScript)**]::
+PostScript-based vector format with bounding box support
+
+link:features/formats/ps[**PS (PostScript)**]::
+Full PostScript document format
+
+link:features/formats/emf[**EMF (Enhanced Metafile)**]::
+Windows vector metafile format
+
+link:features/formats/svg[**SVG (Scalable Vector Graphics)**]::
+XML-based vector format for web graphics
+
+link:features/formats/pdf[**PDF (Portable Document Format)**]::
+Intermediate format for conversion pipeline
+
+== Learning Path
+
+=== Level 1: Get Started (5 minutes)
+
+. link:getting-started/installation[Install Vectory]
+. link:getting-started/quick-start[Try basic examples]
+. link:getting-started/core-concepts[Understand core concepts]
+
+=== Level 2: Learn Features (15 minutes)
+
+. link:features/conversion/[Conversion methods]
+. link:features/format-detection/[Automatic format detection]
+. link:features/dimension-query/[Dimension queries]
+
+=== Level 3: Understand Vectory (30 minutes)
+
+. link:understanding/architecture[Architecture overview]
+. link:understanding/external-dependencies/[External tools: Inkscape and Ghostscript]
+. link:understanding/conversion-pipeline/[Conversion pipeline]
+
+=== Level 4: Advanced Topics (As needed)
+
+* link:features/speed[Speed optimizations]
+* link:guides/metanorma-integration[Metanorma SVG mapping]
+* link:reference/error-handling[Error handling reference]
+
+== Popular Topics
+
+* link:features/conversion/[Supported Conversions] - All format-to-format conversion paths
+* link:reference/api[Public API] - Complete class and method reference
+* link:features/inkscape-version[Inkscape Version Handling] - Version 0.x vs 1.x+ compatibility
+* link:guides/error-handling[Error Handling] - Common errors and solutions
+* link:reference/configuration[Configuration Options] - Environment variables and settings
+
+== Requirements
+
+Vectory requires external tools for vector image conversion:
+
+=== Required Tools
+
+* **Inkscape** (version 0.92 or later recommended)
+** for SVG ↔ EPS/PS/EMF/PDF conversions
+** for dimension queries
+** Version 1.0+ recommended; 1.3.0 for Windows (1.3.1+ has EPS/PS issues)
+
+* **Ghostscript** (version 9.0 or later)
+** for EPS/PS → PDF conversion (bounding box preservation)
+** required for EPS and PS format support
+
+* **Ruby** (version 3.1 or later)
+** runtime environment for Vectory gem
+
+=== Ruby Gems (installed automatically)
+
+* **emf2svg** (~> 1.0)
+** for EMF → SVG conversion
+** provides Windows EMF format support
+
+* **moxml** (~> 0.5)
+** for XML/HTML parsing (Metanorma integration)
+
+See link:getting-started/installation[Installation] for detailed setup instructions including platform-specific requirements.
+
+== Getting Help
+
+**Found a bug?**::
+link:https://github.com/metanorma/vectory/issues[Report an issue on GitHub]
+
+**Have a question?**::
+Search this documentation or check link:reference/glossary[Glossary]
+
+**Want to contribute?**::
+See link:contributing[Contributing to Documentation]

data/docs/lychee.toml

@@ -0,0 +1,25 @@
+# Lychee configuration for Vectory documentation
+# Excludes certain patterns from link checking
+
+# Exclude common localhost patterns
+exclude = [
+  'http://localhost:*',
+  'http://127.0.0.1:*',
+  'file:///*',
+]
+
+# Exclude mailto: links
+exclude = [
+  'mailto:*',
+]
+
+# Exclude version-specific URLs that may break
+exclude = [
+  'https://github.com/*/releases/tag/*',  # GitHub release tags
+  'https://rubygems.org/gems/*/versions/*',  # RubyGem version history
+]
+
+# Allow certain redirects
+exclude = [
+  'https://example.com/*',  # Example domains used in docs
+]

data/docs/reference/api.adoc

@@ -0,0 +1,355 @@
+---
+layout: default
+title: Public API
+parent: Reference
+nav_order: 1
+---
+= API Reference
+
+Complete reference for Vectory's public API.
+
+== Format Classes
+
+=== Vectory::Image
+
+Base class for all image types.
+
+[source,ruby]
+----
+# Factory method (auto-detects format)
+image = Vectory::Image.from_path("diagram.eps")
+----
+
+**Methods**:
+
+* `Vectory::Image.from_path(path)` - Load from file path
+* `Vectory::Image.from_content(content)` - Load from content string
+* `Vectory::Image.from_datauri(uri)` - Load from data URI
+
+=== Vectory::Vector
+
+Abstract base class for vector formats. Inherits from `Vectory::Image`.
+
+[source,ruby]
+----
+# Conversion methods available on all vector formats
+vector.to_eps
+vector.to_ps
+vector.to_emf
+vector.to_svg
+vector.to_pdf
+----
+
+=== Vectory::Eps
+
+Encapsulated PostScript format.
+
+[source,ruby]
+----
+# Load EPS
+eps = Vectory::Eps.from_path("diagram.eps")
+
+# Convert to other formats
+svg = eps.to_svg
+pdf = eps.to_pdf
+ps = eps.to_ps
+----
+
+**Key Methods**:
+
+* `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
+* `#dimensions` - Get [width, height] in points
+* `#to_svg` - Convert to SVG
+* `#to_pdf` - Convert to PDF
+* `#to_eps` - Return self
+* `#to_ps` - Convert to PS
+* `#to_emf` - Convert to EMF (via SVG)
+* `#write(path = nil)` - Write to file
+* `#content` - Raw file content
+* `#initial_path` - Original file location
+* `#path` - Current write location
+
+=== Vectory::Ps
+
+PostScript format. Same API as `Vectory::Eps`.
+
+[source,ruby]
+----
+ps = Vectory::Ps.from_path("document.ps")
+svg = ps.to_svg
+----
+
+=== Vectory::Svg
+
+Scalable Vector Graphics format.
+
+[source,ruby]
+----
+svg = Vectory::Svg.from_path("drawing.svg")
+eps = svg.to_eps
+pdf = svg.to_pdf
+----
+
+=== Vectory::Emf
+
+Enhanced Metafile format.
+
+[source,ruby]
+----
+emf = Vectory::Emf.from_path("chart.emf")
+svg = emf.to_svg
+----
+
+Uses the emf2svg gem for conversion.
+
+=== Vectory::Pdf
+
+PDF format (used internally as intermediate format).
+
+[source,ruby]
+----
+pdf = Vectory::Pdf.from_path("document.pdf")
+svg = pdf.to_svg
+----
+
+## Factory Methods
+
+All format classes support these factory methods:
+
+### from_path
+
+Load from file path:
+
+[source,ruby]
+----
+eps = Vectory::Eps.from_path("diagram.eps")
+----
+
+### from_content
+
+Load from content string:
+
+[source,ruby]
+----
+content = File.read("diagram.eps")
+eps = Vectory::Eps.from_content(content)
+----
+
+### from_datauri
+
+Load from data URI:
+
+[source,ruby]
+----
+uri = "data:image/svg+xml;base64,PHN2Zy..."
+svg = Vectory::Svg.from_datauri(uri)
+----
+
+### from_node
+
+Load from XML node (Metanorma integration):
+
+[source,ruby]
+----
+# Used internally by Metanorma
+svg = Vectory::Svg.from_node(xml_node)
+----
+
+## Conversion Methods
+
+All format classes support conversion to any other format:
+
+[source,ruby]
+----
+# Convert EPS to SVG
+svg = Vectory::Eps.from_path("diagram.eps").to_svg
+
+# Convert SVG to EPS
+eps = Vectory::Svg.from_path("diagram.svg").to_eps
+
+# Convert EMF to SVG
+svg = Vectory::Emf.from_path("chart.emf").to_svg
+----
+
+## Properties
+
+### content
+
+Raw file content as string:
+
+[source,ruby]
+----
+eps = Vectory::Eps.from_path("diagram.eps")
+raw = eps.content
+----
+
+### initial_path
+
+Original file location (read-only):
+
+[source,ruby]
+----
+eps = Vectory::Eps.from_path("diagram.eps")
+puts eps.initial_path  # => "diagram.eps"
+----
+
+### path
+
+Current file location (raises error if not written):
+
+[source,ruby]
+----
+eps = Vectory::Eps.from_path("diagram.eps")
+
+# WRONG: raises error
+puts eps.path  # => NotWrittenToDiskError
+
+# CORRECT: write first
+eps.write("output.eps")
+puts eps.path  # => "output.eps"
+----
+
+### dimensions
+
+Image dimensions as [width, height]:
+
+[source,ruby]
+----
+eps = Vectory::Eps.from_path("diagram.eps")
+width, height = eps.dimensions
+puts "Size: #{width}x#{height}"
+----
+
+## Methods
+
+### write
+
+Write image to file:
+
+[source,ruby]
+----
+# Write to specific path
+svg.write("output.svg")
+
+# Write to temp directory
+svg.write
+----
+
+Returns the path to the written file.
+
+## Utility Classes
+
+### Vectory::FileMagic
+
+Format detection utilities:
+
+[source,ruby]
+----
+# Detect format from content
+content = File.read("unknown_file")
+format = Vectory::FileMagic.detect_format(content)
+
+# Format symbols: :eps, :ps, :emf, :svg, :unknown
+----
+
+### Vectory::InkscapeWrapper
+
+Singleton wrapper for Inkscape:
+
+[source,ruby]
+----
+inkscape = Vectory::InkscapeWrapper.instance
+
+# Check availability
+inkscape.available?
+
+# Get version
+inkscape.version
+
+# Get executable path
+inkscape.executable
+
+# Check if modern version (1.x)
+inkscape.modern?
+----
+
+### Vectory::GhostscriptWrapper
+
+Singleton wrapper for Ghostscript:
+
+[source,ruby]
+----
+gs = Vectory::GhostscriptWrapper.instance
+
+# Check availability
+gs.available?
+
+# Get executable path
+gs.executable
+----
+
+## Error Classes
+
+[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
+----
+
+## Usage Examples
+
+=== Basic Conversion
+
+[source,ruby]
+----
+require 'vectory'
+
+# EPS to SVG
+svg = Vectory::Eps.from_path("diagram.eps").to_svg
+svg.write("diagram.svg")
+----
+
+=== Batch Processing
+
+[source,ruby]
+----
+Dir["diagrams/*.eps"].each do |eps_file|
+  svg = Vectory::Eps.from_path(eps_file).to_svg
+  svg.write(eps_file.sub(".eps", ".svg"))
+end
+----
+
+=== Error Handling
+
+[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}"
+end
+----
+
+=== Dimension Query
+
+[source,ruby]
+----
+eps = Vectory::Eps.from_path("diagram.eps")
+width, height = eps.dimensions
+puts "Dimensions: #{width}x#{height}"
+----
+
+## See Also
+
+* link:../guides/error-handling/[Error Handling Guide] - Common errors and solutions
+* link:../understanding/architecture/[Architecture] - Design patterns
+* link:../features/conversion/[Conversion Features] - Conversion details

data/docs/reference/index.adoc

@@ -0,0 +1,189 @@
+---
+layout: default
+title: Reference
+nav_order: 7
+has_children: true
+---
+= Reference
+
+Complete API reference and technical documentation.
+
+== Overview
+
+This section provides comprehensive reference documentation for Vectory's public API, configuration options, and technical details.
+
+== API Reference
+
+link:api[**Public API**]::
+Complete class and method reference.
++
+`Vectory::Image`, `Vectory::Vector`, format-specific classes.
+
+link:factory-methods[**Factory Methods**]::
+Class methods for creating image objects.
++
+`from_path`, `from_content`, `from_datauri`, `from_node`.
+
+link:conversion-methods[**Conversion Methods**]::
+Format conversion methods.
++
+`to_eps`, `to_ps`, `to_emf`, `to_svg`, `to_pdf`.
+
+== Configuration
+
+link:environment-variables[**Environment Variables**]::
+All configurable environment variables.
++
+`VECTORY_LOG`, tool paths, timeout settings.
+
+link:tool-configuration[**External Tool Configuration**]::
+Inkscape and Ghostscript configuration.
++
+Version requirements, path discovery, compatibility.
+
+== Error Reference
+
+link:error-classes[**Error Classes**]::
+Complete exception hierarchy.
++
+`Vectory::Error`, `SystemCallError`, `NotWrittenToDiskError`, etc.
+
+link:error-messages[**Error Messages**]::
+Common error messages and their causes.
++
+Interpretation and resolution strategies.
+
+== Format Reference
+
+link:format-specs[**Format Specifications**]::
+Technical details for each supported format.
++
+EPS, PS, EMF, SVG, PDF specifications and limitations.
+
+link:magic-numbers[**Magic Numbers**]::
+File signatures used for format detection.
++
+Byte patterns for EPS, PS, EMF identification.
+
+== External Tools
+
+link:inkscape[**Inkscape**]::
+Inkscape requirements and compatibility.
++
+Version differences, command-line options, known issues.
+
+link:ghostscript[**Ghostscript**]::
+Ghostscript requirements and usage.
++
+EPS/PS to PDF conversion, bounding box handling.
+
+link:emf2svg[**emf2svg**]::
+emf2svg gem integration.
++
+EMF format support and limitations.
+
+== Platform Reference
+
+link:windows[**Windows Platform**]::
+Windows-specific behavior and requirements.
++
+Path handling, process management, tool compatibility.
+
+link:macos[**macOS Platform**]::
+macOS-specific configuration.
++
+Display environment, X11 requirements.
+
+link:linux[**Linux Platform**]::
+Linux-specific behavior.
++
+Package requirements, tool availability.
+
+== Quick Reference
+
+=== Class Hierarchy
+
+[source,text]
+----
+Vectory::Image (base class)
+    └── Vectory::Vector (abstract base)
+            ├── Vectory::Eps
+            ├── Vectory::Ps
+            ├── Vectory::Emf
+            ├── Vectory::Svg
+            └── Vectory::Pdf (intermediate format)
+----
+
+=== Factory Methods
+
+All format classes support:
+* `from_path(path)` - Load from file path
+* `from_content(content)` - Load from content string
+* `from_datauri(uri)` - Load from data URI
+* `from_node(node)` - Load from XML node (Metanorma)
+
+=== Conversion Methods
+
+All format classes support:
+* `to_eps` - Convert to EPS
+* `to_ps` - Convert to PS
+* `to_emf` - Convert to EMF
+* `to_svg` - Convert to SVG
+* `to_pdf` - Convert to PDF (intermediate)
+
+=== Properties
+
+* `content` - Raw file content (string)
+* `path` - Current file location (raises error if not written)
+* `initial_path` - Original file location
+* `dimensions` - Array of [width, height]
+* `write(path = nil)` - Write to file (temp directory if no path)
+
+== Method Signatures
+
+=== Vectory::Eps.from_path
+
+[source,ruby]
+----
+def self.from_path(path)
+  # @param path [String] Path to EPS file
+  # @return [Vectory::Eps] EPS image object
+end
+----
+
+=== Vectory::Eps#to_svg
+
+[source,ruby]
+----
+def to_svg
+  # @return [Vectory::Svg] Converted SVG image
+  # @raise [Vectory::ConversionError] If conversion fails
+end
+----
+
+=== Vectory::Eps#dimensions
+
+[source,ruby]
+----
+def dimensions
+  # @return [Array<Integer>] [width, height] in points
+  # @raise [Vectory::InkscapeQueryError] If query fails
+end
+----
+
+=== Vectory::Eps#write
+
+[source,ruby]
+----
+def write(path = nil)
+  # @param path [String, nil] Output path (uses temp if nil)
+  # @return [String] Path to written file
+  # @raise [Vectory::SystemCallError] If write fails
+end
+----
+
+== See Also
+
+* link:../features/[Features] - Feature documentation
+* link:../guides/[Guides] - How-to guides
+* link:../understanding/[Understanding] - Internal architecture