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 A -> 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" A -> 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) A -> B B -> 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) A -> B "anchors" 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) A -> B "styled edge" 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 A -> B "edge label" fill #fef3c7 align ljust valign top textsize 12 bold Arrows and route policy ----------------------- The glyph form of an edge is ``[Name:] A -> B "label" modifier*``. The glyph carries the heads (``->``, ``<-``, ``<->``; ``--`` is a line), the label follows the endpoint it belongs to, a chain ``A -> B "x" -> C`` is one statement per hop, and an endpoint that names no declared handle declares a box. A quoted endpoint's text is its handle: .. sheeptext-example:: :name: reference-arrow-forms :label: Edge forms :alt: A set of labelled arrows, a chain and a line A: box "source" B: box "target" C: box "review" A -> B "named" E: A -> C "named edge" route left B <-> C "both heads" "Audit" -- C The word ``arrow`` form can add a bare direction such as ``right`` to author its first departure direction (the edge's heading intent). SheepText plans the remaining bends and the arrival at the target. This example leaves the source to the right and then turns toward the target: .. sheeptext-example:: :name: reference-edge-heading :label: Authored departure heading :alt: An arrow leaves the source box to the right before turning down to the target A: box "source" at (80, 100) B: box "target" at (360, 230) arrow right from A to B The four **directional** route policies prefer the side an edge should leave by. The final route can still differ when endpoint or layout constraints win; they are not a promise of one exact path. They are taught in :doc:`layout` and can be applied from the editor as described in :doc:`editing`: The layout chapter renders the ``below`` and ``left`` choices. These cards show the other two sides with a flow that makes the detour easy to read: .. sheeptext-example:: :name: reference-route-above :label: Prefer an upper return route :alt: Two horizontally arranged boxes with the response edge routed above them direction right A: box "client" B: box "server" A -> B "request" B -> A "response" route above .. sheeptext-example:: :name: reference-route-right :label: Prefer a right-side return route :alt: Two vertically arranged boxes with the response edge routed to their right direction down A: box "client" B: box "server" A -> B "request" B -> A "response" route right The ``direct``/``orthogonal`` route policies are parser forms retained for the editor's experiments. They are deliberately not presented as product guarantees here because the shipped renderer does not promise a distinct visible result for every combination: .. _reference-experimental-route-policies: .. code-block:: text A -> B "policy" route direct A -> B "policy" route orthogonal Layout direction and strength ----------------------------- Statement strength LEADS the statement: `` ``, never the other way round. ``prefer`` is a soft preference, ``require`` is a hard requirement, and writing neither means ``prefer``. The name after ``row``, ``column``, ``stage`` and ``group`` is optional: .. sheeptext-example:: :name: reference-layout-strengths :label: Preferred and required alignments :alt: Six boxes arranged under an implicit preferred row, an explicit preferred column, and a named required row row: A B prefer column: C D require row Locked: E F A: box "implicit" B: box "prefer" C: box "column" D: box "prefer" E: box "required" F: box "row" ``direction``, ``row``, ``column`` and binary node order accept a strength. ``stage`` and ``group`` do not; they declare a visible container rather than a constraint the solver can fail to honour, and a strength written on one is refused. Binary order relates two nodes along one axis; it does not align them on a shared row or column. As with other constraints, ``prefer`` may degrade with a warning while ``require`` refuses an impossible diagram: .. sheeptext-example:: :name: reference-binary-node-order :label: Preferred and required node order :alt: Two node pairs, one ordered left to right by preference and one ordered top to bottom by requirement prefer Draft left of Review require Publish above Archive Draft: box "draft" Review: box "review" Publish: box "publish" Archive: box "archive" These feasible cards do not promise that every preference will hold. When a preference loses to a requirement, the diagram renders and the editor reports the degraded statement. An impossible set of requirements is refused with diagnostics anchored at the conflicting statements. The binary-order editor interaction is taught in :doc:`editing`. The product automatic-layout path demonstrates right/down directions. Lead with ``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 prefer direction right A: box "first" B: box "second" A -> 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 require direction down A: box "first" B: box "second" A -> 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: .. _reference-layout-direction-fallbacks: .. code-block:: text prefer direction left 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. .. _reference-authored-path: .. code-block:: text A.e -- 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): .. _reference-remote-icon-source-alias: .. code-block:: text use icons "https://example.com/packs/cloud.json" as cloud icon cloud:database