Merge pull request plone#1416 from plone/glossary-cleanup

Glossary cleanup

Author: stevepiercy

docs/backend/upgrading/version-specific-migration/p4x-to-p5x-upgrade.md

@@ -366,7 +366,7 @@ Here the two dependencies are jQuery and the pattern registry.
 We will not get into the pattern registry, as it is off-topic for this discussion.
 It is basically a registry of JavaScript components.
 
-The necessity for using it here is with AJAX calls and binding new DOM elements dynamically added to the page.
+The necessity for using it here is with AJAX calls and binding new {term}`DOM` elements dynamically added to the page.
 
 Additionally, above this `require` call, we provide some backward compatible code that you can inspect.
 

docs/backend/upgrading/version-specific-migration/upgrade-to-51.md

@@ -282,7 +282,7 @@ Adding or editing a document is faster, because care was taken to avoid duplicat
 The [collective.indexing](https://pypi.org/project/collective.indexing) package was merged into the core of Plone.
 This makes sure that objects are only indexed once per transaction.
 
-It also gives hooks for calling external indexers, like Solr and Elasticsearch.
+It also gives {term}`hooks` for calling external indexers, like Solr and Elasticsearch.
 See https://docs.plone.org/develop/plone/searching_and_indexing/external-catalogs.html.
 
 There is a workaround when you get {ref}`catalog-errors-during-upgrades-label`.

docs/glossary.md

@@ -154,30 +154,48 @@ record
     A Rapido app is able to store data as records.
     Records are basic dictionaries.
 
-Project (Volto)
-    The product of running the package `@plone/generator-volto`, resulting in a customizable instance of Volto.
+Add-on
+    An add-on in Plone extends its functionality.
+    It is code that is released as a package to make it easier to install.
 
-Add-on (Volto)
-    A JavaScript package that integrates with Volto's configuration registry and is able to enhance, extend, and customize it.
+    In Volto, an add-on is a JavaScript package.
 
-Add-on configuration loader (Volto)
+    In Plone core, an add-on is a Python package.
+
+    -   [Plone core add-ons](https://github.com/collective/awesome-plone#readme)
+    -   [Volto add-ons](https://github.com/collective/awesome-volto#readme)
+    -   [Add-ons tagged with the trove classifier `Framework :: Plone` on PyPI](https://pypi.org/search/?c=Framework+%3A%3A+Plone)
+
+Volto configuration loader
     A function with signature `config => config`.
-    It gets the Volto Configuration registry, and it must return it back after mutating it.
-    It is similar to `GenericSetup` profiles in Plone Backend.
+    It gets the Volto configuration registry, and it must return it back after mutating it.
+    It is similar to `GenericSetup` profiles in the Plone backend.
     An add-on must provide a default configuration loader that is always loaded when Volto runs.
     An add-on can have multiple configuration loaders, and they can be loaded optionally from the Volto configuration.
 
-Configuration registry (Volto)
-    A singleton object modeled using JavaScript modules.
+Configuration registry
+    In Plone and in general, the configuration registry is where resources are registered for an application.
+
+    In Volto, it is a singleton object modeled using JavaScript modules.
     It is accessible from the Volto project by importing the module `@plone/volto/config` with `import registry from '@plone/volto/config'`.
     It contains the configuration of the Volto app.
+    
+    In Plone core, [`plone.app.registry`](https://pypi.org/project/plone.app.registry/) provides Plone UI and `GenericSetup` integration for [`plone.registry`](https://pypi.org/project/plone.registry/), which in turn implements a configuration registry for Zope applications.
+
+component shadowing
+shadowing
+    Volto uses a technique called component shadowing to override an existing Volto component with our local custom version, without having to modify Volto's source code. 
+
+    Volto's source components are located in the filepath stem of `omelette/src/components/`.
+    Custom components that shadow Volto's source would be located in the filepath stem of `src/customizations/components/`.
+    Shadow components would have the same filepath as Volto's source compenents, excluding the stem.
+    Thus `omelette/src/components/theme/Header/Header.jsx` would be shadowed by `src/customizations/components/theme/Header/Header.jsx`.
 
-Shadowing (Volto)
-    Webpack provides an "alias" mechanism, where the path for a module can be aliased to another module.
-    By using this mechanism Volto enables customization (file overrides), similar to `z3c.jbot.`
+    Webpack provides an alias mechanism that allows component shadowing in Volto, where the path for a module can be aliased to another module.
+    By using this mechanism of file overrides, or component shadowing, Volto enables customization, similar to `z3c.jbot.`
 
 Razzle
-    A tool that simplifies SPA and SSR configuration for React projects.
+    A tool that simplifies {term}`SPA` and {term}`SSR` configuration for React projects.
 
 Webpack
     A tool that loads and bundles code and web resources using loaders.
@@ -194,14 +212,39 @@ Express
     A JavaScript HTTP server with a simple API to build custom applications.
     Volto uses it as its server.
 
-Server-Side Rendering (SSR)
-    When first loading any Plone page, users will get HTML markup that closely matches the final DOM structure of the React components used to render that page.
+SSR
+server-side rendering
+    When a web browser or other HTTP client sends a request, the HTML markup for the page is created on the server, which sends a response consisting of HTML markup back to the client.
 
-Single Page Application (SPA)
-    A type of JavaScript application that aims to provide a better user experience by avoiding unnecessary reloading of the browser page, instead using AJAX to load backend information.
+    In Volto, SSR returns HTML markup that closely matches the final {term}`DOM` structure of the React components used to render that page, but it is not the complete page.
+    After the client loads the initial response, then the {term}`hydration` mechanism performs additional rendering on the client side, populating the DOM with additional HTML markup.
 
-Hot Module Replacement (HMR)
-    A development feature provided by Webpack that automatically reloads, in the browser, the JavaScript modules that have changed on disk.
+    In Classic UI, SSR returns the complete page back to the client in the response.
+    In some rare cases, additional HTML snippets may be loaded, such as in overlays or dialogs.
+
+    SSR enables a developer to customize a website per request and per user.
+    In addition, SSR can improve performance and search engine optimization (SEO) for a website.
+
+DOM
+Document Object Model
+    The Document Object Model (DOM) is a programming interface for web documents.
+    It represents the page so that programs can change the document structure, style, and content.
+    The DOM represents the document as nodes and objects; that way, programming languages, such as JavaScript and React, can interact with the page.
+
+SPA
+single page application
+    A type of JavaScript application that aims to provide a better user experience by avoiding unnecessary reloading of the browser page, instead using {term}`AJAX` to load backend information.
+
+HMR
+hot module replacement
+    [Hot module replacement](https://webpack.js.org/guides/hot-module-replacement/) (HMR) is a development feature provided by Webpack that automatically reloads, in the browser, the JavaScript modules that have changed on disk.
+
+Ajax
+AJAX
+Asynchronous JavaScript and XML
+    AJAX allows web applications to change parts of the page dynamically without reloading the entire page.
+    In Plone, after a page with JavaScript is loaded, the JavaScript will send an asynchronous request to the server.
+    The server will send a response back to the client, which is then rendered on the client side.
 
 Yeoman
     A popular scaffolding tool similar to Plone's `mr.bob` or `ZopeSkel`.
@@ -225,8 +268,8 @@ mrs-developer
 Yarn
     [Yarn](https://classic.yarnpkg.com/) is a JavaScript package manager.
 
-Hydration (SSR)
-    After loading an HTML page generated with SSR in the browser, React can "populate" the existing DOM elements, recreate and attach their coresponding components.
+Hydration
+    After loading an HTML page generated with {term}`SSR` in the browser, React can populate the existing {term}`DOM` elements, and recreate and attach their coresponding components.
 
 JSX
     A dialect of JavaScript that resembles XML, it is transpiled by Babel to JavaScript functions.
@@ -235,16 +278,20 @@ JSX
 Scoped packages
     Namespace for JavaScript packages, they provide a way to avoid naming conflicts for common package names.
 
-middleware (Redux)
-    Custom wrappers for the Redux store dispatch methods.
-    They allow customizing the behavior of the data flow inside the redux store.
+Redux
+Redux middleware
+    Custom wrappers for the [Redux](https://redux.js.org/) store dispatch methods.
+    They allow customizing the behavior of the data flow inside the Redux store.
+
+hook
+hooks
+    In general, a hook in programming is a place in code that allows you to tap in to a module to either provide different behavior or to react when something happens.
 
-hooks (React)
-    Hooks are a React API that allow function components to use React features such as lifecycle methods, states, and so on.
+    **React [Hooks](https://reactjs.org/docs/hooks-overview.html)** are a React API that allow function components to use React features, such as lifecycle methods, states, and so on.
 
-hoisting (Yarn)
-    An optimization provided by Yarn.
-    By default JavaScript packages will directly include dependencies inside their local node_modules.
+hoisting
+    [Hoisting](https://yarnpkg.com/advanced/lexicon#hoisting) is an optimization provided by Yarn.
+    By default JavaScript packages will directly include dependencies inside their local `node_modules`.
     By hoisting we're "lifting" these inner dependencies to the top level `node_modules` directory, and thus optimize the generated bundles.
     In case two dependencies have conflicting version dependencies of the same library, the hoisting will not be possible (for that conflicting dependency) and you'll see multiple instances of the same library in the bundle, or you'll see that the add-on receives its own `node_modules` folder.
 

docs/i18n-l10n/translating-content.md

@@ -61,7 +61,7 @@ Plone will not translate the content for you.
 It will only create the content in the other language folders, and both LRFs' contents will be linked to the translations.
 
 Plone does not use any third party tools to automatically translate content.
-If needed, you will need to develop such connector tools and hook into a content creation process.
+If needed, you will need to develop such connector tools and {term}`hook` into a content creation process.
 
 
 (translating-content-language-independent-content)=

docs/i18n-l10n/translating-text-strings.md

@@ -155,7 +155,7 @@ It will use the text content of the element as `msgid`.
 Use attributes `i18n:translate`, `i18n:attributes`, and so on.
 For examples, look at any core Plone `.pt` files.
 
-The `i18n:translate` attribute will hook into the translation machinery, and will look up the corresponding translated string to the one stated there, while looking in the relevant `domain.po` file corresponding to the `i18n:domain` stated in the file and the language negotiated by Plone.
+The `i18n:translate` attribute will {term}`hook` into the translation machinery, and will look up the corresponding translated string to the one stated there, while looking in the relevant `domain.po` file corresponding to the `i18n:domain` stated in the file and the language negotiated by Plone.
 
 
 (translating-text-strings-automatically-translated-message-ids-label)=

docs/install/install-from-packages.md

@@ -21,7 +21,7 @@ When you want full control over development or deployment, installing Plone from
 
 The hardware requirements below give a rough estimate of the minimum hardware setup needed for a Plone server.
 
-Add-on products and caching solutions may increase RAM requirements.
+{term}`Add-on` products and caching solutions may increase RAM requirements.
 
 A single Plone installation is able to run many Plone sites.
 You may host multiple Plone sites on the same server.

docs/overview/index.md

@@ -74,7 +74,7 @@ Plone is easy to set up compared to other CMSs in its category, extremely flexib
 Plone is a content management platform with its backend written in Python.
 It is built on top of the open source Zope web application server and development system. 
 Plone makes use of the pluggable Zope Component Architecture (ZCA) to provide a highly modular and extensible system.
-Throughout its history, Plone has used server-side rendering to generate HTML-based content, with advanced resource management features for adding and bundling CSS and JavaScript. 
+Throughout its history, Plone has used {term}`server-side rendering` to generate HTML-based content, with advanced resource management features for adding and bundling CSS and JavaScript. 
 Additionally, Plone's use of a component architecture makes it easy to extend and customize, allowing users to create unique, feature rich websites that are tailored to their specific needs.
 
 With the release of Plone 6, you now have the option to choose from two different out-of-the-box supported configurations when setting up a new Plone website.
@@ -86,7 +86,7 @@ It may be used as a base image, adding customizations, to make a derivative imag
 The default and recommended configuration for new websites in Plone is the new React-based JavaScript frontend called "Volto".
 For this setup you still need to run the Python-based backend server, as well as enable the REST API, and update the configuration profile.
 These settings and profile are applied automatically when you select the {guilabel}`Create Plone Site` option in the Plone website creation form.
-In addition a separate NodeJS based frontend server will serve the JavaScript frontend resources and provide SSR with hydration.
+In addition a separate NodeJS based frontend server will serve the JavaScript frontend resources and provide {term}`SSR` with {term}`hydration`.
 To deploy this setup using containers, you will need the `plone-frontend` image for the frontend server.
 
 Beginning with Plone 6, we now support two programming language stacks, one each for Python and JavaScript.