diff --git a/Help/markdown/vscode/announcements/2026-07-26-parse-tree-graphic.md b/Help/markdown/vscode/announcements/2026-07-26-parse-tree-graphic.md new file mode 100644 index 0000000..3ced5a4 --- /dev/null +++ b/Help/markdown/vscode/announcements/2026-07-26-parse-tree-graphic.md @@ -0,0 +1,88 @@ +# 📢 Announcement — See Your Parse Tree + +![NLP++ parse-tree graphic](ParseTreeGraphic.png) + +**Every `.tree` file your analyzer writes can now be drawn as a classic linguistic tree +diagram** — right inside VS Code, beside the text file it came from. + +NLP++ has always given you the parse tree as text: one indented line per node, with its +span and type. That's precise, and it's still there. But a tree is a *picture*, and now you +can see it as one — phrases branching over their words, exactly the way a linguist would +draw it on a whiteboard. + +--- + +## Opening the graphic + +From any `.tree` file: + +- 🌲 **The tree button** in the editor title bar — draws the whole tree. +- 🖱️ **Right-click → Graph Entire Tree** — the same thing, from the context menu. +- 🖱️ **Right-click → Graph Selected Portion of Tree** — draws just the **selected lines**, + or, with nothing selected, the **subtree under your cursor**. Perfect for looking at one + noun phrase in a 400-node tree. + +The graphic is strictly on-demand: opening a `.tree` file never draws anything on its own, +so tree files still open instantly. And it re-uses a single panel, so asking for another +tree replaces the one you're looking at instead of piling up tabs. + +--- + +## Getting around the tree + +The whole diagram is live. The hint bar along the bottom sums it up, but here it is in full: + +| Do this | Get this | +| --- | --- | +| **Scroll** | Zoom in and out | +| **Shift + scroll** | Squeeze or spread the horizontal spacing between nodes | +| **Drag** | Pan around the canvas | +| **Click a phrase node** | Open **one level** — just that node's children | +| **Click a word (leaf)** | **Reveal it in the text** — selects that word in the input file | +| **Right-click** | Menu (below) | + +Trees open with the root expanded and everything else closed, so you **drill down one node +at a time** rather than being hit with hundreds of tokens at once. Small trees (roughly 30 +nodes or fewer) open fully, and every tree is fit to the window when it opens. + +Labels don't collide, either: at **every level** of the tree, labels that would overlap are +staggered into the minimum number of extra rows needed — and they drop back onto a single +line as soon as they fit, or as soon as you spread the tree out with Shift + scroll. + +--- + +## The right-click menu + +Right-click anywhere in the graphic: + +- **Reveal Text** — on **any** node, word or phrase. Selects that node's whole span in the + analyzed text file. Right-click an `_np` and the entire noun phrase lights up. +- **Expand all below** / **Collapse all below** — open or close an entire subtree at once + (shown on nodes that have children). +- **Center all** — fit the whole tree back into the window. +- **Expand all** / **Collapse all** — open or close the entire tree. + +--- + +## The text `.tree` file still does everything it did + +The graphic is an *alternative* view, not a replacement. In the `.tree` file itself, put +your cursor on **any node line** and right-click: + +- **Highlight text** — selects that node's text in the input file and opens it beside the + tree. Works on any node, at any depth — click a phrase node and you highlight the whole + phrase; click a word and you highlight the word. +- **Display Rule Fired** — opens the pass that built the node and jumps straight to the rule + that fired (for nodes that came from a dictionary, it searches the dictionaries instead). +- **Generate @PATH** — writes the context `@PATH` for that node, ready to paste into a rule. +- **Open Pass File** — jumps to the pass that produced this tree. +- **Fold / Unfold** (all, or recursively) — collapse the text tree the same way you collapse + the graphic. + +Between the two views you get both halves of the picture: the graphic for *shape* — how the +parse actually came together — and the text file for *detail*, the spans, the rules, and the +paths you need when you sit down to write the next rule. + +**Read the full guide:** [Parse Trees](../parsetrees.md) + +_See more on the [Help home](../home.md)._ diff --git a/Help/markdown/vscode/announcements/ParseTreeGraphic.png b/Help/markdown/vscode/announcements/ParseTreeGraphic.png new file mode 100644 index 0000000..fbac579 Binary files /dev/null and b/Help/markdown/vscode/announcements/ParseTreeGraphic.png differ diff --git a/Help/markdown/vscode/home.md b/Help/markdown/vscode/home.md index 3c04a4b..856b905 100644 --- a/Help/markdown/vscode/home.md +++ b/Help/markdown/vscode/home.md @@ -32,6 +32,7 @@ the logic is human-written code you can read, [test](testing.md), and ship. - **[Quick Start](quickstart.md)** — install the engine, create or open an analyzer, and run it over text. - **Claude Prompts** — let Claude help you build a prototype analyzer. The Help view lists several ready-to-paste prompts, one per task; choose the one you need and it opens with your machine's engine and analyzer paths already filled in. Start with [**General pointers: Claude + NLP++**](prompts/00-general-pointers.md) for an overview of the library. +- **[Parse Trees](parsetrees.md)** — read the `.tree` files your passes produce, and draw any tree as a linguistic diagram you can zoom, drill into, and click back into the text. - **[Calling Analyzers from Python & Node.js](packages.md)** — drive an analyzer from your own code with the `NLPPlus` (PyPI) / `nlpplus` (npm) packages: pass data in, get results back. - **[Compiling Analyzers](compiling.md)** — turn an analyzer (and/or its knowledge base) into a fast compiled C++ library. - **[Regression Testing](testing.md)** — set up golden-file regression tests so you catch changes in your analyzer's output. diff --git a/Help/markdown/vscode/parsetrees.md b/Help/markdown/vscode/parsetrees.md new file mode 100644 index 0000000..f106332 --- /dev/null +++ b/Help/markdown/vscode/parsetrees.md @@ -0,0 +1,122 @@ +# Parse Trees + +Every pass of an NLP++ analyzer writes out the **parse tree** as it stood when that pass +finished. Those trees are how you see what your rules actually did — which phrases got +built, out of which words, by which rule. + +The extension gives you **two views of the same tree**: the `.tree` **text file**, which +carries all the detail, and the **parse-tree graphic**, which draws it as a classic +linguistic tree diagram. + +[← Back to Help home](home.md) + +![NLP++ parse-tree graphic](announcements/ParseTreeGraphic.png) + +## Where the trees are + +When you analyze a text file, the engine writes a log folder next to it — `MyText.txt_log/` +— containing one `.tree` file per pass (`ana001.tree`, `ana002.tree`, …) plus `final.tree` +for the finished parse. + +You can open them from the file tree, or: + +- **Analyzer Sequence view** → right-click a pass → **Open Tree file** — the tree as of that pass. +- **Display Final Tree** (`Ctrl+Shift+F` / `Cmd+Shift+F` in a pass file) — the finished parse. +- **Display Pass Tree** (`Ctrl+Shift+T` / `Cmd+Shift+T` in a pass file) — the tree for the pass you're editing. +- **View selected tree** — right-click a selection in a text file to see just that portion. + +## Reading the text tree + +A `.tree` file is an indented list. Indent depth is the hierarchy, and each line is a node: + +``` +_ROOT [0,1429,0,1429,0,0,node,un] + _paragraph [0,342,0,342,6,12,node,un] + _sentence [0,183,0,183,5,24,node,un, ("name" "sentence1")] + _city [0,10,0,10,8,13,node] + LOS [0,2,0,2,0,0,alpha] +``` + +The label comes first, then the bracketed fields: the node's **character span** in the +text (`start,end`), the same span in the unnormalized text, the **pass number** and +**rule line** that built it, and the node **type** (`node`, `alpha`, `white`, …). Any +attributes the node carries follow in parentheses. + +## What you can do from the text tree + +Put your cursor on **any node line** — a word or a phrase, at any depth — and right-click: + +- **Highlight text** — selects that node's span in the analyzed text file and opens it + beside the tree. On a phrase node you get the whole phrase; on a word, the word. +- **Display Rule Fired** — opens the pass that built the node and jumps straight to the + rule that fired. For nodes that came out of a dictionary, it searches the dictionaries + instead. +- **Generate @PATH** — writes the context `@PATH` for that node, ready to paste into a rule. +- **Open Pass File** — opens the pass this tree came from. +- **Fold All** (`Ctrl+Shift+F`) / **Unfold All** (`Ctrl+Shift+U`), and fold/unfold + recursively — collapse the tree text to the level you care about. + +## The parse-tree graphic + +From any `.tree` file: + +- 🌲 **The tree button** in the editor title bar — draws the whole tree. +- 🖱️ **Right-click → Graph Entire Tree** — the same, from the context menu. +- 🖱️ **Right-click → Graph Selected Portion of Tree** — draws just the **selected lines**, + or, with nothing selected, the **subtree under the cursor**. Use this to look at one + phrase inside a large tree. + +The graphic is **on-demand only**: opening a `.tree` file never draws anything by itself, +so tree files open instantly. It re-uses a single panel, so graphing another tree replaces +the one on screen rather than opening more tabs. + +### Getting around + +| Do this | Get this | +| --- | --- | +| **Scroll** | Zoom in and out | +| **Shift + scroll** | Squeeze or spread the horizontal spacing between nodes | +| **Drag** | Pan around the canvas | +| **Click a phrase node** | Open **one level** — just that node's children | +| **Click a word (leaf)** | Reveal it in the text — selects that word in the input file | +| **Right-click** | Menu (below) | + +A tree opens fit to the window with the **root expanded and everything else closed**, so +you drill down one node at a time instead of facing hundreds of tokens at once. Small +trees (roughly 30 nodes or fewer) open fully. + +Labels never pile up on each other: at every level, labels that would overlap are staggered +into the fewest extra rows needed, and they drop back onto one line as soon as they fit — +or as soon as you spread the tree out with Shift + scroll. + +### The right-click menu + +- **Reveal Text** — on **any** node, word or phrase. Selects that node's whole span in the + analyzed text file. Right-click an `_np` and the entire noun phrase lights up. +- **Expand all below** / **Collapse all below** — open or close a whole subtree at once + (offered on nodes that have children). +- **Center all** — fit the whole tree back into the window. +- **Expand all** / **Collapse all** — open or close the entire tree. + +Whitespace tokens and the pass banners at the top of the file are left out of the graphic, +so what you see is the linguistic structure. + +## Working with both views + +The two views answer different questions, and they're best used together: + +- **The graphic** shows you **shape** — how the parse came together, where a phrase + attached, what got left flat. +- **The text tree** shows you **detail** — the spans, the attributes, the pass and rule + that built each node, and the `@PATH` you need to write the next rule. + +A common loop: graph the tree, drill down until you find the node that's wrong, right-click +**Reveal Text** to confirm what it covers, then go back to the `.tree` file and use +**Display Rule Fired** on that same node to land on the rule that needs fixing. + +## See also + +- **[Quick Start](quickstart.md)** — create or open an analyzer and run it over text. +- **[Node / Parse Tree Functions](../Table_of_Parse_Tree_Functions.md)** — the NLP++ functions that read and change the tree from inside a rule. +- **[About Parse Trees](../VisualText_Basics/About_Parse_Trees.md)** — the concept behind the tree. +- **[Regression Testing](testing.md)** — lock in the output once the tree looks right.