postsvg 0.1.0 → 0.3.0

data/docs/architecture/generator-stage.adoc

@@ -0,0 +1,1115 @@
+= Generator Stage
+:page-nav_order: 4
+
+== Purpose
+
+This document describes the Generator Stage of Postsvg's conversion pipeline, which transforms the interpreted PostScript operations into optimized SVG output. Understanding the generator helps developers comprehend SVG document assembly, path transformation, coordinate system conversion, and output optimization.
+
+== References
+
+* link:../architecture.adoc[Architecture Overview]
+* link:conversion-pipeline.adoc[Conversion Pipeline]
+* link:interpreter-stage.adoc[Interpreter Stage]
+* link:graphics-state-model.adoc[Graphics State Model]
+* link:../api-reference/svg-generator.adoc[SvgGenerator API Reference]
+
+== Concepts
+
+**SVG Document Assembly**:: Building valid SVG XML structure from accumulated elements.
+
+**Coordinate System Transformation**:: Converting PostScript's bottom-left origin to SVG's top-left origin.
+
+**Path Optimization**:: Minimizing SVG file size through number formatting and deduplication.
+
+**ClipPath Management**:: Deduplicating identical clipping paths to reduce output size.
+
+**Viewport Mapping**:: Mapping PostScript BoundingBox to SVG viewBox.
+
+== Generator Architecture
+
+=== Integrated Generation
+
+Unlike a separate SvgGenerator class, Postsvg integrates SVG generation into the Interpreter:
+
+**Primary Location:** [`lib/postsvg/interpreter.rb`](../../lib/postsvg/interpreter.rb:219)
+
+**Secondary Location:** [`lib/postsvg/execution_context.rb`](../../lib/postsvg/execution_context.rb:246)
+
+**Design Rationale:** SVG elements are generated incrementally during interpretation rather than as a post-processing step.
+
+=== Generation Components
+
+**SVG Output Buffer**:: Accumulates paths, text, and definitions during execution.
+
+**Path Builder**:: Constructs SVG path data strings from PostScript path operations.
+
+**Number Formatter**:: Formats numeric values for optimal SVG output.
+
+**ClipPath Cache**:: Deduplicates identical clipping paths.
+
+**Transform Generator**:: Converts transformation matrices to SVG transform syntax.
+
+== SVG Document Structure
+
+=== Document Template
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg"
+     viewBox="llx lly width height"
+     width="width"
+     height="height">
+  <defs>
+    <!-- Definitions: clipPath, patterns, etc. -->
+  </defs>
+  <g transform="translate(0 height) scale(1 -1)">
+    <!-- Paths and text elements -->
+  </g>
+</svg>
+----
+
+=== Document Assembly
+
+[source,ruby]
+----
+# lib/postsvg/interpreter.rb:219
+def generate_svg_document(svg_out, bbox)
+  # Format dimensions
+  width = num_fmt(bbox[:width])
+  height = num_fmt(bbox[:height])
+  llx = num_fmt(bbox[:llx])
+  lly = num_fmt(bbox[:lly])
+
+  # Create viewBox
+  view_box = "#{llx} #{lly} #{width} #{height}"
+
+  # Build <defs> section (only if needed)
+  defs = svg_out[:defs].empty? ? "" :
+    "\n<defs>\n#{svg_out[:defs].join("\n")}\n</defs>\n"
+
+  # Combine paths and text
+  elements = (svg_out[:paths] + svg_out[:text]).join("\n")
+
+  # Apply global Y-axis flip transformation
+  transform = "translate(0 #{height}) scale(1 -1)"
+  body = "\n<g transform=\"#{transform}\">\n#{elements}\n</g>"
+
+  # Assemble complete document
+  "<?xml version=\"1.0\" encoding="UTF-8"?>\n" \
+    "<svg xmlns=\"http://www.w3.org/2000/svg\" " \
+    "viewBox=\"#{view_box}\" width=\"#{width}\" height=\"#{height}\">" \
+    "#{defs}#{body}\n</svg>"
+end
+----
+
+=== Document Sections
+
+**XML Declaration:**
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+----
+
+**SVG Root Element:**
+
+[source,xml]
+----
+<svg xmlns="http://www.w3.org/2000/svg"
+     viewBox="0 0 200 100"
+     width="200"
+     height="100">
+----
+
+**Definitions Section (Optional):**
+
+[source,xml]
+----
+<defs>
+  <clipPath id="clipPath1">...</clipPath>
+  <pattern id="pattern1">...</pattern>
+</defs>
+----
+
+**Content Group with Transform:**
+
+[source,xml]
+----
+<g transform="translate(0 100) scale(1 -1)">
+  <path d="..." fill="..." />
+  <text x="..." y="...">...</text>
+</g>
+----
+
+== Coordinate System Transformation
+
+=== PostScript vs SVG Coordinates
+
+**PostScript Coordinate System:**
+
+[source]
+----
+      y
+      ↑
+      |
+      |
+      |
+(0,0) └────────→ x
+
+Origin: Bottom-left
+Y-axis: Up is positive
+----
+
+**SVG Coordinate System:**
+
+[source]
+----
+(0,0) ┌────────→ x
+      |
+      |
+      ↓
+      y
+
+Origin: Top-left
+Y-axis: Down is positive
+----
+
+=== Global Y-Flip Transform
+
+**Transformation Applied:**
+
+[source,xml]
+----
+<g transform="translate(0 HEIGHT) scale(1 -1)">
+----
+
+**Effect:**
+
+1. **Translate:** Move origin from top-left to bottom-left
+2. **Scale:** Flip Y-axis (scale by -1 in Y)
+
+**Mathematical Representation:**
+
+[source]
+----
+# Original SVG coordinates
+Point (x, y) in SVG
+
+# After translate(0, HEIGHT)
+Point (x, y - HEIGHT)
+
+# After scale(1, -1)
+Point (x, HEIGHT - y)
+
+# Result matches PostScript coordinates
+----
+
+=== Transformation Example
+
+**PostScript Point:** `(50, 30)` in 100-unit-high viewport
+
+**SVG Transformation:**
+
+[source]
+----
+Step 1: Original SVG would place at (50, 30) from top
+Step 2: translate(0, 100) → (50, 30 - 100) = (50, -70)
+Step 3: scale(1, -1) → (50, 70)
+Result: 70 units from top = 30 units from bottom ✓
+----
+
+== Path Generation
+
+=== Path Data Construction
+
+**PathBuilder Methods:**
+
+[source,ruby]
+----
+# lib/postsvg/path_builder.rb
+@path_builder.move_to(x, y)        # → "M x y"
+@path_builder.line_to(x, y)        # → "L x y"
+@path_builder.curve_to(...)        # → "C x1 y1 x2 y2 x y"
+@path_builder.close                # → "Z"
+----
+
+**Path String Assembly:**
+
+[source,ruby]
+----
+# lib/postsvg/path_builder.rb:75
+def to_path
+  @parts.join(" ")
+end
+
+# Example:
+# @parts = ["M 10 20", "L 30 40", "L 50 40", "Z"]
+# to_path → "M 10 20 L 30 40 L 50 40 Z"
+----
+
+=== SVG Path Element Generation
+
+[source,ruby]
+----
+# lib/postsvg/execution_context.rb:246
+def emit_svg_path(d, mode, fill_id = nil, _bbox = nil)
+  g_state = @graphics_state
+
+  # Sanitize colors
+  fill_color = mode[:fill] ? sanitize_color_value(g_state[:fill] || "black") : "none"
+  stroke_color = mode[:stroke] ? sanitize_color_value(g_state[:stroke] || "black") : "none"
+
+  # Build attributes
+  attrs = []
+  attrs << "d=\"#{d}\""
+
+  # Fill attribute
+  attrs << if fill_id
+             "fill=\"url(##{fill_id})\""
+           else
+             "fill=\"#{fill_color}\""
+           end
+
+  # Stroke attributes
+  if mode[:stroke]
+    attrs << "stroke=\"#{stroke_color}\""
+    width = g_state[:stroke_width] || 1
+    attrs << "stroke-width=\"#{num_fmt(width)}\"" if width != 1
+    attrs << "stroke-dasharray=\"#{g_state[:dash]}\"" if g_state[:dash]
+  else
+    attrs << "stroke=\"none\""
+  end
+
+  # ClipPath reference
+  unless g_state[:clip_stack].empty?
+    clip_id = get_or_create_clippath(g_state[:clip_stack].last)
+    attrs << "clip-path=\"url(#clipPath#{clip_id})\""
+  end
+
+  "<path #{attrs.join(' ')} />"
+end
+----
+
+=== Drawing Mode
+
+**Fill Mode:**
+
+[source,ruby]
+----
+mode = { fill: true, stroke: false }
+# Generates: <path d="..." fill="#808080" stroke="none" />
+----
+
+**Stroke Mode:**
+
+[source,ruby]
+----
+mode = { fill: false, stroke: true }
+# Generates: <path d="..." fill="none" stroke="#000000" stroke-width="1" />
+----
+
+**Both Modes:**
+
+[source,ruby]
+----
+mode = { fill: true, stroke: true }
+# Generates: <path d="..." fill="#808080" stroke="#000000" />
+----
+
+=== Path Examples
+
+**Simple Rectangle (Fill):**
+
+[source,postscript]
+----
+newpath
+0 0 moveto
+100 0 lineto
+100 100 lineto
+0 100 lineto
+closepath
+0.5 setgray
+fill
+----
+
+**Generated SVG:**
+
+[source,xml]
+----
+<path d="M 0 0 L 100 0 L 100 100 L 0 100 Z"
+      fill="#808080"
+      stroke="none" />
+----
+
+**Stroked Path:**
+
+[source,postscript]
+----
+newpath
+50 50 moveto
+150 150 lineto
+2 setlinewidth
+1 0 0 setrgbcolor
+stroke
+----
+
+**Generated SVG:**
+
+[source,xml]
+----
+<path d="M 50 50 L 150 150"
+      fill="none"
+      stroke="#ff0000"
+      stroke-width="2" />
+----
+
+== Number Formatting
+
+=== Optimization Goals
+
+1. **Remove Unnecessary Decimals:** `10.0` → `"10"`
+2. **Remove Trailing Zeros:** `10.500` → `"10.5"`
+3. **Limit Precision:** `10.123456` → `"10.123"`
+4. **Handle Edge Cases:** NaN, Infinity → `"0"`
+
+=== Number Formatter Implementation
+
+[source,ruby]
+----
+# lib/postsvg/interpreter.rb:246
+# lib/postsvg/execution_context.rb:220
+def num_fmt(n)
+  # Handle edge cases
+  return "0" if n.nil?
+  return "0" if n.respond_to?(:nan?) && n.nan?
+  return "0" if n.respond_to?(:infinite?) && n.infinite?
+
+  # Convert to float for consistent handling
+  n = n.to_f
+
+  # Check if effectively an integer (within tolerance)
+  if (n - n.round).abs < 1e-10
+    n.round.to_i.to_s
+  else
+    # Format with up to 3 decimals, strip trailing zeros
+    format("%.3f", n).sub(/\.?0+$/, "")
+  end
+end
+----
+
+=== Formatting Examples
+
+[cols="1,1,2"]
+|===
+|Input |Output |Rationale
+
+|`10.0`
+|`"10"`
+|Effectively integer
+
+|`10.5`
+|`"10.5"`
+|One significant decimal
+
+|`10.500`
+|`"10.5"`
+|Trailing zeros removed
+
+|`10.123`
+|`"10.123"`
+|Three decimals preserved
+
+|`10.123456`
+|`"10.123"`
+|Truncated to 3 decimals
+
+|`0.0001`
+|`"0"`
+|Below tolerance threshold
+
+|`1000000.0`
+|`"1000000"`
+|Large integer
+
+|`NaN`
+|`"0"`
+|Invalid number → safe default
+
+|`Infinity`
+|`"0"`
+|Invalid number → safe default
+|===
+
+=== Size Reduction Impact
+
+**Before Optimization:**
+
+[source,xml]
+----
+<path d="M 10.000000 20.000000 L 30.000000 40.000000" />
+----
+
+**After Optimization:**
+
+[source,xml]
+----
+<path d="M 10 20 L 30 40" />
+----
+
+**Savings:** 28 bytes → 20 bytes (28.6% reduction)
+
+== ClipPath Management
+
+=== ClipPath Deduplication
+
+**Problem:** Multiple identical clipping regions generate duplicate `<clipPath>` definitions.
+
+**Solution:** Cache clipPath definitions and reuse IDs for identical paths.
+
+=== Cache Implementation
+
+[source,ruby]
+----
+# lib/postsvg/execution_context.rb:29
+@clippath_cache = {}  # Maps path data → clipPath ID
+
+# When creating clipPath:
+clip_path_d = g_state[:clip_stack].last
+
+# Check if already exists
+clip_id = @clippath_cache[clip_path_d]
+unless clip_id
+  # Create new clipPath and cache it
+  clip_id = next_clippath_id
+  @clippath_cache[clip_path_d] = clip_id
+  @svg_output[:defs] <<
+    "<clipPath clipPathUnits=\"userSpaceOnUse\" id=\"clipPath#{clip_id}\">" \
+    "<path d=\"#{clip_path_d}\" id=\"path#{clip_id}\" />" \
+    "</clipPath>"
+end
+
+# Reference in path element
+attrs << "clip-path=\"url(#clipPath#{clip_id})\""
+----
+
+=== Deduplication Example
+
+**Without Deduplication:**
+
+[source,xml]
+----
+<defs>
+  <clipPath id="clipPath1">
+    <path d="M 0 0 L 100 0 L 100 100 L 0 100 Z" />
+  </clipPath>
+  <clipPath id="clipPath2">
+    <path d="M 0 0 L 100 0 L 100 100 L 0 100 Z" />
+  </clipPath>
+  <clipPath id="clipPath3">
+    <path d="M 0 0 L 100 0 L 100 100 L 0 100 Z" />
+  </clipPath>
+</defs>
+<g>
+  <path clip-path="url(#clipPath1)" ... />
+  <path clip-path="url(#clipPath2)" ... />
+  <path clip-path="url(#clipPath3)" ... />
+</g>
+----
+
+**With Deduplication:**
+
+[source,xml]
+----
+<defs>
+  <clipPath id="clipPath1">
+    <path d="M 0 0 L 100 0 L 100 100 L 0 100 Z" />
+  </clipPath>
+</defs>
+<g>
+  <path clip-path="url(#clipPath1)" ... />
+  <path clip-path="url(#clipPath1)" ... />
+  <path clip-path="url(#clipPath1)" ... />
+</g>
+----
+
+**Savings:** Eliminates duplicate definitions, reducing file size significantly.
+
+== Transform Generation
+
+=== Matrix to SVG Transform
+
+**Purpose:** Convert transformation matrix to SVG transform attribute.
+
+**Implementation:**
+
+[source,ruby]
+----
+# lib/postsvg/execution_context.rb:323
+def ctm_to_svg_transform(ctm)
+  parts = []
+
+  # Decompose matrix into components
+  decomp = ctm.decompose
+
+  # Add translate if non-zero
+  if decomp[:translate][:x] != 0 || decomp[:translate][:y] != 0
+    parts << "translate(#{num_fmt(decomp[:translate][:x])} " \
+             "#{num_fmt(decomp[:translate][:y])})"
+  end
+
+  # Add rotation if non-zero
+  if decomp[:rotate] != 0
+    parts << "rotate(#{num_fmt(decomp[:rotate])})"
+  end
+
+  # Add scale if not identity
+  if decomp[:scale][:x] != 1 || decomp[:scale][:y] != 1
+    parts << "scale(#{num_fmt(decomp[:scale][:x])} " \
+             "#{num_fmt(decomp[:scale][:y])})"
+  end
+
+  parts.join(" ")
+end
+----
+
+=== Matrix Decomposition
+
+**Matrix Representation:** `[a, b, c, d, e, f]`
+
+[source]
+----
+| a  c  e |
+| b  d  f |
+| 0  0  1 |
+
+Where:
+  a, d = scale factors
+  b, c = rotation/skew components
+  e, f = translation
+----
+
+**Decomposition Steps:**
+
+1. **Extract Translation:** `tx = e`, `ty = f`
+2. **Calculate Scale:** `sx = √(a² + b²)`, `sy = det/sx`
+3. **Calculate Rotation:** `θ = atan2(b, a)`
+4. **Generate Transform String**
+
+=== Transform Examples
+
+**Translation Only:**
+
+[source,postscript]
+----
+10 20 translate
+----
+
+**Matrix:** `[1, 0, 0, 1, 10, 20]`
+
+**SVG Transform:** `"translate(10 20)"`
+
+**Scale Only:**
+
+[source,postscript]
+----
+2 3 scale
+----
+
+**Matrix:** `[2, 0, 0, 3, 0, 0]`
+
+**SVG Transform:** `"scale(2 3)"`
+
+**Rotation:**
+
+[source,postscript]
+----
+45 rotate
+----
+
+**Matrix:** `[0.707, 0.707, -0.707, 0.707, 0, 0]`
+
+**SVG Transform:** `"rotate(45)"`
+
+**Combined:**
+
+[source,postscript]
+----
+10 20 translate
+2 2 scale
+45 rotate
+----
+
+**SVG Transform:** `"translate(10 20) rotate(45) scale(2 2)"`
+
+=== Transform Wrapper
+
+**When Needed:** Paths inside `gsave`/`grestore` with rotations or non-uniform scaling.
+
+[source,ruby]
+----
+# lib/postsvg/execution_context.rb:351
+def needs_transform_wrapper?
+  return false if @saved_ctm_at_gsave.nil?
+  return false if matrices_equal?(@graphics_state[:ctm], @saved_ctm_at_gsave)
+
+  ctm = @graphics_state[:ctm]
+
+  # Check for rotation
+  has_rotation = ctm.b.abs > 1e-10 || ctm.c.abs > 1e-10
+
+  # Check for non-uniform scale
+  has_nonuniform_scale = (ctm.a.abs - ctm.d.abs).abs > 1e-6
+
+  has_rotation || has_nonuniform_scale
+end
+----
+
+**Wrapped Output:**
+
+[source,xml]
+----
+<g transform="rotate(45) scale(2 1)">
+  <path d="M 10 20 L 30 40" fill="black" />
+</g>
+----
+
+== Color Conversion
+
+=== RGB to Hex
+
+**Purpose:** Convert PostScript RGB color (0-1 range) to SVG hex color.
+
+**Implementation:**
+
+[source,ruby]
+----
+# lib/postsvg/graphics_state.rb:153
+def rgb_to_hex(r, g, b)
+  format("#%02x%02x%02x",
+         (r * 255).to_i,
+         (g * 255).to_i,
+         (b * 255).to_i)
+end
+----
+
+=== Color Examples
+
+[cols="1,1,1"]
+|===
+|PostScript |RGB Values |SVG Hex
+
+|`0 setgray`
+|`(0, 0, 0)`
+|`#000000`
+
+|`1 setgray`
+|`(1, 1, 1)`
+|`#ffffff`
+
+|`0.5 setgray`
+|`(0.5, 0.5, 0.5)`
+|`#808080`
+
+|`1 0 0 setrgbcolor`
+|`(1, 0, 0)`
+|`#ff0000`
+
+|`0 1 0 setrgbcolor`
+|`(0, 1, 0)`
+|`#00ff00`
+
+|`0 0 1 setrgbcolor`
+|`(0, 0, 1)`
+|`#0000ff`
+
+|`0.5 0.25 0.75 setrgbcolor`
+|`(0.5, 0.25, 0.75)`
+|`#8040bf`
+|===
+
+=== Color Sanitization
+
+**Purpose:** Handle non-standard color values (patterns, procedures).
+
+[source,ruby]
+----
+# lib/postsvg/execution_context.rb:374
+def sanitize_color_value(color)
+  return color if color.is_a?(String)
+
+  # Handle non-string values → "none"
+  "none"
+end
+----
+
+**Examples:**
+
+[source]
+----
+"#ff0000"                    → "#ff0000" (valid hex)
+{ type: "procedure", ... }   → "none" (pattern procedure)
+[1, 0, 0, 1, 0, 0]          → "none" (matrix)
+----
+
+== Text Rendering
+
+=== Text Element Generation
+
+**Location:** Text commands in [`lib/postsvg/commands/text/`](../../lib/postsvg/commands/text/)
+
+**Basic Text Output:**
+
+[source,xml]
+----
+<text x="100" y="50"
+      font-family="Arial, sans-serif"
+      font-size="12"
+      fill="#000000">
+  Hello World
+</text>
+----
+
+=== Text Attributes
+
+**Position:** `x` and `y` from current point
+
+**Font:** From current font setting
+
+**Size:** From current font size
+
+**Fill:** From current fill color
+
+**Transform:** Inherits from parent `<g>` transform
+
+=== Text Example
+
+**PostScript:**
+
+[source,postscript]
+----
+/Helvetica findfont
+12 scalefont
+setfont
+100 50 moveto
+(Hello World) show
+----
+
+**Generated SVG:**
+
+[source,xml]
+----
+<text x="100" y="50"
+      font-family="Helvetica"
+      font-size="12"
+      fill="#000000">
+  Hello World
+</text>
+----
+
+== ViewBox and Viewport
+
+=== BoundingBox to ViewBox Mapping
+
+**PostScript BoundingBox:**
+
+[source,postscript]
+----
+%%BoundingBox: 0 0 612 792
+----
+
+**SVG Attributes:**
+
+[source,xml]
+----
+<svg viewBox="0 0 612 792" width="612" height="792">
+----
+
+**Mapping:**
+
+[source]
+----
+BoundingBox: llx lly urx ury
+ViewBox:     llx lly (urx-llx) (ury-lly)
+Width:       urx - llx
+Height:      ury - lly
+----
+
+=== Non-Zero Origin
+
+**PostScript BoundingBox:**
+
+[source,postscript]
+----
+%%BoundingBox: 50 50 300 200
+----
+
+**SVG Attributes:**
+
+[source,xml]
+----
+<svg viewBox="50 50 250 150" width="250" height="150">
+----
+
+**Effect:** Content is clipped to BoundingBox region.
+
+== Output Optimization
+
+=== Optimization Techniques
+
+**Number Formatting:**
+
+* Remove unnecessary decimals: `10.0` → `"10"`
+* Strip trailing zeros: `10.500` → `"10.5"`
+* Limit precision: `10.123456` → `"10.123"`
+
+**ClipPath Deduplication:**
+
+* Cache identical clipPaths
+* Reuse clipPath IDs
+* Reduces `<defs>` size
+
+**Default Value Omission:**
+
+* Omit `stroke-width="1"` (default)
+* Omit `fill="none"` when redundant
+* Minimize attribute verbosity
+
+**Whitespace Management:**
+
+* Single spaces between attributes
+* Newlines only for major sections
+* No unnecessary indentation
+
+=== Size Comparison
+
+**Unoptimized:**
+
+[source,xml]
+----
+<path d="M 10.000000 20.000000 L 30.000000 40.000000 L 50.000000 40.000000 Z"
+      fill="#808080"
+      stroke="none"
+      stroke-width="1.000000" />
+----
+
+**Optimized:**
+
+[source,xml]
+----
+<path d="M 10 20 L 30 40 L 50 40 Z" fill="#808080" stroke="none" />
+----
+
+**Reduction:** ~55% smaller
+
+== Complete Generation Example
+
+=== Input PostScript
+
+[source,postscript]
+----
+%%BoundingBox: 0 0 200 100
+newpath
+50 25 moveto
+150 25 lineto
+150 75 lineto
+50 75 lineto
+closepath
+0.8 0.2 0.2 setrgbcolor
+fill
+----
+
+=== Generation Steps
+
+**Step 1: Path Construction**
+
+[source]
+----
+moveto(50, 25)   → path_builder.move_to(50, 25)
+lineto(150, 25)  → path_builder.line_to(150, 25)
+lineto(150, 75)  → path_builder.line_to(150, 75)
+lineto(50, 75)   → path_builder.line_to(50, 75)
+closepath        → path_builder.close
+
+Path String: "M 50 25 L 150 25 L 150 75 L 50 75 Z"
+----
+
+**Step 2: Color Setting**
+
+[source]
+----
+setrgbcolor(0.8, 0.2, 0.2)
+  → fill_color = rgb_to_hex(0.8, 0.2, 0.2)
+  → fill_color = "#cc3333"
+----
+
+**Step 3: SVG Element Generation**
+
+[source]
+----
+fill command:
+  → emit_svg_path("M 50 25 L 150 25 L 150 75 L 50 75 Z",
+                   { fill: true, stroke: false })
+  → "<path d=\"M 50 25 L 150 25 L 150 75 L 50 75 Z\" " \
+     "fill=\"#cc3333\" stroke=\"none\" />"
+----
+
+**Step 4: Document Assembly**
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg"
+     viewBox="0 0 200 100"
+     width="200"
+     height="100">
+<g transform="translate(0 100) scale(1 -1)">
+<path d="M 50 25 L 150 25 L 150 75 L 50 75 Z"
+      fill="#cc3333"
+      stroke="none" />
+</g>
+</svg>
+----
+
+== Performance Characteristics
+
+=== Time Complexity
+
+**Path Generation:** O(p) where p = number of path segments
+
+**Number Formatting:** O(1) per number
+
+**ClipPath Lookup:** O(1) average (hash lookup)
+
+**Document Assembly:** O(e) where e = number of elements
+
+**Overall:** O(e + p) linear in output size
+
+=== Space Complexity
+
+**SVG Buffer:** O(e) where e = number of SVG elements
+
+**ClipPath Cache:** O(c) where c = unique clipPaths
+
+**Temporary Strings:** O(1) for individual elements
+
+**Overall:** O(e + c) linear in output size
+
+=== Optimization Impact
+
+**Number Formatting:** 10-20% size reduction on numeric-heavy output
+
+**ClipPath Deduplication:** Up to 80% reduction when many identical clips
+
+**Attribute Minimization:** 5-10% reduction from omitting defaults
+
+**Combined:** Typical 20-40% reduction vs naive generation
+
+== Testing the Generator
+
+=== Unit Tests
+
+**Number Formatting:**
+
+[source,ruby]
+----
+describe "number formatting" do
+  it "removes unnecessary decimals" do
+    expect(num_fmt(10.0)).to eq("10")
+  end
+
+  it "strips trailing zeros" do
+    expect(num_fmt(10.500)).to eq("10.5")
+  end
+
+  it "limits precision" do
+    expect(num_fmt(10.123456)).to eq("10.123")
+  end
+end
+----
+
+**Color Conversion:**
+
+[source,ruby]
+----
+describe "RGB to hex conversion" do
+  it "converts black" do
+    expect(rgb_to_hex(0, 0, 0)).to eq("#000000")
+  end
+
+  it "converts red" do
+    expect(rgb_to_hex(1, 0, 0)).to eq("#ff0000")
+  end
+
+  it "converts gray" do
+    expect(rgb_to_hex(0.5, 0.5, 0.5)).to eq("#808080")
+  end
+end
+----
+
+**Path Generation:**
+
+[source,ruby]
+----
+describe "path generation" do
+  it "generates simple rectangle" do
+    path_builder.move_to(0, 0)
+    path_builder.line_to(100, 0)
+    path_builder.line_to(100, 100)
+    path_builder.line_to(0, 100)
+    path_builder.close
+
+    expect(path_builder.to_path).to eq("M 0 0 L 100 0 L 100 100 L 0 100 Z")
+  end
+end
+----
+
+=== Integration Tests
+
+**Complete Conversion:**
+
+[source,ruby]
+----
+describe "SVG generation" do
+  it "generates valid SVG document" do
+    ps = <<~PS
+      %%BoundingBox: 0 0 100 100
+      newpath
+      50 50 moveto
+      80 80 lineto
+      stroke
+    PS
+
+    svg = Postsvg.convert(ps)
+
+    # Verify XML declaration
+    expect(svg).to start_with('<?xml version="1.0"')
+
+    # Verify SVG root
+    expect(svg).to include('<svg xmlns=')
+    expect(svg).to include('viewBox="0 0 100 100"')
+
+    # Verify transform group
+    expect(svg).to include('transform="translate(0 100) scale(1 -1)"')
+
+    # Verify path
+    expect(svg).to include('M 50 50 L 80 80')
+  end
+end
+----
+
+== Next Steps
+
+* Review link:command-registry.adoc[Command Registry] for operator implementations
+* Explore link:graphics-state-model.adoc[Graphics State Model] for state management
+* Study link:design-decisions.adoc[Design Decisions] for architectural rationale
+* See link:../development.adoc[Development Guide] for contributing
+
+== Bibliography
+
+* link:conversion-pipeline.adoc[Conversion Pipeline Documentation]
+* link:interpreter-stage.adoc[Interpreter Stage Documentation]
+* link:graphics-state-model.adoc[Graphics State Model]
+* Scalable Vector Graphics (SVG) 1.1 Specification
+* PostScript Language Reference Manual, 3rd Edition (Adobe Systems)
+* SVG Optimization Techniques and Best Practices