postsvg 0.1.0 → 0.3.0

data/docs/cli-reference/version-command.adoc

@@ -0,0 +1,296 @@
+= version Command
+:page-nav_order: 4
+:page-parent: CLI Reference
+
+== Purpose
+
+The `version` command displays the current version of Postsvg installed on your system. This is useful for troubleshooting, verifying installations, and ensuring compatibility.
+
+== References
+
+* link:../index.adoc[Documentation Home]
+* link:../cli-reference.adoc[CLI Reference Overview]
+* link:convert-command.adoc[convert Command]
+* link:../getting-started/installation.adoc[Installation Guide]
+
+== Concepts
+
+**Semantic Versioning**:: Version numbering scheme (MAJOR.MINOR.PATCH) used by Postsvg.
+
+**Gem Version**:: The version of the Postsvg gem installed via RubyGems.
+
+## Command Syntax
+
+[source,sh]
+----
+postsvg version <1>
+----
+<1> Display Postsvg version number
+
+**Arguments:** None
+
+**Options:** None
+
+**Exit Code:** Always `0` (success)
+
+**Source:**
+[`lib/postsvg/cli.rb:145-148`](../../lib/postsvg/cli.rb:145)
+
+== Basic Usage
+
+=== Display Version
+
+[source,sh]
+----
+$ postsvg version
+postsvg version 0.1.0
+----
+
+.Check version after installation
+[example]
+====
+[source,sh]
+----
+# After installing
+$ gem install postsvg
+
+# Verify installation
+$ postsvg version
+postsvg version 0.1.0
+
+# Confirm command is accessible
+$ which postsvg
+/usr/local/lib/ruby/gems/3.2.0/bin/postsvg
+----
+====
+
+== Version Information
+
+=== Version Number Format
+
+Postsvg follows Semantic Versioning (SemVer):
+
+[source]
+----
+MAJOR.MINOR.PATCH
+  │     │     │
+  │     │     └─ Bug fixes
+  │     └─ New features (backwards compatible)
+  └─ Breaking changes
+----
+
+**Example Versions:**
+* `0.1.0` - Initial release
+* `0.1.1` - Bug fix release
+* `0.2.0` - New feature release
+* `1.0.0` - First stable release
+
+=== Version Checking in Scripts
+
+[source,sh]
+----
+#!/bin/bash
+# check-version.sh
+
+VERSION=$(postsvg version | cut -d' ' -f3)
+REQUIRED="0.1.0"
+
+if [ "$VERSION" != "$REQUIRED" ]; then
+  echo "Warning: Expected version $REQUIRED, found $VERSION"
+  exit 1
+fi
+
+echo "✓ Correct version installed"
+----
+
+.Minimum version check
+[example]
+====
+[source,sh]
+----
+#!/bin/bash
+# require-minimum-version.sh
+
+VERSION=$(postsvg version | awk '{print $3}')
+MAJOR=$(echo $VERSION | cut -d. -f1)
+MINOR=$(echo $VERSION | cut -d. -f2)
+
+if [ $MAJOR -eq 0 ] && [ $MINOR -lt 1 ]; then
+  echo "Error: Postsvg 0.1.0 or higher required"
+  echo "Found: $VERSION"
+  exit 1
+fi
+
+echo "✓ Version check passed: $VERSION"
+----
+====
+
+## Troubleshooting
+
+=== Command Not Found
+
+**Problem:**
+[source]
+----
+$ postsvg version
+bash: postsvg: command not found
+----
+
+**Solutions:**
+
+1. **Check if gem is installed:**
+   [source,sh]
+   ----
+   gem list postsvg
+   ----
+
+2. **Install if missing:**
+   [source,sh]
+   ----
+   gem install postsvg
+   ----
+
+3. **Add to PATH:**
+   [source,sh]
+   ----
+   export PATH="$PATH:$(gem environment gemdir)/bin"
+   ----
+
+=== Wrong Version
+
+**Problem:**
+Need different version than installed.
+
+**Solutions:**
+
+1. **Check installed versions:**
+   [source,sh]
+   ----
+   gem list postsvg
+   ----
+
+2. **Install specific version:**
+   [source,sh]
+   ----
+   gem install postsvg -v '0.2.0'
+   ----
+
+3. **Update to latest:**
+   [source,sh]
+   ----
+   gem update postsvg
+   ----
+
+4. **Uninstall old versions:**
+   [source,sh]
+   ----
+   gem uninstall postsvg --version '0.1.0'
+   ----
+
+== Usage Examples
+
+=== System Information Script
+
+[source,sh]
+----
+#!/bin/bash
+# system-info.sh
+
+echo "System Information for Postsvg"
+echo "=============================="
+echo "Postsvg version: $(postsvg version | awk '{print $3}')"
+echo "Ruby version: $(ruby -v)"
+echo "Gem directory: $(gem environment gemdir)"
+echo "Install location: $(which postsvg)"
+echo "=============================="
+----
+
+=== Compatibility Check
+
+[source,sh]
+----
+#!/bin/bash
+# compat-check.sh
+
+PS_VERSION=$(postsvg version | awk '{print $3}')
+RUBY_VERSION=$(ruby -e 'puts RUBY_VERSION')
+
+echo "Environment Check:"
+echo "  Postsvg: $PS_VERSION"
+echo "  Ruby: $RUBY_VERSION"
+
+# Check Ruby version >= 2.7
+RUBY_MAJOR=$(echo $RUBY_VERSION | cut -d. -f1)
+RUBY_MINOR=$(echo $RUBY_VERSION | cut -d. -f2)
+
+if [ $RUBY_MAJOR -lt 2 ] || ([ $RUBY_MAJOR -eq 2 ] && [ $RUBY_MINOR -lt 7 ]); then
+  echo "✗ Ruby 2.7 or higher required"
+  exit 1
+fi
+
+echo "✓ Environment compatible"
+----
+
+=== Version in Help
+
+The version is also shown in help output:
+
+[source,sh]
+----
+$ postsvg help
+Commands:
+  postsvg batch INPUT_DIR [OUTPUT_DIR]  # Convert all PS/EPS files in a directory
+  postsvg check FILES                   # Validate PostScript/EPS files
+  postsvg convert INPUT [OUTPUT]        # Convert PostScript/EPS file to SVG
+  postsvg help [COMMAND]                # Describe available commands...
+  postsvg version                       # Show version
+
+$ postsvg --version
+postsvg version 0.1.0
+----
+
+== Related Information
+
+=== Gem Information
+
+Get more details about the Postsvg gem:
+
+[source,sh]
+----
+# Gem info
+$ gem info postsvg
+
+# All versions installed
+$ gem list postsvg
+
+# Gem specification
+$ gem specification postsvg
+
+# Gem dependencies
+$ gem dependency postsvg
+----
+
+=== Version in Ruby Code
+
+Access version programmatically:
+
+[source,ruby]
+----
+require 'postsvg'
+
+puts Postsvg::VERSION
+# Output: 0.1.0
+----
+
+## Next Steps
+
+* Return to link:../index.adoc[Documentation Home]
+* Review link:convert-command.adoc[convert command]
+* See link:batch-command.adoc[batch command]
+* Check link:check-command.adoc[check command]
+
+== Bibliography
+
+* link:../getting-started/installation.adoc[Installation Guide]
+* link:https://semver.org/[Semantic Versioning Specification]
+* link:https://rubygems.org/gems/postsvg[Postsvg on RubyGems]

data/docs/cli-reference.adoc

@@ -0,0 +1,317 @@
+= CLI Reference
+:page-nav_order: 5
+
+== Purpose
+
+This section provides comprehensive documentation for the Postsvg command-line interface. Learn how to use the `postsvg` command for file conversion, batch processing, and validation.
+
+== References
+
+* link:index.adoc[Documentation Home]
+* link:getting-started.adoc[Getting Started Guide]
+* link:api-reference.adoc[API Reference]
+* link:validation.adoc[Validation System]
+
+== Concepts
+
+**CLI Command**:: A command-line tool that performs PostScript to SVG conversion without writing Ruby code.
+
+**Subcommands**:: Different operations available through the CLI: convert, batch, check, version.
+
+**Options**:: Flags that modify the behavior of CLI commands (e.g., `--strict`, `--verbose`).
+
+**Exit Codes**:: Return values indicating success (0) or failure (1) for scripting and automation.
+
+== CLI Reference Topics
+
+link:cli-reference/convert-command.adoc[**convert Command**]::
+Convert a single PostScript or EPS file to SVG format.
+
+link:cli-reference/batch-command.adoc[**batch Command**]::
+Convert all PS/EPS files in a directory to SVG format.
+
+link:cli-reference/check-command.adoc[**check Command**]::
+Validate PostScript/EPS files with multiple validation levels and output formats.
+
+link:cli-reference/version-command.adoc[**version Command**]::
+Display the Postsvg version number.
+
+link:cli-reference/cli-options.adoc[**CLI Options Reference**]::
+Complete reference for all CLI options and flags.
+
+== Quick Reference
+
+=== Installation Verification
+
+[source,sh]
+----
+# Check installation
+postsvg version
+
+# Get help
+postsvg help
+postsvg help convert
+postsvg help batch
+postsvg help check
+----
+
+=== Convert Command
+
+[source,sh]
+----
+# Convert to file
+postsvg convert input.eps output.svg
+
+# Convert to stdout
+postsvg convert input.ps
+
+# Convert with strict mode
+postsvg convert --strict input.eps output.svg
+----
+
+=== Batch Command
+
+[source,sh]
+----
+# Convert all files in directory
+postsvg batch ps_files/
+
+# Convert to different directory
+postsvg batch ps_files/ svg_files/
+
+# Batch with strict mode
+postsvg batch --strict ps_files/ svg_files/
+----
+
+=== Check Command
+
+[source,sh]
+----
+# Basic validation
+postsvg check document.ps
+
+# Validation with specific level
+postsvg check --level=syntax document.ps
+postsvg check --level=semantic document.ps
+postsvg check --level=full document.ps
+
+# Multiple files
+postsvg check file1.ps file2.eps file3.ps
+
+# JSON output for CI/CD
+postsvg check --format=json --no-color document.ps
+
+# Fail fast on first error
+postsvg check --fail-fast *.ps
+
+# Validate EPS version
+postsvg check --eps-version=3.0 diagram.eps
+----
+
+== Common Usage Patterns
+
+=== Basic Workflow
+
+[source,sh]
+----
+# 1. Validate the file
+postsvg check document.ps
+
+# 2. Convert if valid
+postsvg convert document.ps document.svg
+----
+
+=== Batch Processing
+
+[source,sh]
+----
+# Process entire directory
+postsvg batch input/ output/
+
+# Check status
+echo $?  # 0 = success, 1 = failure
+----
+
+=== CI/CD Integration
+
+[source,sh]
+----
+#!/bin/bash
+# Validation script for CI/CD
+
+# Validate all PostScript files
+postsvg check --format=json --no-color \
+  --level=full --fail-fast *.ps
+
+# Exit with validation status
+exit $?
+----
+
+=== Scripted Conversion
+
+[source,sh]
+----
+#!/bin/bash
+# Convert all EPS files to SVG
+
+for file in *.eps; do
+  basename="${file%.eps}"
+  postsvg convert "$file" "${basename}.svg"
+
+  if [ $? -eq 0 ]; then
+    echo "✓ Converted $file"
+  else
+    echo "✗ Failed $file"
+  fi
+done
+----
+
+== Exit Codes
+
+All Postsvg commands use standard Unix exit codes:
+
+[cols="1,4"]
+|===
+| Code | Meaning
+
+| `0`
+| Success - operation completed without errors
+
+| `1`
+| Failure - operation failed or validation errors found
+|===
+
+.Using exit codes in scripts
+[example]
+====
+[source,sh]
+----
+postsvg check document.ps
+if [ $? -eq 0 ]; then
+  echo "File is valid"
+  postsvg convert document.ps document.svg
+else
+  echo "File has errors"
+  exit 1
+fi
+----
+====
+
+== Output Formats
+
+=== Convert Command Output
+
+**To file:**
+[source,sh]
+----
+$ postsvg convert input.eps output.svg
+Successfully converted input.eps to output.svg
+----
+
+**To stdout:**
+[source,sh]
+----
+$ postsvg convert input.ps
+<svg xmlns="http://www.w3.org/2000/svg"...>
+  ...
+</svg>
+----
+
+=== Check Command Output
+
+**Text format (default):**
+[source,sh]
+----
+$ postsvg check document.ps
+✓ document.ps - Valid PostScript file
+  File type: PostScript
+  Validation level: semantic
+  No errors found
+----
+
+**JSON format:**
+[source,sh]
+----
+$ postsvg check --format=json document.ps
+{
+  "filename": "document.ps",
+  "valid": true,
+  "file_type": "PostScript",
+  "errors": [],
+  "warnings": [],
+  "info": []
+}
+----
+
+**YAML format:**
+[source,sh]
+----
+$ postsvg check --format=yaml document.ps
+---
+filename: document.ps
+valid: true
+file_type: PostScript
+errors: []
+warnings: []
+info: []
+----
+
+=== Batch Command Output
+
+[source,sh]
+----
+$ postsvg batch ps_files/ svg_files/
+Found 3 file(s) to convert
+  ✓ ps_files/file1.ps → svg_files/file1.svg
+  ✓ ps_files/file2.eps → svg_files/file2.svg
+  ✗ ps_files/file3.ps: Conversion error: Invalid syntax
+----
+
+== Environment Variables
+
+Postsvg respects standard Ruby environment variables:
+
+**RUBY_VERSION**:: Minimum Ruby 2.7 required
+**RUBYOPT**:: Ruby interpreter options
+**GEM_HOME**:: Gem installation directory
+
+== Troubleshooting
+
+**Command not found:**
+[source,sh]
+----
+# Ensure gem bin directory is in PATH
+gem environment
+export PATH="$PATH:$(gem environment gemdir)/bin"
+----
+
+**Permission denied:**
+[source,sh]
+----
+# Make executable
+chmod +x $(which postsvg)
+----
+
+**Wrong version:**
+[source,sh]
+----
+# Update to latest
+gem update postsvg
+
+# Or specify version
+gem install postsvg -v '0.1.0'
+----
+
+== Next Steps
+
+* Review link:cli-reference/convert-command.adoc[convert command] details
+* Explore link:cli-reference/check-command.adoc[check command] for validation
+* See link:validation.adoc[Validation System] for quality checks
+* Check link:getting-started/common-workflows.adoc[Common Workflows] for examples
+
+== Bibliography
+
+* link:cli-reference/convert-command.adoc[Convert Command Documentation]
+* link:cli-reference/batch-command.adoc[Batch Command Documentation]
+* link:cli-reference/check-command.adoc[Check Command Documentation]
+* link:https://github.com/erikhuda/thor[Thor CLI Framework]