docs: Rewriting pages about editors (#2552)

* initial changes

* fix: rewriting the IDE-related pages

* edit 'Adding or removing extensions in the embedded Open VSX registry instance'

* rewrite the assembly and remove the outdated concept module

* new edits

* further edits

* fix: typo

* remove the mention of the editorconfig file

* Update modules/end-user-guide/pages/url-parameter-for-the-cloud-ide.adoc

Co-authored-by: Mario Loriedo <mario.loriedo@gmail.com>

* Update modules/end-user-guide/pages/url-parameter-for-the-cloud-ide.adoc

Co-authored-by: Mario Loriedo <mario.loriedo@gmail.com>

* initial changes in response to Mario's feedback

* work in progress

* remove 'cloud' from IDE

* add an admonition requested by Mario

* incorporate new feedback from Artem

* Restarting the jobs

* Add 'Restart Workspace from Local Devfile' command to the corresponding section

Co-authored-by: Max Leonov <mleonov@redhat.com>

* rewrite of the vsx-related procedure due to changes in vsx.org

* Update modules/end-user-guide/partials/proc_adding-vs-code-extensions.adoc

* edit proc_adding-or-removing-extensions-in-the-embedded-open-vsx-registry-instance.adoc

* Apply suggestions from code review

* Update modules/end-user-guide/pages/defining-a-common-ide.adoc

* Update modules/end-user-guide/pages/url-parameter-for-the-ide.adoc

* Update modules/end-user-guide/pages/ides-in-workspaces.adoc

Co-authored-by: Jana Vrbkova <jvrbkova@redhat.com>

* Apply suggestions from code review

* minor edit

* another minor edit

* another minor edit

* another minor edit

* another minor edit

* another minor edit

* another minor edit

* minor edit

* minor edit

* minor edit

* apply changes requested in #2552 (comment)

* manually apply suggestion from code review

* minor edit

* test rearranging the steps due to the snippet file

* rearrange admonition content

* minor edit

* minor edit

* Update modules/end-user-guide/pages/microsoft-visual-studio-code-open-source-ide.adoc

Co-authored-by: Mario Loriedo <mario.loriedo@gmail.com>

* Update modules/end-user-guide/partials/proc_adding-vs-code-extensions.adoc

* rename section heading and file name

* edit the section heading and file name

* minor edit

* merge two tips

* temporary xref fix - correct text, parking file

* temporary cross-reference fix

---------

Co-authored-by: Mario Loriedo <mario.loriedo@gmail.com>
Co-authored-by: RomanNikitenko <rnikiten@redhat.com>
Co-authored-by: Jana Vrbkova <jvrbkova@redhat.com>

modules/administration-guide/partials/proc_adding-or-removing-extensions-in-the-embedded-open-vsx-registry-instance.adoc

@@ -15,43 +15,58 @@ pass:[<!-- vale RedHat.TermsErrors = YES -->]
 
 .Procedure
 
-include::example$snip_{project-context}-steps-to-add-or-remove-extensions-in-openvsx-sync-json.adoc[]
+. Get the publisher and extension names of each chosen extension:
+
+.. Find the extension on the link:https://www.open-vsx.org/[Open VSX registry website] and copy the URL of the extension's listing page.
 
-** If the extension is published on link:https://open-vsx.org[open-vsx.org], you can add its extension `id` in the format __<published_by>__.__<unique_identifier>__. You can find the `id` details on the extension's listing page on link:https://open-vsx.org[open-vsx.org].
+.. Extract the __<publisher>__ and __<extension>__ names from the copied URL:
 +
-[source,json,subs="+quotes"]
+[subs="+quotes"]
 ----
-    {
-        "id": "__<published_by>__.__<unique_identifier>__"
-    }
+https://www.open-vsx.org/extension/__<publisher>__/__<extension>__
 ----
 +
 [TIP]
 ====
-The latest extension version on link:https://open-vsx.org[open-vsx.org] is the default. Alternatively, you can add `"version": "__<extension_version>__"` on a new line to specify a version.
+
+If the extension is only available from link:https://marketplace.visualstudio.com/VSCode[Microsoft Visual Studio Marketplace], but not link:https://open-vsx.org[Open VSX], you can ask the extension publisher to also publish it on link:https://open-vsx.org[open-vsx.org] according to these link:https://github.com/eclipse/openvsx/wiki/Publishing-Extensions#how-to-publish-an-extension[instructions], potentially using this link:https://github.com/marketplace/actions/publish-vs-code-extension[GitHub action].
+
+If the extension publisher is unavailable or unwilling to publish the extension to link:https://open-vsx.org[open-vsx.org], and if there is no Open VSX equivalent of the extension, consider link:https://github.com/open-vsx/publish-extensions/issues[reporting an issue] to the Open VSX team.
+
 ====
 
-** If the extension is only available from link:https://marketplace.visualstudio.com/VSCode[Microsoft Visual Studio Marketplace], but not link:https://open-vsx.org[Open VSX], you can ask the extension publisher to also publish it on link:https://open-vsx.org[open-vsx.org] according to these link:https://github.com/eclipse/openvsx/wiki/Publishing-Extensions#how-to-publish-an-extension[instructions], potentially using this link:https://github.com/marketplace/actions/publish-vs-code-extension[GitHub action].
+include::example$snip_{project-context}-steps-to-add-or-remove-extensions-in-openvsx-sync-json.adoc[]
+
+** To add extensions, add the publisher and extension names to the `openvsx-sync.json` file.
+** To remove extensions, remove the publisher and extension names from the `openvsx-sync.json` file.
+** Use the following JSON syntax:
++
+[source,json,subs="+quotes"]
+----
+    {
+        "id": "__<publisher>__.__<extension>__"
+    }
+----
 +
 [TIP]
 ====
-* If the extension publisher is unavailable or unwilling to publish the extension to link:https://open-vsx.org[open-vsx.org], and if there is no Open VSX equivalent of the extension, consider link:https://github.com/open-vsx/publish-extensions/issues[reporting an issue] to the Open VSX team.
 
-* If you have a closed-source extension or an extension developed only for internal use in your company, you can add the extension directly from a `.vsix` file by using a URL accessible to your custom plugin registry container:
+* The latest extension version on link:https://open-vsx.org[open-vsx.org] is the default. Alternatively, you can add `"version": "__<extension_version>__"` on a new line to specify a version.
+
+* If you have a closed-source extension or an extension developed only for internal use in your organization, you can add the extension directly from a `.vsix` file by using a URL accessible to your custom plugin registry container:
 +
 [source,json,subs="+quotes"]
 ----
     {
-        "id": "__<published_by>__.__<unique_identifier>__",
+        "id": "__<publisher>__.__<extension>__",
         "download": "__<url_to_download_vsix_file>__",
         "version": "__<extension_version>__"
     }
 ----
-====
-+
-WARNING: Please read the link:https://aka.ms/vsmarketplace-ToU[Terms of Use] for the link:https://marketplace.visualstudio.com/VSCode[Microsoft Visual Studio Marketplace] before using its resources.
 
-** You can remove the extension by deleting it from the `openvsx-sync.json` file.
+* Read the link:https://aka.ms/vsmarketplace-ToU[Terms of Use] for the link:https://marketplace.visualstudio.com/VSCode[Microsoft Visual Studio Marketplace] before using its resources.
+
+====
 
 . Build the plugin registry container image and publish it to a container registry like link:https://quay.io/[quay.io]:
 
@@ -69,7 +84,7 @@ $ ./build.sh -o __<username>__ -r quay.io -t custom
 $ {docker-cli} push quay.io/__<username/plugin_registry:custom>__
 ----
 
-. Edit the `CheCluster` custom resource in your organization's cluster to point to the image (for example, on link:https://quay.io/[quay.io]) and then save the changes:
+. Edit the `CheCluster` custom resource in your organization's cluster to point to the image (for example, on link:https://quay.io/[quay.io]) and save the changes:
 +
 [source,yaml,subs="+quotes"]
 ----
@@ -82,6 +97,8 @@ spec:
       openVSXURL: '' 
 ----
 
+.Verification
+
 . Check that the `plugin-registry` pod has restarted and is running.
 
 . Restart the workspace and check the available extensions in the *Extensions* view of the workspace IDE.

modules/administration-guide/partials/proc_selecting-an-open-vsx-registry-instance.adoc

@@ -23,7 +23,7 @@ spec:
 ====
 * The default `openVSXURL` value is `pass:c,a,q[https://open-vsx.org]`.
  
-* To select the embedded Open VSX registry instance in the `plugin-registry` pod, use `openVSXURL: ''`. See the next section for how to customize the included extensions.
+* To select the embedded Open VSX registry instance in the `plugin-registry` pod, use `openVSXURL: ''`. See the next section for how to customize the list of included extensions.
 
 * You can also point `openVSXURL` at the URL of a standalone Open VSX registry instance if its URL is accessible from within your organization's cluster and not blocked by a proxy. 
 ====

modules/end-user-guide/nav.adoc

@@ -10,7 +10,7 @@
 ** xref:starting-a-new-workspace-from-a-devfile-url.adoc[]
 ** xref:optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc[]
 *** xref:url-parameter-concatenation.adoc[]
-*** xref:url-parameter-for-the-workspace-ide.adoc[]
+*** xref:url-parameter-for-the-ide.adoc[]
 *** xref:url-parameter-for-starting-duplicate-workspaces.adoc[]
 *** xref:url-parameter-for-the-devfile-file-name.adoc[]
 *** xref:url-parameter-for-the-devfile-file-path.adoc[]
@@ -20,9 +20,9 @@
 ** xref:authenticating-to-a-git-server-from-a-workspace.adoc[]
 * xref:customizing-workspace-components.adoc[]
 * xref:devfile-introduction.adoc[]
-* xref:selecting-a-workspace-ide.adoc[]
-** xref:selecting-an-in-browser-ide-for-one-new-workspace.adoc[]
-** xref:selecting-an-in-browser-ide-for-all-workspaces-that-clone-the-same-git-repository.adoc[]
+* xref:ides-in-workspaces.adoc[]
+** xref:defining-a-common-ide.adoc[]
+** xref:microsoft-visual-studio-code-open-source-ide.adoc[]
 * xref:using-credentials-and-configurations-in-workspaces.adoc[]
 ** xref:mounting-secrets.adoc[]
 *** xref:creating-image-pull-secrets.adoc[]

modules/end-user-guide/pages/customizing-workspace-components.adoc

@@ -12,8 +12,8 @@ To customize workspace components:
 
 * xref:starting-a-new-workspace-with-a-clone-of-a-git-repository.adoc[Choose a Git repository for your workspace].
 
-* xref:devfile-introduction.adoc[Use a devfile]
+* xref:devfile-introduction.adoc[Use a devfile].
 
-* xref:selecting-a-workspace-ide.adoc[Select and customize your in-browser IDE].
+* xref:ides-in-workspaces.adoc[Configure an IDE].
 
 * Add {prod-short} specific attributes in addition to the generic devfile specification.

modules/end-user-guide/pages/defining-a-common-ide.adoc

@@ -0,0 +1,17 @@
+:_content-type: PROCEDURE
+:navtitle : Defining a common IDE
+:description: Defining a common IDE
+:keywords: select-IDE, che-editor, che-editor-yaml
+:page-aliases: specifying-an-in-browser-ide-for-a-git-repository-by-using-che-editor.yaml.adoc, selecting-an-in-browser-ide-for-all-workspaces-that-clone-the-same-git-repository.adoc
+
+[id="defining-a-common-ide"]
+= Defining a common IDE
+
+While the xref:url-parameter-for-the-ide.adoc[URL parameter for the IDE] enables you to start a workspace with your personal choice of the supported IDE, you might find it more convenient to define the same IDE for all workspaces for the same source code Git repository. To do so, use the `che-editor.yaml` file. This file supports even a detailed IDE configuration.
+
+TIP: If you intend to start most or all of your organization's workspaces with the same IDE other than Microsoft Visual Studio Code - Open Source, an alternative is for the administrator of your organization's {prod-short} instance to specify another supported IDE as the default IDE at the {prod-short} instance level. This can be done with `.spec.devEnvironments.defaultEditor` in the `CheCluster` Custom Resource.
+
+include::partial$proc_setting-up-che-editor-yaml.adoc[leveloffset=+1]
+
+include::partial$ref_parameters-for-che-editor-yaml.adoc[leveloffset=+1]
+

modules/end-user-guide/pages/ides-in-workspaces.adoc

@@ -0,0 +1,30 @@
+:_content-type: PROCEDURE
+:description: IDEs in workspaces
+:keywords: configuring, workspace, editor, ide, cloud ide
+:navtitle: IDEs in workspaces
+:page-aliases:
+
+[id="ides-in-workspaces"]
+= IDEs in workspaces
+
+== Supported IDEs
+
+The default IDE in a new workspace is Microsoft Visual Studio Code - Open Source. Alternatively, you can choose another supported IDE:
+
+.Supported IDEs 
+
+[cols="1,1a,1a"]
+|===
+| IDE | `id` | Note
+
+include::example$snip_{project-context}-table-of-supported-editors.adoc[]
+
+|===
+
+== Repository-level IDE configuration in {prod-short}
+
+You can store IDE configuration files directly in the remote Git repository that contains your project source code. This way, one common IDE configuration is applied to all new workspaces that feature a clone of that repository. Such IDE configuration files might include the following:
+
+* xref:defining-a-common-ide.adoc[The `/.che/che-editor.yaml` file] that stores a definition of the chosen IDE.
+
+* IDE-specific configuration files that one would typically store locally for a desktop IDE. For example, xref:microsoft-visual-studio-code-open-source-ide.adoc[the `/.vscode/extensions.json` file.]

modules/end-user-guide/pages/microsoft-visual-studio-code-open-source-ide.adoc

@@ -0,0 +1,31 @@
+:_content-type: CONCEPT
+:description: Microsoft Visual Studio Code - Open Source IDE
+:keywords: user-guide, selecting, IDE, select, selecting, editor, ide, vs-code, visual-studio, visual-studio-code, jetbrains, intellij, pycharm, theia, che-theia
+:navtitle: Microsoft Visual Studio Code - Open Source
+:page-aliases:
+
+[id="microsoft-visual-studio-code-open-source-ide"]
+= Microsoft Visual Studio Code - Open Source IDE
+
+The {prod-short} build of link:https://github.com/microsoft/vscode[Microsoft Visual Studio Code - Open Source] is the default IDE of a new workspace.
+
+You can automate installation of Microsoft Visual Studio Code extensions from the xref:administration-guide:extensions-for-microsoft-visual-studio-code-open-source.adoc[Open VSX registry] at workspace startup. See _Automating installation of Microsoft Visual Studio Code extensions at workspace startup_.
+
+[TIP]
+====
+
+* Use link:https://code.visualstudio.com/Docs/editor/tasks[Tasks] to find and run the commands specified in `devfile.yaml`.
+
+* Use *{prod2}* commands by clicking *{prod2}* in the link:https://code.visualstudio.com/api/ux-guidelines/status-bar[Status Bar] or finding them through the link:https://code.visualstudio.com/api/ux-guidelines/command-palette[Command Palette]:
+
+** *{prod2}: Open Dashboard*
+** *{prod2}: Stop Workspace*
+** *{prod2}: Restart Workspace*
+** *{prod2}: Restart Workspace from Local Devfile*
+** *{prod2}: Open Documentation*
+
+====
+
+NOTE: You might see your organization's branding in this IDE if your organization customized it through a branded build.
+
+include::partial$proc_automating-installation-of-microsoft-visual-studio-code-extensions-at-workspace-startup.adoc[leveloffset=+1]

modules/end-user-guide/pages/optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc

@@ -10,7 +10,7 @@
 When you start a new workspace, {prod-short} configures the workspace according to the instructions in the devfile. When you use a URL to start a new workspace, you can append optional parameters to the URL that further configure the workspace. You can use these parameters to specify a workspace IDE, start duplicate workspaces, and specify a devfile file name or path.
 
 * xref:url-parameter-concatenation.adoc[]
-* xref:url-parameter-for-the-workspace-ide.adoc[]
+* xref:url-parameter-for-the-ide.adoc[]
 * xref:url-parameter-for-starting-duplicate-workspaces.adoc[]
 * xref:url-parameter-for-the-devfile-file-name.adoc[]
 * xref:url-parameter-for-the-devfile-file-path.adoc[]

modules/end-user-guide/pages/url-parameter-for-the-ide.adoc

@@ -0,0 +1,50 @@
+:_content-type: CONCEPT
+:description: URL parameter for the IDE
+:keywords: ide, editor, workspace-ide, workspace-editor
+:navtitle: URL parameter for the IDE
+:page-aliases: url-parameter-for-the-in-browser-ide.adoc
+
+[id="url-parameter-for-the-ide"]
+= URL parameter for the IDE
+
+You can use the `che-editor=` URL parameter to specify a supported IDE when starting a workspace.
+
+TIP: Use the `che-editor=` parameter when you cannot add or edit a xref:defining-a-common-ide.adoc[`/.che/che-editor.yaml`] file in the source-code Git repository to be cloned for workspaces.
+
+NOTE: The `che-editor=` parameter overrides the xref:defining-a-common-ide.adoc[`/.che/che-editor.yaml`] file.
+
+This parameter accepts two types of values:
+
+* `che-editor=__<editor_key>__`
++
+[source,subs="+quotes,+attributes,+macros"]
+----
+pass:c,a,q[{prod-url}]#__<git_repository_url>__?che-editor=__<editor_key>__
+----
++
+
+.The URL parameter `__<editor_key>__` values for supported IDEs
+[cols="1,1a,1a"]
+|===
+| IDE | `__<editor_key>__` value | Note
+
+include::example$snip_{project-context}-table-of-supported-editors.adoc[]
+
+|===
+
+* `che-editor=__<url_to_a_file>__`
++
+[source,subs="+quotes,+attributes,+macros"]
+----
+pass:c,a,q[{prod-url}]#__<git_repository_url>__?che-editor=__<url_to_a_file>__# <1>
+----
+<1> URL to a file with link:https://devfile.io/docs/2.2.0/what-is-a-devfile[devfile content].
++
+[TIP]
+====
+
+* The URL must point to the raw file content.
+
+* To use this parameter with a xref:defining-a-common-ide.adoc[`che-editor.yaml`] file, copy the file with another name or path, and remove the line with `inline` from the file.
+
+====