codenameone · shai-almog · Apr 30, 2026 · Apr 30, 2026 · Apr 30, 2026
diff --git a/docs/developer-guide/.vale.ini b/docs/developer-guide/.vale.ini
@@ -1,6 +1,34 @@
 StylesPath = styles
 MinAlertLevel = suggestion
+Vocab = CodenameOne
 Packages = https://github.com/errata-ai/packages/releases/download/v0.2.0/Microsoft.zip, https://github.com/errata-ai/packages/releases/download/v0.2.0/proselint.zip, https://github.com/errata-ai/packages/releases/download/v0.2.0/write-good.zip
 
+# How to suppress vale on a specific line
+# ─────────────────────────────────────────────────────────────────────────────
+# Place an asciidoc comment of the form:
+#
+#     // vale-skip: <rule-name>: <reason for the exception>
+#     The next line of content that vale will ignore.
+#
+# Example:
+#
+#     // vale-skip: Microsoft.ComplexWords: 'Approximate' is the correct technical
+#     // term here; substituting 'about' loses precision.
+#     |Approximate fade duration is `durationMs ~= (255 / speed)`...
+#
+# Notes:
+# - The comment must appear on the line immediately preceding the content. It
+#   protects exactly the next non-empty line.
+# - Asciidoctor strips // comments from rendered HTML and PDF output, so the
+#   comment never appears to readers — only in the source as documentation.
+# - The TokenIgnores pattern below matches against asciidoc source, so it works
+#   inside paragraph text, table cells, list items, and admonition blocks.
+# - This skips ALL vale rules for the protected line. Specify the rule name
+#   and reason in the comment so future maintainers understand the exception.
+# - For longer/multi-line exceptions, place a // vale-skip comment before each
+#   line that needs protection.
+# ─────────────────────────────────────────────────────────────────────────────
+
 [*.{adoc,asciidoc}]
 BasedOnStyles = Microsoft, proselint, write-good
+TokenIgnores = (?s)// vale-skip:[^\n]*\n[^\n]+\n
diff --git a/docs/developer-guide/Advanced-Theming.asciidoc b/docs/developer-guide/Advanced-Theming.asciidoc
diff --git a/docs/developer-guide/Advanced-Topics-Under-The-Hood.asciidoc b/docs/developer-guide/Advanced-Topics-Under-The-Hood.asciidoc
diff --git a/docs/developer-guide/Animations.asciidoc b/docs/developer-guide/Animations.asciidoc
diff --git a/docs/developer-guide/Casual-Game-Programming.asciidoc b/docs/developer-guide/Casual-Game-Programming.asciidoc
diff --git a/docs/developer-guide/Events.asciidoc b/docs/developer-guide/Events.asciidoc
diff --git a/docs/developer-guide/Index.asciidoc b/docs/developer-guide/Index.asciidoc
diff --git a/docs/developer-guide/Maven-Appendix-API.adoc b/docs/developer-guide/Maven-Appendix-API.adoc
@@ -17,13 +17,13 @@ Codename One is much more than an API library. It provides a full tool-chain and
 No reflection::
 Codename One apps don't support reflection because reflection makes it impossible to keep app-size down.
 
-=== Kotlin API Support
+=== Kotlin API support
 
-Codename One apps support the https://kotlinlang.org/api/latest/jvm/stdlib/[Kotlin Standard Library]. Kotlin support is still relatively new, so are still discovering which libraries are compatible. APIs that rely on reflection won't be supported, but most other libraries should work.
+Codename One apps support the https://kotlinlang.org/api/latest/jvm/stdlib/[Kotlin Standard Library]. Kotlin support is still new, so are still discovering which libraries are compatible. APIs that rely on reflection won't be supported, but most other libraries should work.
 
-=== Add-on Libraries
+=== Add-on libraries
 
-Add-on libraries can be added to your library in the common/pom.xml file, however, if you use APIs that aren't supported by Codename One (e.g. which use reflection), then your app will fail to build.
+Add-on libraries can be added to your library in the common/pom.xml file, but, if you use APIs that aren't supported by Codename One (for example, which use reflection), then your app will fail to build.
 
 Codename One supports its own library format (cn1lib) which sort of "certifies" that it's compatible with Codename One. You can browse the growing catalog of available cn1libs inside <<settings,Codename One Settings>>.
 

diff --git a/docs/developer-guide/Maven-Appendix-Archetypes.adoc b/docs/developer-guide/Maven-Appendix-Archetypes.adoc
@@ -1,8 +1,8 @@
 [appendix]
-== Project Archetypes
+== Project archetypes
 
 [#cn1app-archetype]
-=== Codename One Application Project Archetype (cn1app-archetype)
+=== Codename One application project archetype (cn1app-archetype)
 
 The `cn1app-archetype` is the basis for all maven Codename One application projects. It provides a multimodule project with the following modules:
 
@@ -11,7 +11,7 @@ See https://shannah.github.io/cn1-maven-archetypes/cn1app-archetype-tutorial/get
 Also see <<cn1app-archetype-example>> for an example using this archetype from the command-line to create a bare-bones Java project.
 
 [#cn1lib-archetype]
-=== Codename One Library Project Archetype (cn1lib-archetype)
+=== Codename One library project archetype (cn1lib-archetype)
 
 The `cn1lib-archetype` provides a project for building Codename One libraries. See <<creating-cn1libs>> for details on using this archetype.
 

diff --git a/docs/developer-guide/Maven-Appendix-Control-Center.adoc b/docs/developer-guide/Maven-Appendix-Control-Center.adoc
@@ -1,13 +1,13 @@
 
 [appendix]
 [#settings]
-== Codename One Settings
+== Codename One settings
 
 The Codename One Settings app (aka Codename One Preferences, aka Control Center) allows you to configure many aspects of your application. This is where you can generate certificates, browse/install add-ons, monitor the status of your cloud builds, configure build hints, and more.
 
-=== Opening Codename One Settings
+=== Opening Codename One settings
 
-==== Opening Codename One Settings from Command-line
+==== Opening Codename One settings from command-line
 
 Use the `run.sh` (or run.bat, if on Windows) to open Codename One settings:
 
@@ -16,27 +16,27 @@ Use the `run.sh` (or run.bat, if on Windows) to open Codename One settings:
 ./run.sh settings
 ----
 
-==== Opening Codename One Settings from IntelliJ
+==== Opening Codename One settings from IntelliJ
 
 Click on the "Configuration" menu in the upper right of the toolbar, and select "Tools" > "Codename One Settings" as shown below.
 
 image::img/intellij-open-settings.png[]
 
 
-==== Opening Codename One Settings from NetBeans
+==== Opening Codename One settings from NetBeans
 
 Right-click on the project in the project inspector, and select "Maven" > "Open Control Center" as shown below:
 
 image::img/netbeans-open-control-center.png[]
 
-==== Opening Codename One Settings from Eclipse
+==== Opening Codename One settings from Eclipse
 
 Press the image:img/eclipse-run-as-button.png[] button, and select the "_My Project_ Settings" option. (Where _My Project_ is the name of your project). E.g.
 
 image:img/eclipse-open-settings.png[]
 
 [#dashboard]
-=== The Dashboard
+=== The dashboard
 
 Once inside Codename One Settings, you'll see a dashboard like the following:
 

diff --git a/docs/developer-guide/Maven-Appendix-Goals.adoc b/docs/developer-guide/Maven-Appendix-Goals.adoc
@@ -1,5 +1,5 @@
 [appendix]
-== Maven Goals
+== Maven goals
 
 include::appendix_goal_build.adoc[]
 

diff --git a/docs/developer-guide/Maven-Appendix-Rich-Properties.adoc b/docs/developer-guide/Maven-Appendix-Rich-Properties.adoc
@@ -1,6 +1,6 @@
 [#rich-properties-file]
 [appendix]
-== Rich Properties File (rpf) Format
+== Rich properties file (rpf) format
 
 The rich properties file (rpf) format is used to store configuration for the `generate-app-project` goal. The format is the same as a regular properties file except that it can more easily accommodate properties whose values are "rich" and lengthy.
 
@@ -18,7 +18,7 @@ Key value <3>
 <3> The property value, which can be one or more lines of content.
 <4> The separator with the same number of equals signs on a line of its own.
 
-=== Example Rich Properties File
+=== Example rich properties file
 
 [source,rpf]
 ----