rsyntaxtree 1.13.1 → 1.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0804e9119e0ebb089b4109ae05c9353180362bd6e86fddbf2e4da00db3b08e18'
-  data.tar.gz: '01867ffda61d7f81fd3d81a9f6ad44ba83eda4f7d89d1b3b05d53b196bc23fa1'
+  metadata.gz: 965fe8dae50ad6fe7907850239f395fda6a5186654a81d36b89400ebe52108f2
+  data.tar.gz: 4a183744f4d05b63efcbd1e9aedb6a4bf060654fde9dfc62abaeb20e6a38ac8a
 SHA512:
-  metadata.gz: 990e4522fe0e0694d009eddebc2b3b2af98e5beda1f3e2daf9fbf1250199cef31b981215d1ae7db3b711d0030826e2445c7011f427223f8e081bffb8d76451ae
-  data.tar.gz: fe620d8c1fe64c289b18d853d6663ceaae5ea8a7486a5f0cf0ce578f8c0e9073e48251f0d7a933d0c7afa9ee7fce896dd6cbf00f3499c8d5314278e9cc0e0b57
+  metadata.gz: ee4fca1e926ad6886aaca041468f61dc0a596eeffa107c4ee3a82576f2ac7ac53eddcdc0ee586fc5f4408fc809188dba1279eb0ff8083892ef1b598aea830ca1
+  data.tar.gz: 19173b80e3c2376a9f25d6ea72604bc5774194af7eccfc2b1158dfdf75939ed5d700f654b8122ecf3df99242036686666266ed829710fbe22d94bbea965ae91b

data/CHANGELOG.md

@@ -1,6 +1,77 @@
 # Changelog
 
-## [1.13.1] - 2026-08
+## [1.14.0] - 2026-08-27
+
+### Added
+- The notation has a map. The reference the gem ships (`--notation`) is one
+  page: the characters that already mean something, then every feature at a
+  line each with the notation beside it, then the options. Both manuals open
+  with the same list, each row pointing at the section that explains it. A test
+  reads the feature set out of the grammar itself and draws every sample, so a
+  feature the grammar gains with no row in the documents fails the build, and a
+  sample that stops meaning what it says fails with it.
+- The changelog is on the documentation site, at /changelog, built from
+  CHANGELOG.md and linked from the manuals and the README.
+
+### Changed
+- Every release in the changelog is dated to the day, from the git tags. Two of
+  the old month-only dates were wrong.
+- What the trap section warns about is now, by definition, what the tool
+  accepts and draws as something other than what was meant. A mistake the tool
+  refuses is the error message's job, and its card has come down; the warning
+  about parentheses, which the Penn Treebank conversion had made false, tells
+  the truth again.
+- The arrow markers' dimensions are rounded; the defs of every SVG carried
+  float dust in an attribute.
+
+### Fixed
+- Turning `derivation` on no longer deletes a column from a node that has no
+  daughters. A rule name is written after a column break and names the step
+  that produced a node from its daughters, so a node with none names no rule —
+  but the label is read before the tree is built, and the name was taken out
+  anyway and then had no rule to be drawn beside. `[A\tfoo]` drew "A foo" with
+  the option off and "A" with it on. The label is put back once the tree is
+  known.
+- A mistake inside a node's label keeps the name of what is wrong with it. The
+  first raw space splits a token into a label and its children, and when the
+  label would not parse, every cause but one was relabelled "a raw space split
+  this" — so the message named an unknown colour while the code and the hint
+  talked about spaces, and a caller acting on the code was sent to fix what was
+  not wrong. Which story is right is now asked of the parser rather than
+  guessed: the token is put back together with its spaces written as the
+  notation writes them, and if it reads, the space was the cause.
+- A hex colour is three digits or six, which is what every message about colour
+  here already said. The grammar asked for three to six, so four and five
+  parsed, passed the validator — which does not look at a value beginning with
+  `#` — and reached librsvg, which cannot read them and draws the label black
+  without reporting it.
+
+## [1.13.2] - 2026-08-27
+
+### Fixed
+- A movement path is drawn as one stroke with its corners eased, in place of
+  three lines meeting at right angles. The dash of a non-directional path now
+  runs round each turn instead of restarting at it, and the arrowhead is the end
+  of the stroke rather than a marker on whichever line finished last. The radius
+  is held down to half of each run it joins, so a short leg cannot be swallowed
+  by its own turn, and to the length of an arrowhead where there is one, so the
+  head is never drawn onto the curve. Three gallery figures carry paths and
+  change with it.
+- Digits are set in the text face again on machines that have a colour emoji
+  font. The font chains named emoji families by name, and asking fontconfig for
+  one is asking for the generic `emoji` family, whose preference list fontconfig
+  then prepends to the whole pattern with a strong binding — so the emoji face
+  arrived ahead of the Noto text faces rather than behind them. A colour emoji
+  font carries the ASCII digits, for keycap sequences, so on an ordinary Linux
+  desktop `[N 20]` came out in the emoji face at more than twice the width.
+  Measurement and drawing read the same chain, so the figure held together; it
+  was simply not the figure the same input gives elsewhere. No emoji family is
+  named now: a codepoint no named family covers reaches fontconfig's own
+  fallback, which is the path this was duplicating. Emoji draw as before, and
+  the gallery is unchanged to the pixel — every raster figure is byte-identical
+  and the SVGs differ only in the family list they carry.
+
+## [1.13.1] - 2026-08-27
 
 ### Fixed
 - `^` at the head of a leaf draws the triangle it asks for. The mark may be
@@ -19,7 +90,7 @@
   every input, because the form still read a `format` select the page no longer
   had. A value that is actually wrong is still rejected.
 
-## [1.13.0] - 2026-08
+## [1.13.0] - 2026-08-24
 
 ### Added
 - Derivations. A derivation puts the words first and the result last, and
@@ -38,7 +109,7 @@
   have when the root is at the top, so every line ran from above the daughter,
   through its label and the mother's, to below the mother.
 
-## [1.12.0] - 2026-08
+## [1.12.0] - 2026-08-22
 
 Everything needed to write this notation is now available as text, built from
 the files the tool itself reads, and a refusal says where that text is.
@@ -68,7 +139,7 @@ the files the tool itself reads, and a refusal says where that text is.
   meant waiting on a pipe that never closes when stdin is not a terminal,
   which is how a script reaches them.
 
-## [1.11.0] - 2026-08
+## [1.11.0] - 2026-08-21
 
 Every input the tool accepts now draws, and every input it refuses says why.
 Line thickness follows the type size, so figures drawn at any font size keep
@@ -127,7 +198,7 @@ fifth lighter than before.
   read as a path to the current directory.
 - Overline was documented as missing from PNG output. It has been there.
 
-## [1.10.0] - 2026-08
+## [1.10.0] - 2026-08-19
 
 A transitional release ahead of 2.0, which drops JPG/GIF output and the
 RMagick dependency.
@@ -150,7 +221,7 @@ RMagick dependency.
   file here carries `frozen_string_literal`, which made the working form the
   unobvious one.
 
-## [1.9.0] - 2026-08
+## [1.9.0] - 2026-08-19
 
 ### Added
 - `hyphen: literal`, which trades the two readings of a hyphen: a bare one is
@@ -218,7 +289,7 @@ RMagick dependency.
   the arrow was drawn small to fit; now the pair is spread and the arrow keeps
   its size. Only pairs that carry a link move, and only when they need to.
 
-## [1.8.2] - 2026-08
+## [1.8.2] - 2026-08-17
 
 ### Changed
 - `tidy: high` now compresses as far as its name promises. The level-balance
@@ -246,7 +317,7 @@ RMagick dependency.
   resolved nowhere on macOS, Debian/Ubuntu or Alpine; the chain fell through
   to `Noto Sans Mono`, which it now names directly.
 
-## [1.8.1] - 2026-08
+## [1.8.1] - 2026-08-15
 
 ### Fixed
 - Arabic rendered as isolated, unjoined letterforms in some environments.
@@ -275,7 +346,7 @@ RMagick dependency.
 - Documentation records how to override any of the named families with a
   fontconfig alias, for users who prefer their own script fonts.
 
-## [1.8.0] - 2026-08
+## [1.8.0] - 2026-08-15
 
 ### Added
 - `tidy` layout scale, one option covering every layout mode from the most
@@ -324,7 +395,7 @@ RMagick dependency.
   when the caller passes only a partial parameter set (e.g. `tidy: off`
   rendered as `symmetric` in the web UI).
 
-## [1.7.0] - 2026-08
+## [1.7.0] - 2026-08-13
 
 ### Changed
 - Text measurement now uses Pango, the same engine (and the same fontconfig
@@ -344,7 +415,7 @@ RMagick dependency.
 - Runtime dependency on the `pango` gem (ruby-gnome). No new system
   requirements: librsvg already depends on Pango.
 
-## [1.6.3] - 2026-07
+## [1.6.3] - 2026-07-19
 
 ### Fixed
 - Packaged files no longer carry owner-only permissions. `gem build` preserves
@@ -356,14 +427,14 @@ RMagick dependency.
   tree had picked up on data files (images, fonts, Markdown, CSS, library
   sources).
 
-## [1.6.2] - 2026-06
+## [1.6.2] - 2026-06-26
 
 ### Fixed
 - Region shade no longer touches the image edge when its padded bounds reach
   past the tree's natural extent (e.g. a deep enclosed/multi-line node): the
   canvas now grows with a margin around the shaded plane.
 
-## [1.6.1] - 2026-06
+## [1.6.1] - 2026-06-26
 
 ### Improved
 - Region shade rendering wraps the subtree more cleanly: wider, balanced
@@ -377,7 +448,7 @@ RMagick dependency.
 - Example 065: nested (overlapping) region shades, shown as progressively
   darker gray.
 
-## [1.6.0] - 2026-06
+## [1.6.0] - 2026-06-25
 
 ### Added
 - Region shade (`%` prefix): paints a semi-transparent plane behind the whole
@@ -405,7 +476,7 @@ RMagick dependency.
 - Region shade on the root/topmost node no longer clipped by the canvas: the
   SVG viewBox now grows to include region planes that extend past the tree.
 
-## [1.5.0] - 2026-04
+## [1.5.0] - 2026-04-06
 
 ### Added
 - Left-to-right tree layout (`-d ltr` / `--direction ltr`)
@@ -420,7 +491,7 @@ RMagick dependency.
 ### Improved
 - TTB path bulge proportional to endpoint distance (reduced excess)
 
-## [1.4.0] - 2026-01
+## [1.4.0] - 2026-01-06
 
 ### Added
 - LSIF (Linguistic Structure Interchange Format) JSON output (`-f lsif`)
@@ -436,15 +507,15 @@ RMagick dependency.
 - Added examples for per-node coloring (054, 055, 056)
 - Added example 057: Subscript and superscript demo
 
-## [1.3.2] - 2024
+## [1.3.2] - 2025-03-03
 
 - Garbage collection friendly implementation
 
-## [1.3.1] - 2024
+## [1.3.1] - 2024-10-24
 
 - Bug fixes and improvements
 
-## [1.3.0] - 2024
+## [1.3.0] - 2024-08-27
 
 - TikZ/forest LaTeX output support
 

data/README.md

@@ -2,6 +2,9 @@
 
 **RSyntaxTree** is a graphical syntax tree generator for linguistic research.
 
+[![Test](https://github.com/yohasebe/rsyntaxtree/actions/workflows/test.yml/badge.svg)](https://github.com/yohasebe/rsyntaxtree/actions/workflows/test.yml)
+[![Gem Version](https://img.shields.io/gem/v/rsyntaxtree)](https://rubygems.org/gems/rsyntaxtree)
+
 <p>
   <a href="https://yohasebe.com/rsyntaxtree"><strong>Web App</strong></a> ·
   <a href="https://yohasebe.github.io/rsyntaxtree/examples"><strong>Example Gallery</strong></a> ·
@@ -203,6 +206,50 @@ fontsize: 18
 
 CLI options override config file settings.
 
+## Using RSyntaxTree with an AI Model
+
+The notation is small, but several characters in it already mean something, so
+a model writing it does better with the reference in front of it than without.
+
+**If the model only writes the notation** and you draw it yourself — in the
+[web interface](https://yohasebe.com/rsyntaxtree) or on your own machine —
+nothing needs installing. Give the model one of these to read:
+
+- [The brief reference](https://yohasebe.github.io/rsyntaxtree/llms.txt), about
+  a page, leading with the characters that already mean something.
+- [Everything in one file](https://yohasebe.github.io/rsyntaxtree/llms-full.txt):
+  the reference, the manual and all the gallery examples, 78 KB.
+
+**If the model can run a shell**, it can draw and then look at what it drew,
+which is the part that lets it correct itself:
+
+```bash
+docker run --rm -v "$PWD:/work" -w /work ghcr.io/yohasebe/rsyntaxtree \
+  rsyntaxtree --notation                       # the reference, on stdout
+docker run --rm -v "$PWD:/work" -w /work ghcr.io/yohasebe/rsyntaxtree \
+  rsyntaxtree -f png -o . "[S [NP a tree] [VP appears]]"
+```
+
+Then read `syntree.png` back. `--examples` prints every gallery example with
+the settings it was drawn at, and `--validate` reports what is wrong with an
+input as JSON — including whether rewriting it is worth trying — without
+drawing anything:
+
+```json
+{ "schema": "rsyntaxtree.error/1", "ok": false,
+  "errors": [ { "code": "unbalanced_brackets",
+                "message": "Error: open and close brackets do not match",
+                "hint": "Count the brackets: every '[' needs one ']'.",
+                "retryable": true } ],
+  "reference": "rsyntaxtree --notation, or https://yohasebe.github.io/rsyntaxtree/llms-full.txt" }
+```
+
+The exit code carries the verdict too, so a script can branch on it without
+reading the JSON. The Docker image is used above because this tool draws
+through Pango and librsvg, and a figure depends on which versions of those —
+and which fonts — are installed; the image fixes all of them. Installed as a
+gem it works the same, once those libraries are on the machine.
+
 ## Documentation
 
 For detailed documentation on syntax and markup:
@@ -210,6 +257,7 @@ For detailed documentation on syntax and markup:
 - [Documentation in English](https://yohasebe.github.io/rsyntaxtree/documentation)
 - [日本語ドキュメント](https://yohasebe.github.io/rsyntaxtree/documentation_ja)
 - [Example Gallery](https://yohasebe.github.io/rsyntaxtree/examples)
+- [Changelog](https://yohasebe.github.io/rsyntaxtree/changelog)
 
 ## How to Cite
 

data/lib/rsyntaxtree/element.rb

@@ -13,7 +13,7 @@ require_relative "color_names"
 
 module RSyntaxTree
   class Element
-    attr_accessor :rule_name, :id, :parent, :type, :level, :width, :height, :content, :content_width, :text_width, :content_height, :horizontal_indent, :vertical_indent, :triangle, :enclosure, :children, :font, :fontsize, :contains_phrase, :path, :color, :raw_content, :region, :region_color
+    attr_accessor :rule_name, :label_with_rule_name, :id, :parent, :type, :level, :width, :height, :content, :content_width, :text_width, :content_height, :horizontal_indent, :vertical_indent, :triangle, :enclosure, :children, :font, :fontsize, :contains_phrase, :path, :color, :raw_content, :region, :region_color
 
     # names_a_rule says the content is a mother's label rather than a leaf's
     # text. Only a mother has a step under it for a name to sit beside, and a
@@ -42,7 +42,11 @@ module RSyntaxTree
       @fontset = fontset
       @fontsize = fontsize
       # In a derivation the label may carry the name of the rule that produced
-      # it, written after a column break: `S/NP\t\>B`. The name belongs beside
+      # it, written after a column break: `S/NP\t>B`. The name is taken out
+      # before the label is read as markup, so it is drawn exactly as written —
+      # `>` and `<` need no escaping there, and escaping them puts the backslash
+      # in the figure. (This example carried one, which is the opposite of what
+      # the gallery's derivations do.) The name belongs beside
       # the rule rather than beside the result, so it comes out of the label
       # here, before the label is measured, and BaseGraph draws it at the end
       # of the rule.
@@ -51,6 +55,11 @@ module RSyntaxTree
         name = at && content[(at + 2)..].to_s.strip
         if name && !name.empty?
           @rule_name = name
+          # Kept whole, because whether this node has daughters — and so
+          # whether it names a rule at all — is not known until the tree
+          # is built. StringParser puts the label back if it turns out
+          # there was no step for the name to belong to.
+          @label_with_rule_name = content
           content = content[0...at]
         end
       end

data/lib/rsyntaxtree/markup_parser.rb

@@ -15,7 +15,14 @@ class MarkupParser < Parslet::Parser
 
   # Color specification: @colorname: or @#hexcode:
   rule(:color_name) { match('[a-zA-Z]').repeat(1) }
-  rule(:color_hex) { str('#') >> match('[0-9a-fA-F]').repeat(3, 6) }
+  # Three digits or six, which is what every message about colour in this
+  # codebase already says. The rule used to be written as "three to six", so
+  # four and five passed the parser, passed the validator (which does not look
+  # at a value beginning with '#' at all), and went into the SVG — where
+  # librsvg cannot read them and draws the label black, with nothing reported.
+  # Six first: on a six-digit value the three-digit branch matches and then
+  # the ':' is not there to be found.
+  rule(:color_hex) { str('#') >> (match('[0-9a-fA-F]').repeat(6, 6) | match('[0-9a-fA-F]').repeat(3, 3)) }
   rule(:color_spec) { str('@') >> (color_hex | color_name).as(:color_value) >> str(':') }
 
   # Region shade: '%' marks the node so that the whole subtree it governs

data/lib/rsyntaxtree/notation_core.md

@@ -1,52 +1,105 @@
-RSyntaxTree notation, in brief.
+RSyntaxTree notation, on one page.
 
 A tree is labeled brackets: [S [NP the cat] [VP sat]]. The label follows the
-opening bracket; children follow the label.
-
-Within a label:
-- `\n` breaks a line; `\t` separates columns, and every line is cut at the
-  same points, so the columns line up down the label. (`\t` is the two
-  characters backslash and t, not a real tab.)
-- `#label` draws square brackets around the whole label; `##label` a
-  rectangle. `#( ... #)` nests a matrix inside a label, to any depth.
-- `*italic*`, `**bold**`, `x_sub_`, `x__super__`, `|x|` in a box, `{x}` in a
-  circle, `---` a horizontal rule.
-- `+n` on two nodes links them with a movement arrow; `+>n` puts the
-  arrowhead on that end.
-
-Four traps, because these characters already mean something:
-- `<` and `>` are never angle brackets in this notation: `<>` is one space,
-  `<3>` is three. Wherever linguistics uses angle brackets — a list ⟨NP⟩,
-  an argument structure like 'hand⟨SUBJ,OBJ⟩', anything — write the
-  characters ⟨ and ⟩ themselves (U+27E8 and U+27E9):
-  SPR\t⟨<>NP<>⟩    PRED\t'hand⟨SUBJ,OBJ⟩'
-- `-` opens and closes an underline, so a bare hyphen in ANY word is an
-  error: V-bar, f-structure, HEAD-DTR. Write `V'`, or escape the hyphen:
-  `V\-bar`, `f\-structure`, `HEAD\-DTR`.
-- A raw space is safe in a one-line label, and unreliable in a label that
-  has `\n` or `\t` in it: there it splits a value that carries markup, and
-  it breaks a matrix nested with `#( ... #)`. Since matrices are exactly the
-  multi-line case, write a space as `<>` inside any label with columns:
-  'a<>toy', not 'a toy'.
-- Parentheses are not brackets, and this is silent: `(S (NP ...))` raises no
-  error and draws one leaf with that text in it. Convert it first.
-
-An attribute-value matrix is columns plus an enclosure:
-
-    [#*word*\
-      HEAD\t*verb*\
-      SPR\t⟨<>NP<>⟩\
-      COMPS\t⟨<>⟩
-    ]
+opening bracket; children follow the label. Parentheses are read as Penn
+Treebank notation and converted: (S (NP the cat) (VP sat)) draws the same tree.
+
+## What already means something
+
+The characters that bite, first. A mistake the tool can see is refused with a
+hint; everything below is taken silently, and the figure that draws is not the
+figure that was meant.
+
+- `<>` is one space and `<3>` is three, everywhere — never angle brackets.
+  Where linguistics wants the brackets themselves, write ⟨ and ⟩ (U+27E8/9):
+  SPR\t⟨<>NP<>⟩, 'hand⟨SUBJ,OBJ⟩'. A label written <NP> is refused with this
+  advice; a stray <3> simply draws three spaces.
+- A pair of hyphens underlines what stands between them: well-made-word draws
+  "made" underlined. (A lone hyphen is refused with a hint.) Write `\-` for a
+  hyphen — V\-bar, HEAD\-DTR — or set the hyphen option to literal.
+- A raw space is safe in a one-line label and unreliable in a label that has
+  `\n` or `\t` in it: there it can split a value that carries markup, and it
+  breaks a nested #( ... #) matrix. Inside any label with columns, write a
+  space as `<>`: 'a<>toy', not 'a toy'.
+- A straight apostrophe is typeset as the curly ’ (U+2019).
+- A backslash takes the character after it, whatever it is: \q draws q, and
+  C:\path draws C:path. A backslash itself is \\.
+- The prefixes of a label compose in one order, and only this one:
+  `^` → `#`/`##`/`###` → `%` → `@color:`. So ^#%@red:NP is read whole, while
+  @red:%NP leaves the % as a literal character and silently drops the shade.
+- A rule name (for derivations) is written after the label's last `\t`, as in
+  [S/NP\t>B ...], and needs the derivation option ON — with it off the name is
+  drawn as a column. The name is taken out before markup runs, so `>` and `<`
+  need no escaping there and `\>` would put the backslash in the figure. A
+  label that also carries `\n` keeps all its columns instead.
+
+## What there is
+
+Structure:
+
+| what                                   | how it is written |
+|----------------------------------------|-------------------|
+| a node with children                   | [S [NP the cat] [VP sat]] |
+| a phrase under one leaf (triangle)     | [NP a toy] — one word, forced: [NP ^cats] |
+| an invisible joint, to align leaves    | a label of only <>, as in [X [<> [Y y]] [Z z]] |
+| a movement path (dashed)               | [S [NP a+1] [VP [V b] [NP c+1]]] |
+| the same, with an arrowhead            | write +>1 on the end the arrow points at |
+| an extra straight connector            | +-1 on two nodes; +->1 for an arrowhead |
 
-A value can be another matrix. Nest it with `#( ... #)`, never with square
-brackets — those are read as tree structure:
+Inside a label:
+
+| what                                   | how it is written |
+|----------------------------------------|-------------------|
+| italic, bold, both                     | *x*, **x**, ***x*** |
+| subscript, superscript                 | x_i_, x__2__ |
+| small capitals                         | H___EAD___ |
+| overline, underline, strikethrough     | =x=, -x-, ~x~ |
+| a line break; a blank line             | a\nb (or a\ b); \n\n |
+| columns, aligned down the label        | HEAD\t*verb*\nSPR\t⟨<>⟩ |
+| a horizontal rule across the label     | a line of --- (or === for a double rule) |
+| boxed, circled text                    | |1|, {2} — more than one character draws a capsule |
+| empty and hatched boxes and circles    | ||, {}, |/|, {/} |
+| bar and arrows as symbols              | --, ->, <-, <-> — bold with *...*, as in *->* |
+
+Around a label:
+
+| what                                   | how it is written |
+|----------------------------------------|-------------------|
+| square brackets, rectangle, bold       | #NP, ##NP, ###NP |
+| a feature matrix as a value            | #(HEAD\tnoun#), nested to any depth |
+| a whole label that is one matrix       | [#(CAT\tS#) [#(CAT\tNP#) Kim] [#(CAT\tVP#) sleeps]] |
+| a region shade behind the subtree      | %NP, coloured: %@blue:NP |
+| a colour                               | @red:NP, @#3af:NP, @#33aaff:NP (3 or 6 hex digits) |
+
+An attribute-value matrix is columns plus an enclosure, and a value can be
+another matrix — nested with #( ... #), never with square brackets, which are
+read as tree structure:
 
     [#PRED\t'hand⟨SUBJ,OBJ⟩'\
       TENSE\tpast\
       SUBJ\t#(PRED\t'David'#)
     ]
 
-A movement arrow links the two nodes that carry the same number:
+Options (the command line spells them --like-this):
+
+| option     | what it decides |
+|------------|-----------------|
+| format     | png, svg, pdf, gif, jpg, tikz, lsif |
+| fontstyle  | sans, serif, mono, cjk |
+| fontsize   | 6–26 |
+| color      | modern, traditional, off, gray |
+| linewidth  | every line's weight, 0.5–3.0, as a ratio of the font size |
+| leafstyle  | auto, bar, nothing — what joins a node to its leaf |
+| direction  | ttb, ltr, btt |
+| mirror     | flip the finished layout, for RTL scripts |
+| tidy       | off, symmetric, low, medium, high — how tightly subtrees pack |
+| hspacing   | horizontal spacing factor, 0.5–3.0 (tidy_spacing is its old name) |
+| vheight    | vertical spacing factor, 0.5–5.0 |
+| derivation | one rule across the daughters, categorial-grammar style |
+| hyphen     | markup (hyphens underline) or literal (hyphens are hyphens) |
+
+The full manual explains each of these with figures, and every example in the
+gallery is written out beside the figure it draws:
 
-    [S [NP what+>1] [VP [V see] [NP+1 t]]]
+    https://yohasebe.github.io/rsyntaxtree/documentation
+    https://yohasebe.github.io/rsyntaxtree/examples

data/lib/rsyntaxtree/string_parser.rb

@@ -96,9 +96,44 @@ module RSyntaxTree
       end
     end
 
+    # Whether the raw space that split this token is what stopped it parsing.
+    # Asked of the parser rather than reasoned about: the whole token, with its
+    # spaces written as `<>`, either reads as one label or it does not.
+    def space_is_the_cause?(token, parent)
+      Element.new(-1, parent, token.gsub(" ", WHITESPACE_BLOCK), @level,
+                  @fontset, @fontsize, @global, true)
+      true
+    rescue StandardError
+      false
+    end
+
     def parse
       make_tree(0);
       @elist.set_hierarchy
+      restore_rule_names_without_a_rule
+    end
+
+    # A rule name names the step that produced a node from its daughters. A node
+    # with no daughters is the product of no step, so what looked like a name is
+    # a column of the label like any other, and it goes back.
+    #
+    # Whether a node will have daughters is not known where the label is read —
+    # they arrive as later tokens — so the label is read first and put right
+    # here, once the tree is built. Left alone, turning the option on deleted a
+    # column: `[A\tfoo]` drew "A foo" with derivation off and "A" with it on,
+    # and said nothing about the difference.
+    def restore_rule_names_without_a_rule
+      @elist.elements.each_with_index do |e, i|
+        next if e.rule_name.nil? || e.rule_name.empty?
+        next unless e.children.empty?
+        next if e.label_with_rule_name.nil?
+
+        restored = Element.new(e.id, e.parent, e.label_with_rule_name,
+                               e.level, @fontset, @fontsize, @global)
+        restored.children = e.children
+        restored.type = e.type
+        @elist.elements[i] = restored
+      end
     end
 
     def get_elementlist
@@ -215,7 +250,21 @@ module RSyntaxTree
                 # parse, the likeliest story is that the space belongs
                 # inside the label and cut a construct in two — say so,
                 # unless a more specific cause is already known.
-                raise e if e.code == :bare_hyphen
+                #
+                # Which story is right is not a thing to guess at: ask
+                # whether the space is the one that breaks it. Put the whole
+                # token back together with the spaces written as the notation
+                # writes them, and try again. If it parses, the space was
+                # cutting a construct in two and that is what to say. If it
+                # fails the same way, the space is a red herring and the cause
+                # already named is the one to keep.
+                #
+                # It used to keep :bare_hyphen and relabel every other cause,
+                # so one error said two things: the message naming an unknown
+                # colour while the code and the hint talked about spaces. A
+                # caller acting on the code — which is what these are for —
+                # was sent to fix what was not wrong.
+                raise e unless space_is_the_cause?(token_r.join, parent)
 
                 raise RSTError.new(e.message,
                                    code: :label_split,

data/lib/rsyntaxtree/svg_graph.rb

@@ -92,8 +92,11 @@ module RSyntaxTree
 
       extra_lines = @extra_lines.join("\n")
 
-      as2 = @global[:h_gap_between_nodes] * 1.0
-      as4 = as2 * 3
+      # Rounded like the stroke widths are: the arithmetic leaves float dust
+      # (13.600000000000001) in an attribute of every figure, and the SVG is a
+      # deliverable people open in editors.
+      as2 = (@global[:h_gap_between_nodes] * 1.0).round(3)
+      as4 = (as2 * 3).round(3)
       # The hatch density follows the type size the way the enclosure it
       # fills does: the cell is 10/32 of the font size, the line 4/32 —
       # the ratios the absolute 10 and 4 had at the default size.
@@ -108,6 +111,9 @@ module RSyntaxTree
             <marker id="arrow" markerUnits="userSpaceOnUse" viewBox="0 0 10 10" refX="10" refY="5" markerWidth="#{as2}" markerHeight="#{as2}" orient="auto">
               <path d="M 0 0 L 10 5 L 0 10" fill="#{@col_extra}"/>
             </marker>
+            <marker id="arrowStart" markerUnits="userSpaceOnUse" viewBox="0 0 10 10" refX="0" refY="5" markerWidth="#{as2}" markerHeight="#{as2}" orient="auto">
+              <path d="M 10 0 L 0 5 L 10 10" fill="#{@col_extra}"/>
+            </marker>
             <marker id="arrowBackward" markerUnits="userSpaceOnUse" viewBox="0 0 10 10" refX="5" refY="5" markerWidth="#{as2}" markerHeight="#{as2}" orient="auto">
               <path d="M 0 0 L 10 5 L 0 10 z" fill="#{@col_extra}"/>
             </marker>
@@ -259,9 +265,83 @@ module RSyntaxTree
       b
     end
 
+    # A point the given distance from `from` along the line towards `to`.
+    def along(from, to, distance)
+      dx = to[0] - from[0]
+      dy = to[1] - from[1]
+      length = Math.sqrt((dx * dx) + (dy * dy))
+      return from.dup if length.zero?
+
+      [from[0] + (dx / length * distance), from[1] + (dy / length * distance)]
+    end
+
+    # The `d` of a polyline whose corners are eased into quarter turns.
+    #
+    # The radius is clamped to half of each of the two runs meeting at a corner,
+    # so a short leg can never be swallowed by its own turn and two adjacent
+    # corners can never overlap — which is the whole of the arithmetic that
+    # rounding a right angle needs, and why it can be a constant everywhere
+    # else.
+    def rounded_polyline_d(points, radius)
+      return +"" if points.size < 2
+
+      at = ->(p) { "#{p[0].round(3)},#{p[1].round(3)}" }
+      d = +"M#{at.call(points[0])}"
+      points.each_cons(3) do |before, corner, after|
+        r = [radius,
+             Math.sqrt(((corner[0] - before[0])**2) + ((corner[1] - before[1])**2)) / 2.0,
+             Math.sqrt(((after[0] - corner[0])**2) + ((after[1] - corner[1])**2)) / 2.0].min
+        if r < 0.01
+          d << " L#{at.call(corner)}"
+        else
+          d << " L#{at.call(along(corner, before, r))}" \
+               " Q#{at.call(corner)} #{at.call(along(corner, after, r))}"
+        end
+      end
+      d << " L#{at.call(points.last)}"
+    end
+
+    # One stroke rather than three lines meeting at right angles. Drawn this way
+    # the dash pattern runs round each turn instead of restarting at it, and an
+    # arrowhead is the end of the stroke rather than a marker on whichever line
+    # happens to finish last.
+    def generate_path(points, col, dashed: false, radius: 0, start_arrow: false, end_arrow: false)
+      # An arrowhead is drawn back along the run it ends, so the corner before
+      # it has to leave that run its full length. Without this the shorter of
+      # the two end runs — which is only as long as the path's bulge — lost half
+      # of itself to the turn and the head came out sitting on the curve.
+      arrow_length = @global[:h_gap_between_nodes]
+      leg = ->(a, b) { Math.sqrt(((a[0] - b[0])**2) + ((a[1] - b[1])**2)) }
+      radius = [radius, leg.call(points[0], points[1]) - arrow_length].min if start_arrow
+      radius = [radius, leg.call(points[-2], points[-1]) - arrow_length].min if end_arrow
+      radius = [radius, 0].max
+
+      dash = @fontsize / 4.0
+      dasharray = dashed ? "stroke-dasharray='#{dash} #{dash}' " : ""
+      markers = +""
+      markers << "marker-start='url(#arrowStart)' " if start_arrow
+      markers << "marker-end='url(#arrow)' " if end_arrow
+
+      # A round cap is half the stroke's width of ink past the point the stroke
+      # ends at, and an arrowhead has its tip at exactly that point — so the
+      # line came through the tip: 13% ink on the pixel beyond the head of a
+      # path, and 81% beyond its tail, where the marker's apex sits on the
+      # anchor rather than behind it. Squared off, the stroke stops where the
+      # head begins. Only where there is a head: a path without one is the
+      # dashed form, and every dash of it wants its round ends.
+      linecap = start_arrow || end_arrow ? "butt" : "round"
+
+      "<path d='#{rounded_polyline_d(points, radius)}' style='fill: none; stroke: #{col}; " \
+        "stroke-width:#{@global[:stroke_normal]}; stroke-linecap:#{linecap}; stroke-linejoin:round;' " \
+        "#{dasharray}#{markers}/>"
+    end
+
     def draw_a_path(s_x, s_y, t_x, t_y, target_arrow = :none)
       spacing = @global[:h_gap_between_nodes] * 1.25
       min_bulge = @global[:height_connector_to_text]
+      # Small enough that the turn reads as an eased corner rather than as an
+      # arc, and taken from a layout measure so it holds at every font size.
+      corner_radius = min_bulge / 2.0
 
       # Centered offset for multiple lines at the same endpoint
       s_key = "#{s_x.round}"
@@ -288,20 +368,11 @@ module RSyntaxTree
         new_s_y = s_y + s_offset
         new_t_y = t_y + t_offset
 
-        case target_arrow
-        when :single
-          @extra_lines << generate_line(s_x, new_s_y, new_x, new_s_y, @col_path, dashed)
-          @extra_lines << generate_line(new_x, new_s_y, new_x, new_t_y, @col_path, dashed)
-          @extra_lines << generate_line(new_x, new_t_y, t_x, new_t_y, @col_path, dashed, true)
-        when :double
-          @extra_lines << generate_line(new_x, new_s_y, s_x, new_s_y, @col_path, dashed, true)
-          @extra_lines << generate_line(new_x, new_s_y, new_x, new_t_y, @col_path, dashed)
-          @extra_lines << generate_line(new_x, new_t_y, t_x, new_t_y, @col_path, dashed, true)
-        else
-          @extra_lines << generate_line(s_x, new_s_y, new_x, new_s_y, @col_path, dashed)
-          @extra_lines << generate_line(new_x, new_s_y, new_x, new_t_y, @col_path, dashed)
-          @extra_lines << generate_line(new_x, new_t_y, t_x, new_t_y, @col_path, dashed)
-        end
+        @extra_lines << generate_path([[s_x, new_s_y], [new_x, new_s_y],
+                                       [new_x, new_t_y], [t_x, new_t_y]],
+                                      @col_path, dashed: dashed, radius: corner_radius,
+                                      start_arrow: target_arrow == :double,
+                                      end_arrow: target_arrow != :none)
         @width = new_x if new_x > @width
       else
         # TTB: route BELOW the tree (U shape)
@@ -315,20 +386,11 @@ module RSyntaxTree
         new_s_x = s_x - s_offset
         new_t_x = t_x - t_offset
 
-        case target_arrow
-        when :single
-          @extra_lines << generate_line(new_s_x, s_y, new_s_x, new_y, @col_path, dashed)
-          @extra_lines << generate_line(new_s_x, new_y, new_t_x, new_y, @col_path, dashed)
-          @extra_lines << generate_line(new_t_x, new_y, new_t_x, t_y, @col_path, dashed, true)
-        when :double
-          @extra_lines << generate_line(new_s_x, new_y, new_s_x, s_y, @col_path, dashed, true)
-          @extra_lines << generate_line(new_s_x, new_y, new_t_x, new_y, @col_path, dashed)
-          @extra_lines << generate_line(new_t_x, new_y, new_t_x, t_y, @col_path, dashed, true)
-        else
-          @extra_lines << generate_line(new_s_x, s_y, new_s_x, new_y, @col_path, dashed)
-          @extra_lines << generate_line(new_s_x, new_y, new_t_x, new_y, @col_path, dashed)
-          @extra_lines << generate_line(new_t_x, new_y, new_t_x, t_y, @col_path, dashed)
-        end
+        @extra_lines << generate_path([[new_s_x, s_y], [new_s_x, new_y],
+                                       [new_t_x, new_y], [new_t_x, t_y]],
+                                      @col_path, dashed: dashed, radius: corner_radius,
+                                      start_arrow: target_arrow == :double,
+                                      end_arrow: target_arrow != :none)
         @height = new_y if new_y > @height
       end
     end

data/lib/rsyntaxtree/utils.rb

@@ -28,14 +28,22 @@ SCRIPT_FAMILIES_SANS = ["Noto Sans Arabic", "Noto Sans Hebrew", "Noto Sans Devan
 # Arabic behind it for systems that ship one but not the other.
 SCRIPT_FAMILIES_SERIF = ["Noto Naskh Arabic", "Noto Sans Arabic", "Noto Serif Hebrew", "Noto Serif Devanagari", "Noto Serif Thai", "Noto Serif Khmer"].freeze
 
-# Monochrome emoji faces only. Colour emoji fonts carry their glyphs as bitmap
-# or COLR tables, which Pango happily measures but librsvg does not draw, so a
-# colour font in this list would give a figure whose emoji are blank or blobbed.
+# No emoji family is named in the chains below, and naming one was a mistake.
 #
-# This holds only where Pango resolves through fontconfig. On macOS it goes
-# through CoreText, which answers every emoji codepoint with Apple Color Emoji
-# whatever the chain asks for; emoji figures have to be generated elsewhere.
-EMOJI_FAMILIES = ["OpenMoji", "OpenMoji Color", "OpenMoji Black", "Noto Emoji"].freeze
+# Asking for an emoji face by name is asking fontconfig for it, and fontconfig
+# aliases the name to the generic `emoji` family, whose preference list it then
+# prepends to the whole pattern with a strong binding. The requested face
+# arrives at the head of the chain rather than at the tail, ahead of the Noto
+# text faces — and a colour emoji font carries ASCII digits, for the keycap
+# sequences. So on any machine with one installed, which is every ordinary
+# Linux desktop, `[N 20]` was set in the emoji face at more than twice the
+# width. Measurement and drawing read the same chain, so the figure held
+# together; it was simply not the figure the same input gives anywhere else.
+#
+# Emoji still draw. A codepoint no named family covers reaches fontconfig's own
+# fallback, which finds the emoji font — that is the path this list was
+# duplicating, and it was already the path taken wherever these families were
+# not installed.
 
 # Mathematical alphanumerics (U+1D400–) label heads such as the little v of vP.
 # Neither Noto Sans nor Noto Serif covers the block, so without these entries
@@ -49,15 +57,15 @@ MATH_FAMILIES_SANS = ["Noto Sans Math"].freeze
 MATH_FAMILIES_SERIF = ["DejaVu Serif", "Noto Sans Math"].freeze
 
 FONT_FAMILIES = {
-  sans:  (["Noto Sans", "Noto Sans JP", "Noto Sans CJK JP"] + SCRIPT_FAMILIES_SANS + MATH_FAMILIES_SANS + EMOJI_FAMILIES + ["sans-serif"]).freeze,
-  serif: (["Noto Serif", "Noto Serif JP", "Noto Serif CJK JP"] + SCRIPT_FAMILIES_SERIF + MATH_FAMILIES_SERIF + EMOJI_FAMILIES + ["serif"]).freeze,
+  sans:  (["Noto Sans", "Noto Sans JP", "Noto Sans CJK JP"] + SCRIPT_FAMILIES_SANS + MATH_FAMILIES_SANS + ["sans-serif"]).freeze,
+  serif: (["Noto Serif", "Noto Serif JP", "Noto Serif CJK JP"] + SCRIPT_FAMILIES_SERIF + MATH_FAMILIES_SERIF + ["serif"]).freeze,
   # Noto ships no monospaced faces for these scripts, so the mono style borrows
   # the proportional ones rather than dropping to the generic fallback.
-  mono:  (["Noto Sans Mono", "Noto Sans JP", "Noto Sans Mono CJK JP"] + SCRIPT_FAMILIES_SANS + MATH_FAMILIES_SANS + EMOJI_FAMILIES + ["monospace"]).freeze,
+  mono:  (["Noto Sans Mono", "Noto Sans JP", "Noto Sans Mono CJK JP"] + SCRIPT_FAMILIES_SANS + MATH_FAMILIES_SANS + ["monospace"]).freeze,
   # The cjk style puts a full-coverage CJK family first, for text that mixes
   # Han, Hangul and kana. Latin falls back to the same Noto faces the sans
   # style uses. (Before 1.8.0 this was WQY Zen Hei.)
-  cjk:   (["Noto Sans CJK JP", "Noto Sans", "Noto Sans JP"] + SCRIPT_FAMILIES_SANS + MATH_FAMILIES_SANS + EMOJI_FAMILIES + ["sans-serif"]).freeze
+  cjk:   (["Noto Sans CJK JP", "Noto Sans", "Noto Sans JP"] + SCRIPT_FAMILIES_SANS + MATH_FAMILIES_SANS + ["sans-serif"]).freeze
 }.freeze
 
 module FontFamily

data/lib/rsyntaxtree/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RSyntaxTree
-  VERSION = "1.13.1"
+  VERSION = "1.14.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rsyntaxtree
 version: !ruby/object:Gem::Version
-  version: 1.13.1
+  version: 1.14.0
 platform: ruby
 authors:
 - Yoichiro Hasebe