diff --git a/Help/markdown/vscode/TextbookLaunch.png b/Help/markdown/vscode/TextbookLaunch.png new file mode 100644 index 0000000..17ed1ac Binary files /dev/null and b/Help/markdown/vscode/TextbookLaunch.png differ diff --git a/Help/markdown/vscode/announcements/2026-06-29-textbook-launch.md b/Help/markdown/vscode/announcements/2026-06-29-textbook-launch.md new file mode 100644 index 0000000..b17783b --- /dev/null +++ b/Help/markdown/vscode/announcements/2026-06-29-textbook-launch.md @@ -0,0 +1,16 @@ +# 📢 Announcement — The NLP++ Textbook is Here + +[![The NLP++ Textbook](TextbookLaunch.png)](https://book.visualtext.org) + +**The first textbook on the NLP++ programming language is now available world-wide.** + +Written for programmers, it takes you from the basics to building real analyzers that parse +text and extract information **deterministically** — no training data, just rules you write +and can read, test, and ship. A strong, auditable alternative to an LLM in agentic flows. + +**Get your copy:** + +- 🛒 **Amazon** — [amazon.visualtext.org](https://amazon.visualtext.org) +- 🛒 **BPB Online** — [book.visualtext.org](https://book.visualtext.org) + +_See more on the [Help home](../home.md)._ diff --git a/Help/markdown/vscode/announcements/TextbookLaunch.png b/Help/markdown/vscode/announcements/TextbookLaunch.png new file mode 100644 index 0000000..17ed1ac Binary files /dev/null and b/Help/markdown/vscode/announcements/TextbookLaunch.png differ diff --git a/Help/markdown/vscode/home.md b/Help/markdown/vscode/home.md index 1993367..bcf8df6 100644 --- a/Help/markdown/vscode/home.md +++ b/Help/markdown/vscode/home.md @@ -6,9 +6,32 @@ Welcome to the **NLP++ Language Extension** for Visual Studio Code. This page is hub for the extension's help. Pick a topic below, or open any of these any time from the **Help** view in the NLP++ sidebar or the 📖 book button on the view toolbars. +--- + +# 📘 Now Available — The NLP++ Textbook + +[![The NLP++ Textbook](TextbookLaunch.png)](https://book.visualtext.org) + +**The first textbook on the NLP++ programming language is here — available world-wide.** +Written for programmers, it takes you from these help pages to real fluency: how the +language works, and how to build analyzers that parse text and extract information +**deterministically**. + +NLP++ needs **no training data** — you write the rules and the analyzer behaves predictably +every time. That makes it a strong, auditable alternative to an LLM in **agentic flows**: +the logic is human-written code you can read, [test](testing.md), and ship. + +### 🛒 Get your copy + +- **Amazon** — [amazon.visualtext.org](https://amazon.visualtext.org) +- **BPB Online** — [book.visualtext.org](https://book.visualtext.org) + +--- + ## Getting started - **[Quick Start](quickstart.md)** — install the engine, create or open an analyzer, and run it over text. +- **Create Claude Prompt** — let Claude help you build a prototype analyzer. Click **Create Claude Prompt** in the Help view (or the 💬 button on the Analyzers toolbar) to open a ready-to-paste prompt with your machine's engine and analyzer paths already filled in. - **[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. - **[Lazy Loading](lazyload.md)** — keep startup fast and memory low by loading knowledge-base data only when it's needed. @@ -25,4 +48,3 @@ opens automatically the first time you run that version. - **[Master Help Index](../index.md)** — the full VisualText / NLP++ help table of contents. - **[NLP++ Functions](../NLP_PP_Stuff/Functions.md)** and **[NLP++ Variables](../NLP_PP_Stuff/About_NLP++_Variables.md)**. -- 📘 **[The NLP++ Textbook](../NLP++_Textbook.md)**. diff --git a/README.md b/README.md index 82adbad..96d5e68 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,41 @@ See [`analyzers/README.md`](analyzers/README.md) for the conventions a submitted Source content for VisualText's offline help system, including a precompiled `Help.chm` and the underlying `helps/` directory of HTML pages. Each NLP++ function, pattern variable, and special symbol has a corresponding `.htm` file (e.g. `$start.htm`, `@@RULES.htm`, `RECURSE.htm`) that the extension opens when a user invokes "Lookup Word" on an NLP++ token. +The markdown help system lives under [`Help/markdown/`](Help/markdown/), and the VSCode-specific help pages are under [`Help/markdown/vscode/`](Help/markdown/vscode/) (see below). + +## VS Code Help, Version Notes & Announcements (`Help/markdown/vscode/`) + +The NLP++ VSCode extension shows a **Help** view (and a 📖 book button) backed by the markdown under [`Help/markdown/vscode/`](Help/markdown/vscode/). Pages render in VS Code's markdown preview, so **keep any image in the same folder as the page that references it** — parent-folder paths like `../logo.png` are blocked by the preview's security policy. + +| File | Shown as | +| ---- | -------- | +| `home.md` | the Help hub (logo, links, featured content) | +| `quickstart.md`, `compiling.md`, `testing.md`, `lazyload.md` | the guide pages | +| `versions/.md` | **version notes** (see below) | +| `announcements/.md` | **announcements** (see below) | + +### Version notes — `versions/.md` + +A version note is a "what's new" page tied to the **extension version**. Create one **only for a release significant enough that users should see it**, named after the version — e.g. `versions/3.2.0.md`. + +- On a **first install**, the extension opens `home.md`. +- On an **upgrade**, it opens the **newest version note the user hasn't seen yet** whose version is greater than the last-seen version and ≤ the installed version — once. The last-seen version is remembered per user. +- All version notes are also listed on `home.md` and in the Help view's **Version Notes** node. + +Because they are keyed to the extension version, a version note only appears when users **update the extension** to (at least) that version. + +### Announcements — `announcements/.md` + +An announcement is a broadcast that is **independent of the extension version**. Drop a new file in `announcements/` and it shows **once, on the user's next relogin** — even if the extension version hasn't changed (e.g. delivered through a normal VisualText-files content update). + +- Keyed by **id** (the file name without `.md`), **not** version. Seen ids are remembered per user, so each announcement shows at most once. +- **Name files so they sort newest-first** — a date prefix works well, e.g. `announcements/2026-06-29-textbook-launch.md`. The extension shows the newest unseen one. +- Keep any image **inside the `announcements/` folder** and reference it by plain file name. +- On a given startup the extension shows **at most one** popup: a pending version note takes priority over an announcement. +- Announcements are listed in the Help view's **Announcements** node, and the **Show Latest Announcement** (📣) button opens the newest one on demand. + +> Version notes and announcements reach users only after this repo is **released** (so the files ship inside `visualtext.zip`). See [Releases](#releases). + ## spec/ Reusable libraries of NLP++ passes that an analyzer can pull into its sequence rather than re-implementing common patterns.