SVG Essentials

An SVG document is an element tree plus a document profile. Lowercase calls add SVG elements to the tree. Capitalized words create supporting values or operate on elements. In library code, operations outside the document block use the SVG. facade receiver; types and namespaces use SVG::. The standard component checks known SVG names and their allowed attributes, content, and parents.

Construct a document

drawing = SVG :minimal, width: 32, height: 20 do
  g id: "badge" do
    rect width: 32, height: 20, rx: 4, fill: "gold"
    text "S", x: 16, y: 14, "text-anchor": "middle"
  end
end

drawing.Render

Document profiles

A profile controls document metadata and extra DSL capabilities, not canvas size or checking policy. All four profiles use the same validation and lint lifecycle.

Use :minimal for compact output, :default for a standalone SVG file, :html for SVG embedded in HTML, and :inkscape when editor metadata or its additional helpers belong to the drawing. The Inkscape root adds Sevgi, Inkscape, and Sodipodi namespaces plus shape-rendering="crispEdges". The presence of Draw and Hatch on :inkscape is a convenience default, not an Inkscape format requirement.

SVG::Document::Base is the public common extension layer, not a selectable profile. Advanced consumers can target it with SVG.Mixin to change every descendant profile process-wide. Minimal and Default are sibling concrete profiles: Minimal adds no metadata and is not the base of the other profiles. Subclass Base first when an extension should remain scoped.

For example, Draw and Hatch can be added to a private Base-derived profile without adopting profile metadata:

profile = Class.new(SVG::Document::Base)
SVG.Mixin :Hatch, profile
region = Sevgi::Geometry::Rect[24, 12]

SVG(profile) do
  Draw region.lines, stroke: "silver"
  Hatch region, angle: 30, step: 3, stroke: "black"
end.Render

Element dispatch

The DSL recognizes SVG element names dynamically, so it does not need a Ruby method for every element in each SVG release. Sevgi validates the resulting standard SVG before checked output. Names are case-sensitive: linearGradient is an SVG element, while LinearGradient would be a different Ruby call.

Use Element when producing foreign XML or when a qualified name cannot be expressed as a bare Ruby call:

SVG :minimal do
  Element "catalog:item", "featured", "catalog:rank": 1
end.Render

Content safety

Ordinary String arguments are XML text-encoded automatically. Use a Content constructor only when content needs a different serialization channel.

drawing = SVG :minimal do
  text "A & B"
  text SVG::Content.encoded("A & B")
  style SVG::Content.cdata(".note { fill: red; }")
  style SVG::Content.css(".note" => {fill: "red"})
  g SVG::Content.verbatim("<title>trusted markup</title>")
end

drawing.Render

Advanced consumers may subclass SVG::Content and implement render(output, depth). The rendering engine ignores the method's return value. A custom implementation must escape any data it inserts into markup; use SVG::Content.encoded(...).to_s rather than interpolating caller text directly.

Validation lifecycle

Render, Save, and Out prepare a document before writing it. Call PreRender(validate: true, lint: true) to run that phase yourself, or use Validate() and Lint() for an earlier check. For non-SVG XML, choose a suitable document profile or render directly instead of running the standard SVG checks.

For the standard vocabulary, use the MDN SVG element reference. For Sevgi operations, use the DSL Catalog.