website re-generate with tommy's suggestions

website/docs/install/_common/_automated-install.mdx

@@ -193,8 +193,10 @@ export PATH=<...project-path...>/xpacks/.bin:$PATH
 
 { props.isWindows === 'True' ?
   <Admonition type="tip">
-    <p>When not using the Git console, adjust the syntax for the
-  corresponding shell.</p>
+    <p>This syntax is for the Git Bash console.
+      When using COMMAND.EXE or Power Shell,
+      adjust the syntax for the corresponding Windows specific shell.
+    </p>
   </Admonition>
  : ''
 }
@@ -206,10 +208,10 @@ export PATH=<...project-path...>/xpacks/.bin:$PATH
 The above `xpm install` command will do the following:
 
 * identify the platform specific archive for the latest available version
-  of GNU RISC-V Embedded GCC, download it in a cache and unpack
+  of GNU RISC-V Embedded GCC, download it into a cache and unpack
   it into a versioned folder
   in the **central xPacks store** (if not already there);
-  check the output of the `xpm` command for the actual
+  check the output of the `xpm install` command for the actual
   folder used on your platform;
 * create a local symbolic link
   like <code>xpacks/@xpack-dev-tools/riscv-none-elf-gcc</code> pointing to the
@@ -274,11 +276,13 @@ This is particularly useful for CI/CD environments.
 
 ### Install globally
 
-For older development environments (like the initial **Eclipse Embedded C/C++ plug-ins**; the current version also supports project installs),
+For older development environments,
 it is also possible to install GNU RISC-V Embedded GCC only globally in the **central
-xPacks store**, without any local <LinksVsForwarders isWindows={ props.isWindows }/>,
-assuming the development environments are capable of handling
-the paths themselves.
+xPacks store**, without any
+local <LinksVsForwarders isWindows={ props.isWindows }/>; it
+is the developer's responsibility to configure the path to the tools.
+
+No other files are installed in any system folders or other locations.
 
 <CodeBlock language="sh"> {
 `xpm install @xpack-dev-tools/riscv-none-elf-gcc@latest --global --verbose`

website/docs/install/_common/_automated-uninstall.mdx

@@ -11,8 +11,10 @@ import LinksVsForwarders from '@site/src/components/LinksVsForwarders'
 
 ### Uninstall
 
-The binaries are distributed as portable archives; therefore they do not need
-to run a setup and do not require an uninstall; simply removing the
+The binaries do not use any form of installer; instead they
+are distributed as
+portable { props.isWindows ? <code>.zip</code> : <code>.tar.gz</code> } archives;
+therefore they do not require to run any uninstaller; simply removing the
 links and possibly the central store folder is enough.
 
 To remove the <LinksVsForwarders isWindows={ props.isWindows }/> created by

website/docs/install/_install-linux.mdx

@@ -25,6 +25,52 @@ the project build configurations need a PATH adjustment:
 } </CodeBlock>
 </details>
 
+<AutomatedUninstall/>
+
+### Quick test
+
+To check if the GNU RISC-V Embedded GCC installed by **xpm** starts properly, use something like:
+
+<CodeBlock language="console"> {
+`$ ~/.local/xPacks/@xpack-dev-tools/riscv-none-elf-gcc/${ customField('upstreamVersion') }-${ customField('xpackSubversion') }.${ customField('npmSubversion') }/.content/bin/riscv-none-elf-gcc --version
+riscv-none-elf-gcc (xPack GNU RISC-V Embedded GCC x86_64) ${ customField('upstreamVersion') }`
+} </CodeBlock>
+
+<ManualInstall/>
+
+<ManualInstallLinux/>
+
+<ManualInstallInfo/>
+
+<details>
+<summary>PATH setup</summary>
+
+With all binary tools installed in `xpacks/.bin`, the project build
+configurations need a single PATH adjustment:
+
+```sh
+export PATH=<...project-path...>/xpacks/.bin:$PATH
+```
+
+:::tip
+
+On Windows, when not using the Git console, adjust the syntax for the
+corresponding shell.
+
+:::
+</details>
+
+### Quick test
+
+To check if the GNU RISC-V Embedded GCC installed manually starts properly, use something like:
+
+<CodeBlock language="console"> {
+`$ ~/.local/xPacks/riscv-none-elf-gcc/xpack-riscv-none-elf-gcc-${ customField('upstreamVersion') }-${ customField('xpackSubversion') }/bin/riscv-none-elf-gcc --version
+riscv-none-elf-gcc (xPack GNU RISC-V Embedded GCC x86_64) ${ customField('upstreamVersion') }`
+} </CodeBlock>
+
+## Miscellaneous
+
 <details>
 <summary>Folder hierarchy</summary>
 
@@ -134,50 +180,4 @@ After install, the package creates a folder hierarchy like the following
 20 directories, 77 files`
 } </CodeBlock>
 
-No other files are installed in any system folders or other locations.
-
 </details>
-
-<AutomatedUninstall/>
-
-### Quick test
-
-To check if the GNU RISC-V Embedded GCC installed by **xpm** starts properly, use something like:
-
-<CodeBlock language="console"> {
-`$ ~/.local/xPacks/@xpack-dev-tools/riscv-none-elf-gcc/${ customField('upstreamVersion') }-${ customField('xpackSubversion') }.${ customField('npmSubversion') }/.content/bin/riscv-none-elf-gcc --version
-riscv-none-elf-gcc (xPack GNU RISC-V Embedded GCC x86_64) ${ customField('upstreamVersion') }`
-} </CodeBlock>
-
-<ManualInstall/>
-
-<ManualInstallLinux/>
-
-<ManualInstallInfo/>
-
-<details>
-<summary>PATH setup</summary>
-
-With all binary tools installed in `xpacks/.bin`, the project build
-configurations need a single PATH adjustment:
-
-```sh
-export PATH=<...project-path...>/xpacks/.bin:$PATH
-```
-
-:::tip
-
-On Windows, when not using the Git console, adjust the syntax for the
-corresponding shell.
-
-:::
-</details>
-
-### Quick test
-
-To check if the GNU RISC-V Embedded GCC installed manually starts properly, use something like:
-
-<CodeBlock language="console"> {
-`$ ~/.local/xPacks/riscv-none-elf-gcc/xpack-riscv-none-elf-gcc-${ customField('upstreamVersion') }-${ customField('xpackSubversion') }/bin/riscv-none-elf-gcc --version
-riscv-none-elf-gcc (xPack GNU RISC-V Embedded GCC x86_64) ${ customField('upstreamVersion') }`
-} </CodeBlock>

website/docs/install/_install-macos.mdx

@@ -25,6 +25,36 @@ the project build configurations need a PATH adjustment:
 } </CodeBlock>
 </details>
 
+<AutomatedUninstall/>
+
+### Quick test
+
+To check if the GNU RISC-V Embedded GCC installed by **xpm** starts properly, use something like:
+
+<CodeBlock language="console"> {
+`$ ~/Library/xPacks/@xpack-dev-tools/riscv-none-elf-gcc/${ customField('upstreamVersion') }-${ customField('xpackSubversion') }.${ customField('npmSubversion') }/.content/bin/riscv-none-elf-gcc --version
+riscv-none-elf-gcc (xPack GNU RISC-V Embedded GCC x86_64) ${ customField('upstreamVersion') }`
+} </CodeBlock>
+
+<ManualInstall/>
+
+<ManualInstallMacOS/>
+
+<ManualInstallInfo/>
+
+The result is a structure identical to the above.
+
+### Quick test
+
+To check if the GNU RISC-V Embedded GCC installed manually starts properly, use something like:
+
+<CodeBlock language="console"> {
+`$ ~/Library/xPacks/riscv-none-elf-gcc/${ customField('upstreamVersion') }-${ customField('xpackSubversion') }/bin/riscv-none-elf-gcc --version
+${ customField('upstreamVersion') }`
+} </CodeBlock>
+
+## Miscellaneous
+
 <details>
 <summary>Folder hierarchy</summary>
 
@@ -118,33 +148,3 @@ After install, the package creates a folder hierarchy like the following
 } </CodeBlock>
 
 </details>
-
-No other files are installed in any system folders or other locations.
-
-<AutomatedUninstall/>
-
-### Quick test
-
-To check if the GNU RISC-V Embedded GCC installed by **xpm** starts properly, use something like:
-
-<CodeBlock language="console"> {
-`$ ~/Library/xPacks/@xpack-dev-tools/riscv-none-elf-gcc/${ customField('upstreamVersion') }-${ customField('xpackSubversion') }.${ customField('npmSubversion') }/.content/bin/riscv-none-elf-gcc --version
-riscv-none-elf-gcc (xPack GNU RISC-V Embedded GCC x86_64) ${ customField('upstreamVersion') }`
-} </CodeBlock>
-
-<ManualInstall/>
-
-<ManualInstallMacOS/>
-
-<ManualInstallInfo/>
-
-The result is a structure identical to the above.
-
-### Quick test
-
-To check if the GNU RISC-V Embedded GCC installed manually starts properly, use something like:
-
-<CodeBlock language="console"> {
-`$ ~/Library/xPacks/riscv-none-elf-gcc/${ customField('upstreamVersion') }-${ customField('xpackSubversion') }/bin/riscv-none-elf-gcc --version
-${ customField('upstreamVersion') }`
-} </CodeBlock>

website/docs/install/_install-windows.mdx

@@ -32,6 +32,34 @@ corresponding shell.
 :::
 </details>
 
+<AutomatedUninstall isWindows={ props.isWindows }/>
+
+### Quick test
+
+To check if the GNU RISC-V Embedded GCC installed by **xpm** starts properly, use something like:
+
+<CodeBlock language="console"> {
+`C:\\> %USERPROFILE%\\AppData\\Roaming\\xPacks\\@xpack-dev-tools\\riscv-none-elf-gcc\\${ customField('upstreamVersion') }-${ customField('xpackSubversion') }.${ customField('npmSubversion') }\\.content\\bin\\riscv-none-elf-gcc.exe --version
+riscv-none-elf-gcc (xPack GNU RISC-V Embedded GCC x86_64) ${ customField('upstreamVersion') }`
+} </CodeBlock>
+
+<ManualInstall/>
+
+<ManualInstallWindows/>
+
+<ManualInstallInfo/>
+
+### Quick test
+
+To check if the GNU RISC-V Embedded GCC installed manually starts properly, use something like:
+
+<CodeBlock language="console"> {
+`C:\\> %USERPROFILE%\\AppData\\Roaming\\xPacks\\riscv-none-elf-gcc\\xpack-riscv-none-elf-gcc-${ customField('upstreamVersion') }-${ customField('xpackSubversion') }\\bin\\riscv-none-elf-gcc.exe --version
+riscv-none-elf-gcc (xPack GNU RISC-V Embedded GCC x86_64) ${ customField('upstreamVersion') }`
+} </CodeBlock>
+
+## Miscellaneous
+
 <details>
 <summary>Folder hierarchy</summary>
 
@@ -164,32 +192,4 @@ Volume serial number is B02D-925C
 28 directories, 91 files`
 } </CodeBlock>
 
-No other files are installed in any system folders or other locations.
-
 </details>
-
-<AutomatedUninstall isWindows={ props.isWindows }/>
-
-### Quick test
-
-To check if the GNU RISC-V Embedded GCC installed by **xpm** starts properly, use something like:
-
-<CodeBlock language="console"> {
-`C:\\> %USERPROFILE%\\AppData\\Roaming\\xPacks\\@xpack-dev-tools\\riscv-none-elf-gcc\\${ customField('upstreamVersion') }-${ customField('xpackSubversion') }.${ customField('npmSubversion') }\\.content\\bin\\riscv-none-elf-gcc.exe --version
-riscv-none-elf-gcc (xPack GNU RISC-V Embedded GCC x86_64) ${ customField('upstreamVersion') }`
-} </CodeBlock>
-
-<ManualInstall/>
-
-<ManualInstallWindows/>
-
-<ManualInstallInfo/>
-
-### Quick test
-
-To check if the GNU RISC-V Embedded GCC installed manually starts properly, use something like:
-
-<CodeBlock language="console"> {
-`C:\\> %USERPROFILE%\\AppData\\Roaming\\xPacks\\riscv-none-elf-gcc\\xpack-riscv-none-elf-gcc-${ customField('upstreamVersion') }-${ customField('xpackSubversion') }\\bin\\riscv-none-elf-gcc.exe --version
-riscv-none-elf-gcc (xPack GNU RISC-V Embedded GCC x86_64) ${ customField('upstreamVersion') }`
-} </CodeBlock>

website/docs/support/index.mdx

@@ -48,8 +48,9 @@ and enter a **New discussion**; use the **Q&A** category for questions.
 
 ## Register a new support ticket only if necessary
 
-If you are convinced that you identified a bug related to the binary
-distribution, not GNU RISC-V Embedded GCC itself (if you have doubts, use the GitHub Discussions),
+If you are convinced that you identified a bug related to the xPack binary
+distribution, not to the upstream GNU RISC-V Embedded GCC itself
+(if you have doubts, use the GitHub Discussions),
 or if you have a pertinent suggestion how to enhance the **xPack GNU RISC-V Embedded GCC**
 distribution, register a **New Issue** in the
 [GitHub Issues](https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/issues/)
@@ -74,7 +75,7 @@ private e-mail for support, **use the
 :::
 
 Sending private messages will be automatically replied with
-a link to this page.
+a short message including a link to this page.
 The reason for this rude behaviour is simply an attempt to use
 the time more efficiently; since discussions are archived, other people
 having similar problems might benefit from the answers.

website/docs/user-info/_common/_libraries-and-rpath.mdx

@@ -9,7 +9,7 @@ On all platforms the binary xPack packages are standalone,
 and expect only the standard
 runtime to be present on the host.
 
-All dependencies that are build as shared libraries are copied locally
+All dependencies that are built as shared libraries are copied locally
 in the `libexec` folder (or in the same folder as the executable for Windows).
 
 ### `DT_RPATH` and `LD_LIBRARY_PATH`
@@ -21,13 +21,14 @@ $ readelf -d library.so | grep runpath
  0x000000000000001d (RPATH)            Library rpath: [$ORIGIN]
 ```
 
-In the GNU ld.so search strategy, the `DT_RPATH` has
-the highest priority, higher than `LD_LIBRARY_PATH`, so if this later one
+In the GNU `ld.so` search strategy, the `DT_RPATH` has
+the highest priority, higher than `LD_LIBRARY_PATH`, so if this latter one
 is set in the environment, it should not interfere with the xPack binaries.
 
 Please note that previous versions, up to mid-2020, used `DT_RUNPATH`, which
-has a priority lower than `LD_LIBRARY_PATH`, and does not tolerate setting
-it in the environment.
+has a priority lower than `LD_LIBRARY_PATH`; setting `LD_LIBRARY_PATH`
+in the environment overrode `DT_RUNPATH`, resulting in failures to loader_path
+the libraries.
 
 ### `@rpath` and `@loader_path`
 

website/docs/user-info/_common/_versioning.mdx

@@ -14,13 +14,19 @@ import LinksVsForwarders from '@site/src/components/LinksVsForwarders'
 
 The version string used by the { props.upstreamName ? props.upstreamName : 'GNU RISC-V Embedded GCC' } project
 is a three number string
-like <code>{ customField('upstreamVersion') }</code>; to this string the xPack distribution adds a four number,
-but since semver allows only three numbers, all additional ones can
+like <code>{ customField('upstreamVersion') }</code>;
+to this string the xPack distribution adds a fourth number,
+but since [SemVer](https://semver.org) allows only three numbers,
+all additional ones can
 be added only as pre-release strings, separated by a dash,
-like <code>{ customField('upstreamVersion') }-{ customField('xpackSubversion') }</code>. When published as a npm package, the version gets
-a fifth number, like <code>{ customField('upstreamVersion') }-{ customField('xpackSubversion') }.{ customField('npmSubversion') }</code>.
+like <code>{ customField('upstreamVersion') }-{ customField('xpackSubversion') }</code>. When
+published as a npm package, the version gets
+a fifth number,
+like <code>{ customField('upstreamVersion') }-{ customField('xpackSubversion') }.{ customField('npmSubversion') }</code>.
 
-Since adherence of third party packages to semver is not guaranteed,
+Since adherence of third party packages to SemVer is not guaranteed,
 it is recommended to avoid referring to the xPack GNU RISC-V Embedded GCC dependency via
-a semver expressions like <code>^{ customField('upstreamVersion') }</code> or
-<code>~{ customField('upstreamVersion') }</code>, and prefer exact matches, like <code>{ customField('upstreamVersion') }-{ customField('xpackSubversion') }.{ customField('npmSubversion') }</code>.
+a SemVer expressions
+like <code>^{ customField('upstreamVersion') }</code> or <code>~{ customField('upstreamVersion') }</code>, and
+prefer exact matches,
+like <code>{ customField('upstreamVersion') }-{ customField('xpackSubversion') }.{ customField('npmSubversion') }</code>.