DOC-1969: lists and advlists plugins, text_patterns, and implicit and explicit list-creation UIs

changelog.md

@@ -6,6 +6,7 @@ The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/
 
 ### Unreleased
 
+- DOC-1969: edits, corrections and added material to `text_patterns.adoc`, `lists.adoc`, `advlists.adoc`, and `migration-from-5x.adoc` re implicit and explicit list-creation UIs.
 - DOC-1955: added the TinyMCE 6.4.2 specific changes to changelog.adoc.
 
 ### 2023-04-19

modules/ROOT/pages/advlist.adoc

@@ -15,9 +15,13 @@ IMPORTANT: The xref:lists.adoc[Lists] (`+lists+`) plugin must be activated for t
 tinymce.init({
   selector: 'textarea', // change this value according to your HTML
   plugins: 'lists advlist'
+  toolbar: 'bullist numlist',
 });
 ----
 
+include::partial$configuration/text_patterns-and-lists.adoc[]
+
+
 == Options
 
 These settings affect the execution of the `+advlist+` plugin by providing more granular control of list styles.

modules/ROOT/pages/lists.adoc

@@ -5,21 +5,106 @@
 :pluginname: Lists
 :plugincode: lists
 
-The `+lists+` plugin allows you to add numbered and bulleted lists to {productname}. To enable advanced lists (e.g. alpha numbered lists, square bullets) you should also enable the xref:advlist.adoc[Advanced List] (`+advlist+`) plugin.
+The `+lists+` plugin enables numbered and bulleted lists in {productname}. To enable advanced lists (for example, lists ordered by letter or unordered lists presented with square bullets) enable the xref:advlist.adoc[Advanced List] (`+advlist+`) plugin.
 
-The plugin also normalizes list behavior between browsers. Enable it if you have problems with consistency making lists.
+The `+lists+` plugin also normalizes list behavior between browsers. Enable it if you have problems with consistency making lists.
 
-== Basic setup
+It is important to note that, by default, {productname} includes both implicit and explicit list-creation user-interfaces.
+
+Adding the `lists` plugin and the `bullist` and `numlist` toolbar items to a {productname} configuration enables the explicit list-creation user-interface (UI).
+
+The implicit list-creation UI comes via xref:content-behavior-options.adoc#text_patterns[text patterns]. The default set of `text_patterns` enabled when {productname} is initialized include https://daringfireball.net/projects/markdown/syntax[Markdown]-based patterns that {productname} automatically turns into basic ordered and unordered lists.
+
+If the xref:advlist.adoc[Advanced Lists] Premium plugin is part of a {productname} configuration, the default `text_patterns` set also includes patterns that provide an implicit UI for generating the advanced ordered and unordered lists this plugin makes possible.
+
+== Basic lists UI: implicit and explicit
+
+[source,js]
+----
+tinymce.init({
+  selector: 'textarea',  // change this value according to your HTML
+  plugins: 'lists',
+  toolbar: 'bullist numlist',
+});
+----
+
+
+== Basic lists UI: explicit lists UI but no implicit lists UI
 
 [source,js]
 ----
 tinymce.init({
   selector: 'textarea',  // change this value according to your HTML
   plugins: 'lists',
-  toolbar: 'numlist bullist'
+  toolbar: 'bullist numlist',
+  text_patterns: false,
 });
 ----
 
+include:partial$misc/admon-turning-text_patterns-off.adoc[]
+
+
+== Basic setup for explicit lists UI and a specifically defined implicit lists UI
+
+[source,js]
+----
+tinymce.init({
+  selector: 'textarea',  // change this value according to your HTML
+  plugins: 'lists',
+  toolbar: 'numlist bullist',
+  text_patterns: [
+    { start: '#', format: 'h1' },
+    { start: '##', format: 'h2' },
+    { start: '###', format: 'h3' },
+    { start: '####', format: 'h4' },
+    { start: '#####', format: 'h5' },
+    { start: '######', format: 'h6' },
+    { start: '* ', cmd: 'InsertUnorderedList' },
+    { start: '- ', cmd: 'InsertUnorderedList' },
+    { start: '1. ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'decimal' } },
+    // the block patterns below require the Advanced Lists plugin
+    { start: '1) ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'decimal' } },
+    { start: 'a. ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'lower-alpha' } },
+    { start: 'a) ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'lower-alpha' } },
+    { start: 'i. ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'lower-roman' } },
+    { start: 'i) ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'lower-roman' } }
+  ]
+});
+----
+
+The `text_patterns` array in the example above duplicates the default `text_patterns` set available even if `text_patterns` is not explicitly specified in a {productname} configuration.
+
+== Basic setup for a specifically defined implicit lists UI but no explicit lists UI
+
+
+[source,js]
+----
+tinymce.init({
+  selector: 'textarea',  // change this value according to your HTML
+  plugins: 'lists',
+  text_patterns: [
+    { start: '#', format: 'h1' },
+    { start: '##', format: 'h2' },
+    { start: '###', format: 'h3' },
+    { start: '####', format: 'h4' },
+    { start: '#####', format: 'h5' },
+    { start: '######', format: 'h6' },
+    { start: '* ', cmd: 'InsertUnorderedList' },
+    { start: '- ', cmd: 'InsertUnorderedList' },
+    { start: '1. ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'decimal' } },
+    // the block patterns below require the Advanced Lists plugin
+    { start: '1) ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'decimal' } },
+    { start: 'a. ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'lower-alpha' } },
+    { start: 'a) ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'lower-alpha' } },
+    { start: 'i. ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'lower-roman' } },
+    { start: 'i) ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'lower-roman' } }
+  ]
+});
+----
+
+The `text_patterns` array in the example above also duplicates the default `text_patterns` set. This example, however, removes the ordered and unordered list toolbar items. The `list` plugin does not provide a menu item, so not loading the toolbar items removes the explicit lists UI.
+
+
 == Options
 
 These settings affect the execution of the `+lists+` plugin.
@@ -28,6 +113,7 @@ include::partial$configuration/lists_indent_on_tab.adoc[leveloffset=+1]
 
 include::partial$misc/plugin-toolbar-button-id-boilerplate.adoc[]
 
+
 == Commands
 
 The Lists plugin provides the following {productname} commands.

modules/ROOT/pages/migration-from-5x.adoc

@@ -205,20 +205,23 @@ NOTE: The `link_default_protocol` value is only applied to an edited or inserted
 
 As noted in the xref:6.0-release-notes-core-changes.adoc#removed-or-deprecated-options-textpattern[_{productname} 6.0 Release Notes_], the `textpattern_patterns` option:
 
-* Was renamed to `text_patterns`;
-* Had its functionality moved to the Core of {productname} 6.0.
+* Was renamed to `text_patterns`; and
+* Had its functionality moved to the core of {productname} 6.0.
 
 As well, the `textpattern` API has been removed.
 
 Finally, and unlike in previous versions of {productname}, text patterns are now on by default. `text_patterns: false` turns the functionality off.
 
-NOTE: Using `text_patterns: []` to turn `text_patterns` off is not supported. It sets `text_patterns` to an empty array. Having, consequently, no patterns to match, it presents as if `text_patterns` is off. Appearance is not reality, however. Setting `text_patterns: false` is the only supported way of disabling `text_patterns`.
+include:partial$misc/admon-turning-text_patterns-off.adoc[]
 
 After upgrading:
 
 * Rename any options in your {productname} init configuration to match the new name.
 * Remove `textpattern` from your plugins list.
 
+include::partial$configuration/text_patterns-and-lists.adoc[]
+
+
 [[plugins]]
 == Plugins
 

modules/ROOT/partials/configuration/text_patterns-and-lists.adoc

@@ -0,0 +1,10 @@
+=== Text patterns and lists
+
+As a consequence of
+
+. `text_patterns` being moved to the core of {productname};
+. `text_patterns` being turned on by default; and
+. the set of `text_patterns` which are included by default
+
+{productname} now includes both implicit and explicit list creation user interfaces. See xref:lists.adoc[Lists] for details and basic configuration examples.
+

modules/ROOT/partials/configuration/text_patterns.adoc

@@ -1,13 +1,27 @@
 [[text_patterns]]
 == `+text_patterns+`
 
-This option allows configuring the text patterns that get matched while typing in the editor. Text patterns can be used to apply formats, replace text, or execute commands. By default, basic markdown patterns are enabled so the user can type `+# text+` to produce a header or `+**text**+` to make text *bold*. To disable text patterns getting replaced, set the option to `false`.
+This option allows configuring the text patterns that get matched while typing in the editor. Text patterns can be used to apply formats, replace text, or execute commands.
 
-There are three types of patterns: `+inline+`, `+block+`, and `+replacement+` patterns. Inline patterns have a `+start+` and an `+end+` text pattern whereas the block and replacement patterns only have a `+start+`. A user can specify the formats to be applied to the selection, commands to be executed, or text to be replaced.
+Basic https://daringfireball.net/projects/markdown/syntax[Markdown] patterns are enabled by default. A user can, for example, type `+# text+` to produce a header or `+**text**+` to make text *bold*.
+
+To disable all text patterns, set the `text_patterns` option to `false`.
+
+There are three pattern types:
+
+.`+inline+`;
+.`+block+`; and
+.`+replacement+`.
+
+Inline patterns have a `+start+` and an `+end+` text pattern.
+
+Block and replacement patterns only have a `+start+`.
+
+The formats to be applied to the selection, commands to be executed, or text to be replaced can all be specified in a {productname} configuration.
 
 [IMPORTANT]
 ====
-Any formats or commands used in text patterns need to be registered with the editor when it is initialized. This may include enabling relevant plugins, such as the `+lists+` plugin. For information on:
+Any formats or commands used in text patterns need to be registered with the editor when it is initialized. This may include enabling relevant plugins. For information on:
 
 * Registering formats for {productname}, see: xref:content-formatting.adoc#formats[Content formatting options - `+formats+`].
 * Registering commands for {productname}, see: xref:apis/tinymce.editor.adoc#addCommand[{productname} APIs - addCommand].
@@ -27,7 +41,6 @@ Any formats or commands used in text patterns need to be registered with the edi
   { start: '####', format: 'h4' },
   { start: '#####', format: 'h5' },
   { start: '######', format: 'h6' },
-  // The following text patterns require the `lists` plugin
   { start: '1. ', cmd: 'InsertOrderedList' },
   { start: '* ', cmd: 'InsertUnorderedList' },
   { start: '- ', cmd: 'InsertUnorderedList' }
@@ -44,16 +57,14 @@ Inline patterns must have the following:
 
 This allows for patterns to be used to either apply a format or execute a command, optionally with the given value.
 
-NOTE: Inline patterns are executed on either pressing the *spacebar* or the *Enter* key.
+NOTE: Inline patterns are executed on either pressing the *spacebar* or pressing the *Return* or *Enter* key.
 
 ==== Example: using inline patterns
 
 [source,js]
 ----
 tinymce.init({
   selector: 'textarea',  // change this value according to your HTML
-  // The `link` plugin is required for the `createLink` command
-  plugin: 'link',
   text_patterns: [
     { start: '*', end: '*', format: 'italic' },
     { start: '**', end: '**', format: 'bold' },
@@ -64,9 +75,25 @@ tinymce.init({
 
 Using the configuration in this example:
 
-* `+{ start: '*', end: '*', format: 'italic' }+` - Entering text between`+*+` and then pressing the *spacebar* will result in the `+italic+` format being applied to the text between the `+*+` symbols.
-* `+{ start: '**', end: '**', format: 'bold' }+` - Entering text between`+**+` and then pressing the *spacebar* will result in the `+bold+` format being applied.
-* `+{ start: '~', end: '~', cmd: 'createLink', value: 'https://tiny.cloud' }+` - This executes `+editor.execCommand('createLink', false, 'https://tiny.cloud')+`, which will wrap the text between the `+~+` symbols in a link that points to `+https://tiny.cloud+`.
+* `+{ start: '*', end: '*', format: 'italic' }+`
++
+Enter text immediately after an initial `+*+` and end the entered string with a closing `+*+`; then press the *spacebar*.
++
+The text between the `+*+` characters is set in _italics_, and the `+*+` characters is removed.
+
+* `+{ start: '**', end: '**', format: 'bold' }+`
++
+Enter text immediately after an initial `+**+` and end the entered string with a closing `+**+`; then press the *spacebar*.
++
+The text between the `+**+` characters is set *bold*, and the `+**+` characters is removed.
+
+
+* `+{ start: '~', end: '~', cmd: 'createLink', value: 'https://tiny.cloud' }+`
++
+This text pattern executes `+editor.execCommand('createLink', false, 'https://tiny.cloud')+`.
++
+This commands takes a string delimited by `+~+` characters and, when the *spacebar* is pressed, wraps the string in an anchor tag pointing to `+https://tiny.cloud+`. It then removes the delimiting `+~+` characters.
+
 
 === Block patterns
 
@@ -76,18 +103,16 @@ Block patterns must have the following:
 * A `+format+` or a `+cmd+`
 ** If `+cmd+` is specified, an optional `+value+` property is allowed.
 
-The block patterns do not have an `+end+` property. This allows for patterns to be used to either apply a block format or execute a command, optionally, with the given value.
+Block patterns do not have an `+end+` property. This allows for patterns to be used to either apply a block format or execute a command, optionally, with the given value.
 
-NOTE: Block patterns are only executed on *Enter*, *not* on pressing the *spacebar*.
+NOTE: Block patterns are only executed on pressing *Return* or *Enter*, *not* on pressing the *spacebar*.
 
 ==== Example: using block patterns
 
 [source,js]
 ----
 tinymce.init({
-  selector: 'textarea', // change this value according to your HTML
-  // The `lists` plugin is required for list-related text patterns
-  plugin: 'lists',
+  selector: 'textarea',  // change this value according to your HTML
   text_patterns: [
     { start: '#', format: 'h1' },
     { start: '##', format: 'h2' },
@@ -98,6 +123,7 @@ tinymce.init({
     { start: '* ', cmd: 'InsertUnorderedList' },
     { start: '- ', cmd: 'InsertUnorderedList' },
     { start: '1. ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'decimal' } },
+    // the block patterns below require the Advanced Lists plugin
     { start: '1) ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'decimal' } },
     { start: 'a. ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'lower-alpha' } },
     { start: 'a) ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'lower-alpha' } },
@@ -109,8 +135,19 @@ tinymce.init({
 
 Using the configuration in this example:
 
-* `+{ start: '#', format: 'h1' }+` - Typing `+#+`, some text, and then pressing `+Enter+` will convert the text to a `+h1+` heading.
-* Typing `+1.+` followed by a space, the desired text, and then pressing `+Enter+`; the editor will convert the text into an ordered list, with the original text as the first list item, and the new line as the second list item. Since we have specified `+value+`, this pattern will execute `+editor.execCommand('InsertOrderedList', false, { 'list-style-type': 'decimal'})+`.
+* `+{ start: '#', format: 'h1' }+`
++
+Type `+#+`, `+some text+`, and then press *Return* or *Enter*.
++
+The string, `+some text+`, is turned into an `+h1+` heading, and the `+#+` character is removed.
+
+* `+{ start: '1. ', cmd: 'InsertOrderedList', value: { 'list-style-type': 'decimal' } }+`
++
+Type `+1.+` followed by a space and `+some text+`. Then press *Return* pr *Enter*.
++
+The string, `+some text+`, is converted into the first item in an ordered list, and the new line becomes the second item in the list.
++
+Since `+value+` is specified, this pattern will execute `+editor.execCommand('InsertOrderedList', false, { 'list-style-type': 'decimal'})+`.
 
 === Replacements patterns
 
@@ -121,7 +158,7 @@ Replacement patterns must have the following:
 
 Whether a replacement pattern inserts a block or inline element depends on what the `+replacement+` string is.
 
-NOTE: Replacement patterns are executed on either pressing the *spacebar* or the *Enter* key.
+NOTE: Replacement patterns are executed on either pressing the *spacebar* or pressing the *Return* or *Enter* key.
 
 ==== Example: using replacement patterns
 
@@ -142,7 +179,18 @@ tinymce.init({
 
 Using the configuration in this example:
 
-* Typing `+---+` and then either pressing the *spacebar* or the *Enter* key will insert a horizontal rule block.
-* Typing `+(c)+` and then either pressing the *spacebar* or the *Enter* key will insert an inline copyright symbol.
+* `+{ start: '---', replacement: '<hr/>' }+`
++
+Type `+---+` and then press the *spacebar* or press the *Return* or *Enter* key.
++
+The string of four hyphens is replaced by a horizontal rule block.
+
+* `+{ start: '(c)', replacement: '©' }+`
++
+Type `+(c)+` and then press the *spacebar* or press the *Return* or *Enter* key.
++
+The entered string, `+(c)+`, is replaced by the copyright symbol — © — set inline.
+
+Replacement patterns are useful for commonly used phrases or symbols and can be leveraged to create implicit content templates. The last example pattern above is an example of this.
 
-This is useful for commonly used phrases or symbols and can be leveraged to create content templates. The last pattern is an example of this.
+include::partial$configuration/text_patterns-and-lists.adoc[]

modules/ROOT/partials/misc/admon-turning-text_patterns-off.adoc

@@ -0,0 +1 @@
+NOTE: Using `text_patterns: []` to turn `text_patterns` off is not supported. It sets `text_patterns` to an empty array. Having, consequently, no patterns to match, it presents as if `text_patterns` is off. Appearance is not reality, however. Setting `text_patterns: false` is the only supported way of disabling `text_patterns`.