vectory 0.8.0 → 0.8.1

data/docs/_config.yml

@@ -0,0 +1,179 @@
+# Jekyll configuration for Vectory documentation
+# Uses Just the Docs theme - https://just-the-docs.com/
+
+# Site settings
+title: Vectory
+description: Vector image conversion library for Ruby (EPS, PS, EMF, SVG)
+url: https://claricle.github.io
+baseurl: /vectory
+
+# Repository
+repository: claricle/vectory
+
+# Theme
+theme: just-the-docs
+remote_theme: just-the-docs/just-the-docs@v0.7.0
+color_scheme: light
+
+# AsciiDoc support
+asciidoc: {}
+asciidoctor:
+  attributes:
+    idprefix: ''
+    idseparator: '-'
+    source-highlighter: rouge
+    icons: font
+    experimental: true
+    sectanchors: true
+    linkattrs: true
+    sectnums: true
+    toc: left
+    toclevels: 3
+
+# Search configuration
+search_enabled: true
+search:
+  heading_level: 3
+  previews: 3
+  preview_words_before: 5
+  preview_words_after: 10
+  tokenizer_separator: /[\s/]+/
+  rel_url: true
+  button: true
+
+# Navigation
+nav_sort: case_insensitive
+nav_fold: true
+
+# External links
+aux_links:
+  "Source":
+    - "https://github.com/claricle/vectory"
+  "Report Issues":
+    - "https://github.com/claricle/vectory/issues"
+  "RubyGems":
+    - "https://rubygems.org/gems/vectory"
+
+aux_links_new_tab: true
+
+# Back to top
+back_to_top: true
+back_to_top_text: "Back to top"
+
+# Heading anchors
+heading_anchors: true
+
+# Footer
+footer_content: 'Copyright &copy; 2025 Ribose. Distributed under the <a href="https://github.com/claricle/vectory/blob/main/LICENSE">MIT License</a>.'
+
+# Footer last edit timestamp
+last_edit_timestamp: true
+last_edit_time_format: "%b %e %Y at %I:%M %p"
+
+# Enable code copy button
+enable_copy_code_button: true
+
+# Callouts
+callouts_level: quiet
+callouts:
+  highlight:
+    color: yellow
+  important:
+    title: Important
+    color: blue
+  new:
+    title: New
+    color: green
+  note:
+    title: Note
+    color: purple
+  warning:
+    title: Warning
+    color: red
+
+# Plugins
+plugins:
+  - jekyll-asciidoc
+  - jekyll-seo-tag
+  - jekyll-sitemap
+
+# Markdown settings (for any markdown files)
+markdown: kramdown
+kramdown:
+  input: GFM
+  hard_wrap: false
+  syntax_highlighter: rouge
+
+# Collections for organizing content
+collections:
+  # Core documentation pages (getting-started, interfaces, etc.)
+  pages:
+    permalink: "/:path/"
+    output: true
+
+  # Feature documentation
+  features:
+    permalink: "/:collection/:path/"
+    output: true
+
+  # Understanding/internal documentation
+  understanding:
+    permalink: "/:collection/:path/"
+    output: true
+
+  # Guides (task-oriented tutorials)
+  guides:
+    permalink: "/:collection/:path/"
+    output: true
+
+  # Reference documentation
+  reference:
+    permalink: "/:collection/:path/"
+    output: true
+
+# # Just the Docs collection configuration
+# just_the_docs:
+#   collections:
+#     pages:
+#       name: Pages
+#       nav_fold: false
+#     features:
+#       name: Features
+#       nav_fold: true
+#     understanding:
+#       name: Understanding
+#       nav_fold: true
+#     guides:
+#       name: Guides
+#       nav_fold: true
+#     reference:
+#       name: Reference
+#       nav_fold: true
+
+# Defaults
+defaults:
+  - scope:
+      path: ""
+      type: pages
+    values:
+      layout: default
+
+# Include additional files
+include:
+  - "*.adoc"
+
+# Exclude from processing
+exclude:
+  - Gemfile
+  - Gemfile.lock
+  - node_modules
+  - vendor
+  - .sass-cache
+  - .jekyll-cache
+  - .bundle
+  - README.md
+  - LICENSE
+  - .git
+  - .gitignore
+
+permalink: pretty

data/docs/features/conversion.adoc

@@ -0,0 +1,205 @@
+---
+layout: default
+title: Conversion Features
+parent: Features
+nav_order: 1
+---
+= Conversion Features
+
+How Vectory converts between vector image formats.
+
+== Overview
+
+Vectory supports pairwise conversion between EPS, PS, EMF, SVG, and PDF formats. Conversions are performed through external tools (Inkscape, Ghostscript, emf2svg) with a unified Ruby interface.
+
+== Conversion Paths
+
+=== Direct Conversions (via Inkscape)
+
+Inkscape handles direct conversions between SVG and other formats:
+
+* **SVG → EPS**: Export SVG to Encapsulated PostScript
+* **SVG → PS**: Export SVG to PostScript
+* **SVG → EMF**: Export SVG to Enhanced Metafile
+* **SVG → PDF**: Export SVG to PDF
+* **EPS → SVG**: Import EPS and export to SVG
+* **PS → SVG**: Import PS and export to SVG
+* **EMF → SVG**: Import EMF and export to SVG
+* **PDF → SVG**: Import PDF and export to SVG
+
+[source,ruby]
+----
+# Direct conversion examples
+svg_to_eps = Vectory::Svg.from_path("diagram.svg").to_eps
+eps_to_svg = Vectory::Eps.from_path("diagram.eps").to_svg
+----
+
+=== Two-Step Conversions (EPS/PS → SVG)
+
+EPS and PS files are converted to SVG through a PDF intermediate:
+
+1. **EPS/PS → PDF** (via Ghostscript): Preserves BoundingBox information
+2. **PDF → SVG** (via Inkscape): Converts PDF to SVG
+
+[source,ruby]
+----
+# Two-step conversion (automatic)
+eps = Vectory::Eps.from_path("diagram.eps")
+svg = eps.to_svg  # Internally: EPS → PDF → SVG
+----
+
+This two-step process ensures accurate dimension preservation from EPS/PS files.
+
+=== EMF Conversions (via emf2svg)
+
+EMF files are converted using the emf2svg gem:
+
+[source,ruby]
+----
+# EMF to SVG conversion
+emf = Vectory::Emf.from_path("chart.emf")
+svg = emf.to_svg  # Uses emf2svg gem
+----
+
+== Conversion Matrix
+
+[cols="2,1a,2a"]
+|===
+|Source|Target|Tool Used
+
+|SVG|EPS|Inkscape
+|SVG|PS|Inkscape
+|SVG|EMF|Inkscape
+|SVG|PDF|Inkscape
+
+|EPS|SVG|Ghostscript + Inkscape (two-step)
+|EPS|PDF|Ghostscript
+|EPS|PS|Via PDF intermediate
+
+|PS|SVG|Ghostscript + Inkscape (two-step)
+|PS|PDF|Ghostscript
+|PS|EPS|Via PDF intermediate
+
+|EMF|SVG|emf2svg gem
+|EMF|EPS|Via SVG intermediate
+|EMF|PS|Via SVG intermediate
+
+|PDF|SVG|Inkscape
+|PDF|EPS|Via SVG intermediate
+|PDF|PS|Via SVG intermediate
+|===
+
+== Quality Considerations
+
+=== BoundingBox Preservation
+
+Ghostscript preserves exact BoundingBox dimensions from EPS/PS files when converting to PDF:
+
+[source,ruby]
+----
+eps = Vectory::Eps.from_path("diagram.eps")
+pdf = eps.to_pdf  # BoundingBox preserved exactly
+----
+
+=== Font Handling
+
+* **Ghostscript**: Embeds fonts in PDF intermediate
+* **Inkscape**: May convert fonts to paths for SVG output
+
+=== Precision
+
+Vector graphics maintain full precision through conversions. Rasterization does not occur.
+
+== Performance
+
+=== Conversion Speed
+
+* **Direct conversions** (via Inkscape): ~1-3 seconds for typical files
+* **Two-step conversions** (EPS/PS → SVG): ~2-5 seconds (Ghostscript + Inkscape)
+* **EMF conversions** (via emf2svg): ~1-2 seconds
+
+=== Caching
+
+Vectory caches external tool information:
+
+* **Inkscape version**: Detected once per session
+* **Tool paths**: Discovered once and cached
+
+[source,ruby]
+----
+# Version detection is cached
+inkscape = Vectory::InkscapeWrapper.instance
+puts inkscape.version  # Cached result
+----
+
+== Common Conversion Tasks
+
+=== Batch Conversions
+
+Convert multiple files in a directory:
+
+[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
+----
+
+=== Content Conversion
+
+Convert from content string without writing to disk:
+
+[source,ruby]
+----
+eps_content = File.read("diagram.eps")
+svg = Vectory::Eps.from_content(eps_content).to_svg
+svg_content = svg.content
+----
+
+=== Dimension-Preserving Conversion
+
+Query dimensions before conversion:
+
+[source,ruby]
+----
+eps = Vectory::Eps.from_path("diagram.eps")
+width, height = eps.dimensions
+puts "Original size: #{width}x#{height}"
+
+svg = eps.to_svg
+svg_width, svg_height = svg.dimensions
+puts "Converted size: #{svg_width}x#{svg_height}"
+----
+
+== Error Handling
+
+=== Conversion Failures
+
+[source,ruby]
+----
+begin
+  svg = Vectory::Eps.from_path("invalid.eps").to_svg
+rescue Vectory::ConversionError => e
+  puts "Conversion failed: #{e.message}"
+  puts "Diagnostics: #{e.diagnostics}"
+end
+----
+
+=== Tool Not Found
+
+[source,ruby]
+----
+begin
+  svg = Vectory::Eps.from_path("diagram.eps").to_svg
+rescue Vectory::InkscapeNotFoundError => e
+  puts "Inkscape not found: #{e.message}"
+  puts "Install Inkscape or set INKSCAPE_PATH"
+end
+----
+
+== See Also
+
+* link:../understanding/conversion-pipeline/[Conversion Pipeline] - Internal conversion architecture
+* link:../guides/error-handling/[Error Handling Guide] - Common errors and solutions
+* link:../reference/api/[API Reference] - Conversion method documentation

data/docs/features/external-dependencies.adoc

@@ -0,0 +1,305 @@
+---
+layout: default
+title: External Dependencies
+parent: Features
+nav_order: 3
+---
+= External Dependencies
+
+Comprehensive guide to external tools and gems used by Vectory.
+
+== Overview
+
+Vectory relies on external tools for vector image conversion. This document explains each dependency, its purpose, and how Vectory integrates with it.
+
+== Tool Dependencies
+
+=== Inkscape
+
+**Purpose**: Primary conversion engine
+
+Inkscape handles most vector format conversions:
+
+* SVG ↔ EPS/PS/EMF/PDF conversions
+* Dimension queries
+* High-quality vector output
+
+**Version Requirements**:
+
+* **Recommended**: 1.0 or later
+* **Minimum**: 0.92
+* **Windows**: 1.3.0 (1.3.1+ has EPS/PS issues)
+
+**Integration**:
+
+[source,ruby]
+----
+# Singleton pattern for efficiency
+inkscape = Vectory::InkscapeWrapper.instance
+
+# Version detection
+puts inkscape.version  # => "1.3.0"
+
+# Executable path
+puts inkscape.executable  # => "/usr/bin/inkscape"
+
+# Version-specific command generation
+inkscape.modern?  # => true for 1.x, false for 0.x
+----
+
+**Version Compatibility**:
+
+Inkscape 0.x and 1.x use different command-line syntax. Vectory automatically detects the version and uses appropriate commands:
+
+[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 handles this automatically.
+
+**Known Issues**:
+
+* **Inkscape 1.3.1+ on Windows**: EPS/PS conversion issues
+* **macOS**: May timeout without `DISPLAY=""` environment variable
+
+**Installation**: See link:../../getting-started/installation/[Installation Guide]
+
+=== Ghostscript
+
+**Purpose**: EPS/PS to PDF conversion
+
+Ghostscript converts PostScript files to PDF while preserving:
+
+* BoundingBox information
+* Font embeddings
+* Vector paths
+
+**Version Requirements**:
+
+* **Recommended**: 9.0 or later
+* **Minimum**: 8.x (limited features)
+
+**Integration**:
+
+[source,ruby]
+----
+# Singleton pattern
+gs = Vectory::GhostscriptWrapper.instance
+
+# Executable path
+puts gs.executable  # => "/usr/bin/gs"
+
+# EPS to PDF conversion
+pdf = gs.eps_to_pdf("diagram.eps", "output.pdf")
+----
+
+**BoundingBox Preservation**:
+
+[source,ruby]
+----
+# Ghostscript preserves exact BoundingBox
+eps = Vectory::Eps.from_path("diagram.eps")
+pdf = eps.to_pdf  # BoundingBox preserved from EPS
+----
+
+**Installation**: See link:../../getting-started/installation/[Installation Guide]
+
+== Gem Dependencies
+
+=== emf2svg
+
+**Purpose**: EMF format support
+
+**Version**: ~> 1.0
+
+emf2svg provides EMF to SVG conversion without external tool dependencies.
+
+**Integration**:
+
+[source,ruby]
+----
+# Automatic conversion
+emf = Vectory::Emf.from_path("chart.emf")
+svg = emf.to_svg  # Uses emf2svg internally
+----
+
+**Features**:
+
+* Cross-platform EMF support
+* No external tool dependency
+* Native Ruby implementation
+
+=== moxml
+
+**Purpose**: XML/HTML parsing (Metanorma integration)
+
+**Version**: ~> 0.5
+
+moxml parses XML/HTML for link:../../guides/metanorma-integration/[Metanorma SVG mapping].
+
+**Integration**:
+
+[source,ruby]
+----
+# Used internally by SvgMapping
+require 'vectory/svg_mapping'
+
+mapping = Vectory::SvgMapping.new(xml_doc, base_uri)
+mapping.process  # Uses moxml for parsing
+----
+
+**Features**:
+
+* Link rewriting for embedded SVGs
+* ID preservation and suffixing
+* Namespace handling
+
+== Tool Discovery
+
+=== Automatic Discovery
+
+Vectory automatically discovers tools in system PATH:
+
+[source,ruby]
+----
+# Automatic discovery
+inkscape = Vectory::InkscapeWrapper.instance
+puts inkscape.executable  # => "/usr/bin/inkscape" (or similar)
+----
+
+=== Custom Paths
+
+Override with environment variables:
+
+[source,bash]
+----
+export INKSCAPE_PATH="/custom/path/to/inkscape"
+export GHOSTSCRIPT_PATH="/custom/path/to/gs"
+----
+
+Or in Ruby:
+
+[source,ruby]
+----
+ENV["INKSCAPE_PATH"] = "/custom/path/to/inkscape"
+inkscape = Vectory::InkscapeWrapper.instance
+----
+
+=== Verification
+
+Check if tools are available:
+
+[source,ruby]
+----
+# Check Inkscape
+if Vectory::InkscapeWrapper.instance.available?
+  puts "Inkscape found"
+else
+  puts "Inkscape not found"
+end
+
+# Check Ghostscript
+if Vectory::GhostscriptWrapper.instance.available?
+  puts "Ghostscript found"
+else
+  puts "Ghostscript not found"
+end
+----
+
+== Error Handling
+
+=== Tool Not Found
+
+[source,ruby]
+----
+begin
+  svg = Vectory::Eps.from_path("diagram.eps").to_svg
+rescue Vectory::InkscapeNotFoundError => e
+  puts "Inkscape not found: #{e.message}"
+  puts "Install Inkscape or set INKSCAPE_PATH"
+end
+----
+
+=== Version Incompatibility
+
+[source,ruby]
+----
+# Check version compatibility
+inkscape = Vectory::InkscapeWrapper.instance
+if inkscape.version < "0.92"
+  puts "Warning: Inkscape version is too old"
+end
+----
+
+=== Tool Execution Failures
+
+[source,ruby]
+----
+begin
+  svg = Vectory::Eps.from_path("diagram.eps").to_svg
+rescue Vectory::SystemCallError => e
+  puts "Tool execution failed: #{e.message}"
+  puts "Command: #{e.command}"
+  puts "Exit code: #{e.exit_code}"
+end
+----
+
+== Platform-Specific Notes
+
+=== macOS
+
+* **Inkscape**: May timeout without `DISPLAY=""`
+* **Fix**: Vectory automatically sets `DISPLAY=""` on macOS
+
+=== Windows
+
+* **Inkscape 1.3.1+**: EPS/PS conversion issues
+* **Fix**: Use Inkscape 1.3.0
+* **Process management**: Uses `taskkill` instead of `Process.kill`
+
+=== Linux
+
+* Standard Unix behavior
+* Ensure proper file permissions
+
+== CI/CD Integration
+
+Example GitHub Actions setup:
+
+[source,yaml]
+----
+- name: Install dependencies
+  run: |
+    sudo apt-get update
+    sudo apt-get install -y inkscape ghostscript
+  env:
+    DISPLAY: ""
+
+- name: Run tests
+  run: bundle exec rspec
+----
+
+## Troubleshooting
+
+**Inkscape timeout on macOS**::
+Set `DISPLAY=""` environment variable (automatic in Vectory)
+
+**Inkscape 1.3.1+ EPS issues on Windows**::
+Downgrade to Inkscape 1.3.0
+
+**Ghostscript not found**::
+Install Ghostscript or set `GHOSTSCRIPT_PATH`
+
+**emf2svg conversion fails**::
+Ensure emf2svg gem is installed: `gem install emf2svg`
+
+== See Also
+
+* link:../../getting-started/installation/[Installation Guide] - Detailed setup instructions
+* link:../understanding/inkscape-wrapper/[Inkscape Wrapper] - Technical details
+* link:../understanding/ghostscript-wrapper/[Ghostscript Wrapper] - Technical details