rsyntaxtree 1.8.2 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 232efc991d608eb2af9ff19d6816d9f22f9bc4a1006506276507c1b8705f34ec
-  data.tar.gz: da8e1ab08b470d76d47809b89ae4fd5b7bf0ef7519847ef3bc7e2955814f5521
+  metadata.gz: 38f3abe8841c2097201c6120f900a0d9eb99fb8bea9c6dc8388ac38a8e0df2c7
+  data.tar.gz: d22ebd93a2a2ed135e4afcc21797f4f057a3b5d340fdfd265a7f5490ccc642fb
 SHA512:
-  metadata.gz: 5af80d2af48070f3733c21f19cb543da6a2f443b4e4e2fb4fa2f5a0760584cedcfac5e3b86067623f5f24ba63cfe3267e69692f5ddbc44b3c9fdf35f1de34ace
-  data.tar.gz: 3d391279ae3b669f87f6c62cfa6b2f44cb607a6f5c9d0adbfd37e147cd9a9d2a8c4f998a3e508c423886a4adfe56610e5041c838ffcd40d47f958e96b45d9d49
+  metadata.gz: b3c9dc57831246bdd189e92998ba8325606635669e4e63839509d84db3e21911d0eb928f615b2d2d0f5d9ed6e711c2fed3785d3f1453988deef333a5e513ec48
+  data.tar.gz: eea07050d7df010b52615c475d4681749420c7b16687169c9e5ae3de5fbc6683daf939b9c17795442ed2589ad08dfddd745ad41b6d169f5238f521eaab638d3b

data/CHANGELOG.md

@@ -1,5 +1,96 @@
 # Changelog
 
+## [1.10.0] - 2026-08
+
+A transitional release ahead of 2.0, which drops JPG/GIF output and the
+RMagick dependency.
+
+### Deprecated
+- JPG and GIF output: the CLI prints a warning to stderr when either is
+  requested, and the documentation marks both as deprecated. JPEG blurs
+  line art and GIF has no use case here — use PNG. Both formats are
+  removed in 2.0.
+
+### Changed
+- The library no longer loads RMagick at require time. SVG, PNG, PDF,
+  TikZ and LSIF work without ImageMagick installed; only a JPG or GIF
+  request needs RMagick, and a request without it reports the missing
+  dependency as a regular input error instead of a bare `LoadError`.
+
+### Fixed
+- `RSTError` mutated the message it was given, so raising one with a plain
+  string literal crashed inside the error class with a `FrozenError`. Every
+  file here carries `frozen_string_literal`, which made the working form the
+  unobvious one.
+
+## [1.9.0] - 2026-08
+
+### Added
+- `hyphen: literal`, which trades the two readings of a hyphen: a bare one is
+  a hyphen and `\-underlined\-` underlines. Feature names in HPSG and its
+  relatives are full of hyphens, and escaping each one is a poor trade for a
+  rule that work never uses.
+- A matrix nested in a label, written between `#(` and `#)`. The value of an
+  attribute can be another attribute-value matrix, to any depth, which is what
+  a feature path such as SYNSEM | LOCAL | CATEGORY | HEAD needs and what HPSG,
+  SBCG and LFG are written in. The nested matrix draws its own brackets and
+  lays out its own columns, and the rows after it clear its full height.
+- `\t` in a label cuts the line into cells. Every line is cut at the same
+  points and each column is drawn at the width of its widest cell, so the
+  parts line up down the label. Together with the bracket enclosure and the
+  horizontal rule this gives attribute-value matrices — the feature structures
+  of HPSG, SBCG and LFG — without spacing each row by hand, which is how the
+  gallery's HPSG example used to do it.
+- `color: gray`, a scheme that keeps node and leaf labels black and draws the
+  connectors, triangles and movement paths in grey. It is for diagrams whose
+  links outnumber their labels — an ontology, a network of constructions —
+  where a page of black lines buries the text. `grey` is accepted too.
+- Gallery examples for two more frameworks: LFG (an annotated c-structure and
+  the f-structure it maps to, after Kaplan & Bresnan 1982 and Bresnan 2001)
+  and DRT (a discourse representation structure, after Kamp 1981).
+- The example gallery scales each figure by its own width rather than by one
+  factor for all of them, so a small tree and a wide one are read at a similar
+  apparent size; a figure now fits its row instead of scrolling, loads lazily,
+  and carries an anchor of its own.
+
+### Changed
+- Every box and circle in a figure is drawn at one size and on one centre
+  line. The size used to come from the line's height, which left a box
+  standing a head taller than the numeral inside it, and each shape was
+  centred on its own glyph, so the box around `s` sat lower than the one
+  around `G`. A shape is now drawn at a fixed fraction of the font size,
+  centred on a capital, and grows only for content that will not fit. Every
+  figure with a boxed or circled label is redrawn.
+- The SVG's declared width and height agree with its viewBox. They did not,
+  so every figure was scaled down by a few percent and letterboxed inside
+  its own canvas.
+
+### Fixed
+- TikZ export dropped everything inside a nested matrix: a feature structure
+  came out as its outermost attribute names and nothing else. The export still
+  cannot draw the brackets, but it keeps what they hold. The documented list of
+  what TikZ does not carry now names column alignment, nested matrices and the
+  grey line scheme.
+- LSIF records which of the two readings of a hyphen the input was parsed
+  under. It records the input verbatim, and the same string means different
+  things under the two, so a reader could not re-parse it.
+- A line-type connection with only one end raised a NoMethodError from inside
+  the drawing instead of being reported as the input error it is.
+- A line-type connection between two nodes was anchored a full inter-node gap
+  outside each of them, so the link fell short of both boxes where the gap was
+  wide and reached inside them where it was narrow. It now runs between the
+  boxes' own edges, a quarter of a gap short of each. The double arrowhead
+  keeps the shape it had but is sized to the link, instead of one fixed size
+  that spilled over both boxes on a short link. The same anchors are used in
+  left-to-right layout, where a link between siblings had been drawn diagonally
+  from the movement-path anchors and now runs straight between the facing
+  edges.
+- Two nodes joined by a line-type connection are laid out far enough apart for
+  a full-size arrowhead between them. Where the layout had packed them closer
+  than the arrow is wide — the two leaves at the foot of the quicksort figure —
+  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
 
 ### Changed

data/CITATION.cff

@@ -11,8 +11,8 @@ repository-code: "https://github.com/yohasebe/rsyntaxtree"
 # Concept DOI: always resolves to the latest archived version on Zenodo
 doi: "10.5281/zenodo.21916150"
 license: MIT
-version: 1.8.2
-date-released: 2026-08-15
+version: 1.10.0
+date-released: 2026-08-19
 keywords:
   - linguistics
   - syntax tree

data/README.md

@@ -66,7 +66,7 @@ Connect nodes with lines or arrows:
 
 ### Multiple Output Formats
 
-Generate trees in PNG, SVG, PDF, JPG, GIF, or LSIF (JSON) format.
+Generate trees in PNG, SVG, PDF, or LSIF (JSON) format. (JPG and GIF are deprecated and will be removed in 2.0.)
 
 ## Web Interface
 
@@ -167,15 +167,16 @@ Usage:
 | Option | Description | Default |
 |--------|-------------|---------|
 | `-o, --outdir` | Output directory | `./` |
-| `-f, --format` | Output format: png, gif, jpg, pdf, svg, lsif | `png` |
+| `-f, --format` | Output format: png, svg, pdf, lsif, tikz (jpg and gif are deprecated) | `png` |
 | `-l, --leafstyle` | Leaf style: auto, triangle, bar, nothing | `auto` |
 | `-n, --fontstyle` | Font style: sans, serif, cjk, mono | `sans` |
 | `-s, --fontsize` | Font size: 8-26 | `16` |
-| `-c, --color` | Color mode: modern, traditional, off | `modern` |
+| `-c, --color` | Color mode: modern, traditional, gray (black text, grey lines), off | `modern` |
 | `-p, --polyline` | Polyline connectors: on, off | `off` |
 | `-d, --direction` | Tree layout direction: ttb, ltr | `ttb` |
 | `--tidy` | Layout scale: off, symmetric, low, medium, high | `off` |
 | `--hspacing` | Horizontal spacing factor, all layout modes (0.5-3.0) | `1.0` |
+| `--hyphen` | How a hyphen reads: markup (`-underline-`) or literal | `markup` |
 | `-m, --mirror` | Flip the tree horizontally (RTL convention): on, off | `off` |
 
 Run `rsyntaxtree -h` for the full list of options.

data/Rakefile

@@ -37,6 +37,11 @@ task :generate do
     require_relative "dev/generate_examples"
 end
 
+desc "Record the pixel size of each gallery figure for the examples page"
+task :figure_sizes do
+    ruby "dev/stamp_figure_sizes.rb"
+end
+
 desc "Docker image Build"
 task :docker_build do
     `docker build ./ -t rsyntaxtree_devel`
@@ -50,6 +55,12 @@ task :docker_generate do
     `cat #{docpath}/generate_examples.log`
 end
 
+# The examples page scales every figure by the size recorded here, so the
+# record has to be refreshed whenever the figures are.
+["generate", "docker_generate"].each do |name|
+    Rake::Task[name].enhance { Rake::Task["figure_sizes"].invoke }
+end
+
 # Add new task for macOS environment configuration
 
 desc "Configure Bundler build options for macOS"

data/bin/rsyntaxtree

@@ -18,7 +18,7 @@ CONFIG_VALIDATORS = {
   fontsize: ->(v) { v.is_a?(Integer) && v >= 8 && v <= 26 ? nil : "must be in the range of 8-26" },
   linewidth: ->(v) { v.is_a?(Integer) && v >= 1 && v <= 5 ? nil : "must be in the range of 1-5" },
   vheight: ->(v) { v.is_a?(Numeric) && v >= 0.5 && v <= 5.0 ? nil : "must be in the range of 0.5-5.0" },
-  color: ->(v) { /\A(modern|traditional|on|off|true|false)\z/ =~ v.to_s ? nil : "must be modern, traditional, or off" },
+  color: ->(v) { /\A(modern|traditional|gray|grey|on|off|true|false)\z/ =~ v.to_s ? nil : "must be modern, traditional, gray, or off" },
   symmetrize: ->(v) { /\A(on|off|true|false)\z/ =~ v.to_s ? nil : "must be on or off" },
   transparent: ->(v) { /\A(on|off|true|false)\z/ =~ v.to_s ? nil : "must be on or off" },
   polyline: ->(v) { /\A(on|off|true|false)\z/ =~ v.to_s ? nil : "must be on or off" },
@@ -27,7 +27,8 @@ CONFIG_VALIDATORS = {
   tidy: ->(v) { /\A(off|symmetric|low|medium|high|on|compact|true|false)\z/ =~ v.to_s ? nil : "must be off, symmetric, low, medium, or high" },
   hspacing: ->(v) { v.is_a?(Numeric) && v >= 0.5 && v <= 3.0 ? nil : "must be in the range of 0.5-3.0" },
   tidy_spacing: ->(v) { v.is_a?(Numeric) && v >= 0.5 && v <= 3.0 ? nil : "must be in the range of 0.5-3.0" },
-  direction: ->(v) { /\A(ttb|ltr)\z/ =~ v.to_s ? nil : "must be ttb or ltr" }
+  direction: ->(v) { /\A(ttb|ltr)\z/ =~ v.to_s ? nil : "must be ttb or ltr" },
+  hyphen: ->(v) { /\A(markup|literal)\z/ =~ v.to_s ? nil : "must be markup or literal" }
 }.freeze
 
 # Validate configuration and return errors/warnings
@@ -107,7 +108,7 @@ opts = Optimist.options do
   opt :fontsize, "Size: 8-26", default: 16, short: :s
   opt :linewidth, "Size: 1-5", default: 1, short: :i
   opt :vheight, "Connector Height: 0.5-5.0", default: 2.0, short: :v
-  opt :color, "Color text and bars: modern, traditional, or off", default: "modern", short: :c
+  opt :color, "Color text and bars: modern, traditional, gray, or off", default: "modern", short: :c
   opt :symmetrize, "DEPRECATED alias of --tidy symmetric: on or off", default: "off", short: :y
   opt :transparent, "Make background transparent: on or off", default: "off", short: :r
   opt :polyline, "draw polyline connectors: on or off", default: "off", short: :p
@@ -117,17 +118,19 @@ opts = Optimist.options do
   opt :hspacing, "Horizontal spacing factor (counterpart of vheight): 0.5-3.0", default: 1.0, short: :none
   opt :tidy_spacing, "DEPRECATED alias of --hspacing: 0.5-3.0", default: 1.0, short: :none
   opt :direction, "Tree layout direction: ttb (top-to-bottom) or ltr (left-to-right)", default: "ttb", short: :d
+  opt :hyphen, "How a hyphen in a label reads: markup (-underline-) or literal (a hyphen; \-underline\- then underlines)", default: "markup", short: :none
   opt :help, "This is a custom help message", short: :h
 end
 
 Optimist.die :outdir, "must be an exsting directory path" unless FileTest.directory?(opts[:outdir])
 Optimist.die :direction, "must be ttb or ltr" unless /\A(ttb|ltr)\z/ =~ opts[:direction]
+Optimist.die :hyphen, "must be markup or literal" unless /\A(markup|literal)\z/ =~ opts[:hyphen]
 Optimist.die :format, "must be png, pdf, svg, or lsif" unless /\A(png|jpg|gif|pdf|svg|lsif)\z/ =~ opts[:format]
 Optimist.die :leafstyle, "must be auto, triangle, bar, or nothing" unless /\A(auto|triangle|bar|nothing)\z/ =~ opts[:leafstyle]
 Optimist.die :fontstyle, "must be sans, serif, cjk, or mono" unless /\A(sans|serif|cjk|mono)\z/ =~ opts[:fontstyle]
 Optimist.die :fontsize, "must be in the range of 8-26" unless opts[:fontsize] >= 8 && opts[:fontsize] <= 26
 Optimist.die :linewidth, "must be in the range of 1-5" unless opts[:linewidth] >= 1 && opts[:linewidth] <= 5
-Optimist.die :color, "must be either modern, traditional, or off" unless /\A(modern|traditional|on|off|true|false)\z/ =~ opts[:color]
+Optimist.die :color, "must be either modern, traditional, gray, or off" unless /\A(modern|traditional|gray|grey|on|off|true|false)\z/ =~ opts[:color]
 Optimist.die :symmetrize, "must be either on or off" unless /\A(on|off|true|false)\z/ =~ opts[:symmetrize]
 Optimist.die :vheight, "must be in the range of 0.5-5.0" if opts[:vheight] < 0.5 || opts[:vheight] > 5.0
 Optimist.die :transparent, "must be either on or off" unless /\A(on|off|true|false)\z/ =~ opts[:transparent]
@@ -157,6 +160,10 @@ opts.each do |key, value|
   end
 end
 
+if %w[jpg gif].include?(string_opts[:format])
+  warn "Warning: #{string_opts[:format].upcase} output is deprecated and will be removed in RSyntaxTree 2.0. Use PNG instead."
+end
+
 data = if ARGV[0] && File.exist?(File.expand_path(ARGV[0]))
          File.read ARGV[0]
        elsif ARGV[0]

data/lib/rsyntaxtree/base_graph.rb

@@ -35,6 +35,17 @@ module RSyntaxTree
         @col_path = "purple"
         @col_extra = "purple"
         @col_emph = "red"
+      # Text stays black; the lines that hold the diagram together are drawn
+      # lighter. A figure whose links outnumber its labels — an ontology, a
+      # construction network — reads as a black thicket in the monochrome
+      # scheme, and grey scaffolding lets the labels come forward again.
+      when "gray"
+        @col_node = "black"
+        @col_leaf = "black"
+        @col_path = "#666666"
+        @col_extra = "#666666"
+        @col_emph = "black"
+        @col_connector = "#666666"
       else
         @col_node  = "black"
         @col_leaf  = "black"
@@ -44,11 +55,12 @@ module RSyntaxTree
 
       @col_bg   = "none"
       @col_fg   = "black"
+      @col_connector ||= "black"
 
       @col_line = if params[:hide_default_connectors] == true
                     "none"
                   else
-                    "black"
+                    @col_connector
                   end
 
       @leafstyle = params[:leafstyle]
@@ -595,6 +607,152 @@ module RSyntaxTree
       @element_list.get_elements.each { |e| e.horizontal_indent += offset }
     end
 
+    # --- Line-type connections: room for the arrow ---
+
+    # The clearance a horizontally linked pair of boxes needs, in units of
+    # h_gap_between_nodes. SvgGraph#bothways_arrows draws the two heads at a
+    # span of 3 gaps whenever the link is long enough, shrinking only when it
+    # is not (span = link length × 0.8 then). The full span therefore wants a
+    # link of 3 / 0.8 gaps, and the link itself stops a 0.25-gap margin short
+    # of each box. Layout side of the same contract: spread the pair so the
+    # full-size arrow fits, and let the clamp cover what cannot be spread.
+    LINK_ARROW_CLEARANCE = 3.0 / 0.8 + 0.25 * 2
+
+    # Pairs of elements joined by a line-type connection (path entries of the
+    # -N / ->N / -<N form), mirroring the pool in SvgGraph#draw_paths.
+    def link_connection_pairs
+      pool = {}
+      @element_list.get_elements.each do |e|
+        e.path.each do |tr|
+          next unless /\A-(>|<)?(\d+)\z/ =~ tr
+
+          (pool[$2] ||= []) << e
+        end
+      end
+      pool.values.select { |ends| ends.size == 2 }
+    end
+
+    # Ids of the strict ancestors of +element+ (not including the element
+    # itself): the nodes that must stay put while a linked pair is spread,
+    # so they can be re-centred over their children afterwards.
+    def ancestor_ids(element)
+      ids = []
+      current = element
+      until current.parent.to_i.zero?
+        current = @element_list.get_id(current.parent)
+        ids << current.id
+      end
+      ids
+    end
+
+    # For every parent with an odd number of children, the offset of the
+    # middle child's centre from the centre of the children's span. In a
+    # balanced tree that offset is zero and the parent's edge to the middle
+    # child is vertical. The spread below moves the right side of a linked
+    # pair rightward, so re-centring the parents afterwards puts the span
+    # centre — and the parent — off the middle child. Recorded before the
+    # spread so the pass can hand the alignment back; see
+    # restore_middle_child_alignment.
+    def middle_child_alignment
+      @element_list.get_elements
+                   .reject { |e| e.children.empty? || e.children.size.even? }
+                   .to_h do |p|
+        kids = p.children.map { |c| @element_list.get_id(c) }
+        centers = kids.map { |k| k.horizontal_indent + k.content_width / 2.0 }
+        mid = kids[kids.size / 2]
+        [p.id, (mid.horizontal_indent + mid.content_width / 2.0) - (centers.min + centers.max) / 2.0]
+      end
+    end
+
+    # Undo whatever the spread did to the middle-child alignment of every
+    # odd-child parent, deepest first. The drift is cancelled by shifting
+    # the whole side the drift points away from: when the span centre ran
+    # right of the middle child, everything right of the middle child's
+    # subtree moves right by twice the drift (moving the span centre back
+    # by exactly the drift). The side moves rigidly, so no gap inside it
+    # changes, and the gap across the middle only widens — no overlaps.
+    def restore_middle_child_alignment(before)
+      parents = @element_list.get_elements
+                             .reject { |e| e.children.empty? || e.children.size.even? }
+      parents.sort_by { |p| -p.level }.each do |p|
+        kids = p.children.map { |c| @element_list.get_id(c) }
+        mid = kids[kids.size / 2]
+        centers = kids.map { |k| k.horizontal_indent + k.content_width / 2.0 }
+        dx = (mid.horizontal_indent + mid.content_width / 2.0) - (centers.min + centers.max) / 2.0
+        drift = dx - before[p.id]
+        next if drift.abs < 0.01
+
+        if drift.positive?
+          split = get_rightmost(mid.id)
+          @element_list.get_elements.each do |e|
+            e.horizontal_indent += drift * 2 if e.horizontal_indent >= split - 0.001
+          end
+        else
+          split = get_leftmost(mid.id)
+          @element_list.get_elements.each do |e|
+            e.horizontal_indent += drift * 2 if e.horizontal_indent + e.content_width <= split + 0.001
+          end
+        end
+        node_centering
+      end
+    end
+
+    # Push linked pairs apart until the gap between their boxes holds a
+    # full-size arrow. Runs after the tidy passes: a compression pass would
+    # simply undo any room reserved in the width calculation, while shifting
+    # the right-hand side rightward here can never create an overlap, so
+    # tidy's guarantee survives. Only links drawn horizontally need room —
+    # the two y ranges must overlap, the same test draw_paths applies. The
+    # pair's own ancestors stay put and are re-centred over their children
+    # afterwards; everything else right of the split moves by the deficit.
+    # LTR is excluded: its sibling links are vertical, and sizing them to the
+    # same span would stretch every stacked pair far beyond what the compact
+    # stacking justifies — the clamp covers those.
+    def spread_linked_pairs
+      return if @direction == "ltr"
+
+      pairs = link_connection_pairs
+      return if pairs.empty?
+
+      hct = @global[:height_connector_to_text]
+      required = @global[:h_gap_between_nodes] * LINK_ARROW_CLEARANCE
+      alignment_before = middle_child_alignment
+      spread = false
+      pairs.map { |a, b| [a, b].sort_by(&:horizontal_indent) }
+           .sort_by { |a, _b| a.horizontal_indent }
+           .each do |a, b|
+        a_top = a.vertical_indent + hct / 2
+        b_top = b.vertical_indent + hct / 2
+        a_bottom = a.vertical_indent + a.content_height + hct
+        b_bottom = b.vertical_indent + b.content_height + hct
+        next if a_top > b_bottom || b_top > a_bottom
+
+        gap = b.horizontal_indent - (a.horizontal_indent + a.content_width)
+        deficit = required - gap
+        next if deficit <= 0.01
+
+        ancestors = ancestor_ids(a) + ancestor_ids(b)
+        split = a.horizontal_indent + a.content_width
+        @element_list.get_elements.each do |e|
+          e.horizontal_indent += deficit if e.horizontal_indent >= split - 0.001 && !ancestors.include?(e.id)
+        end
+        spread = true
+      end
+      # A figure whose links already had their room is left exactly as tidy
+      # left it: re-centring it would move nothing but the last decimal.
+      return unless spread
+
+      node_centering
+      # The spread pushed the right side of each linked pair rightward, which
+      # pulls an odd-child parent's span centre off its middle child (the
+      # middle edge slants). Give the alignment back before settling.
+      restore_middle_child_alignment(alignment_before)
+      normalize_horizontal
+      # The dynamic connector height couples level spacing to the horizontal
+      # spread, so let it settle against the widened layout.
+      calculate_height
+    end
+
     # Snapshot / restore of everything the tidy passes mutate.
     def layout_snapshot
       @element_list.get_elements.map { |e| [e.horizontal_indent, e.vertical_indent, e.height] }
@@ -724,6 +882,15 @@ module RSyntaxTree
         restore_layout(snapshot) if layout_overlaps?
       end
 
+      # Give line-linked pairs room for a full-size arrow (no-op without
+      # links). Guarded the same way tidy is: if spreading ever produced an
+      # overlap, roll back and let the arrow clamp instead.
+      if @element_list.elements.size > 1
+        snapshot = layout_snapshot
+        spread_linked_pairs
+        restore_layout(snapshot) if layout_overlaps?
+      end
+
       # Phase 2: swap axes and restore content dimensions for LTR
       finalize_ltr if @direction == "ltr"