Feature/7/test pr

-new-material-templates/plugin-documentation-templates/ROOT/examples/live-demos/full-featured/index.html

@@ -1,6 +1,5 @@
 <!--
 
-Add necessary material to this file to make it possible for the
-full-featured-with-premium-plugins demo to demonstrate the new plugin.
+Update tinymce-docs/modules/ROOT/examples/live-demos/full-featured/index.html to include the new plugin.
 
 -->

-new-material-templates/plugin-documentation-templates/ROOT/examples/live-demos/full-featured/index.js

@@ -1,6 +1,6 @@
 /*
 
-Add new plugin to this file’s extant configuration
+Update tinymce-docs/modules/ROOT/examples/live-demos/full-featured/index.js to include the new plugin.
 
 */
 

-new-material-templates/plugin-documentation-templates/ROOT/examples/live-demos/<plugincode>/example.js → -new-material-templates/plugin-documentation-templates/ROOT/examples/live-demos/{plugincode}/example.js

@@ -23,7 +23,7 @@ NB: there is one UX consequence of setting up demos to work in
 these cases. The *Edit on CodePen* tab does not — and cannot —
 present in the documentation.
 
-The initial setup of these ‘inclues-an-emulated-back-end’ examples
+The initial setup of these ‘includes-an-emulated-back-end’ examples
 will almost certainly include significant initial input from the
 plugin’s developer.
 

-new-material-templates/plugin-documentation-templates/ROOT/nav.adoc

@@ -1,13 +1,8 @@
 * xref:plugins.adoc[Plugins]
 ** Premium plugins
-// If the new plugin is a Premium plugin
-// Replace the boilerplate below with the file-name of the new Premium plugin.
-// Also, place this new Premium plugin into alphabetical place within the Premium plugin sub-section.
-*** xref:<plugincode>.adoc[<pluginname>]
-** Open source plugins
-// If the new plugin is an open source plugin
-// Replace the boilerplate below with the file-name of the new open source plugin.
-// Also, place this new open source plugin into alphabetical place within the open source plugin sub-section.
-*** xref:<plugincode>.adoc[<pluginname>]
+// If Premium plugin, place the following entry into Premium plugins list in alphabetical order by plugin name.
+*** xref:<plugincode>.adoc[<Plugin name>]
 
-// This file is instructional and is never included in the published name-space.
+** Open source plugins
+// If Open source plugin, place the following entry into Open source plugins list in alphabetical order by plugin name.
+*** xref:<plugincode>.adoc[<Plugin name>]

-new-material-templates/plugin-documentation-templates/ROOT/pages/available-menu-items.adoc

@@ -1,13 +1,6 @@
-// 0. Set :plugincategory: to appropriate value
-//    1. premium; or
-//    2. opensource.
-//      Note neither value is capitalised.
-//      Note the second value has no space between the two words.
-// 1. Replace <place-holder text> instances with appropriate material.
-// 2. Add the edited material to
-//    /tinymce-docs/modules/ROOT/pages/available-menu-items.adoc
-//    in alphabetical order by <Plugin name>. (*not* <plugincode>).
-// 3. Do not bring these comments over with the edited material.
+// Add the edited material to
+// tinymce-docs/modules/ROOT/pages/available-menu-items.adoc
+// in alphabetical order by <Plugin name>. (*not* <plugincode>).
 
 :plugincategory: <premium|opensource>
 :pluginname: <Plugin name>

-new-material-templates/plugin-documentation-templates/ROOT/pages/available-toolbar-buttons.adoc

@@ -1,13 +1,6 @@
-// 0. Set :plugincategory: to appropriate value
-//    1. premium; or
-//    2. opensource.
-//      Note neither value is capitalised.
-//      Note the second value has no space between the two words.
-// 1. Replace <place-holder text> instances with appropriate material.
-// 2. Add the edited material to
-//    /tinymce-docs/modules/ROOT/pages/available-toolbar-buttons.adoc
-//    in alphabetical order by <Plugin name>. (*not* <plugincode>).
-// 3. Do not bring these comments over with the edited material.
+// Add the edited material to
+// tinymce-docs/modules/ROOT/pages/available-toolbar-buttons.adoc
+// in alphabetical order by <Plugin name>. (*not* <plugincode>).
 
 :plugincategory: <premium|opensource>
 :pluginname: <Plugin name>

-new-material-templates/plugin-documentation-templates/ROOT/pages/editor-command-identifiers.adoc

@@ -1,16 +1,14 @@
-// 0. Replace <place-holder text> instances with appropriate material.
-// 1. Add the edited material to
-//    /tinymce-docs/modules/ROOT/pages/editor-command-identifiers.adoc
-//    in alphabetical order by <Plugin name>. (*not* <plugincode>).
-// 2. Do not bring these comments over with the edited material.
+// Add the edited material to
+// tinymce-docs/modules/ROOT/pages/editor-command-identifiers.adoc
+// in alphabetical order by <Plugin name>. (*not* <plugincode>).
 
-// add an xref in alphabetical order to the summary list that is below the following lines:
+// add an xref in alphabetical order by <Plugin name> to the summary list that is below the following lines:
 // [[plugin-commands]]
 // === Plugin Commands
 
 * xref:<plugincode>[<Plugin name>]
 
-// add the include in alphabetical order to the body of the "Plugin Commands" section
+// add the include in alphabetical order by <Plugin name> to the body of the "Plugin Commands" section
 
 [[<plugincode>]]
 ==== <Plugin name>

-new-material-templates/plugin-documentation-templates/ROOT/pages/events.adoc

@@ -1,15 +1,13 @@
-// 0. Replace <place-holder text> instances with appropriate material.
-// 1. Add the edited material to
-//    /tinymce-docs/modules/ROOT/pages/events.adoc
-//    in alphabetical order by <Plugin name>. (*not* <plugincode>).
-// 2. Do not bring these comments over with the edited material.
+// Add the edited material to
+// tinymce-docs/modules/ROOT/pages/events.adoc
+// in alphabetical order by <Plugin name>. (*not* <plugincode>).
 
 // add the xref in alphabetical order to the summary list that is below the following line:
 // == Plugin events
 
 * xref:<plugincode>-events[<Plugin name> events]
 
-// add the include in alphabetical order to the body of the "Plugin events" section
+// add the include in alphabetical order by <Plugin name> to the body of the "Plugin events" section
 
 [[<plugincode>-events]]
 === <Plugin name> events

-new-material-templates/plugin-documentation-templates/ROOT/pages/pluginpage.adoc

@@ -1,6 +1,3 @@
-// Replace <place-holder text> instances with material then remove this, and other comments.
-
-// <Plugin name>: the product name. Reference on this page with the {pluginname} variable.
 = <Plugin name> plugin
 :navtitle: <Plugin name>
 :description: <What does this plugin do? What is the benefit? (One sentence description)>.
@@ -11,25 +8,22 @@
 // opensource plugin = tieroneplan
 // premium plugin    = tiertwoplan or tierthreeplan or enterpriseplan
 :pluginminimumplan: <tier>
-// <plugincode>: adds the plugin to an editor configuration.
-// Reference on this page with the {plugincode} variable
 :plugincode: <plugincode>
-:plugincategory: premium|opensource
+:plugincategory: <premium|opensource>
 
 // Remove the line below (and this comment) for open source plugins
 include::partial$misc/admon-premium-plugin.adoc[]
 
-// Edit the line below to add the correct requires-<versionnumber> file from `/partials/misc`.
+// Edit the line below to add the correct requires-<versionnumber> file from `tinymce-docs/modules/ROOT/partials/misc`.
 include::partial$misc/admon-requires-<versionnumber>v.adoc
 
 // Add an introduction. What does the plugin do? Why would I use this plugin? Keep it concise.
 
 == Interactive example
 
-// No Lorem Ipsum. Add test material, or, at least, a description of how end-users use the feature.
 liveDemo::{plugincode}[]
 
-// Logic for customising what presents from this included file relies on
+// Logic for customizing what presents from this included file relies on
 // the :pluginminimumplan: attribute value above.
 //
 // 2023-09-06 addendum: the logic in purchase-premium-plugins.adoc needs
@@ -49,9 +43,9 @@ For example:
 ----
 tinymce.init({
   selector: 'textarea',  // change this value according to your HTML
-  plugins: '{{plugincode}}',
+  plugins: '<plugincode>',
   toolbar: '<toolbar-button(s)>',
-  an_essential_option: false
+  <an_essential_option>: false
 });
 ----
 
@@ -65,9 +59,7 @@ The following configuration options affect the behavior of the {pluginname} plug
 // The template file for each such file is
 // -new-material-templates/partials/commands/<configuration_option>.adoc
 // Add one include:: statement for each added file as per the example immediately below.
-include::partial$configuration/<setting_name>.adoc[][leveloffset=+1]
-
-
+include::partial$configuration/<configuration_name>.adoc[leveloffset=+1]
 
 // If the plugin offers toolbar buttons
 // 1. Add an entry to /pages/available-toolbar-buttons.adoc
@@ -131,6 +123,4 @@ include::partial$events/{plugincode}-events.adoc[]
 
 The {pluginname} plugin provides the following APIs.
 
-include::partial$plugin-apis/{plugincode}-apis.adoc[]
-
-// Remove all comment lines and comment blocks before publishing.
+include::partial$plugin-apis/{plugincode}-apis.adoc[]

-new-material-templates/plugin-documentation-templates/ROOT/partials/commands/{plugincode}-cmds.adoc

@@ -0,0 +1,33 @@
+[cols="1,3",options="header"]
+|===
+|Command         |Description
+
+|<mceCommandOne>   |<Description one.>
+// Boilerplate for commands that require further documentation
+|<mceCommandTwo>   |Description two. For details, see xref:using-<mcecommandtwo>[Using `+<mceCommandTwo>+`].
+|===
+
+.Examples
+[source,js]
+----
+tinymce.activeEditor.execCommand('<mceCommandOne>');
+tinymce.activeEditor.execCommand('<mceCommandTwo>', <true|false>, { <key1>: '<value1>', <key2>: '<number>' });
+----
+
+// Boilerplate for further documentation of commands that require it.
+[[using-<mcecommandtwo>]]
+== Using `+<mceCommandTwo>+`
+
+`+<mceCommandTwo>+` accepts an object with the following key-value pairs:
+
+[cols="1,,1,2",options="header"]
+|===
+|Name      |Value                               |Requirement      |Description
+
+|<key1>    |`+'<value1>'+` or `+'<value2>'+`    |<Not r|R>equired |<Key-value description one.>
+|<key2>    |`+<number>+`                        |<Not r|R>equired |<Key-value description two.>
+|===
+
+// Further notes as required. Delete this comment once notes are added or if they are not required.
+
+// Remove all comment lines and comment blocks before publishing.

-new-material-templates/plugin-documentation-templates/ROOT/partials/configuration/icon_list.adoc

@@ -1,7 +1,6 @@
-// 0. Replace <place-holder text> instances with appropriate material.
-// 1. Add the edited material to
-//    /tinymce-docs/modules/ROOT/partials/configuration/icon_list.adoc
+// 1. Replace <place-holder text> instances with appropriate material.
+// 2. Add the edited material to
+//    tinymce-docs/modules/ROOT/partials/configuration/icon_list.adoc
 //    in alphabetical order by <icon-identifier>. (*not* <icon-file-name>).
-// 2. Do not bring these comments over with the edited material.
 
 | `+<icon-identifier>+` | image:icons/<icon-file-name>.svg[<icon-file-name>.svg] | `+<icon-file-name>.svg+`

-new-material-templates/plugin-documentation-templates/ROOT/partials/configuration/<configuration_option>.adoc → -new-material-templates/plugin-documentation-templates/ROOT/partials/configuration/{configuration_option}.adoc

@@ -1,12 +1,6 @@
 [[<configuration_option>]]
 == `<configuration_option>`
 
-// Replace all instances of <configuration_option> with the
-// configuration option name then remove this comment.
-
-// Add explanatory material as per the comment block below then remove
-// the block and this comment.
-
 ////
 What does the option do?
 Why use it?
@@ -32,7 +26,7 @@ Are there risks?
 [source,js]
 ----
 tinymce.init({
-  selector: 'textarea',  // change this value according to your html
+  selector: 'textarea',  // Change this value according to your HTML
   <configuration_option>: '<value>'
 });
 ----
@@ -46,24 +40,18 @@ To disable <feature>, set `<configuration_option>` to `false`.
 [source,js]
 ----
 tinymce.init({
-  selector: 'textarea',  // change this value according to your HTML
+  selector: 'textarea',  // Change this value according to your HTML
   <configuration_option>: 'false'
 });
 ----
 
 // Remove if not applicable.
-// Edit the sub-head to singular or plural as required.
-=== Limitation(s) of the `<configuration_option>` option
+=== Limitation<s> of the `<configuration_option>` option
 
 The `<configuration_option>` option has the following limitations.
 
-// Add explanatory material as per the comment block below then remove
-// the block and this comment.
-
 ////
 Known limitations.
 Complicated scenarios.
 Anything that warrants a CAUTION or WARNING admonition.
-////
-
-// Remove all comment lines and comment blocks before publishing.
+////

-new-material-templates/plugin-documentation-templates/ROOT/partials/events/<plugincode>-events.adoc → -new-material-templates/plugin-documentation-templates/ROOT/partials/events/{plugincode}-events.adoc

@@ -3,8 +3,6 @@ The following events are provided by the xref:<plugincode>.adoc[<Plugin name> pl
 [cols="1,1,2",options="header"]
 |===
 |Name       |Data                                       |Description
-
-// Five boilerplate rows.
 |EventOne   |`+{ <key1>: <value1> }+`                   |Fired when event one description.
 |EventTwo   |`+{ <key2>: <value2>, <key3>: <value3> }+` |Fired when event two description.
 |EventThree |N/A                                        |Fired when event three description.
@@ -16,6 +14,4 @@ The following events are provided by the xref:<plugincode>.adoc[<Plugin name> pl
 include::partial$misc/admon-requires-<version.version>v.adoc[]
 |EventFour  |`+{ <key6>: <value6> }+`                   |Fired when the event seven description.
 |EventEn    |`+{ <key4>: <value4>, <key5>: <value5> }+` |Fired when event en description.
-|===
-
-// Remove all comment lines and comment blocks before publishing.
+|===

-new-material-templates/plugin-documentation-templates/ROOT/partials/index-pages/opensource-plugins.adoc

@@ -1,10 +1,8 @@
 // Table row for an open-source plugin.
-// Place this row into the extant table in `partials/index-pages/opensource-plugins.adoc` in alphabetical order.
+// Place this row into the existing table in `partials/index-pages/opensource-plugins.adoc` in alphabetical order by <Plugin name>.
 
 a|
 [.lead]
 xref:<plugincode>.adoc[<Plugin name>]
 
-<One sentence plugin description.>
-
-// This file is instructional and is never included in the published name-space.
+<One sentence plugin description.>

-new-material-templates/plugin-documentation-templates/ROOT/partials/index-pages/premium-plugins.adoc

@@ -1,10 +1,8 @@
 // Table row for a Premium plugin.
-// Place this row into the extant table in `partials/index-pages/premium-plugins.adoc` in alphabetical order.
+// Place this row into the existing table in `partials/index-pages/premium-plugins.adoc` in alphabetical order by <Plugin name>.
 
 a|
 [.lead]
 xref:<plugincode>.adoc[<Plugin name>]
 
-<One sentence plugin description.>
-
-// This file is instructional and is never included in the published name-space.
+<One sentence plugin description.>