rsyntaxtree 1.11.0 → 1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6afa75eb042fe177454d387fa097c74fb6b44fd317ae709f91495f2f9b8df269
-  data.tar.gz: 60e201c577b1cf02d12f6506b10e62b1b21e419d6d37955e4a69a338b28bfd90
+  metadata.gz: 160b79f9047cb7674fe1c980dcf9e1a4044ca2c68eb3c758eabc9389d73d829a
+  data.tar.gz: 648c5297ccfbaefde5c2904cc5266ed56207487bc6ac64320041ac7e135e4814
 SHA512:
-  metadata.gz: 27d3c6eaf4e9d892238f41c7cce05bea11a639351069e80e130af6ad809916e89794dd41bbaf32b407c8560e49b8dc45c243fe7724d4aa36a3a1ce727dc61321
-  data.tar.gz: c3744c0b738859a27699dc444f9d27d3169b5d8ee91bd04be2d9296deca560050f9f7cce8db69b7cb980342ef94a1dd2f29e627030b04f7de990cb4adf0850f9
+  metadata.gz: 5465a152a7de5a453731cee9595f5d98636640fc8f97f7a21320e3ac66d14cf9876c10941518f936b586e0e6613944c2eb6e05175b6740a49aab544c97008e54
+  data.tar.gz: 78c83cee893a040d10959508199f354d3c568aa2a65fcba7bb486ddce6839314f6fcbd7d094c759804a77df07df660811508949ab7ffb9a9a7e81559e0e85b89

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [1.12.0] - 2026-08
+
+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.
+
+### Added
+- `--examples` prints every published example with the options it was drawn
+  with. The gallery examples are checked against the parser that draws them,
+  so each one is known to be accepted.
+- The site carries the same material as plain text for a reader that can fetch
+  a URL but cannot run a command: `llms.txt` and `llms-full.txt`, the second
+  holding the reference, the manual and every example in one file. Both are
+  generated from their sources, and a test fails if they fall behind.
+- A refusal names where the notation is written down, once, alongside the
+  cause and the fix. A hint repairs the mistake in front of it and says
+  nothing about the rest, which is not enough for a caller that was guessing.
+
+### Changed
+- The angle bracket the reference recommends is U+27E8 and U+27E9, which it
+  had always named while writing U+3008 and U+3009 in its own examples. The
+  East Asian pair draws a full em wide, wider than a capital, and had spread
+  through the gallery and into the repair that corrects ASCII brackets. Both
+  pairs still parse; documents written before this are unaffected.
+- Two feature-structure figures are redrawn at the narrower bracket.
+
+### Fixed
+- `--notation` and `--examples` answer before the input is read. Reading first
+  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
 
 Every input the tool accepts now draws, and every input it refuses says why.

data/Rakefile

@@ -42,6 +42,14 @@ task :generate do
     require_relative "dev/generate_examples"
 end
 
+# What a language model is given: the reference, the manual and every example,
+# built from the files those already live in. Run it after changing any of
+# them; llm_payload_test.rb fails if the built files are out of date.
+desc "Build the notation payload for language models (gem and site)"
+task :llm_payload do
+    ruby "dev/generate_llm_payload.rb"
+end
+
 desc "Record the pixel size of each gallery figure for the examples page"
 task :figure_sizes do
     ruby "dev/stamp_figure_sizes.rb"

data/bin/rsyntaxtree

@@ -126,6 +126,7 @@ opts = Optimist.options do
   opt :hyphen, "How a hyphen in a label reads: markup (-underline-) or literal (a hyphen; \-underline\- then underlines)", default: "markup", short: :none
   opt :validate, "Validate the input without drawing or writing a file: print a machine-readable diagnosis (JSON) to stdout and report the result in the exit code", short: :none
   opt :notation, "Print the notation reference to stdout and exit", short: :none
+  opt :examples, "Print every gallery example, with the options each needs, to stdout and exit", short: :none
   opt :help, "This is a custom help message", short: :h
 end
 
@@ -171,6 +172,21 @@ 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
 
+# These print and exit, so they answer before the input is read. Reading
+# first meant waiting on a pipe that never closes when stdin is not a
+# terminal, which is how they are reached from a script.
+if opts[:notation]
+  puts File.read(File.expand_path("../lib/rsyntaxtree/notation_core.md", __dir__))
+  exit 0
+end
+
+# The examples are the reference's counterpart: the rules in brief there, and
+# here every published tree with the options it was drawn with.
+if opts[:examples]
+  puts File.read(File.expand_path("../lib/rsyntaxtree/notation_examples.md", __dir__))
+  exit 0
+end
+
 # An argument names a file only if it really is one: File.exist? on an
 # expanded empty string answers for the current directory, and reading that
 # as the tree ended the run with a Ruby error.
@@ -187,11 +203,6 @@ data = if ARGV[0] && !ARGV[0].empty? && File.file?(File.expand_path(ARGV[0]))
 # Auto-convert Penn TreeBank format to bracket notation
 data = RSyntaxTree::FormatConverter.to_bracket(data) if data
 
-if opts[:notation]
-  puts File.read(File.expand_path("../lib/rsyntaxtree/notation_core.md", __dir__))
-  exit 0
-end
-
 # Validate without drawing or writing anything: the diagnosis goes to stdout
 # as JSON and the exit code carries the verdict.
 if opts[:validate]

data/lib/rsyntaxtree/element.rb

@@ -133,8 +133,8 @@ module RSyntaxTree
        ->(s) { s.sub(/\A%?@(?:#[0-9a-zA-Z]+|[a-zA-Z]+)?:/, "") },
        "A color is @name: with a CSS color name, or @#rgb: / @#rrggbb: with 3 or 6 hex digits (e.g. @blue:VP, @#3af:VP)."],
       [:angle_brackets,
-       ->(s) { s.gsub(/(?<!\\)<([^<>]*[^<>\d][^<>]*)>/) { "〈#{$1}〉" } },
-       "'<' and '>' mark whitespace here, not a list. Write the angle bracket characters themselves: 〈NP〉, 'hand〈SUBJ,OBJ〉'."],
+       ->(s) { s.gsub(/(?<!\\)<([^<>]*[^<>\d][^<>]*)>/) { "⟨#{$1}⟩" } },
+       "'<' and '>' mark whitespace here, not a list. Write the angle bracket characters themselves: ⟨NP⟩, 'hand⟨SUBJ,OBJ⟩'."],
       [:bare_hyphen,
        ->(s) { Element.escape_hyphens(s) },
        "A hyphen opens an underline. Escape it (e.g. f\\-structure, V\\-bar) or set the hyphen option to literal."],
@@ -175,7 +175,7 @@ module RSyntaxTree
       # away, one of them starting the split and the next ending it.
       if label.strip.empty?
         return details.merge(code: :label_split,
-                             hint: "Raw spaces left this label empty. Write a space inside a label as <> (e.g. 〈<>NP<>〉).",
+                             hint: "Raw spaces left this label empty. Write a space inside a label as <> (e.g. ⟨<>NP<>⟩).",
                              retryable: true)
       end
 
@@ -195,7 +195,7 @@ module RSyntaxTree
       # a hint that admits no one cause was found rather than naming a wrong
       # one. retryable: false is for what no rewriting reaches.
       details.merge(code: :invalid_markup,
-                    hint: "No single cause fits, which usually means more than one mistake in this label. Check that *, _, =, ~, |, { and #(...#) are paired, that hyphens are escaped, and that 〈 〉 are the angle bracket characters.",
+                    hint: "No single cause fits, which usually means more than one mistake in this label. Check that *, _, =, ~, |, { and #(...#) are paired, that hyphens are escaped, and that ⟨ ⟩ are the angle bracket characters.",
                     retryable: true)
     end
 

data/lib/rsyntaxtree/notation_core.md

@@ -16,10 +16,10 @@ Within a label:
 
 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〉'
+  `<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`.
@@ -35,14 +35,14 @@ An attribute-value matrix is columns plus an enclosure:
 
     [#*word*\
       HEAD\t*verb*\
-      SPR\t〈<>NP<>〉\
-      COMPS\t〈<>〉
+      SPR\t⟨<>NP<>⟩\
+      COMPS\t⟨<>⟩
     ]
 
 A value can be another matrix. Nest it with `#( ... #)`, never with square
 brackets — those are read as tree structure:
 
-    [#PRED\t'hand〈SUBJ,OBJ〉'\
+    [#PRED\t'hand⟨SUBJ,OBJ⟩'\
       TENSE\tpast\
       SUBJ\t#(PRED\t'David'#)
     ]