docs: replace term "Plugin Developer" with "Adopter" (#970)

Author: sebthom

README.md

@@ -142,9 +142,9 @@ TM4E is split into three main bundles plus an optional language pack feature:
 
 ## 🔌 Integrating TM4E
 
-If you are an Eclipse plug-in developer or Java tool author and want to consume TM4E:
+If you are an Eclipse plug-in developer or Java tool author and want to integrate TM4E in your own tools:
 
-- Start with the [Plugin Developer Guide](docs/plugin-developer-guide.md) for how to depend on TM4E, contribute grammars, themes, and language configurations, and wire TM4E into editors.
+- Start with the [Adopter Guide](docs/adopter-guide.md) for how to depend on TM4E, contribute grammars, themes, and language configurations, and wire TM4E into editors.
 - For integration questions, best practices, and design discussions, use [GitHub discussions](https://github.com/eclipse-tm4e/tm4e/discussions).
 - To report bugs or request new APIs or integration features, file issues in [GitHub issues](https://github.com/eclipse-tm4e/tm4e/issues).
 

docs/plugin-developer-guide.md docs/adopter-guide.mddocs/plugin-developer-guide.md renamed to docs/adopter-guide.md

@@ -1,6 +1,8 @@
-# TM4E Plugin Developer Guide
+# TM4E Adopter Guide
+
+This guide is for Eclipse plug-in and RCP application developers who want to integrate TM4E into Eclipse editors, and
+Java developers who want to use the TM4E core TextMate engine in their own applications outside Eclipse.
 
-This guide is for Eclipse plugin developers who want to add TextMate-based syntax highlighting and language configuration features to their editors.
 It explains the main TM4E concepts, how to contribute grammars and themes, how to connect editors to TM4E, and how to use the TM partitioner and language configuration support.
 
 
@@ -15,6 +17,7 @@ It explains the main TM4E concepts, how to contribute grammars and themes, how t
    1. [Using `TextEditor`](#using-texteditor)
    1. [Using the Generic Editor](#using-the-generic-editor)
 1. [Using the TM Partitioner from Code](#using-the-tm-partitioner-from-code)
+1. [Handling Conflicting Grammar Registrations](#handling-conflicting-grammar-registrations)
 1. [Diagnostics: Token and Scope Hover](#diagnostics-token-and-scope-hover)
 1. [Samples and Tools](#samples-and-tools)
 1. [Further Reading](#further-reading)
@@ -284,6 +287,45 @@ Convenience methods such as `TMPartitions.hasPartitioning(doc)` and `TMPartition
 Generic Editor extension points still refer to the editor's primary partitioning via their `partitionType` attribute; you always query TM4E's secondary partitioner from code instead of configuring it directly in the extension XML.
 
 
+## Handling Conflicting Grammar Registrations
+
+In real Eclipse installations it is common for several plug-ins (including the TM4E language pack) to register grammars for the same TextMate scope, or to provide overlapping grammars for a given file type.
+TM4E's registry is designed to handle this without forcing every plug-in to invent unique scope names.
+
+At a high level:
+
+- Grammars are always selected based on *content types* and their normal Eclipse priorities, not just on the bare scope name.
+- Internally, TM4E qualifies scopes with the contributing plug-in ID to disambiguate registrations, but external code and grammar authors can continue to use the shared, unqualified scope name.
+
+### 1) Which grammar wins for a file
+
+When an editor is opened, `TMPresentationReconciler` asks the registry for a grammar using the document's content types:
+
+- The content types are computed using the usual Eclipse mechanisms (file extension, content-type base types, and priority).
+- `GrammarRegistryManager` looks for a grammar that is explicitly bound to the highest priority content type via `scopeNameContentTypeBinding`.
+- If multiple plug-ins register a grammar for the same TextMate scope (for example `source.batchfile`), each plug-in typically also defines its own content type and binds that content type to the shared scope.
+
+From a plug-in author's perspective:
+
+- The content type that "wins" according to Eclipse content-type priority rules controls which plug-in's grammar is used for a given document.
+- If you want your grammar to take precedence for a specific file extension, define your own content type for that extension and bind it to your grammar scope via `scopeNameContentTypeBinding`.
+
+### 2) Referencing shared scopes from other grammars
+
+Grammars often embed other languages via shared scopes, for example an HTML grammar embedding JavaScript using `source.js`.
+When multiple plug-ins provide a grammar for the same embedded scope:
+
+- You can continue to reference the shared, unqualified scope (such as `source.js` or `text.html`) in your grammar.
+- TM4E resolves that shared scope to an internal, plug-in-specific variant based on the active registry state and the same content-type bindings described above.
+
+This means:
+
+- You do not need to create plug-in-specific scope names just to avoid collisions.
+- Embedded language references in your grammars remain stable even when users install additional plug-ins or language packs that also contribute grammars for those scopes.
+
+For a deeper, implementation-level description of how the registry qualifies scopes and resolves grammars (including a concrete `source.batchfile` example), see the *Handling Conflicting Grammar Registrations* section in the contributor guide (`docs/contributor-guide.md`).
+
+
 ## Diagnostics: Token and Scope Hover
 
 When debugging grammars, themes, or partitioning, it is often helpful to see exactly which TextMate token and scopes TM4E has computed at a given location in the editor.

docs/user-guide.md

@@ -68,7 +68,7 @@ For advanced users, some editors expose a TextMate token hover that shows the to
 
 ![TextMate Token Hover](img/tm_token_hover.png)
 
-For details on how to use the token hover and other diagnostics when developing plugins, see the [TM4E Plugin Developer Guide](plugin-developer-guide.md).
+For details on how to use the token hover and other diagnostics when developing plugins, see the [TM4E Adopter Guide](adopter-guide.md).
 
 
 ## Language Pack and Additional Grammars
@@ -87,7 +87,8 @@ Most user-facing configuration lives under the `TextMate` section in the Eclipse
 
 1. The main `TextMate` page provides an overview and general switches.
 1. `TextMate > Grammar` lets you manage available grammars and their associations to Eclipse content types (the way Eclipse classifies file types).
-   Here you can enable or disable grammars and control which grammar applies to a file type.\
+   Here you can enable or disable grammars and control which grammar applies to a file type.
+   For each selected grammar you can also inspect details, adjust the content types it applies to, configure grammar injections, and manage per-grammar theme associations using the built-in preview.\
    ![Grammar Preferences](img/grammar_preferences.png)
 
 1. `TextMate > Language Configuration` lets you control language-configuration based features and attach additional configuration files:
@@ -101,7 +102,7 @@ Most user-facing configuration lives under the `TextMate` section in the Eclipse
 1. `TextMate > Task Tags` lets you define tags in comments (such as `TODO` or `FIXME`) that should be treated as tasks or problems, and configure how they are marked in the workspace.\
    ![Task Tags Preferences](img/task_tags_preferences.png)
 
-1. `TextMate > Themes` lets you choose between built-in Light and Dark themes and any additional themes contributed by installed plugins.
+1. `TextMate > Themes` lets you choose between built-in Light and Dark themes and any additional themes contributed by installed plugins, as well as import extra theme files and set the default theme for light and dark modes.
    You can also switch themes from the editor's context menu under `TextMate`.\
    ![Themes Preferences](img/themes_preferences.png)
 
@@ -118,6 +119,7 @@ This is useful if a plugin does not already provide a configuration file for tha
 
 Themes are contributed by plugins and selected on the `TextMate > Themes` page.
 Built-in themes cover common Light and Dark appearances, while plugin-provided themes can add alternative color schemes.
+You can also use the `New...` button on that page to import additional TextMate theme files from disk and mark one as the default for Light or Dark mode.
 If you are interested in authoring themes or grammars yourself, see the Plugin Developer Guide for extension point and authoring details.
 
 
@@ -136,12 +138,12 @@ If you are interested in authoring themes or grammars yourself, see the Plugin D
   If the Generic Editor shows TM4E-based highlighting while a custom editor does not, the custom editor may not be wired to TM4E or may rely solely on its own partitioning or language server integration.
 
 - **Collecting diagnostics for bug reports**:
-  When you need to provide more technical information, enable extra tracing by adding `org.eclipse.tm4e.ui/trace=true` to a debug options file (usually named `debug.options`) and starting Eclipse with `-debug /path/to/debug.options`.
-  To capture text events and generate a Java test skeleton, add `org.eclipse.tm4e.ui/debug/log/GenerateTest=true` to the same file and close an editor that uses TM4E; the test skeleton is written to the error output stream.
+  To capture text events and generate a Java test skeleton, add `org.eclipse.tm4e.ui/debug/log/GenerateTest=true` to a debug options file (usually named `debug.options`) and start Eclipse with `-debug /path/to/debug.options`; the test skeleton is written to the error output stream when you close an editor that uses TM4E.
+  If you need TM4E to fail fast when no grammar is found for a document (for example when isolating a bug), you can additionally set `org.eclipse.tm4e.ui/debug/log/ThrowError=true`, which causes an exception to be thrown instead of silently disabling TM4E for that document.
 
 
 ## Further Reading
 
 For additional background on what TM4E provides in Eclipse and how it fits into the IDE, see the Eclipse newsletter article "TM4E" (June 2018): https://www.eclipse.org/community/eclipse_newsletter/2018/june/tm4e.php
 
-If you plan to implement your own TM4E-based editor or customize integration at the plugin level, switch to the [TM4E Plugin Developer Guide](plugin-developer-guide.md), which is targeted specifically at plugin authors.
+If you plan to implement your own TM4E-based editor or customize integration at the plugin level, switch to the [TM4E Adopter Guide](adopter-guide.md), which is targeted specifically at plugin adopters and plug-in authors.