LG-53877 LG-53879 - review core section

apiconcepts/core/overview.md

@@ -1,26 +1,28 @@
-Plug-in Framework Overview
-====
-This help system describes the Plug-in Framework. This framework offers plug-in functionality to applications and components. Application developers can define extension points and dynamically load any plug-ins providing extensions targeting these extension points using the plug-in framework.
-
-Version
----
-The version of the Plug-in Framework documented here is the one that was released with Var:ProductNameWithEdition.
-
-Main Concepts and Definitions
-----
-This section introduces a number of concepts and definitions that are central to the plug-in framework.
-
-* **Hosting Application** <br>
-  This is the application (or component) which provides plug-in capabilities. The hosting application will define certain extension points and will use the plug-in framework to discover and load plug-ins and extensions for these extension points.<br><br>
-* **Extension Point** <br>
-  An extension point is a point in the application or component that allows adding extensions to it. An extension point is defined by a .Net attribute, called an extension attribute. All extension attributes should derive from the [ExtensionAttribute](../../api/core/Sdl.Core.PluginFramework.ExtensionAttribute.yml) base class.<br><br>
-* **Extension** <br>
-  An extension is an individual unit of logic that adds functionality to an application or component through a specific extension point. An extension is defined by a .Net class, defined in a plug-in assembly, annotated with the extension attribute that identifies the extension point it targets. An extension class typically implements an interface that is required by the extension point it is targeting.<br><br>
-* **Plug-in** <br>
-  A plug-in can contain one or more extensions. A plug-in consist is a .Net assembly which is annotated with the assembly-level [PluginAttribute](../../api/core/Sdl.Core.PluginFramework.PluginAttribute.yml), which has a Name property that contains the friendly name of the plug-in. The presence of this attribute tells the framework that this is a plug-in assembly.<br><br>
-* **Plug-in Registry** <br>
-  The central object in the plug-in framework is the plug-in registry ([IPluginRegistry](../../api/core/Sdl.Core.PluginFramework.IPluginRegistry.yml)). The plug-in registry provides functionality to the host application to detect which plug-ins and extensions are available and create instances of the extensions provided by these plug-ins.<br><br>
-* **Plug-in Manifest** <br>
-  A plug-in manifest is an XML file, which contains serialized metadata about a plug-in assembly, it contains:
-    * The plug-in name, plus the plug-in assembly's name and version.
-    * A list of all the extensions defined within the plug-in assembly, together with the meta data defined in the extension attributes.
+# Plug-in Framework Overview
+The Plug-in Framework enables applications and components to support plug-in functionality. Developers can define extension points and dynamically load plug-ins that provide targeted extensions using this framework.
+
+## Version
+This documentation covers the version of the Plug-in Framework released with `Var:ProductNameWithEdition`.
+
+## Main Concepts and Definitions
+This section outlines key concepts and definitions central to the Plug-in Framework.
+
+### Hosting Application
+The hosting application (or component) provides plug-in capabilities. It defines extension points and uses the Plug-in Framework to discover and load plug-ins and extensions for these points.
+
+### Extension Point
+An extension point is a location in the application or component that supports adding extensions. It is defined by a .NET attribute, called an extension attribute. All extension attributes derive from the [ExtensionAttribute](../../api/core/Sdl.Core.PluginFramework.ExtensionAttribute.yml) base class.
+
+### Extension
+An extension is a unit of logic that enhances an application or component through a specific extension point. It is defined by a .NET class within a plug-in assembly and annotated with the extension attribute identifying its target extension point. Typically, an extension class implements an interface required by the targeted extension point.
+
+### Plug-in
+A plug-in contains one or more extensions. It is a .NET assembly annotated with the assembly-level [PluginAttribute](../../api/core/Sdl.Core.PluginFramework.PluginAttribute.yml), which includes a Name property for the plug-in's friendly name. This attribute indicates to the framework that the assembly is a plug-in.
+
+### Plug-in Registry
+The plug-in registry ([IPluginRegistry](../../api/core/Sdl.Core.PluginFramework.IPluginRegistry.yml)) is the central object in the framework. It enables the host application to detect available plug-ins and extensions and create instances of the extensions provided by these plug-ins.
+
+### Plug-in Manifest
+A plug-in manifest is an XML file containing serialized metadata about a plug-in assembly. It includes:
+- The plug-in name, assembly name, and version.
+- A list of all extensions defined within the plug-in assembly, along with metadata specified in the extension attributes.

apiconcepts/core/plugin_resources_and_localizability.md

@@ -1,41 +1,43 @@
-Plug-in Resources and Localizability
-======
+# Plug-in Resources and Localizability
 This section explains how to make extension meta-data localizable.
 
-Plug-in Resources and Localizability
------
-All the string metadata values used for the properties of the extension attributes shown in the example above are hard-coded strings. In reality these strings need to be localized.
+## Overview
+All string metadata values used for the properties of extension attributes in the example above are hard-coded strings. These strings need to be localized.
 
-For that reason, the framework allows adding a specific plug-in resource file to a plug-in project. Instead of hard-coding the strings in code, you can specify the key of a resource string defined in the plug-in resources file. The framework resolves these resource strings at runtime based on the current UI culture and automatically populates the string properties of extension attributes with the corresponding localized values.
+To achieve this, the framework allows adding a specific plug-in resource file to a plug-in project. Instead of hard-coding strings in code, you can specify the key of a resource string defined in the plug-in resource file. The framework resolves these resource strings at runtime based on the current UI culture and automatically populates the string properties of extension attributes with the corresponding localized values.
 
-To indicate that the value of a certain property needs to be retrieved from the plug-in resources file, the definition of that property within the extension attribute definition must be annotated with the `PluginResource` attribute. For instance, a plug-in button extension point, with a localizable `ToolTipText` property becomes:
+### Using the `PluginResource` Attribute
+To indicate that a property's value needs to be retrieved from the plug-in resource file, annotate the property within the extension attribute definition with the `PluginResource` attribute. For example, a plug-in button extension point with a localizable `ToolTipText` property becomes:
 
 # [C#](#tab/tabid-1)
 [!code-csharp[AdvancedPluginFramework](code_samples/AdvancedPluginFramework.cs#L25-L34)]
 ***
 <br>
 
-An extension targeting this extension point, `MyPluginButton`:
+An extension targeting this extension point, `MyPluginButton`, is defined as:
 
 # [C#](#tab/tabid-2)
 [!code-csharp[AdvancedPluginFramework](code_samples/AdvancedPluginFramework.cs#L40-L50)]
 ***
 <br>
 
-In the above code sample, `MyPluginButton_Name` and `MyPluginButton_ToolTipText` are keys of strings defined in the plugin resource file, `PluginResources.resx`.
-As mentioned before, the plug-in manifest generator requires that you pass the path to the plug-in resx file as the second parameter. To avoid having to load the plug-in assembly to get access to the embedded resource strings when the plug-in meta data is accessed, the plug-in manifest generator compiles an external .Net plug-in resource file. This compiled resource file is copied alongside the plug-in manifest file, so that it can be loaded separately from the plug-in assembly itself. For instance, for the plug-in assembly, PluginLibrary, this becomes:
+In the above code sample, `MyPluginButton_Name` and `MyPluginButton_ToolTipText` are keys of strings defined in the plug-in resource file, `PluginResources.resx`.
+The plug-in manifest generator requires the path to the plug-in `.resx` file as the second parameter. To avoid loading the plug-in assembly to access embedded resource strings when accessing plug-in metadata, the manifest generator compiles an external .NET plug-in resource file. This compiled resource file is copied alongside the plug-in manifest file, allowing it to be loaded separately from the plug-in assembly. For example, for the plug-in assembly `PluginLibrary`, the following files are generated:
 
 * `PluginLibrary.dll`: the plug-in assembly
 * `PluginLibrary.plugin.xml`: the plug-in manifest file
 * `PluginLibrary.plugin.resources`: the plug-in resources file containing strings for the neutral culture.
 * `PluginLibrary.plugin.*.resources`: any number of resource files containing the localized strings
 
-The use of the `PluginResource` attribute is supported in the following cases:
+### Supported Use Cases
+The `PluginResource` attribute can be used in the following cases:
 
 * Extension attribute string properties
 * Auxiliary extension attribute string properties
 * Assembly-level `PluginAttribute` string attributes
-For non-string properties, like for instance an icon, the plug-in resource file can also be used, however, because of the type difference, the value of these kinds of properties cannot be automatically resolved. Define the actual property as a string property, to which uses must assign a resource key. Then, when you need the actual icon, get it from the plug-in resource file using the `GetPluginResource<T>` method:
+
+### Non-String Properties
+For non-string properties, such as an icon, the plug-in resource file can also be used. However, due to type differences, these properties cannot be automatically resolved. Define the property as a string property, and assign a resource key to it. When the actual icon is needed, retrieve it from the plug-in resource file using the `GetPluginResource<T>` method:
 
 # [C#](#tab/tabid-3)
 [!code-csharp[AdvancedPluginFramework](code_samples/AdvancedPluginFramework.cs#L16-L17)]

apiconcepts/core/serialization_performance.md

@@ -1,19 +1,22 @@
-Serialization Performance
-=====
+## Serialization Performance
 This section describes how to make sure that extensions can be loaded in the most optimal way.
 
-Serialization Performance
------
+### Overview
 The automatic serialization mechanism that comes with .Net is quite handy, since it let’s you serialize and deserialize objects to and from xml in a virtually a single line of code.
 
-However, as it is often the case, there is a downside to this ease of use: the first time you serialize an object of a certain type, the .Net runtime uses reflection to get the list of properties of the type, then automatically generates code that can serialize and deserialize these properties, compiles that code to an assembly, and finally loads it.
+However, this ease of use comes with a downside: the first time you serialize an object of a certain type, the .NET runtime uses reflection to retrieve the list of properties of the type. It then generates code to serialize and deserialize these properties, compiles the code into an assembly, and loads it.
 
-Especially in the desktop application scenario, this will impact performance dramatically, since this process will be repeated for every extension or auxiliary extension attribute type that is used at start-up.
+In desktop application scenarios, this process can significantly impact performance, as it is repeated for every extension or auxiliary extension attribute type used at startup.
 
-We can avoid this automatic serialization overhead, by explicitly implementing the `System.Xml.Serialization.IXmlSerializable` interface. The extension attribute base class already defines the methods required by this interface: `GetSchema`, `ReadXml` and `WriteXml`. All you need to do is mark your attribute class to implement `IXmlSerializable` and override `ReadXml` and `WriteXml` to read and write additional properties, making sure to call the base class method to read and write the base class properties:
+### Optimizing Serialization
+To avoid the overhead of automatic serialization, explicitly implement the `System.Xml.Serialization.IXmlSerializable` interface. The extension attribute base class already defines the methods required by this interface: `GetSchema`, `ReadXml`, and `WriteXml`. To optimize serialization:
+
+1. Mark your attribute class to implement `IXmlSerializable`.
+2. Override `ReadXml` and `WriteXml` to handle additional properties.
+3. Ensure you call the base class methods to read and write base class properties.
 
 # [C#](#tab/tabid-1)
 [!code-csharp[AdvancedPluginFramework](code_samples/AdvancedPluginFramework.cs#L85-L110)]
 ***
 
-The plug-in framework calls the `ReadXml` and `WriteXml` methods directly, avoiding the overhead of automatic xml serialization.
+The plug-in framework directly calls the `ReadXml` and `WriteXml` methods, eliminating the overhead of automatic XML serialization.

apiconcepts/core/the_plugin_manifest_generator.md

@@ -1,15 +1,14 @@
 ---
 uid: the_plugin_manifest_generator.md
 ---
-The Plug-in Manifest Generator
-======
-The section describes how plug-in projects are built and how the plug-in manifest is generated.
+## The Plug-in Manifest Generator
+This section describes how plug-in projects are built and how the plug-in manifest is generated.
 
-Plug-in Manifest Generator
-----
-The purpose of the plug-in manifest is to avoid loading all the plug-in assemblies at runtime and reflecting over them to discover the available extensions, which would affect startup performance, an important aspect of desktop applications.
+### Overview
+The plug-in manifest prevents the need to load all plug-in assemblies at runtime and reflect over them to discover available extensions. This optimization significantly improves startup performance, which is critical for desktop applications.
 
- The plug-in manifest generator is implemented as an MSBuild task, which runs as part of the standard Var:VisualStudioEdition build. This build task is contained in [Sdl.Core.PluginFramework.Build](https://www.nuget.org/packages/Sdl.Core.PluginFramework.Build/) package that needs to be refreneced by the project.
+### Implementation
+The plug-in manifest generator is implemented as an MSBuild task, running as part of the standard Var:VisualStudioEdition build. This build task is included in the [Sdl.Core.PluginFramework.Build](https://www.nuget.org/packages/Sdl.Core.PluginFramework.Build/) package, which must be referenced by the project.
 
 ```xml
 <Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

apiconcepts/overview.md

@@ -1,23 +1,23 @@
 ## [Core](core/overview.md)
-This is the foundation which provides the plug-in framework available in Var:ProductName, used by other APIs to define extension points inside the software.
+The Core API is the foundation of Var:ProductName, providing the plug-in framework that enables other APIs to define extension points within the software.
 
 ## [File Type Support Framework](filetypesupport/overview.md)
-In order to translate content from a certain file type, Var:ProductName extracts it into an SDLXliff. If you want to work with an unsupported file type that isn't already available with Var:ProductName, you can use this API to extract the content and create the SDLXliff needed for translation.
+The File Type Support Framework API enables you to work with unsupported file types by extracting their content and generating the SDLXliff required for translation in Var:ProductName.
 
 ## [Project Automation](projectautomation/overview.md)
-There are many activities that must be done as part of the translation process and this is why Var:ProductName provides project management features, such as analysis, pre-translation and more. Using the Project Automation API, you can build a customized translation workflow based on activities specific to your needs.
+The Project Automation API allows you to streamline translation workflows by automating project management activities such as analysis, pre-translation, and more.
 
 ## [Translation Memory](translationmemory/overview.md)
-Translation memories are an essential piece of technology for translators. Var:ProductName comes with this capability, but if you're interested in using a different piece of technology for translation memories, you can enable that in Var:ProductName by creating a new translation memory provider.
+The Translation Memory API lets you integrate alternative translation memory technologies into Var:ProductName by developing custom translation memory providers.
 
 ## [Integration](integration/overview.md)
-This API enables you to extend or customize the user interface or create custom functionalities for Var:ProductName. You can create new views, new sections in the menu ribbon, new options in the context menu or hook into the editor to create, update or delete certain information.
+The Integration API enables you to enhance or customize the user interface and functionalities of Var:ProductName, including creating new views, adding menu options, and hooking into the editor.
 
 ## [Verification](verification/overview.md)
-Var:ProductName allows translators to check their work by running verifiers during translation. There are many ways to verify the quality of a translation and it can also become very specific. So to address that need, Var:ProductName allows custom verifiers to be built and run.
+The Verification API allows you to create and run custom verifiers to ensure translation quality during the translation process in Var:ProductName.
 
 ## [Batch Tasks](batchtasks/overview.md)
-As part of a project management workflow, there are certain tasks that need to be applied, such as pre-translation, analysis and more. Var:ProductName comes with a predefined set of tasks, but with this API, you can also create your own custom tasks that can be included in your workflows.
+The Batch Tasks API lets you develop custom tasks for project workflows, extending the predefined tasks available in Var:ProductName.
 
 ## [Terminology Provider](terminology/overview.md)
-This API allows you to enable the use of different terminology technology in Var:ProductName, by creating new terminology providers.
+The Terminology Provider API enables you to integrate alternative terminology technologies into Var:ProductName by building custom terminology providers.

apiconcepts/toc.yml

@@ -4,16 +4,13 @@
   href: core/overview.md
   items:
   - name: Plug-in Framework Overview
-    href: core/overview.md
-  - name: Plugin overview
-    href: core/pluginOverview.md
-    items:            
-    - name: Plug-in Resources and Localizability
-      href: core/plugin_resources_and_localizability.md    
-    - name: The Plug-in Manifest Generator
-      href: core/the_plugin_manifest_generator.md
-    - name: Serialization Performance
-      href: core/serialization_performance.md
+    href: core/overview.md            
+  - name: Plug-in Resources and Localizability
+    href: core/plugin_resources_and_localizability.md    
+  - name: The Plug-in Manifest Generator
+    href: core/the_plugin_manifest_generator.md
+  - name: Serialization Performance
+    href: core/serialization_performance.md
   - name: Extensions and extension points
     href: core/extensions.md 
   - name: API Reference