sevgi-appendix 1.0.0 → 1.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +26 -0
- data/agents/skills/sevgi/SKILL.md +11 -11
- data/agents/skills/sevgi/references/derender.md +8 -8
- data/agents/skills/sevgi/references/drawing.md +6 -6
- data/agents/skills/sevgi/references/dsl.md +48 -48
- data/agents/skills/sevgi/references/inspection.md +8 -8
- data/agents/skills/sevgi/references/layout.md +25 -25
- data/agents/skills/sevgi/references/output.md +39 -9
- data/agents/skills/sevgi/references/svg.md +11 -11
- data/agents/skills/sevgi/references/toolkit.md +27 -27
- data/lib/sevgi/appendix/version.rb +1 -1
- metadata +1 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: d23c6d89c514bdc94618bdcc2778f3a86366687beb5fbe9d21588e1a56c443e1
|
|
4
|
+
data.tar.gz: fa11ffe7af56a676c780ee3cf917486c1c08b3efd2fa6074cb2ccfbe94313e76
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: d33b180dddc36af52f7290e6664d01d5f657491f872a6575cb6b6502707c757807d20d9fa6aba63336cbd7c00bf1d1222a62bf950fce1766b2b8a659c94d6fae
|
|
7
|
+
data.tar.gz: 38cf88caf762ac6288cc1530e84a80ef3b27cb796eaa44c0726af72a99b5ce6df37c156c56573e0b910a0cadbcc6b1341a1d5e55359996a55aee7571fad4e4d5
|
data/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,32 @@
|
|
|
3
3
|
This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and follows
|
|
4
4
|
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
|
5
5
|
|
|
6
|
+
## Unreleased
|
|
7
|
+
|
|
8
|
+
## 1.1.1 - 2026-10-29
|
|
9
|
+
|
|
10
|
+
### Fixed
|
|
11
|
+
|
|
12
|
+
- Pass the configuration flag after the pdfcpu subcommand so A5-on-A4 export works.
|
|
13
|
+
|
|
14
|
+
## 1.1.0 - 2026-10-29
|
|
15
|
+
|
|
16
|
+
### Added
|
|
17
|
+
|
|
18
|
+
- `Classes` returns an element's distinct CSS class names without changing the element; `Classify` shares its attribute normalization.
|
|
19
|
+
- Generic document-local Style declarations with `Target`, `Param`, `Group`, and `Profiles`, and optional prepared PDF export through the native Mainz CLI.
|
|
20
|
+
- Backend-independent `fallback: false` for export failures and `F.executable` for executable path lookup.
|
|
21
|
+
- `F.path` for path validation and expansion, and `F.output_path` for default output names and directory targets.
|
|
22
|
+
|
|
23
|
+
### Changed
|
|
24
|
+
|
|
25
|
+
- Moved Graphics XML validation into auxiliary helpers and kept built-in paper dimensions in `Paper`.
|
|
26
|
+
- Shared path validation between Graphics writers and Sundries exports while preserving output paths and error messages.
|
|
27
|
+
|
|
28
|
+
### Fixed
|
|
29
|
+
|
|
30
|
+
- Stamp code placeholders in nested and shared PDF Forms, with cycle-safe resource traversal.
|
|
31
|
+
|
|
6
32
|
## 1.0.0 - 2026-09-16
|
|
7
33
|
|
|
8
34
|
### Added
|
|
@@ -54,14 +54,14 @@ visible intent.
|
|
|
54
54
|
|
|
55
55
|
## References
|
|
56
56
|
|
|
57
|
-
| Need
|
|
58
|
-
|
|
|
59
|
-
| Choose script/library syntax, profiles, SVG elements, or Sevgi DSL words
|
|
60
|
-
| Choose a component and locate user, YARD, or checkout documentation
|
|
61
|
-
| Structure `.sevgi` and library code as idiomatic Ruby
|
|
62
|
-
| Apply the renderer/program ownership boundary and diagnose visual mismatches | [drawing.md](references/drawing.md)
|
|
63
|
-
| Measure SVG geometry, browser layout, or painted pixels
|
|
64
|
-
| Find an SVG capability and its authoritative specification
|
|
65
|
-
| Choose repetition, tiling, ruler, grid, Draw, pattern, or Hatch
|
|
66
|
-
| Integrate editor-authored SVG/XML through Derender
|
|
67
|
-
| Render, save, or export SVG, PDF, or PNG
|
|
57
|
+
| Need | Read |
|
|
58
|
+
| ---------------------------------------------------------------------------- | ----------------------------------------- |
|
|
59
|
+
| Choose script/library syntax, profiles, SVG elements, or Sevgi DSL words | [dsl.md](references/dsl.md) |
|
|
60
|
+
| Choose a component and locate user, YARD, or checkout documentation | [toolkit.md](references/toolkit.md) |
|
|
61
|
+
| Structure `.sevgi` and library code as idiomatic Ruby | [ruby.md](references/ruby.md) |
|
|
62
|
+
| Apply the renderer/program ownership boundary and diagnose visual mismatches | [drawing.md](references/drawing.md) |
|
|
63
|
+
| Measure SVG geometry, browser layout, or painted pixels | [inspection.md](references/inspection.md) |
|
|
64
|
+
| Find an SVG capability and its authoritative specification | [svg.md](references/svg.md) |
|
|
65
|
+
| Choose repetition, tiling, ruler, grid, Draw, pattern, or Hatch | [layout.md](references/layout.md) |
|
|
66
|
+
| Integrate editor-authored SVG/XML through Derender | [derender.md](references/derender.md) |
|
|
67
|
+
| Render, save, or export SVG, PDF, or PNG | [output.md](references/output.md) |
|
|
@@ -11,14 +11,14 @@ SVG/XML is a real input artifact.
|
|
|
11
11
|
|
|
12
12
|
## Choose the Relationship
|
|
13
13
|
|
|
14
|
-
| Intent
|
|
15
|
-
|
|
|
16
|
-
| Inspect an immutable parsed node
|
|
17
|
-
| Generate editable Sevgi Ruby source
|
|
18
|
-
| Add the selected node to an existing tree
|
|
19
|
-
| Add only the selected node's children
|
|
20
|
-
| Include a selected file node inside an SVG block
|
|
21
|
-
| Include only a selected file node's children inside a block | —
|
|
14
|
+
| Intent | Inline content | File | Result |
|
|
15
|
+
| ----------------------------------------------------------- | ---------------------- | -------------------------- | ------------------------- |
|
|
16
|
+
| Inspect an immutable parsed node | `SVG.Decompile` | `SVG.DecompileFile` | `Sevgi::Derender::Node` |
|
|
17
|
+
| Generate editable Sevgi Ruby source | `SVG.Derender` | `SVG.DerenderFile` | formatted Ruby String |
|
|
18
|
+
| Add the selected node to an existing tree | `SVG.Evaluate` | `SVG.EvaluateFile` | included element or `nil` |
|
|
19
|
+
| Add only the selected node's children | `SVG.EvaluateChildren` | `SVG.EvaluateChildrenFile` | frozen child snapshot |
|
|
20
|
+
| Include a selected file node inside an SVG block | — | `Include` | included element or `nil` |
|
|
21
|
+
| Include only a selected file node's children inside a block | — | `IncludeChildren` | frozen child snapshot |
|
|
22
22
|
|
|
23
23
|
Use `DerenderFile` when generated Ruby becomes the maintained source. Use `Include`, `EvaluateFile`, or their children
|
|
24
24
|
variants when the editor file remains the geometry source. Use `DecompileFile` to inspect names, attributes,
|
|
@@ -2,16 +2,16 @@
|
|
|
2
2
|
|
|
3
3
|
## Renderer First
|
|
4
4
|
|
|
5
|
-
Treat SVG as the rendering model, not merely as an output format. The governing question is not whether Ruby
|
|
5
|
+
Treat SVG as the rendering model, not merely as an output format. The governing question is not whether Ruby _can_
|
|
6
6
|
calculate a value, but which layer has the knowledge and responsibility to determine it.
|
|
7
7
|
|
|
8
8
|
Use this ownership boundary:
|
|
9
9
|
|
|
10
|
-
| Owner
|
|
11
|
-
|
|
|
12
|
-
| SVG renderer | SVG can state the intent and the final result depends on rendering context
|
|
13
|
-
| Sevgi
|
|
14
|
-
| Program
|
|
10
|
+
| Owner | Test | Action |
|
|
11
|
+
| ------------ | --------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
|
|
12
|
+
| SVG renderer | SVG can state the intent and the final result depends on rendering context | Encode the intent with SVG elements, attributes, CSS, or transforms |
|
|
13
|
+
| Sevgi | Sevgi already names the SVG operation or supplies the required layout abstraction | Use the DSL or helper instead of rebuilding it |
|
|
14
|
+
| Program | The value must exist before rendering and SVG neither derives nor exposes it | Compute it with ordinary Ruby or `Sevgi::Geometry` |
|
|
15
15
|
|
|
16
16
|
Before computing, first ask whether SVG can state the desired relationship rather than its current numeric result. If
|
|
17
17
|
it can, keep that relationship declarative. Then check whether Sevgi already wraps it. Compute only when the program
|
|
@@ -2,17 +2,17 @@
|
|
|
2
2
|
|
|
3
3
|
## Host Grammar
|
|
4
4
|
|
|
5
|
-
| Form
|
|
6
|
-
|
|
|
7
|
-
| `rect`, `circle`, `linearGradient`, `clipPath`, ...
|
|
8
|
-
| `Translate`, `Tile`, `Call`, `Render`, ...
|
|
9
|
-
| `css`, `square`, `symbol!`, `layer`, `layer!`, `base` | Examples of deliberate lowercase Sevgi words. The DSL catalog owns the full list
|
|
10
|
-
| `SVG(...)`
|
|
11
|
-
| `SVG.Canvas(...)`
|
|
12
|
-
| `SVG.Module { ... }`
|
|
13
|
-
| `extend SVG::Module`
|
|
14
|
-
| `SVG::Canvas`
|
|
15
|
-
| `Canvas(...)`
|
|
5
|
+
| Form | Meaning |
|
|
6
|
+
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------ |
|
|
7
|
+
| `rect`, `circle`, `linearGradient`, `clipPath`, ... | Standard SVG elements created by exact, case-sensitive names that normally start lowercase |
|
|
8
|
+
| `Translate`, `Tile`, `Call`, `Render`, ... | Sevgi operations, normally capitalized to stand apart from SVG elements |
|
|
9
|
+
| `css`, `square`, `symbol!`, `layer`, `layer!`, `base` | Examples of deliberate lowercase Sevgi words. The DSL catalog owns the full list |
|
|
10
|
+
| `SVG(...)` | Build a document in both script and library code |
|
|
11
|
+
| `SVG.Canvas(...)` | Call a full-toolkit facade operation in library code |
|
|
12
|
+
| `SVG.Module { ... }` | Build an anonymous callable with public steps and private or protected helpers |
|
|
13
|
+
| `extend SVG::Module` | Apply the same callable contract to an existing or explicitly declared module |
|
|
14
|
+
| `SVG::Canvas` | Refer to a type or namespace |
|
|
15
|
+
| `Canvas(...)` | Call the promoted operation in an executable `.sevgi` script |
|
|
16
16
|
|
|
17
17
|
Use Ruby hashes for SVG attributes. Quote hyphenated SVG names:
|
|
18
18
|
|
|
@@ -22,11 +22,11 @@ text "Ready", x: 12, y: 16, "text-anchor": "middle", "font-weight": "bold"
|
|
|
22
22
|
|
|
23
23
|
## Dependency Surface
|
|
24
24
|
|
|
25
|
-
| Host
|
|
26
|
-
|
|
|
27
|
-
| Executable script
|
|
28
|
-
| Full-toolkit library
|
|
29
|
-
| Focused graphics library | `require "sevgi/graphics"`
|
|
25
|
+
| Host | Load | Vocabulary |
|
|
26
|
+
| ------------------------ | ---------------------------------------------------- | ---------------------------------------------------------------------------------------- |
|
|
27
|
+
| Executable script | `sevgi file.sevgi` or an executable `.sevgi` shebang | bare promoted operations such as `Canvas`, `Paper`, and `Grid` |
|
|
28
|
+
| Full-toolkit library | `require "sevgi"` | `SVG(...)` plus facade operations such as `SVG.Canvas` and `SVG.Grid` |
|
|
29
|
+
| Focused graphics library | `require "sevgi/graphics"` | `Sevgi::Graphics.SVG` and lowercase component constructors without the full `SVG` facade |
|
|
30
30
|
|
|
31
31
|
Follow the consumer's declared gems and existing dialect. Do not require the full toolkit merely to obtain facade
|
|
32
32
|
spelling, and do not use facade operations when only a focused component is installed.
|
|
@@ -69,12 +69,12 @@ File.write "badge.svg", drawing.Render
|
|
|
69
69
|
|
|
70
70
|
Keep physical size and serialization dialect independent:
|
|
71
71
|
|
|
72
|
-
| Need
|
|
73
|
-
|
|
|
74
|
-
| Register a named physical size
|
|
75
|
-
| Look up a registered physical size
|
|
76
|
-
| Build one drawing surface
|
|
77
|
-
| Define or select an SVG document profile | `SVG.Document` / script `Document` | root attributes and preambles
|
|
72
|
+
| Need | Use | Owns |
|
|
73
|
+
| ---------------------------------------- | ---------------------------------- | -------------------------------------------------- |
|
|
74
|
+
| Register a named physical size | `SVG.Paper` / script `Paper` | width, height, and unit |
|
|
75
|
+
| Look up a registered physical size | `SVG::Paper.fetch` | the registered size value |
|
|
76
|
+
| Build one drawing surface | `SVG.Canvas` / script `Canvas` | size, margins, unit, name, and resulting `viewBox` |
|
|
77
|
+
| Define or select an SVG document profile | `SVG.Document` / script `Document` | root attributes and preambles |
|
|
78
78
|
|
|
79
79
|
Omitting the profile selects `:default`. A Canvas or Paper can be the first argument when the default profile is
|
|
80
80
|
suitable. Otherwise, the first argument selects a document profile and the optional second argument supplies the
|
|
@@ -87,30 +87,30 @@ With `margins: -2`, it starts at `(2, 2)` instead. Negative margins enlarge the
|
|
|
87
87
|
|
|
88
88
|
## Task-to-Word Map
|
|
89
89
|
|
|
90
|
-
| Task
|
|
91
|
-
|
|
|
92
|
-
| Create SVG structure
|
|
93
|
-
| Choose page dimensions and document metadata | `Paper`, `Canvas`, and `Document` with separate responsibilities
|
|
94
|
-
| Set reusable styles
|
|
95
|
-
| Transform an element or group
|
|
96
|
-
| Center known inner and outer boxes
|
|
97
|
-
| Draw simple line/path wrappers
|
|
98
|
-
| Reuse or repeat drawing
|
|
99
|
-
| Compose reusable drawing code
|
|
100
|
-
| Move existing element trees
|
|
101
|
-
| Draw or hatch Geometry values
|
|
102
|
-
| Inspect or validate output
|
|
103
|
-
| Produce output
|
|
104
|
-
| Import existing SVG/XML
|
|
90
|
+
| Task | Start with |
|
|
91
|
+
| -------------------------------------------- | ------------------------------------------------------------------------------------ |
|
|
92
|
+
| Create SVG structure | SVG element names with blocks for nested containers |
|
|
93
|
+
| Choose page dimensions and document metadata | `Paper`, `Canvas`, and `Document` with separate responsibilities |
|
|
94
|
+
| Set reusable styles | `css`, classes, presentation attributes |
|
|
95
|
+
| Transform an element or group | `Translate`, `Rotate`, `Scale`, `Skew`, `Flip` |
|
|
96
|
+
| Center known inner and outer boxes | element `Align`, or `Sevgi::Geometry::Operation` for edge alignment or a Ruby result |
|
|
97
|
+
| Draw simple line/path wrappers | `LineTo`, `LineBy`, `HLineTo`, `HLineBy`, `VLineTo`, `VLineBy` |
|
|
98
|
+
| Reuse or repeat drawing | `defs`/`use`, `Tile`, `TileX`, `TileY`, `Duplicate` |
|
|
99
|
+
| Compose reusable drawing code | `SVG.Module`, `SVG::Module`, `base`, `Call`, and profile-specific wrappers |
|
|
100
|
+
| Move existing element trees | `Append`, `Prepend`, `Adopt`, `AdoptFirst`, `Orphan` |
|
|
101
|
+
| Draw or hatch Geometry values | `Draw`, `Hatch` on `:inkscape` or an explicitly extended custom profile |
|
|
102
|
+
| Inspect or validate output | `Identifiers`, `Validate`, `Lint` |
|
|
103
|
+
| Produce output | `Render`, `Out`, `Save`, and optional `PDF` or `PNG` export |
|
|
104
|
+
| Import existing SVG/XML | `Include`, `Evaluate`, `Derender`, `Decompile` and their file variants |
|
|
105
105
|
|
|
106
106
|
## Verification Boundaries
|
|
107
107
|
|
|
108
|
-
| Check
|
|
109
|
-
|
|
|
110
|
-
| `Validate`
|
|
111
|
-
| `Lint`
|
|
112
|
-
| `Render`
|
|
113
|
-
| Visual inspection | Appearance in the inspected context
|
|
108
|
+
| Check | Establishes | Does not establish |
|
|
109
|
+
| ----------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------- |
|
|
110
|
+
| `Validate` | SVG vocabulary and nesting compliance when Standard is available | Visual correctness; without Standard it returns `nil` and performs no validation |
|
|
111
|
+
| `Lint` | No duplicate visible IDs | Complete reference integrity or SVG standard compliance |
|
|
112
|
+
| `Render` | SVG serialization | Correct appearance in a browser or export engine |
|
|
113
|
+
| Visual inspection | Appearance in the inspected context | Correctness in untested contexts |
|
|
114
114
|
|
|
115
115
|
For a new or changed drawing, run `Lint` and, when Standard is available, `Validate` before accepting the output.
|
|
116
116
|
Report a missing Standard component as unavailable validation, not a successful check.
|
|
@@ -118,11 +118,11 @@ Inspect visually changed output against the user's acceptance criteria.
|
|
|
118
118
|
|
|
119
119
|
## Profiles
|
|
120
120
|
|
|
121
|
-
| Profile
|
|
122
|
-
|
|
|
123
|
-
| `:minimal`
|
|
124
|
-
| `:default`
|
|
125
|
-
| `:html`
|
|
121
|
+
| Profile | Use |
|
|
122
|
+
| ----------- | ---------------------------------------------------------- |
|
|
123
|
+
| `:minimal` | SVG without default preamble or namespace metadata |
|
|
124
|
+
| `:default` | Standalone SVG with XML declaration and SVG namespace |
|
|
125
|
+
| `:html` | SVG intended for HTML embedding |
|
|
126
126
|
| `:inkscape` | Editor metadata plus convenient `Draw` and `Hatch` helpers |
|
|
127
127
|
|
|
128
128
|
Do not invent a Sevgi word from a likely name. Check the [online DSL catalog](https://sevgi.roktas.dev/dsl/) for
|
|
@@ -9,14 +9,14 @@ environment contract, then fix that owner.
|
|
|
9
9
|
|
|
10
10
|
State the question before selecting a tool:
|
|
11
11
|
|
|
12
|
-
| Question
|
|
13
|
-
|
|
|
14
|
-
| Is the declared coordinate model correct?
|
|
15
|
-
| What geometry does this SVG element contain?
|
|
16
|
-
| Where does it appear after layout and transforms?
|
|
17
|
-
| What is a path's renderer-computed length or point?
|
|
18
|
-
| Which pixels were actually painted?
|
|
19
|
-
| Does the result have the intended balance or density? | Visual inspection at representative outputs
|
|
12
|
+
| Question | Evidence | Space |
|
|
13
|
+
| ----------------------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------- |
|
|
14
|
+
| Is the declared coordinate model correct? | `viewBox`, viewport dimensions, `preserveAspectRatio` | SVG user units and viewport policy |
|
|
15
|
+
| What geometry does this SVG element contain? | Browser `getBBox()` | SVG user units |
|
|
16
|
+
| Where does it appear after layout and transforms? | Browser `getBoundingClientRect()` or an equivalent automation API | Viewport-relative CSS pixels |
|
|
17
|
+
| What is a path's renderer-computed length or point? | `getTotalLength()` or `getPointAtLength()` | SVG user units |
|
|
18
|
+
| Which pixels were actually painted? | A deterministic PNG or browser screenshot inspected as raster data | Raster pixels |
|
|
19
|
+
| Does the result have the intended balance or density? | Visual inspection at representative outputs | Perceptual because no single bounding box proves it |
|
|
20
20
|
|
|
21
21
|
Do not compare values from different spaces as if they shared units. Label every recorded measurement with:
|
|
22
22
|
|
|
@@ -4,20 +4,20 @@ Choose by the value the caller needs after the operation, not merely by the visi
|
|
|
4
4
|
|
|
5
5
|
## Repetition
|
|
6
6
|
|
|
7
|
-
| Need
|
|
8
|
-
|
|
|
9
|
-
| Repeat one SVG subtree in the rendered document
|
|
10
|
-
| Copy and independently edit an existing subtree
|
|
11
|
-
| Copy a subtree without attachment or ID changes
|
|
12
|
-
| Inspect repeated cells or row/column bounds in Ruby | `Sevgi::Sundries::Tile`
|
|
7
|
+
| Need | Use | Result |
|
|
8
|
+
| --------------------------------------------------- | --------------------------------------------- | ------------------------------------------ |
|
|
9
|
+
| Repeat one SVG subtree in the rendered document | `defs`/`use`, or DSL `Tile`, `TileX`, `TileY` | SVG references with generated positions |
|
|
10
|
+
| Copy and independently edit an existing subtree | `Duplicate`, `DuplicateX`, `DuplicateY` | Independent SVG element trees |
|
|
11
|
+
| Copy a subtree without attachment or ID changes | `dup` or `clone` | Independent subtree with IDs preserved |
|
|
12
|
+
| Inspect repeated cells or row/column bounds in Ruby | `Sevgi::Sundries::Tile` | Geometry values and boxes, no SVG elements |
|
|
13
13
|
|
|
14
14
|
The repetition APIs have different block contracts:
|
|
15
15
|
|
|
16
|
-
| API channel
|
|
17
|
-
|
|
|
18
|
-
| `Tile`, `TileX`, `TileY` block
|
|
19
|
-
| Tile `proc:`
|
|
20
|
-
| `Duplicate`, `DuplicateX`, `DuplicateY` block | Every copied element
|
|
16
|
+
| API channel | Runs for | Use |
|
|
17
|
+
| --------------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------- |
|
|
18
|
+
| `Tile`, `TileX`, `TileY` block | One template under `defs` | Draw the shared subtree, not each cell |
|
|
19
|
+
| Tile `proc:` | Each generated `use` element | Mutate that element through the callback argument. Row and column indices are zero-based |
|
|
20
|
+
| `Duplicate`, `DuplicateX`, `DuplicateY` block | Every copied element | Customize the yielded element, not a new drawing context |
|
|
21
21
|
|
|
22
22
|
`Duplicate` moves visible `id` attributes to non-rendering `-id` metadata before customization.
|
|
23
23
|
An existing `-id` takes precedence. When replacing IDs, update their references as well.
|
|
@@ -28,11 +28,11 @@ Use the exact callback keywords from the selected method's YARD contract. The Ti
|
|
|
28
28
|
|
|
29
29
|
## Intervals and Grids
|
|
30
30
|
|
|
31
|
-
| Need
|
|
32
|
-
|
|
|
33
|
-
| Fit whole major/minor intervals into a span and inspect their distances
|
|
34
|
-
| Require an even major-interval count
|
|
35
|
-
| Combine two fitted rulers and obtain lines, points, cells, or a fitted canvas | `SVG.Grid` or `Sevgi::Sundries::Grid`
|
|
31
|
+
| Need | Use |
|
|
32
|
+
| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
|
33
|
+
| Fit whole major/minor intervals into a span and inspect their distances | script `Ruler`, library `SVG.Ruler`, or component `Sevgi::Sundries::Ruler` |
|
|
34
|
+
| Require an even major-interval count | `Sevgi::Sundries::RulerEven` |
|
|
35
|
+
| Combine two fitted rulers and obtain lines, points, cells, or a fitted canvas | `SVG.Grid` or `Sevgi::Sundries::Grid` |
|
|
36
36
|
|
|
37
37
|
`Ruler` constructs a Ruby layout value without drawing SVG elements. `Grid` also returns a layout model.
|
|
38
38
|
`Draw` materializes its geometry as SVG when lines are required. In a Grid, `grid.x` returns horizontal lines and
|
|
@@ -40,11 +40,11 @@ Use the exact callback keywords from the selected method's YARD contract. The Ti
|
|
|
40
40
|
|
|
41
41
|
## Alignment
|
|
42
42
|
|
|
43
|
-
| Need
|
|
44
|
-
|
|
|
45
|
-
| Center known inner and outer boxes with an SVG translation
|
|
43
|
+
| Need | Use |
|
|
44
|
+
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
|
|
45
|
+
| Center known inner and outer boxes with an SVG translation | element `Align` with `:center` |
|
|
46
46
|
| Align Geometry at center or an edge and return the value or offset | `Sevgi::Geometry::Operation.align` or `Sevgi::Geometry::Operation.alignment` |
|
|
47
|
-
| Align rendered text or other renderer-owned content
|
|
47
|
+
| Align rendered text or other renderer-owned content | SVG anchoring, baseline, layout, or transform semantics |
|
|
48
48
|
|
|
49
49
|
Geometry alignment accepts `:center`, `:left`, `:right`, `:top`, and `:bottom`. The element DSL's narrower `Align`
|
|
50
50
|
contract accepts only `:center`. Do not calculate font or painted-content bounds only to feed either API. Use these
|
|
@@ -72,11 +72,11 @@ increases downward. See [Geometry](https://sevgi.roktas.dev/geometry/#arcs-and-e
|
|
|
72
72
|
|
|
73
73
|
## Drawing and Hatching
|
|
74
74
|
|
|
75
|
-
| Need
|
|
76
|
-
|
|
|
77
|
-
| A visual repeated fill whose individual strokes are irrelevant
|
|
78
|
-
| Explicit finite hatch segments that must remain separate geometry/SVG paths | Geometry sweep or `Hatch`
|
|
79
|
-
| Existing Geometry values rendered as SVG elements
|
|
75
|
+
| Need | Use |
|
|
76
|
+
| --------------------------------------------------------------------------- | ------------------------------------------------- |
|
|
77
|
+
| A visual repeated fill whose individual strokes are irrelevant | SVG `pattern` that the renderer repeats and clips |
|
|
78
|
+
| Explicit finite hatch segments that must remain separate geometry/SVG paths | Geometry sweep or `Hatch` |
|
|
79
|
+
| Existing Geometry values rendered as SVG elements | `Draw` |
|
|
80
80
|
|
|
81
81
|
`Hatch` computes finite segments and emits each as a separate SVG path. Use it for editable, inspectable, plotter-like,
|
|
82
82
|
or otherwise explicit line geometry. Do not use it only because a region needs stripes. `Draw` and `Hatch` are included
|
|
@@ -2,13 +2,13 @@
|
|
|
2
2
|
|
|
3
3
|
Keep document construction and output policy separate. Choose the final operation from the artifact the caller needs:
|
|
4
4
|
|
|
5
|
-
| Artifact
|
|
6
|
-
|
|
|
7
|
-
| SVG String owned by surrounding Ruby code
|
|
8
|
-
| SVG on standard output
|
|
9
|
-
| SVG file
|
|
10
|
-
| PDF file
|
|
11
|
-
| PNG file
|
|
5
|
+
| Artifact | Use |
|
|
6
|
+
| -------------------------------------------------- | ------------------------------ |
|
|
7
|
+
| SVG String owned by surrounding Ruby code | `Render` |
|
|
8
|
+
| SVG on standard output | `Out` |
|
|
9
|
+
| SVG file | `Save` |
|
|
10
|
+
| PDF file | `PDF` |
|
|
11
|
+
| PNG file | `PNG` |
|
|
12
12
|
| Export an existing SVG String outside the document | `Sevgi::Sundries::Export.call` |
|
|
13
13
|
|
|
14
14
|
The `sevgi` command reads standard input when no file is given. Use `sevgi --as badge` to make an implicit `Save`, `PDF`,
|
|
@@ -48,8 +48,38 @@ Self-closing or prefixed roots and comments after the root are unsupported with
|
|
|
48
48
|
does not apply. Sevgi escapes CSS as XML text but does not validate the stylesheet. Native `Export.call` runs its source
|
|
49
49
|
callback after insertion and before conversion. Inspect the final output for changed visibility, size, and clipping.
|
|
50
50
|
|
|
51
|
-
SVG output has no native graphics dependency. PDF and PNG export lazily require Cairo, RSVG, and HexaPDF.
|
|
52
|
-
missing optional component rather than
|
|
51
|
+
SVG output has no native graphics dependency. Ordinary PDF and PNG export lazily require Cairo, RSVG, and HexaPDF.
|
|
52
|
+
Report a missing optional component rather than substituting an unrequested command or raster workaround.
|
|
53
|
+
|
|
54
|
+
### Editable styles
|
|
55
|
+
|
|
56
|
+
Use the document's `Style` operation when the caller needs editable PDF paint controls:
|
|
57
|
+
|
|
58
|
+
```ruby
|
|
59
|
+
drawing.Style do
|
|
60
|
+
Target "ink", selectors: ["#outline"]
|
|
61
|
+
Param "display", targets: ["ink"], property: "display",
|
|
62
|
+
schema: {type: "string", enum: %w[inline none]}
|
|
63
|
+
Param "opacity", targets: ["ink"], property: "stroke-opacity",
|
|
64
|
+
schema: {type: "number", minimum: 0, maximum: 1}
|
|
65
|
+
end
|
|
66
|
+
drawing.PDF "prepared.pdf", fallback: false
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
The SVG must contain the selected group or direct `use` placement. Each target needs a `display` parameter.
|
|
70
|
+
Keep JSON Schema names such as `minimum` and `maximum`. `Group` orders controls; `Profiles` declares named overrides.
|
|
71
|
+
`Style` changes export metadata, not SVG appearance. Lowercase `style` remains the SVG CSS element.
|
|
72
|
+
|
|
73
|
+
`drawing.Style` returns a deeply frozen Hash with JSON String keys, or nil when no declaration is attached.
|
|
74
|
+
Pass this Hash as `style:` to `Sevgi::Sundries::Export.call` when the application owns the SVG separately.
|
|
75
|
+
For explicit required production, use `Sevgi::Sundries::Mainz.produce(svg, output, declaration: drawing.Style)`.
|
|
76
|
+
|
|
77
|
+
Styled PDF export invokes the native `mainz` executable on `PATH` without ordinary export gems.
|
|
78
|
+
By default, missing Mainz or failed preparation warns and falls back to ordinary PDF export.
|
|
79
|
+
Use `fallback: false` when the prepared contract is required; preparation failures then raise
|
|
80
|
+
`Sevgi::Sundries::Mainz::Error`. Unstyled exports remain ordinary in either mode.
|
|
81
|
+
Invalid arguments, filesystem failures, and interrupts propagate in both modes. Parallel exports use separate staging.
|
|
82
|
+
Mainz owns selector admission, supported paint properties, and PDF baselines. Publication policy stays with the caller.
|
|
53
83
|
|
|
54
84
|
## Verification
|
|
55
85
|
|
|
@@ -3,17 +3,17 @@
|
|
|
3
3
|
Use this page to identify the SVG mechanism. Then make sure that MDN or the SVG specification documents its exact
|
|
4
4
|
behavior. Do not turn this index into a cookbook of one-off drawing tips.
|
|
5
5
|
|
|
6
|
-
| Rendering concept
|
|
7
|
-
|
|
|
8
|
-
| Coordinate system and responsive scaling | `viewBox`, viewport dimensions, `preserveAspectRatio`
|
|
9
|
-
| Relative placement of an element tree
|
|
10
|
-
| Reusable drawing definitions
|
|
11
|
-
| Repeated visual fill
|
|
12
|
-
| Paint
|
|
13
|
-
| Visibility boundaries
|
|
14
|
-
| Line decoration
|
|
15
|
-
| Renderer effects
|
|
16
|
-
| Text relationships
|
|
6
|
+
| Rendering concept | Start with |
|
|
7
|
+
| ---------------------------------------- | -------------------------------------------------------------------------------- |
|
|
8
|
+
| Coordinate system and responsive scaling | `viewBox`, viewport dimensions, `preserveAspectRatio` |
|
|
9
|
+
| Relative placement of an element tree | `transform` with Sevgi's transform helpers when available |
|
|
10
|
+
| Reusable drawing definitions | `defs`, `symbol`, `use` |
|
|
11
|
+
| Repeated visual fill | `pattern` |
|
|
12
|
+
| Paint | presentation attributes or CSS, gradients, opacity |
|
|
13
|
+
| Visibility boundaries | `clipPath` for hard clipping and `mask` for luminance/alpha compositing |
|
|
14
|
+
| Line decoration | `marker`, stroke width, line cap, line join, dash array |
|
|
15
|
+
| Renderer effects | `filter` and filter primitives |
|
|
16
|
+
| Text relationships | text positioning and anchoring attributes with font metrics left to the renderer |
|
|
17
17
|
|
|
18
18
|
Resolve questions in this order:
|
|
19
19
|
|
|
@@ -2,17 +2,17 @@
|
|
|
2
2
|
|
|
3
3
|
## Choose the Owner
|
|
4
4
|
|
|
5
|
-
| Need
|
|
6
|
-
|
|
|
7
|
-
| Build SVG documents and element trees
|
|
8
|
-
| Choose paper size, canvas geometry, or root serialization metadata | `SVG.Paper`, `SVG.Canvas`, `SVG.Document`
|
|
9
|
-
| Validate SVG vocabulary and nesting
|
|
10
|
-
| Calculate geometry SVG cannot supply
|
|
11
|
-
| Inspect circle, ellipse, or finite arc geometry
|
|
12
|
-
| Fit rulers, grids, and reusable tile layouts
|
|
13
|
-
| Reuse supported cross-component helpers
|
|
14
|
-
| Import or inspect existing SVG/XML
|
|
15
|
-
| Render SVG as PDF or PNG
|
|
5
|
+
| Need | Component / entry point | Boundary |
|
|
6
|
+
| ------------------------------------------------------------------ | ---------------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
|
7
|
+
| Build SVG documents and element trees | Graphics with `SVG(...)` and SVG element calls | Default starting point for every drawing |
|
|
8
|
+
| Choose paper size, canvas geometry, or root serialization metadata | `SVG.Paper`, `SVG.Canvas`, `SVG.Document` | Keep physical size, drawing surface, and document profile independent |
|
|
9
|
+
| Validate SVG vocabulary and nesting | Standard | Use validation instead of hand-maintained element/attribute allowlists |
|
|
10
|
+
| Calculate geometry SVG cannot supply | `Sevgi::Geometry` | Use for constructed values, intersections, sweeps, and algorithmic bounds—not renderer layout |
|
|
11
|
+
| Inspect circle, ellipse, or finite arc geometry | `Sevgi::Geometry::Circle`, `Ellipse`, `Arc` | See `layout.md` for the distinction from renderer-owned `ArcTo` and `ArcBy` |
|
|
12
|
+
| Fit rulers, grids, and reusable tile layouts | `Sevgi::Sundries`, `SVG.Grid` | Choose the exact model through `layout.md` |
|
|
13
|
+
| Reuse supported cross-component helpers | `Sevgi::F` | Use it before adding a project-local Sevgi helper. Do not treat it as a general utility library |
|
|
14
|
+
| Import or inspect existing SVG/XML | Derender facade methods | Choose the source/evaluation relationship through `derender.md` |
|
|
15
|
+
| Render SVG as PDF or PNG | Sundries export / document `PDF` and `PNG` | Choose the output boundary through `output.md` |
|
|
16
16
|
|
|
17
17
|
Before reimplementing shared behavior, check `Sevgi::F` for degree trigonometry and precision, `.sevgi` discovery,
|
|
18
18
|
generated-file I/O, argv-safe child processes, Sevgi-facing names, and status output.
|
|
@@ -21,13 +21,13 @@ generated-file I/O, argv-safe child processes, Sevgi-facing names, and status ou
|
|
|
21
21
|
|
|
22
22
|
When a Sevgi checkout is available, prefer its canonical sources:
|
|
23
23
|
|
|
24
|
-
| Need
|
|
25
|
-
|
|
|
26
|
-
| Machine-readable DSL inventory and examples | `showcase/doc/data/dsl.yml`
|
|
27
|
-
| Task-oriented user semantics
|
|
28
|
-
| Runnable complete drawings
|
|
29
|
-
| Exact public contracts
|
|
30
|
-
| Rendered local YARD
|
|
24
|
+
| Need | Source |
|
|
25
|
+
| ------------------------------------------- | ------------------------------------------------------------------------------- |
|
|
26
|
+
| Machine-readable DSL inventory and examples | `showcase/doc/data/dsl.yml` |
|
|
27
|
+
| Task-oriented user semantics | `showcase/doc/content/` |
|
|
28
|
+
| Runnable complete drawings | examples under `showcase/srv` that are linked from the user docs or DSL catalog |
|
|
29
|
+
| Exact public contracts | the owning component's `lib/` YARD comments |
|
|
30
|
+
| Rendered local YARD | `.local/var/ruby/doc/api` after `bundle exec rake doc` |
|
|
31
31
|
|
|
32
32
|
## Installed Gems
|
|
33
33
|
|
|
@@ -45,14 +45,14 @@ Do not assume that the latest online API exists in the installed version.
|
|
|
45
45
|
4. Read YARD for signatures, return values, and failure contracts.
|
|
46
46
|
5. Read MDN or the SVG specification for renderer behavior.
|
|
47
47
|
|
|
48
|
-
| Topic
|
|
49
|
-
|
|
|
50
|
-
| Script and library forms
|
|
51
|
-
| SVG documents and composition | [Documents](https://sevgi.roktas.dev/documents/), [Compose](https://sevgi.roktas.dev/compose/), [DSL Catalog](https://sevgi.roktas.dev/dsl/) | [`sevgi-graphics`](https://www.rubydoc.info/gems/sevgi-graphics)
|
|
52
|
-
| Geometry
|
|
53
|
-
| Rulers, grids, and tiles
|
|
54
|
-
| SVG, PDF, and PNG output
|
|
55
|
-
| Shared helpers
|
|
56
|
-
| SVG/XML import and round trip | [Derender](https://sevgi.roktas.dev/derender/)
|
|
48
|
+
| Topic | User guide | YARD |
|
|
49
|
+
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
|
|
50
|
+
| Script and library forms | [Getting Started](https://sevgi.roktas.dev/start/), [Usage](https://sevgi.roktas.dev/usage/) | [`sevgi`](https://www.rubydoc.info/gems/sevgi) |
|
|
51
|
+
| SVG documents and composition | [Documents](https://sevgi.roktas.dev/documents/), [Compose](https://sevgi.roktas.dev/compose/), [DSL Catalog](https://sevgi.roktas.dev/dsl/) | [`sevgi-graphics`](https://www.rubydoc.info/gems/sevgi-graphics) |
|
|
52
|
+
| Geometry | [Geometry](https://sevgi.roktas.dev/geometry/) | [`sevgi-geometry`](https://www.rubydoc.info/gems/sevgi-geometry) |
|
|
53
|
+
| Rulers, grids, and tiles | [Layout](https://sevgi.roktas.dev/layout/) | [`sevgi-sundries`](https://www.rubydoc.info/gems/sevgi-sundries) |
|
|
54
|
+
| SVG, PDF, and PNG output | [Output](https://sevgi.roktas.dev/output/) | [`sevgi-graphics`](https://www.rubydoc.info/gems/sevgi-graphics), [`sevgi-sundries`](https://www.rubydoc.info/gems/sevgi-sundries) |
|
|
55
|
+
| Shared helpers | [Functions](https://sevgi.roktas.dev/functions/) | [`sevgi-function`](https://www.rubydoc.info/gems/sevgi-function) |
|
|
56
|
+
| SVG/XML import and round trip | [Derender](https://sevgi.roktas.dev/derender/) | [`sevgi-derender`](https://www.rubydoc.info/gems/sevgi-derender) |
|
|
57
57
|
|
|
58
58
|
When working in a Sevgi checkout, prefer the checked-out docs and source over an installed gem's online YARD version.
|