8
0
Просмотр исходного кода

Merge branch 'stable' into code-blocks-docs-gifs

Radek Kozieł 6 лет назад
Родитель
Сommit
0475c2ec55

+ 1 - 1
packages/ckeditor5-code-block/docs/api/code-block.md

@@ -18,7 +18,7 @@ See the {@link features/code-blocks Code block feature} guide and the {@link mod
 
 ## Installation
 
-```bash
+```
 npm install --save @ckeditor/ckeditor5-code-block
 ```
 

+ 23 - 19
packages/ckeditor5-code-block/docs/features/code-blocks.md

@@ -6,7 +6,11 @@ category: features
 
 {@snippet features/build-code-block-source}
 
-The {@link module:code-block/codeblock~CodeBlock} feature allows inserting and editing blocks of pre–formatted code into the editor. Code blocks have their [specific languages](#configuring-code-block-languages) (e.g. "Java" or "CSS") and support basic editing tools, for instance, [changing the line indentation](#changing-line-indentation) using the keyboard.
+The {@link module:code-block/codeblock~CodeBlock} feature allows inserting and editing blocks of pre–formatted code into the WYSIWYG editor. Each code block has a [specific programming language assigned](#configuring-code-block-languages) (e.g. "Java" or "CSS") and supports basic editing tools, for instance, [changing the line indentation](#changing-line-indentation) using the keyboard.
+
+<info-box>
+	If you would like to use inline code formatting in your WYSIWYG editor, check out the {@link features/basic-styles basic text styles feature} with its support for inline `<code>` element.
+</info-box>
 
 ## Demo
 
@@ -14,13 +18,13 @@ The {@link module:code-block/codeblock~CodeBlock} feature allows inserting and e
 
 ## Configuring code block languages
 
-Each code block can have its language. The language of the code block is represented as a CSS class of the `<code>` element, both when editing and in the editor data:
+Each code block can be assigned a programming language. The language of the code block is represented as a CSS class of the `<code>` element, both when editing and in the editor data:
 
 ```html
 <pre><code class="language-javascript">window.alert( 'Hello world!' )</code></pre>
 ```
 
-It is possible to configure which languages are available. You can use the {@link module:code-block/codeblock~CodeBlockConfig#languages `codeBlock.languages`} configuration and define your own languages. For example, the following editor supports only two languages (CSS and XML/HTML):
+It is possible to configure which languages are available to the users. You can use the {@link module:code-block/codeblock~CodeBlockConfig#languages `codeBlock.languages`} configuration and define your own languages. For example, the following editor supports only two languages (CSS and XML/HTML):
 
 ```js
 ClassicEditor
@@ -38,7 +42,7 @@ ClassicEditor
 
 {@snippet features/code-block-custom-languages}
 
-By default, the CSS class of the `<code>` element in data and editing is generated using the `language` property (prefixed with "language-"). You can customize it by specifying an optional `class` property:
+By default, the CSS class of the `<code>` element in the data and editing is generated using the `language` property (prefixed with "language-"). You can customize it by specifying an optional `class` property:
 
 ```js
 ClassicEditor
@@ -64,14 +68,14 @@ ClassicEditor
 ```
 
 <info-box>
-	The first language defined in the configuration is considered the default one. This means it will be applied to code blocks loaded from data that have no CSS `class` specified (or no `class` matching the {@link module:code-block/codeblock~CodeBlockConfig#languages configuration}). It will also be used when creating new code blocks using the toolbar button. By default it is "Plain text" (`language-plaintext` CSS class).
+	The first language defined in the configuration is considered the default one. This means it will be applied to code blocks loaded from the data that have no CSS `class` specified (or no `class` matching the {@link module:code-block/codeblock~CodeBlockConfig#languages configuration}). It will also be used when creating new code blocks using the toolbar button. By default it is "Plain text" (the `language-plaintext` CSS class).
 </info-box>
 
 ### Integration with code highlighters
 
-Although the live code block highlighting is impossible when editing in CKEditor 5 ([learn more](https://github.com/ckeditor/ckeditor5/issues/436#issuecomment-548399675)), the content can be highlighted when displayed in the frontend (e.g. in blog posts, messages, etc.).
+Although live code block highlighting is impossible when editing in CKEditor 5 ([learn more](https://github.com/ckeditor/ckeditor5/issues/436#issuecomment-548399675)), the content can be highlighted when displayed in the frontend (e.g. in blog posts, messages, etc.).
 
-The code language {@link module:code-block/codeblock~CodeBlockConfig#languages configuration} helps to integrate with external code highlighters (e.g. [highlight.js](https://highlightjs.org/) or [Prism](https://prismjs.com/)). Please refer to the documentation of the highlighter of your choice and make sure CSS classes configured in `codeBlock.languages` correspond with the code syntax auto–detection feature of the highlighter.
+The code language {@link module:code-block/codeblock~CodeBlockConfig#languages configuration} helps to integrate with external code highlighters (e.g. [highlight.js](https://highlightjs.org/) or [Prism](https://prismjs.com/)). Please refer to the documentation of the highlighter of your choice and make sure the CSS classes configured in `codeBlock.languages` correspond with the code syntax auto–detection feature of the highlighter.
 
 ## Tips and tweaks
 
@@ -79,11 +83,11 @@ The code language {@link module:code-block/codeblock~CodeBlockConfig#languages c
 
 There could be situations when there is no obvious way to set the caret before or after a block of code and type. This can happen when the code block is preceded or followed by a widget (e.g. a table) or when the code block is the first or the last child of the document (or both).
 
-* To type **before the code block**: Put the selection at the beginning of the first line of the code block and press <kbd>Enter</kbd>. Move the selection to the empty line that has been created and press <kbd>Enter</kbd> again. A new paragraph will be created before the code block you can type in.
+* To type **before the code block**: Put the selection at the beginning of the first line of the code block and press <kbd>Enter</kbd>. Move the selection to the empty line that has been created and press <kbd>Enter</kbd> again. A new paragraph that you can type in will be created before the code block.
 
 {@img assets/img/typing-before.gif 770 The animation shows typing before the code blocks in CKEditor 5 rich text editor.}
 
-* To type **after the code block**: Put the selection at the end of the last line of the code block and press <kbd>Enter</kbd> twice. A new paragraph will be created after the code block you can type in.
+* To type **after the code block**: Put the selection at the end of the last line of the code block and press <kbd>Enter</kbd> twice. A new paragraph that you can type in will be created after the code block.
 
 {@img assets/img/typing-after.gif 770 The animation shows typing after the code blocks in CKEditor 5 rich text editor.}
 
@@ -101,7 +105,7 @@ You can change the indentation of the code using keyboard shortcuts and toolbar
 </info-box>
 
 <info-box>
-	You can disable the indentation tools and their associated keystrokes altogether by setting the {@link module:code-block/codeblock~CodeBlockConfig#indentSequence `codeBlock.indentSequence`}  configuration `false`.
+	You can disable the indentation tools and their associated keystrokes altogether by setting the {@link module:code-block/codeblock~CodeBlockConfig#indentSequence `codeBlock.indentSequence`}  configuration to `false`.
 </info-box>
 
 ### Preserving line indentation
@@ -112,13 +116,13 @@ To speed up the editing, when typing in a code block, the indentation of the cur
 
 ## Installation
 
-To add this feature to your editor install the [`@ckeditor/ckeditor5-code-block`](https://www.npmjs.com/package/@ckeditor/ckeditor5-code-block) package:
+To add the code blocks feature to your rich-text editor, install the [`@ckeditor/ckeditor5-code-block`](https://www.npmjs.com/package/@ckeditor/ckeditor5-code-block) package:
 
-```bash
+```
 npm install --save @ckeditor/ckeditor5-code-block
 ```
 
-And add it to your plugin list and the toolbar configuration:
+Then add it to your plugin list and the toolbar configuration:
 
 ```js
 import CodeBlock from '@ckeditor/ckeditor5-code-block/src/codeblock';
@@ -140,10 +144,10 @@ ClassicEditor
 
 The {@link module:code-block/codeblock~CodeBlock} plugin registers:
 
-* The `'codeBlock'` split button with a dropdown allowing to choose the language of the block,
+* The `'codeBlock'` split button with a dropdown allowing to choose the language of the block.
 * The {@link module:code-block/codeblockcommand~CodeBlockCommand `'codeBlock'`} command.
 
-	The command converts selected editor content into a code block. If no content is selected, it creates a new code block at the place of the selection.
+	The command converts selected WYSIWYG editor content into a code block. If no content is selected, it creates a new code block at the place of the selection.
 
 	You can choose which language the code block is written in when executing the command. The language will be set in the editor model and reflected as a CSS class visible in the editing view and the editor (data) output:
 
@@ -171,7 +175,7 @@ The {@link module:code-block/codeblock~CodeBlock} plugin registers:
 	]
 	```
 
-	**Note**: If you execute a command with a specific `language` when the selection is anchored in a code block and use the additional `forceValue: true` parameter, it will update the language of this particular block.
+	**Note**: If you execute the command with a specific `language` when the selection is anchored in a code block, and use the additional `forceValue: true` parameter, it will update the language of this particular block.
 
 	```js
 	editor.execute( 'codeBlock', { language: 'java', forceValue: true } );
@@ -180,10 +184,10 @@ The {@link module:code-block/codeblock~CodeBlock} plugin registers:
 	**Note**: If the selection is already in a code block, executing the command will convert the block back into plain paragraphs.
 * The {@link module:code-block/indentcodeblockcommand~IndentCodeBlockCommand `'indentCodeBlock'`} and {@link module:code-block/outdentcodeblockcommand~OutdentCodeBlockCommand `'outdentCodeBlock'`} commands.
 
-	Both commands are used by the <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keystrokes as described in [one of the chapters](#changing-line-indentation):
+	Both commands are used by the <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keystrokes as described in the [section about indentation](#changing-line-indentation):
 
-	* The former is enabled when the selection is anchored anywhere in the code block and allows increasing the indentation of the lines of code. The indentation character (sequence) is configurable using the {@link module:code-block/codeblock~CodeBlockConfig#indentSequence `codeBlock.indentSequence`} configuration.
-	* The later is enabled when the indentation of any code lines within the selection can be decreased. Executing it will remove the indentation character (sequence) from those lines, as configured by {@link module:code-block/codeblock~CodeBlockConfig#indentSequence `codeBlock.indentSequence`}.
+	* The `'indentCodeBlock'` command is enabled when the selection is anchored anywhere in the code block and it allows increasing the indentation of the lines of code. The indentation character (sequence) is configurable using the {@link module:code-block/codeblock~CodeBlockConfig#indentSequence `codeBlock.indentSequence`} configuration.
+	* The `'outdentCodeBlock'` command is enabled when the indentation of any code lines within the selection can be decreased. Executing it will remove the indentation character (sequence) from these lines, as configured by {@link module:code-block/codeblock~CodeBlockConfig#indentSequence `codeBlock.indentSequence`}.
 
 <info-box>
 	We recommend using the official {@link framework/guides/development-tools#ckeditor-5-inspector CKEditor 5 inspector} for development and debugging. It will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more.

+ 9 - 8
packages/ckeditor5-code-block/src/codeblock.js

@@ -14,10 +14,11 @@ import CodeBlockUI from './codeblockui';
 /**
  * The code block plugin.
  *
- * For more information about this feature check the {@glink api/code-block package page}.
+ * For more information about this feature check the {@glink api/code-block package page} and the
+ * {@glink features/code-blocks code block feature guide}.
  *
- * This is a "glue" plugin which loads the {@link module:code-block/codeblockediting~CodeBlockEditing code block editing feature}
- * and {@link module:code-block/codeblockui~CodeBlockUI code block UI feature}.
+ * This is a "glue" plugin that loads the {@link module:code-block/codeblockediting~CodeBlockEditing code block editing feature}
+ * and the {@link module:code-block/codeblockui~CodeBlockUI code block UI feature}.
  *
  * @extends module:core/plugin~Plugin
  */
@@ -50,7 +51,7 @@ export default class CodeBlock extends Plugin {
  *
  *		ClassicEditor
  *			.create( editorElement, {
- * 				codeBlock:  ... // Code block feature configuration.
+ * 				codeBlock:  ... // The code block feature configuration.
  *			} )
  *			.then( ... )
  *			.catch( ... );
@@ -70,7 +71,7 @@ export default class CodeBlock extends Plugin {
  *
  * @typedef {Object} module:code-block/codeblock~CodeBlockLanguageDefinition
  * @property {String} language The name of the language that will be stored in the model attribute. Also, when `class`
- * is not specified, it will also be used to create the CSS class associated with the language (prefixed by "language-").
+ * is not specified, it will be used to create the CSS class associated with the language (prefixed by "language-").
  * @property {String} label The human–readable label associated with the language and displayed in the UI.
  * @property {String} [class] The CSS class associated with the language. When not specified the `language`
  * property is used to create a class prefixed by "language-".
@@ -102,13 +103,13 @@ export default class CodeBlock extends Plugin {
  *
  *		<pre><code class="language-javascript">window.alert( 'Hello world!' )</code></pre>
  *
- * You can customize the CSS class by specifying an optional `class` property in a language definition:
+ * You can customize the CSS class by specifying an optional `class` property in the language definition:
  *
  *		ClassicEditor
  *			.create( document.querySelector( '#editor' ), {
  *				codeBlock: {
  *					languages: [
- *						// Do not render CSS class for the plain text code blocks.
+ *						// Do not render the CSS class for the plain text code blocks.
  * 						{ language: 'plaintext', label: 'Plain text', class: '' },
  *
  *						// Use the "php-code" class for PHP code blocks.
@@ -144,7 +145,7 @@ export default class CodeBlock extends Plugin {
  *		]
  *
  * **Note**: The first language defined in the configuration is considered the default one. This means it will be
- * applied to code blocks loaded from data that have no CSS `class` specified (or no matching `class` in the config).
+ * applied to code blocks loaded from the data that have no CSS `class` specified (or no matching `class` in the configuration).
  * It will also be used when creating new code blocks using the main UI button. By default it is "Plain text".
  *
  * @member {Array.<module:code-block/codeblock~CodeBlockLanguageDefinition>} module:code-block/codeblock~CodeBlockConfig#languages

+ 1 - 1
packages/ckeditor5-code-block/src/codeblockcommand.js

@@ -34,7 +34,7 @@ export default class CodeBlockCommand extends Command {
 	}
 
 	/**
-	 * Executes the command. When the command {@link #value is on}, all top-most code blocks within
+	 * Executes the command. When the command {@link #value is on}, all topmost code blocks within
 	 * the selection will be removed. If it is off, all selected blocks will be flattened and
 	 * wrapped by a code block.
 	 *

+ 4 - 4
packages/ckeditor5-code-block/src/converters.js

@@ -13,7 +13,7 @@ import {
 } from './utils';
 
 /**
- * A modelview (both editing and data) converter for the `codeBlock` element.
+ * A model-to-view (both editing and data) converter for the `codeBlock` element.
  *
  * Sample input:
  *
@@ -30,7 +30,7 @@ import {
  * @param {module:engine/model/model~Model} model
  * @param {Array.<module:code-block/codeblock~CodeBlockLanguageDefinition>} languageDefs The normalized language
  * configuration passed to the feature.
- * @param {Boolean} [useLabels=false] When `true`, the `<pre>` will get a `data-language` attribute with a
+ * @param {Boolean} [useLabels=false] When `true`, the `<pre>` element will get a `data-language` attribute with a
  * human–readable label of the language. Used only in the editing.
  * @returns {Function} Returns a conversion callback.
  */
@@ -83,7 +83,7 @@ export function modelToViewCodeBlockInsertion( model, languageDefs, useLabels =
 }
 
 /**
- * A model → data-view converter for the new line (`softBreak`) separator.
+ * A model-to-data view converter for the new line (`softBreak`) separator.
  *
  * Sample input:
  *
@@ -115,7 +115,7 @@ export function modelToDataViewSoftBreakInsertion( model ) {
 }
 
 /**
- * A view → model converter for `<pre>` with `<code>` html.
+ * A view-to-model converter for `<pre>` with the `<code>` HTML.
  *
  * Sample input:
  *

+ 1 - 1
packages/ckeditor5-code-block/src/outdentcodeblockcommand.js

@@ -24,7 +24,7 @@ export default class OutdentCodeBlockCommand extends Command {
 		super( editor );
 
 		/**
-		 * A sequence of characters or removed from the line when the command is executed.
+		 * A sequence of characters removed from the line when the command is executed.
 		 *
 		 * @readonly
 		 * @private

+ 10 - 10
packages/ckeditor5-code-block/src/utils.js

@@ -12,11 +12,11 @@ import first from '@ckeditor/ckeditor5-utils/src/first';
 /**
  * Returns code block languages as defined in `config.codeBlock.languages` but processed:
  *
- * * to consider the editor localization, i.e. to display {@link module:code-block/codeblock~CodeBlockLanguageDefinition}
- * in the correct language — there is no way to use {@link module:utils/locale~Locale#t} when the user
+ * * To consider the editor localization, i.e. to display {@link module:code-block/codeblock~CodeBlockLanguageDefinition}
+ * in the correct language. There is no way to use {@link module:utils/locale~Locale#t} when the user
  * configuration is defined because the editor does not exist yet.
- * * to make sure each definition has a CSS class associated with it even if not specified
- * in the original config.
+ * * To make sure each definition has a CSS class associated with it even if not specified
+ * in the original configuration.
  *
  * @param {module:core/editor/editor~Editor} editor
  * @returns {Array.<module:code-block/codeblock~CodeBlockLanguageDefinition>}.
@@ -39,7 +39,7 @@ export function getNormalizedAndLocalizedLanguageDefinitions( editor ) {
 }
 
 /**
- * Returns an object associating certain language definition properties with another. For instance:
+ * Returns an object associating certain language definition properties with others. For instance:
  *
  * For:
  *
@@ -106,7 +106,7 @@ export function getLeadingWhiteSpaces( textNode ) {
  *		</DocumentFragment>
  *
  * @param {module:engine/model/writer~Writer} writer
- * @param {String} text A raw code text to be converted.
+ * @param {String} text The raw code text to be converted.
  */
 export function rawSnippetTextToModelDocumentFragment( writer, text ) {
 	const fragment = writer.createDocumentFragment();
@@ -140,7 +140,7 @@ export function rawSnippetTextToModelDocumentFragment( writer, text ) {
  *		    baz]qux                                   ^bazqux
  *		</codeBlock>                               </codeBlock>
  *
- * it also works across other non–code blocks:
+ * It also works across other non–code blocks:
  *
  *		<codeBlock>                                <codeBlock>
  *		    foo[bar                                   ^foobar
@@ -150,8 +150,8 @@ export function rawSnippetTextToModelDocumentFragment( writer, text ) {
  *		    baz]qux                                   ^bazqux
  *		</codeBlock>                               </codeBlock>
  *
- * **Note:** The positions are in the reverse order so they do not get outdated when iterating over them and
- * the writer inserts or removes things.
+ * **Note:** The positions are in reverse order so they do not get outdated when iterating over them and
+ * the writer inserts or removes things at the same time.
  *
  * **Note:** The position is situated after the leading white spaces in the text node.
  *
@@ -194,7 +194,7 @@ export function getIndentOutdentPositions( model ) {
 }
 
 /**
- * Checks if any of the blocks within model selection is a code block.
+ * Checks if any of the blocks within the model selection is a code block.
  *
  * @param {module:engine/model/selection~Selection} selection
  * @returns {Boolean}