Merge pull request #15351 from ckeditor/ck/3627-40.1.0-docs-review

Docs: a 40.1.0 review.

docs/examples/experiments/mermaid.md

@@ -12,7 +12,7 @@ modified_at: 2023-06-14
 
 You can create flowcharts and diagrams in CKEditor 5 thanks to the experimental integration with the [Mermaid](https://mermaid.js.org/) library. Mermaid uses a Markdown-inspired syntax to create and dynamically modify flowcharts, Gantt diagrams, pie or quadrant charts, graphs, mindmaps, and more.
 
-The example below lets you test creating diagrams and flowcharts right during the content creation — no more screenshots that need to be re-created and re-uploaded each time something needs a change! You can also check out a live implementation in [GitHub Writer](https://ckeditor.com/blog/github-writer-now-available-with-mermaid-support/).
+The example below lets you test creating diagrams and flowcharts right during the content creation – no more screenshots that need to be re-created and re-uploaded each time something needs a change! You can also check out a live implementation in [GitHub Writer](https://ckeditor.com/blog/github-writer-now-available-with-mermaid-support/).
 
 {@snippet examples/mermaid}
 

docs/examples/how-tos.md

@@ -168,7 +168,7 @@ const modelFragment = editor.data.toModel( viewFragment );
 editor.model.insertContent( modelFragment );
 ```
 
-Remember, if some element or attribute does not have declared converters (whether by the dedicated feature or {@link features/html/general-html-support General HTML support) plugin then those won't get inserted.
+Remember, if some element or attribute does not have declared converters (whether by the dedicated feature or {@link features/general-html-support General HTML support}) plugin then those will not get inserted.
 
 ### How to focus the editor?
 
@@ -293,7 +293,7 @@ for ( const range of wordRanges ) {
 }
 ```
 
-### How to listen on a double click (e.g. link elements)?
+### How to listen on a double-click (e.g. link elements)?
 
 ```js
 // Add observer for double click and extend a generic DomEventObserver class by a native DOM dblclick event:

docs/examples/index.md

@@ -34,7 +34,7 @@ If you need even more, try our experimental plugins, like the integration of the
 
 ## How-tos
 
-There come times when you don't need deep-dive guides, elaborate solutions, and complicated examples. Sometimes, you just need to know how to set the height of CKEditor 5. Or, maybe you want to learn how to focus the editor? This is what the {@link examples/how-tos How-to} section is for!
+There come times when you do not need deep-dive guides, elaborate solutions, and complicated examples. Sometimes, you just need to know how to set the height of CKEditor 5. Or, maybe you want to learn how to focus the editor? This is what the {@link examples/how-tos How-to} section is for!
 
 
 **Related links**

docs/features/image-upload.md

@@ -8,7 +8,7 @@ order: 10
 {@snippet features/build-image-upload-source}
 # Image upload overview
 
-Inserting {@link features/images-overview images} into content created with CKEditor 5 is a very common task. In a properly configured rich-text editor, there are several ways for the end user to insert images:
+Inserting {@link features/images-overview images} into content created with CKEditor 5 is quite a common task. In a properly configured rich-text editor, there are several ways for the end user to insert images:
 
 * **Pasting** an image from the clipboard.
 * **Dragging** a file from the file system.
@@ -41,7 +41,7 @@ Except for pasting URLs to images, all other solutions mentioned above require t
 
 ### CKBox
 
-CKBox is the most complete solution for not just image upload but also file management in CKEditor 5.
+CKBox is the ultimate solution for not just image upload but also file management in CKEditor 5.
 
 It is a modern file uploader with a clean interface, automatic support for responsive images, and top-notch UX. It also provides editing capabilities like cropping, rotating, or flipping.
 
@@ -73,7 +73,7 @@ The {@link features/simple-upload-adapter simple upload adapter} allows uploadin
 The {@link features/base64-upload-adapter Base64 upload feature} converts images inserted into the editor into [Base64 strings](https://en.wikipedia.org/wiki/Base64) in the {@link installation/getting-started/getting-and-setting-data editor output}.
 
 <info-box warning>
-	Please remember that while `Base64` upload is a very easy solution, it is also highly inefficient. The image file itself is kept as data in the database, generating a much heavier data load and higher transfer. We recommend using alternative ways to upload images into CKEditor&nbsp;5.
+	Please remember that while `Base64` upload is an easy solution, it is also highly inefficient. The image file itself is kept as data in the database, generating a much heavier data load and higher transfer. We recommend using alternative ways to upload images into CKEditor&nbsp;5.
 </info-box>
 
 {@link features/base64-upload-adapter **Learn how to use Base64–encoded images in CKEditor&nbsp;5**}.

docs/features/index.md

@@ -41,7 +41,7 @@ Rich text would not be rich without images. You can upload them, caption them, s
 
 An essential feature for online content are {@link features/link links} {@icon @ckeditor/ckeditor5-link/theme/icons/link.svg Link} - these can be easily pasted, changed and attributed.
 
-Provide clear and accessible data using {@link features/tables tables} {@icon @ckeditor/ckeditor5-table/theme/icons/table.svg Table} (you can even nest them to create advanced layouts), ordered {@icon @ckeditor/ckeditor5-list/theme/icons/numberedlist.svg Numbered List} and unordered {@link features/lists lists} {@icon @ckeditor/ckeditor5-list/theme/icons/bulletedlist.svg} Bulleted List with various markers to choose from and {@link features/todo-lists to-do lists} {@icon @ckeditor/ckeditor5-list/theme/icons/todolist.svg Todo List}. Use {@link features/indent indents and outdents} {@icon @ckeditor/ckeditor5-indent/theme/icons/indent.svg Indent} as well as {@link features/block-quote block quotes} {@icon @ckeditor/ckeditor5-core/theme/icons/quote.svg Quote} to structure the content and draw the reader's attention to it.
+Provide clear and accessible data using {@link features/tables tables} {@icon @ckeditor/ckeditor5-table/theme/icons/table.svg Table} (you can even nest them to create advanced layouts), ordered {@icon @ckeditor/ckeditor5-list/theme/icons/numberedlist.svg Numbered List} and unordered {@link features/lists lists} {@icon @ckeditor/ckeditor5-list/theme/icons/bulletedlist.svg} Bulleted List with various markers to choose from and {@link features/todo-lists to-do lists} {@icon @ckeditor/ckeditor5-list/theme/icons/todolist.svg To-do List}. Use {@link features/indent indents and outdents} {@icon @ckeditor/ckeditor5-indent/theme/icons/indent.svg Indent} as well as {@link features/block-quote block quotes} {@icon @ckeditor/ckeditor5-core/theme/icons/quote.svg Quote} to structure the content and draw the reader's attention to it.
 
 Enrich you content further by {@link features/html-embed embedding HTML code} {@icon @ckeditor/ckeditor5-html-embed/theme/icons/html.svg HTML} - this one is especially useful for webmasters. If you need to present code instead of employing it - use the {@link features/code-blocks code block} {@icon @ckeditor/ckeditor5-code-block/theme/icons/codeblock.svg Code Block} that lets you produce code listing with a syntax highlight, too!
 
@@ -59,13 +59,13 @@ Additionally, CKEditor 5 offers the {@link features/restricted-editing rest
 
 {@img assets/img/features-collaboration.png 800 CKEditor 5 collaboration features.}
 
-You can also easily track the progress and changes done in the content with the {@link features/revision-history revision history feature} {@icon @ckeditor/ckeditor5-core/theme/icons/history.svg Revision history}. This modern and robust document versioning tool lets you create named versions, compare changes, and restore previous document versions at ease, tracking all progress — also when multiple editors work together.
+You can also easily track the progress and changes done in the content with the {@link features/revision-history revision history feature} {@icon @ckeditor/ckeditor5-core/theme/icons/history.svg Revision history}. This modern and robust document versioning tool lets you create named versions, compare changes, and restore previous document versions at ease, tracking all progress – also when multiple editors work together.
 
 {@img assets/img/features-revision-history.png 800 CKEditor 5 document versioning feature.}
 
 ### Document conversion
 
-If you need to share the document outside your team, use the {@link features/export-pdf export to PDF feature} {@icon @ckeditor/ckeditor5-export-pdf/theme/icons/exportpdf.svg Export to PDF} to produce industry standard, portable, cross-platform final files. If you need to work further on the document, choose the {@link features/export-word export to Word feature} {@icon @ckeditor/ckeditor5-export-word/theme/icons/exportword.svg Export to Word} instead — and keep your comments and changes in the resulting document, ready to be edited further. These two are accompanied by the {@link features/pagination pagination feature} {@icon @ckeditor/ckeditor5-pagination/theme/icons/arrow-up.svg Previous page}{@icon @ckeditor/ckeditor5-pagination/theme/icons/arrow-down.svg Next page}, to ensure all produced documents will always look the way they should.
+If you need to share the document outside your team, use the {@link features/export-pdf export to PDF feature} {@icon @ckeditor/ckeditor5-export-pdf/theme/icons/exportpdf.svg Export to PDF} to produce industry standard, portable, cross-platform final files. If you need to work further on the document, choose the {@link features/export-word export to Word feature} {@icon @ckeditor/ckeditor5-export-word/theme/icons/exportword.svg Export to Word} instead – and keep your comments and changes in the resulting document, ready to be edited further. These two are accompanied by the {@link features/pagination pagination feature} {@icon @ckeditor/ckeditor5-pagination/theme/icons/arrow-up.svg Previous page}{@icon @ckeditor/ckeditor5-pagination/theme/icons/arrow-down.svg Next page}, to ensure all produced documents will always look the way they should.
 
 ### HTML and Markdown output
 

docs/framework/architecture/core-editor-architecture.md

@@ -246,7 +246,7 @@ command.on( 'change:value', ( evt, propertyName, newValue, oldValue ) => {
 command.value = true; // -> 'value has changed from undefined to true'
 ```
 
-Observables have one more feature which is widely used by the editor (especially in the UI library) — the ability to bind the value of one object's property to the value of some other property or properties (of one or more objects). This, of course, can also be processed by callbacks.
+Observables have one more feature which is widely used by the editor (especially in the UI library) – the ability to bind the value of one object's property to the value of some other property or properties (of one or more objects). This, of course, can also be processed by callbacks.
 
 Assuming that `target` and `source` are observables and that used properties are observable:
 

docs/framework/architecture/editing-engine.md

@@ -18,7 +18,7 @@ The editing engine implements an MVC architecture. The shape of it is not enforc
 
 [{@img assets/img/framework-architecture-engine-diagram.png Diagram of the engine's MVC architecture.}](%BASE_PATH%/assets/img/framework-architecture-engine-diagram.png)
 
-What you can see, are three layers: **model**, **controller** and **view**. There is one **model document** which is {@link framework/deep-dive/conversion/intro **converted**} into separate views — the [**editing view**](#editing-pipeline) and the [**data view**](#data-pipeline). These two views represent, respectively, the content that the user is editing (the DOM structure that you see in the browser) and the editor input and output data (in a format that the plugged data processor understands). Both views feature virtual DOM structures (custom, DOM-like structures) on which converters and features work and which are then **rendered** to the DOM.
+What you can see, are three layers: **model**, **controller** and **view**. There is one **model document** which is {@link framework/deep-dive/conversion/intro **converted**} into separate views – the [**editing view**](#editing-pipeline) and the [**data view**](#data-pipeline). These two views represent, respectively, the content that the user is editing (the DOM structure that you see in the browser) and the editor input and output data (in a format that the plugged data processor understands). Both views feature virtual DOM structures (custom, DOM-like structures) on which converters and features work and which are then **rendered** to the DOM.
 
 The green blocks are the code introduced by editor features (plugins). These features control what changes are made to the model, how they are converted to the view and how the model needs to be changed based on fired events (the view's and model's ones).
 
@@ -78,7 +78,7 @@ editor.model.change( writer => {
 
 ### Text attributes
 
-Text styles such as "bold" and "italic" are kept in the model not as elements but as text attributes (think — like element attributes). The following DOM structure:
+Text styles such as "bold" and "italic" are kept in the model not as elements but as text attributes (think – like element attributes). The following DOM structure:
 
 ```html
 <p>
@@ -109,7 +109,7 @@ Such representation of inline text styling allows to significantly reduce the co
 </p>
 ```
 
-and you have a selection before the letter `"b"` (`"Foo ^bar"`), is this position inside or outside `<strong>`? If you use [native DOM Selection](https://developer.mozilla.org/en-US/docs/Web/API/Selection), you may get both positions &mdash; one anchored in `<p>` and the other anchored in `<strong>`. In CKEditor&nbsp;5 this position translates exactly to `"Foo ^bar"`.
+and you have a selection before the letter `"b"` (`"Foo ^bar"`), is this position inside or outside `<strong>`? If you use [native DOM Selection](https://developer.mozilla.org/en-US/docs/Web/API/Selection), you may get both positions &ndash; one anchored in `<p>` and the other anchored in `<strong>`. In CKEditor&nbsp;5 this position translates exactly to `"Foo ^bar"`.
 
 ### Selection attributes
 
@@ -180,7 +180,7 @@ This information is then used by the features and the engine to make decisions o
 * To which elements the heading feature can be applied (which blocks can be turned to headings and which elements are blocks in the first place).
 * Which elements can be wrapped with a block quote.
 * Whether the bold button is enabled when the selection is in a heading (and whether the text in this heading can be bolded).
-* Where the selection can be placed (which is &mdash; only in text nodes and on object elements).
+* Where the selection can be placed (which is &ndash; only in text nodes and on object elements).
 * etc.
 
 The schema is, by default, configured by editor plugins. It is recommended that every editor feature comes with rules that enable and preconfigure it in the editor. This will make sure that the plugin user can enable it without worrying to re-configure their schema.
@@ -197,7 +197,7 @@ Let's again take a look at the editing engine's architecture:
 
 [{@img assets/img/framework-architecture-engine-diagram.png Diagram of the engine's MVC architecture.}](%BASE_PATH%/assets/img/framework-architecture-engine-diagram.png)
 
-So far, we talked about the topmost layer of this diagram &mdash; the model. The role of the model layer is to create an abstraction over the data. Its format was designed to allow storing and modifying the data in the most convenient way, while enabling implementation of complex features. Most features operate on the model (read from it and change it).
+So far, we talked about the topmost layer of this diagram &ndash; the model. The role of the model layer is to create an abstraction over the data. Its format was designed to allow storing and modifying the data in the most convenient way, while enabling implementation of complex features. Most features operate on the model (read from it and change it).
 
 The view, on the other hand, is an abstract representation of the DOM structure which should be presented to the user (for editing) and which should (in most cases) represent the editor's input and output (i.e. the data returned by `editor.getData()`, the data set by `editor.setData()`, pasted content, etc.).
 
@@ -242,7 +242,7 @@ Additionally, you can define {@link module:engine/view/element~Element#getCustom
 
 * Whether an element is a widget (added by {@link module:widget/utils~toWidget `toWidget()`}).
 * How an element should be marked when a [marker](#markers) highlights it.
-* Whether an element belongs to a certain feature &mdash; if it is a link, progress bar, caption, etc.
+* Whether an element belongs to a certain feature &ndash; if it is a link, progress bar, caption, etc.
 
 #### Non-semantic views
 
@@ -269,8 +269,8 @@ editor.editing.view.change( writer => {
 <info-box>
 	There are two view writers:
 
-	* {@link module:engine/view/downcastwriter~DowncastWriter} &mdash; available in the `change()` blocks, used during downcasting the model to the view. It operates on a "semantic view" so a view structure which differentiates between different types of elements (see [Element types and custom data](#element-types-and-custom-data)).
-	* {@link module:engine/view/upcastwriter~UpcastWriter} &mdash; a writer to be used when pre-processing the "input" data (e.g. pasted content) which happens usually before the conversion (upcasting) to the model. It operates on ["non-semantic views"](#non-semantic-views).
+	* {@link module:engine/view/downcastwriter~DowncastWriter} &ndash; available in the `change()` blocks, used during downcasting the model to the view. It operates on a "semantic view" so a view structure which differentiates between different types of elements (see [Element types and custom data](#element-types-and-custom-data)).
+	* {@link module:engine/view/upcastwriter~UpcastWriter} &ndash; a writer to be used when pre-processing the "input" data (e.g. pasted content) which happens usually before the conversion (upcasting) to the model. It operates on ["non-semantic views"](#non-semantic-views).
 </info-box>
 
 ### Positions
@@ -365,8 +365,8 @@ Let's take a look at the diagram of the engine's MVC architecture and see where
 {@link framework/deep-dive/conversion/downcast#downcast-pipelines **Editing downcasting**} is a bit different process than the other two.
 
 * It takes place in the "editing pipeline" (the left branch of the diagram).
-* It does not have its counterpart &mdash; there is no *editing upcasting* because all user actions are handled by editor features by listening to [view events](#observers), analyzing what happened and applying necessary changes to the model. Hence, this process does not involve conversion.
-* Unlike {@link module:engine/controller/datacontroller~DataController} (which handles the *data pipeline*), {@link module:engine/controller/editingcontroller~EditingController} maintains a single instance of the {@link module:engine/view/document~Document} view document's for its entire life. Every change in the model is converted to changes in that view so changes in that view can then be rendered to the DOM (if needed &mdash; i.e. if the DOM actually differs from the view at this stage).
+* It does not have its counterpart &ndash; there is no *editing upcasting* because all user actions are handled by editor features by listening to [view events](#observers), analyzing what happened and applying necessary changes to the model. Hence, this process does not involve conversion.
+* Unlike {@link module:engine/controller/datacontroller~DataController} (which handles the *data pipeline*), {@link module:engine/controller/editingcontroller~EditingController} maintains a single instance of the {@link module:engine/view/document~Document} view document's for its entire life. Every change in the model is converted to changes in that view so changes in that view can then be rendered to the DOM (if needed &ndash; i.e. if the DOM actually differs from the view at this stage).
 
 ### More information