Syntax reference ================= This page collects the small authoring forms that are useful when moving from the guided tutorial to a real document. Every rendered card below is checked by the site build and carries the exact source into the editor. Statement separators, comments, and continuation ------------------------------------------------- Newlines and semicolons separate statements. ``//`` and ``#`` (when followed by whitespace) are line comments; ``/* ... */`` is a block comment. A trailing backslash joins the next physical line into one logical statement: .. sheeptext-example:: :name: reference-comments :label: Separators and comments :alt: Two boxes connected after semicolon, hash, and block comments # a hash comment /* a block comment */ A: box "A"; B: box "B" // an end-of-line comment arrow from A to B .. sheeptext-example:: :name: reference-continuation :label: A continued statement :alt: Two boxes connected after a width expression continued onto the next line A: box "A" width \ 120 B: box "B" arrow from A to B Expressions and dimensions -------------------------- Numeric expressions accept decimal and scientific literals, unary signs, parentheses, and the ordinary ``+``, ``-``, ``*``, and ``/`` operators. The same expression forms work in ``width``, ``height``, ``size``, ``textsize``, ``gap``, and coordinate fields: .. sheeptext-example:: :name: reference-expressions :label: Numeric expression forms :alt: Boxes sized by decimal, scientific, unary, grouped, and arithmetic expressions base = 1.25e2 inset = -(1 + 2) * -3 A: box "decimal + scientific" width base / 2 B: box "unary + grouped" width base + inset height 40 C: box "all operators" width (base - 10) * 2 / 5 at (500, 120) arrow from A to B arrow from B to C Placement fields are coordinates, named places, anchors, and ``between`` expressions. ``at`` and ``with`` are equivalent placement forms for a shape: .. sheeptext-example:: :name: reference-placement :label: Placement fields :alt: Boxes placed by corners with a connector between their anchors A: box "source" with .nw at (40, 50) B: box "target" at (420, 300) Caption: text "between" at between(A, B, 1/2) arrow "anchors" from A to B Sizing and text alignment ------------------------- Boxes accept ``width`` and ``height`` (or the shared ``size`` qualifier), and ``fill none`` leaves a shape unfilled. Text and edge labels accept all three horizontal alignments and all three vertical alignments: .. sheeptext-example:: :name: reference-sizing-alignment :label: Size, fill, and alignment :alt: Sized boxes with no fill and styled text at all alignment positions A: box "wide" width 160 height 44 fill none B: box "tall" size 72 fill #dbeafe at (320, 120) text "left / top" align ljust valign top at (80, 220) text "center / center" align center valign center at (300, 220) text "right / bottom" align rjust valign bottom at (520, 220) arrow "styled edge" from A to B fill #fef3c7 align rjust valign bottom textsize 13 bold italic Blocks and label styling ------------------------ Square-bracket blocks are labelled containers. Their label supports fill, text size, weight, style, and alignment qualifiers. The same style qualifiers are accepted on boxes, standalone text, and edge labels: .. sheeptext-example:: :name: reference-block-styles :label: Styled block and edge label :alt: A styled group containing two boxes and a styled edge label Region: [ A: box "api" B: box "worker" ] "Service block" fill #336699 textsize 16 bold italic align center valign bottom arrow "edge label" from A to B fill #fef3c7 align ljust valign top textsize 12 bold Arrows and route policy ----------------------- The named, keyword-first, and place-first arrow forms are equivalent: .. sheeptext-example:: :name: reference-arrow-forms :label: Named arrow forms :alt: A set of labelled arrows using keyword-first and place-first forms A: box "source" B: box "target" C: box "review" arrow "keyword first" from A to B A arrow "place first" to C Arrow-head directions, compact arrow glyphs, and direct/orthogonal route policies are parser forms retained for compatibility. They are deliberately not presented as product guarantees here because the shipped renderer does not promise a distinct visible result for every combination: .. code-block:: text arrow "heads" from A to B heads left arrow "heads" from A to B heads up arrow "glyph" from A to B <-> arrow "policy" from A to B route direct arrow "policy" from A to B route orthogonal Layout direction and strength ----------------------------- The product automatic-layout path demonstrates right/down directions. Append ``prefer`` for a soft preference or ``require`` for a hard direction/row/column requirement: .. sheeptext-example:: :name: reference-preferred-layout :label: Preferred layout direction :alt: A preferred rightward layout flow layout direction right prefer A: box "first" B: box "second" arrow from A to B ``require`` is a hard strength. This supported downward requirement is a compact form that remains feasible for the automatic solver: .. sheeptext-example:: :name: reference-required-layout :label: Required layout direction :alt: A required downward layout flow layout direction down require A: box "first" B: box "second" arrow from A to B The ``left`` and ``up`` direction tokens remain parser/reference forms. Their automatic fallback is intentionally not a product quality promise, so they are shown only as syntax: .. code-block:: text layout direction left prefer layout direction up After automatic layout has produced a useful baseline, an authored ``path`` is an explicit parser escape hatch for a route that must follow particular bends. It is retained in the reference corpus but has no product card because current production rendering does not guarantee a distinct visible route for every authored path. .. code-block:: text line from A.e to B.w path right 80 then down 90 then right 60 Icons and source aliases ------------------------ Built-in packs are the product-supported offline path. ``labelside`` accepts ``left``, ``right``, ``top``, and ``bottom``. A remote source alias is retained as a grammar/reference form but is intentionally not published here: a build must never depend on an unavailable network pack. The editor can still show the alias text when experimenting with a locally available pack. .. sheeptext-example:: :name: reference-icon-sides :label: Icon caption sides :alt: Four AWS server icons with captions on each side use icons aws L: icon aws:server labelside left "left" at (100, 150) R: icon aws:server labelside right "right" at (280, 150) T: icon aws:server labelside top "top" at (460, 150) B: icon aws:server labelside bottom "bottom" at (640, 150) Grammar-only reference (not a published render): .. code-block:: text use icons "https://example.com/packs/cloud.json" as cloud icon cloud:database