website update

website/docs/cli/xpm/index.mdx

@@ -1,7 +1,7 @@
 ---
 
 title: xpm - common options
-description: Options common to all xcdl commands
+description: Options common to all xpm commands.
 keywords:
   - xpack
   - xpm

website/docs/cli/xpm/init/index.mdx

@@ -1,7 +1,13 @@
 ---
 
 title: xpm init
-
+description: The definition of the `xpm init` command.
+keywords:
+  - xpack
+  - xpm
+  - cli
+  - init
+
 date: 2017-10-09 12:55:00 +0300
 
 ---

website/docs/cli/xpm/install/index.mdx

@@ -1,6 +1,12 @@
 ---
 
 title: xpm install
+description: The definition of the `xpm install` command.
+keywords:
+  - xpack
+  - xpm
+  - cli
+  - install
 
 date: 2017-10-09 12:56:00 +0300
 

website/docs/cli/xpm/link/index.mdx

@@ -1,6 +1,12 @@
 ---
 
 title: xpm link
+description: The definition of the `xpm link` command.
+keywords:
+  - xpack
+  - xpm
+  - cli
+  - link
 
 date: 2021-03-27 16:16:00 +0200
 

website/docs/cli/xpm/list/index.mdx

@@ -1,6 +1,12 @@
 ---
 
 title: xpm list
+description: The definition of the `xpm list` command.
+keywords:
+  - xpack
+  - xpm
+  - cli
+  - link
 
 date: 2021-01-27 22:32:00 +0200
 

website/docs/cli/xpm/run/index.mdx

@@ -1,6 +1,12 @@
 ---
 
 title: xpm run
+description: The definition of the `xpm run` command.
+keywords:
+  - xpack
+  - xpm
+  - cli
+  - run
 
 date: 2017-10-09 12:57:00 +0300
 

website/docs/cli/xpm/uninstall/index.mdx

@@ -1,6 +1,12 @@
 ---
 
 title: xpm uninstall
+description: The definition of the `xpm uninstall` command.
+keywords:
+  - xpack
+  - xpm
+  - cli
+  - uninstall
 
 date: 2021-01-27 22:22:00 +0200
 

website/docs/developer/_coverage-exceptions.mdx

@@ -0,0 +1,4 @@
+
+{/* ------------------------------------------------------------------------ */}
+
+- none

website/docs/developer/_style-exceptions.mdx

@@ -0,0 +1,4 @@
+
+{/* ------------------------------------------------------------------------ */}
+
+- none

website/docs/developer/index.mdx

@@ -24,6 +24,8 @@ import Prerequisites from './_common/_prerequisites.mdx';
 import GetProjectSources from './_common/_get-project-sources.mdx';
 
 import TestResults from './_test-results.mdx';
+import StyleExceptions from './_style-exceptions.mdx';
+import CoverageExceptions from './_coverage-exceptions.mdx';
 
 {/* ------------------------------------------------------------------------ */}
 
@@ -119,7 +121,7 @@ all files should limit the line length to 80.
 
 Known and accepted exceptions:
 
-- none
+<StyleExceptions />
 
 To manually fix compliance with the style guide (where possible):
 

website/docs/developer/windows-symbolic-links/index.mdx

@@ -1,7 +1,7 @@
 ---
 
 title: Windows symbolic links
-description: Why symbolic links to files cannot be used on Windows
+description: Why symbolic links to files cannot be used on Windows.
 keywords:
   - xpack
   - xpm
@@ -15,9 +15,13 @@ date: 2022-04-19 16:23:00 +0300
 
 # Windows symbolic links
 
+This page explains why, on Windows, in the `xpack/.bin` folder contains
+`.cmd` and `.ps1` scripts.
+
 ## Brief
 
-The short version is **Windows does not support symbolic links to files**.
+The short version is because **Windows does not support symbolic
+links to files**.
 
 ## Problem
 
@@ -56,7 +60,6 @@ not from the junction created in the local project.
 
 ## Examples
 
-
 ```txt title="clang.cmd"
 @ECHO off
 GOTO start

website/docs/faq/index.mdx

@@ -2,7 +2,6 @@
 
 title: FAQ
 description: Answers to previously asked questions, so you can find solutions without having to ask again.
-
 keywords:
   - xpack
   - xpm

website/docs/getting-started/glossary/index.mdx

@@ -1,7 +1,7 @@
 ---
 
 title: Glossary
-# description: ...
+description: Some of the definitions used in the xpm project.
 keywords:
   - xpack
   - xpm
@@ -13,12 +13,11 @@ date: 2024-11-24 18:58:00 +0300
 
 # Terms used across the **xpm** project
 
-The definitions used in the xCDL project are listed below.
+## Terminology
 
-More elaborate definitions are available in the
-[Concepts](/docs/guide/concepts/) page.
+The definitions used in the **xpm** project are listed below.
 
-## xpm
+### xpm
 
 **xpm** is the xPack Project manager. It uses several concepts:
 
@@ -27,3 +26,8 @@ More elaborate definitions are available in the
 - **build configurations**: sets of dependencies, properties and actions used for different builds
 - **build configurations inheritance**: to avoid redundancy, it is possible for a build configuration to inherit definitions from another build configurations and then redefine some of them
 - **LiquidJS substitutions**: a mechanism for textual substitutions with variables, tags, filters used to define _smart_ properties
+
+## More
+
+More elaborate definitions are available in the
+[Concepts](/docs/guide/concepts/) page.

website/docs/guide/concepts/index.mdx

@@ -1,10 +1,123 @@
 ---
 
-title: Concepts
+title: The xpm concepts
+description: Some of the key concepts used by the xpm project.
+keywords:
+  - xpack
+  - xpm
+  - concepts
 
 date: 2024-12-03 21:32:00 +0200
 
 ---
 
-TODO
+# The xpm concepts
+
+## Terminology
+
+The design of xpm draws inspiration from npm, utilising the same
+fundamental concepts while also incorporating several new features.
+
+### npm dependencies
+
+**npm** dependencies are Node.js packages, typically containing
+JavaScript or TypeScript code, essential for the operation of
+the current package. These dependencies are automatically
+installed when the current package is added as a dependency
+in another package.
+
+### npm development dependencies
+
+**npm** development dependencies (`devDependencies`) are Node.js packages
+that include tools utilised during the development of the current package.
+
+These dependencies are automatically installed when the `npm install`
+command is executed without any arguments in the current package.
+
+### xpm dependencies
+
+**xpm** dependencies are akin to npm dependencies but specify the
+source packages, typically C/C++ code, needed during the compile/link phase.
+
+### xpm development dependencies
+
+**xpm** development dependencies (`devDependencies`) are similar to
+**npm** development dependencies but specify binary tools, such as
+compilers and builders, that are used during the development of the
+current package.
+
+These dependencies are automatically installed when the `xpm install`
+command is executed without any arguments in the current package.
+
+### `package.json`
+
+This file is used to store xpm metadata. It is the same file
+as used by **npm**.
+
+To prevent conflicts, all **xpm** definitions are stored under a
+JSON member named `xpack`.
+
+### Variable substitutions
+
+Variable substitutions enable the dynamic insertion of values into
+a generic template definition, thereby enhancing flexibility and
+customisation.
+
+### LiquidJS substitutions
+
+LiquidJS substitutions use the [LiquidJS](https://liquidjs.com/) template
+engine for variable substitutions.
+
+Beyond basic variable substitutions, the LiquidJS engine also offers
+filters for various forms of string processing, and tags that introduce
+programmatic logic, such as `if` and `for` statements.
+
+### xPack Properties
+
+The values used for variable substitutions originate from multiple sources.
+
+Some values are predefined and depend on the platform, such as `os.arch`
+and `path.sep`.
+
+The package author can also contribute values through the xPack
+`properties` definitions in `package.json`.
+
+These properties can be defined for the entire project or for each
+specific build configuration.
+
+### Build Configurations
+
+Build configurations are sets of definitions used to create different
+artefacts within the same project. These artefacts can be variants of
+the same application, such as debug/release versions, or
+platform/architecture-specific variants, like Cortex-M or RISC-V,
+when the same application needs to run on multiple boards.
+
+### xPack Build Configurations
+
+xPack Build Configurations are sets of xpm metadata definitions, like
+`dependencies`, `properties` and `actions`,
+used for different builds.
+
+### xPack Build configurations inheritance
+
+To avoid redundancy, a build configuration can inherit definitions
+from one or more other build configurations and then redefine some
+of them as needed.
+
+### npm scripts
+
+**npm** allows to run shell commands by short `npm run ...` commands.
+
+The commands are executed in an environment where all installed development
+dependencies are preferred to all system tools with the same names.
+
+### xPack Actions
+
+**xpm** extends **npm** scripts and can define multi-line commands with
+substitutions.
+
+The commands are executed in an environment where all installed development
+dependencies are preferred to all system tools with the same names.
+
 

website/docs/guide/files/index.mdx

@@ -1,6 +1,11 @@
 ---
 
 title: xpm files
+description: The files used in projects managed by xpm.
+keywords:
+  - xpack
+  - xpm
+  - files
 
 date: 2017-10-09 14:13:00 +0300
 

website/docs/guide/files/package.json/index.mdx

@@ -1,12 +1,22 @@
 ---
 
 title: package.json
-#description: ...
+description: The definition of the `package.json` file used by xpm.
+keywords:
+  - xpack
+  - xpm
+  - files
+  - package.json
 
 date: 2019-07-02 00:36:00 +0300
 
 ---
 
+import Objects from '@site/docs/metadata/_shared/_objects.mdx';
+import GlobalProperties from '@site/docs/metadata/_shared/_global-properties.mdx';
+
+{/* ------------------------------------------------------------------------ */}
+
 # package.json
 
 ## Overview
@@ -16,6 +26,10 @@ basically the same as the **npm**
 [`package.json`](https://docs.npmjs.com/files/package.json),
 with some extensions.
 
+The mandatory properties are `name` and `version`.
+
+In addition, **xpm** groups several specific definitions below `xpack`.
+
 ## The mandatory `xpack` definitions
 
 The mandatory `xpack` definitions is used to store all
@@ -28,3 +42,11 @@ In addition to the `xpacks` definitions, another key extension
 that comes with **xpm** is the use of
 **LiquidJS substitutions**, described in a
 [separate page](/docs/metadata/liquidjs-substitutions/).
+
+## Global properties
+
+<GlobalProperties />
+
+## Objects and arrays
+
+<Objects />

website/docs/guide/index.mdx

@@ -1,10 +1,10 @@
 ---
 
 title: Packages Author's Guide
-description: The extensive manual for those who want to create new xpm packages
+description: The extensive manual for those who want to create new xpm packages.
 keywords:
   - xpack
-  - xcdl
+  - xpm
   - guide
 
 date: 2024-11-26 01:34:00 +0200