Fix#187: Refactor product schema (openSUSE#197)

These changes reflect broad architectural shifts and naming conventions
throughout the entire configuration system.

* **Rebranding**: The naming convention has shifted from Docserv to Portal.
  This is reflected in namespace changes and element renaming
  (e.g., `<product>` is now part of a portal root).

* **Documentation-First Design**: The schema now heavily utilizes `db:refname`
  and `db:refpurpose` annotations for almost every element and attribute.
  This allows for automated generation of human-readable documentation directly
  from the RNC file.

* *Enhanced Modularity**: The schema now explicitly supports splitting large
  configuration files into smaller, more manageable parts. By utilizing
  inclusion mechanisms, you can maintain different sections of the portal
  (like `<categories>` or specific products) in separate files, leading to
  a cleaner and more maintainable structure.

* **Implicit Language Logic**: Master/source language identification has shifted
  from a boolean attribute (`@default`) to a value-based system.
  The schema now assumes `en-us` is the source locale for products and deliverables.

* **Migration Tooling**: To facilitate the transition, an XSLT migration stylesheet
  is available. This tool automates the conversion of version 6.0 configuration
  files to the 7.0 format, handling the renaming of elements, restructuring of
  attributes, and the removal of deprecated metadata.

Version 7.0 introduces several elements to support a more hierarchical portal
structure and better metadata documentation.

* New elements
  * New `<portal>` element (root element of everything)
  * Add optional `<spotlight>` element
    The `linkend` attribute points to a specific product, docset, or deliverable.
    Two possible notations: with and without text (empty element).
  * Insert XInclude definition
    Disable specific attributes like `xpointer`, `fragid`, `language`, and
    `accept`.
  * Add `<productfamilies>` and `<series>` to portal
    Both contain an `<item id="..."> ... </item>`.
    Having text inside `<item>` makes it easier and we don't need an
    additional `name` attribute.

* Changed content models
  * The `start` pattern allows `<product>`, `<docset>`, `<categories>`,
    `<category>`, and `<descriptions>`.
  * Simplified `<link>`: Allows multiple URLs in `<link>`. This makes it
    possible to have different formats. Additionally allow a `<desc>`
    element to describe the resource.
  * Major elements now support `<xi:include>`, allowing configuration files
    to be broken into smaller, manageable chunks.
  * `<ref/>` contains only a `@linkend` attribute to link to a resource.
    You don't need `dc`, `product`, or some other strange combination.

* Renamed elements
  * `<desc>` -> `<descriptions>`
    Move <desc> elements into a parent <descriptions>
  * `<builddocs>` -> `<resources>`
    Container for definitions of resources
  * `<overridedesc>` -> `<descriptions>`
    Version-specific content
  * `<builddocs>/<language>` -> `<locale>`
    Require at least one <locale> with lang="en-us" as default language.

* Removed elements
  * Disable `<param>` in `<deliverable>`
  * Remove `<buildcontainer>` from `<builddocs>`
  * Remove ds.deliverablerestricted ds.subdeliverablerestricted

* New attributes
  * Add xml:base for all start elements
    This is needed when elements are xincluded they get
    automatically a xml:base attribute.
  * Add `family` and `series` for `<product>`
  * Add optional `rank` in `<product>`
  * Optional `sitemap` for `<deliverable>`
  * Add `linkend` in `<language>`
  * Include `lang` in `<url>`

* Changed attributes
  * Use xsd:language for ds.type.lang pattern
    The xsd:token isn't the right one.
  * Make schemaversion optional on <product>
  * Add datatypes library (xsd prefix)
  * Raise `schemaversion` value to `7.0`
  * Change type from xsd:token to xsd:IDREFS for `category`

* Renamed attributes
  * `productid`, `categoryid`, `setid`, `linkid` are all "id" now
    They are of type ID (not just token or string)

* Removed attributes
  * `meta` in deliverable
  * `default` in `<desc>`
    Use required lang="en-us" instead of default="true"
  * Remove double ds.titleformat.attr definition

Author: tomschr

.gitignore

@@ -289,3 +289,4 @@ audit_reports/
 git_repos/
 .DS_Store
 lean_audit.txt
+output/

src/docbuild/config/xml/data/README.md

@@ -0,0 +1,197 @@
+# Portal Configuration
+
+This directory contains:
+
+* A RELAX NG schema (`src/docbuild/config/xml/data/product-config-schema.rnc`).
+  It's the successor of the previous Docserv product schema.
+* An example `config.d` directory.
+
+## File structure
+
+The `config.d` directory contains several subdirectories
+
+```text
+config.d/
+├── categories/
+│   ├── [... more languages ...]
+│   ├── de-de.xml
+│   └── en-us.xml
+├── cloudnative/
+│   ├── [... similar to sles/... ]
+│   └── cloudnative.xml
+├── portal.xml
+└── sles/
+    ├── desc
+    │   ├── [... more languages ...]
+    │   ├── descriptions.xml
+    │   ├── de-de.xml
+    │   └── en-us.xml
+    ├── docsets
+    │   ├── [... more docsets ...]
+    │   └── 16.0.xml
+    └── sles.xml
+```
+
+* `config.d/`: the configuration directory with all portal configuration
+* `categories/`: A directory that contains all categories.
+* `portal.xml`: The main entry file which references all categories and
+  product configuration.
+* `sles/sles.xml`: The main product configuration for SLES.
+* `sles/desc/`: contains all language specific descriptions.
+* `sles/docsets/`: contains all docsets of a product.
+  Depending on the complexity of the product, this may not always be
+  needed. For SLES, it would probably useful.
+
+## Creating combined config
+
+To create a single XML config, use the following command:
+
+```shell
+xmllint --xinclude \
+  --output portal-$(date --iso-8601).xml \
+  src/docbuild/config/xml/data/config.d/portal.xml
+```
+
+## Migrating to the new portal schema
+
+To migrate an old Docserv stitchfile to a _single portal XML config_, use
+the following command:
+
+```shell
+$ xsltproc --param use.xincludes "0" \
+         --stringparam outputdir "./" \
+         --stringparam outputfile portal-test.xml \
+         --stringparam schemafile "portal-config.rnc" \
+convert-v6-to-v7.xsl docserv-stitch-2026-??-??.xml
+Written file: "portal-test.xml"
+```
+
+The result is written to the file `portal-test.xml`.
+
+The XSLT parameters have the following meaning:
+
+* `use.xinclude` (default: `false()`): split the result config into different files and use XInclude elements to refer to.
+* `outputdir` (default `output/`): determines the directory to write output files to. Mind the trailing slash.
+* `outputfile` (default: `portal.xml`): The main output base filename.
+* `schemafile` (default: empty): The RNG or RNC schema file that is referenced in a `<?xml-model?>` processing instruction at the header.
+  The stylesheet takes care of the format and creates the appropriate PI.
+
+To create a splited XML config, use the following command:
+
+
+```shell
+xsltproc --xinclude \
+  --param use.xinclude 1 \
+  --stringparam outputdir "config.d/" \
+  convert-v6-to-v7.xsl \
+  docserv-stitch-2026-??-??.xml
+```
+
+## General Changes
+These changes reflect broad architectural shifts and naming conventions throughout the entire configuration system.
+
+* **Rebranding**: The naming convention has shifted from "Docserv²" to "Portal."
+
+* **Enhanced Modularity**: The schema now explicitly supports splitting large configuration files into smaller, more manageable parts. By utilizing inclusion mechanisms, you can maintain different sections of the portal (like `<categories>` or specific products) in separate files, leading to a cleaner and more maintainable structure.
+
+* **Documentation-First Design**: The schema now heavily utilizes `db:refname` and `db:refpurpose` annotations for almost every element and attribute. This allows for automated generation of human-readable documentation directly from the RNC file.
+
+* **Implicit Language Logic**: Master/source language identification has shifted from a boolean attribute (`@default`) to a value-based system. The schema now assumes `en-us` is the default language for products and deliverables.
+
+* **Migration Tooling**: To facilitate the transition, an XSLT migration stylesheet is available. This tool automates the conversion of version 6.0 configuration files to the 7.0 format, handling the renaming of elements, restructuring of attributes, and the removal of deprecated metadata.
+
+* **Resolving Ambiguity**: Some elements were used in multiple contexts, for example, the multipurpose `<language>` element. The new portal schema resolves this ambiguity.
+
+## New Elements and Attributes
+Version 7.0 introduces several elements to support a more hierarchical portal structure and better metadata documentation.
+
+### Elements
+* `<portal>`: The new root element for the entire portal configuration.
+* `<spotlight>`: Used to highlight specific products or deliverables on the entry page.
+* `<productfamilies>`: A container for defining product family groupings.
+* `<series>`: Defines series/tabs (e.g., SBP, TRD, Products & Solutions).
+* `<item>`: Generic element for entries within a family or series.
+* `<descriptions>`: A unified wrapper for product or version descriptions.
+* `<categories>`: A wrapper for grouping category definitions.
+* `<resources>`: Replaces the old `<builddocs>` element for defining deliverables.
+* `<prebuilt>`: Specifically for defining pre-built content links with metadata.
+* `<xi:include>`:  An XInclude element pointing to an external XML resource to facilitate modularity.
+
+### Attributes
+
+* `@schemaversion`: Replaces the previous versioning logic for stricter validation against the 7.0 spec.  
+* `@rank`: Determines the sorting order of products on the portal homepage.  
+* `@family`: Links a product to a specific product family via `IDREF`.  
+* `@series`: Links a product to a specific series/tab via IDREF.  
+* `@path`: Used on products and docsets to specify relative directory names.  
+* `@linkend`: Used in `<ref\>` elements to point to external link identifiers.  
+* `@treatment`: Defines how version-specific descriptions interact with global ones (append, prepend, or replace).
+* `@sitemap`: Determines whether the resource is included in the sitemap. Default is `true`.
+
+## Renamed Elements and Attributes
+
+Many elements were renamed to move away from "Docserv²" terminology and adopt a cleaner "Portal" naming convention.
+
+| Old Name (v6.0) | New Name (v7.0) | Context |
+| :---- | :---- | :---- |
+| `<desc>`         | `<descriptions>` | Move a single description into a parent `<descriptions>` |
+| `<builddocs>`    | `<resources>` | Container for definitions of resources |
+| `<overridedesc>` | `<descriptions>` | Version-specific content |
+| `<language>` (in resources) | `<locale>` | Regional build definitions |
+| `@productid`     | `@id` (type ID) | Unique identifier for products |
+| `@setid`         | `@id` (type ID) | Unique identifier for docsets |
+| `@categoryid`    | `@id` (type ID) | Unique identifier for categories |
+| `@linkid`        | `@id` (type ID) | Unique identifier for external links |
+
+## Removed Elements and Attributes
+
+The following items were deprecated or removed to simplify the build process and clean up the configuration.
+
+* `<buildcontainer>`: Support for specifying custom Docker images per version has been removed.  
+* `<param>`: Support for custom XSLT parameters via the config file is removed.  
+* `@translation-type`: The distinction between "list" and "full" translations has been replaced by a more flexible \<locale\> and reference model.
+* `@default`: This attribute (previously used in `<desc>` and `<language>` to flag the source/master language) has been removed. Language master ship is now determined by the explicit `en-us` value in the `@lang` attribute.
+* `@meta` from `<deliverable>`
+
+## Changed Content Models
+The structure of the schema has evolved to be more modular and better documented.
+
+### Modularization (XInclude)
+Major elements now support `xi:include`, allowing configuration files to be broken into smaller, manageable chunks.
+
+## link
+Allows multiple URLs in `<link>`. This makes it possible to have different formats. Additionally allow a `<desc>` element to describe the resource.
+
+The minimum structure is this:
+
+```xml
+<external>
+    <link category="about" gated="false">
+      <!-- Cardinality for <url>: one or more -->
+      <url href="http://example.com" format="html"/>
+      <descriptions>
+    <desc lang="en-us">
+      <title></title>
+    </desc>
+    <!-- more <desc> for other languages -->
+      </descriptions>
+    </link>
+</external>
+```
+
+### Deliverable References
+In version 7.0, translations of deliverables are primarily handled as references (`<ref\>`) back to the source DC file in the en-us locale, rather than duplicating the full deliverable metadata.
+
+Additionally, the `<ref/>` contains only a `@linkend` attribute to link to a resource. You don't need `dc`, `product`, or other strange combinations anymore.
+
+### Expanded Root Element Support
+The schema no longer restricts the start of a document to just a product definition. It now allows for much more variety in valid root elements, supporting the standalone definition of `<product>`s, `<docset>`s, `<categories>`, and more.
+
+### Simplified External Link Model
+The model for external links has been significantly flattened. The previous hierarchical structure involving nested `<language>` elements has been removed. Now, a `<link>` directly contains a list of `<url>` elements and a unified `<descriptions>` block, simplifying how external resources are defined across different locales.
+
+
+## Additional Sources
+
+* https://github.com/openSUSE/docbuild/pull/197
+* https://confluence.suse.com/x/0QB5e

src/docbuild/config/xml/data/config.d/appliance/appliance.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<product xmlns:xi="http://www.w3.org/2001/XInclude" id="appliance" family="f.linux" series="s.pas" rank="04150">
+  <name>Appliance building</name>
+  <acronym>appliance</acronym>
+  <maintainers>
+    <!-- <contact>[email protected]</contact> -->
+    <contact>[email protected]</contact>
+    <contact>[email protected]</contact>
+  </maintainers>
+  <xi:include href="desc/desc.xml"/>
+  <!-- Description is needed for validation, even if empty. Do not remove! -->
+  <xi:include href="kiwi-9.xml"/>
+  <xi:include href="keg-2.xml"/>
+</product>

src/docbuild/config/xml/data/config.d/appliance/desc/desc.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<descriptions xmlns:xi="http://www.w3.org/2001/XInclude">
+  <xi:include href="en-us.xml"/>
+</descriptions>

src/docbuild/config/xml/data/config.d/appliance/desc/en-us.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<desc lang="en-us">
+    <title>Linux system appliance building</title>
+    
+  </desc>

src/docbuild/config/xml/data/config.d/appliance/keg-2.xml

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<docset xmlns:xi="http://www.w3.org/2001/XInclude" lifecycle="supported" id="appliance.keg-2" path="keg-2">
+  <name>Keg Image Description Generator</name>
+  <version>2</version>
+  <descriptions treatment="append">
+    <desc lang="en-us">
+        <p>
+          Keg is a tool which helps to create and manage image descriptions
+          suitable for the KIWI appliance builder. The primary use case for keg
+          are situations where many image descriptions must be managed and the
+          image descriptions have considerable overlap with respect to content
+          and setup.
+        </p>
+      </desc>
+  </descriptions>
+  <resources>
+    <git remote="https://github.com/SUSE-Enceladus/keg.git"/>
+    <locale lang="en-us" sitemap="false">
+      <branch>main</branch>
+      <subdir>doc</subdir>
+      <deliverable id="app.keg-2.dc-keg" type="dc">
+        <dc file="DC-keg">
+          <format epub="0" html="1" pdf="1" single-html="1"/>
+        </dc>
+      </deliverable>
+    </locale>
+  </resources>
+</docset>

src/docbuild/config/xml/data/config.d/appliance/kiwi-9.xml

@@ -0,0 +1,112 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<docset xmlns:xi="http://www.w3.org/2001/XInclude" lifecycle="supported" id="appliance.kiwi-9" path="kiwi-9">
+  <name>KIWI Appliance Builder</name>
+  <version>9</version>
+  <descriptions treatment="append">
+    <desc lang="en-us">
+      <p>
+        KIWI NG (Next Generation) is the command-line utility to build Linux
+        system appliances. The documentation published here is written for the
+        latest KIWI NG upstream version. The upstream version may be slightly
+        ahead of the version shipped in the latest release of SUSE Linux
+        Enterprise.
+      </p>
+      <p>
+        Builds of the upstream version of KIWI NG for your OS version are
+        <a href="https://download.opensuse.org/repositories/Virtualization:/Appliances:/Builder">available from OBS</a>.
+        These builds are supported on a best-effort basis.
+      </p>
+      </desc>
+    <desc lang="de-de">
+        <p>
+        KIWI NG (Nächste Generation) ist ein Kommandozeilenwerkzeug, mit dem sich
+        Linux-System-Appliances erstellen lassen.
+        Die hier veröffentlichte Dokumentation wurde für die neueste Version von
+        KIWI NG erstellt.
+        Diese Upstream-Version kann etwas anders funktionieren, als die Version,
+        die in der aktuellen Version von SUSE Linux Enterprise enthalten ist.
+      </p>
+      <p>
+        Builds der Upstream-Version von KIWI NG für Ihr Betriebssystem finden Sie
+        <a href="https://download.opensuse.org/repositories/Virtualization:/Appliances:/Builder">im OBS</a>.
+        Wir bemühen uns, diese Builds zu unterstützen.
+      </p>
+      </desc>
+    <desc lang="es-es">
+      <p>
+        KIWI NG (Next Generation) es la utilidad de línea de comandos para crear
+        dispositivos de sistema Linux.
+        La documentación publicada aquí está escrita para la versión de nivel
+        superior más reciente de KIWI NG.
+        Esta versión puede funcionar de forma ligeramente diferente a la versión
+        incluida en la versión más reciente de SUSE Linux Enterprise.
+      </p>
+      <p>
+        Las compilaciones de la versión de nivel superior de KIWI NG para la
+        versión de su sistema operativo están
+        <a href="https://download.opensuse.org/repositories/Virtualization:/Appliances:/Builder">disponibles en OBS</a>.
+        La asistencia para estas compilaciones se ofrece con una filosofía de
+        mejor esfuerzo.
+      </p>
+    </desc>
+    <desc lang="fr-fr">
+      <p>
+        KIWI NG (Next Generation) est l'utilitaire de ligne de
+        commande qui permet de créer des applicatifs système Linux.
+        La documentation publiée ici est destinée à la dernière version en
+        amont de KIWI NG.
+        Cette version en amont peut fonctionner légèrement différemment de
+        celle livrée dans la dernière édition de SUSE Linux Enterprise.
+      </p>
+      <p>
+        Les builds de la version en amont de KIWI NG pour votre version de
+        système d'exploitation sont
+        <a href="https://download.opensuse.org/repositories/Virtualization:/Appliances:/Builder">disponibles sur OBS</a>.
+        Ces builds sont pris en charge du mieux possible.
+      </p>
+    </desc>
+    <desc lang="ja-jp">
+      <p>
+        KIWI NG (Next Generation)は、Linuxシステムアプライアンスを構築するためのコマンドラインユーティリティです。ここで公開されているマニュアルは、最新のKIWI NGアップストリームバージョン用に作成されています。このアップストリームバージョンは、SUSE Linux Enterpriseの最新リリースで出荷されたバージョンとは若干異なる動作をする場合があります。
+      </p>
+      <p>
+        ご使用のOSバージョン向けKIWI NGのアップストリームバージョンのビルドは、<a href="https://download.opensuse.org/repositories/Virtualization:/Appliances:/Builder">OBSから入手可能</a>です。これらのビルドは、ベストエフォートベースでサポートされています。
+      </p>
+    </desc>
+    <desc lang="pt-br">
+      <p>
+        KIWI NG (Next Generation) é o utilitário de linha de comando para criar
+        aplicações de sistema Linux.
+        A documentação publicada aqui foi escrita para a versão de upstream
+        mais recente do KIWI NG.
+        Essa versão de upstream pode funcionar de maneira um pouco diferente da
+        versão fornecida no último lançamento do SUSE Linux Enterprise.
+      </p>
+      <p>
+        Os builds da versão de upstream do KIWI NG referentes à sua versão do OS estão
+        <a href="https://download.opensuse.org/repositories/Virtualization:/Appliances:/Builder">disponíveis no OBS</a>.
+        Esses builds são suportados na base dos melhores esforços.
+      </p>
+    </desc>
+    <desc lang="zh-cn">
+      <p>
+        KIWI NG（下一代）是用于构建 Linux 系统设备的命令行实用程序。此处发布的文档是为最新的 KIWI NG 上游版本编写的。此上游版本的工作方式可能与最新的 SUSE Linux Enterprise 版本中随附的版本略有不同。
+      </p>
+      <p>
+        适用于您的操作系统版本的 KIWI NG 上游版本的内部版本<a href="https://download.opensuse.org/repositories/Virtualization:/Appliances:/Builder">可从 OBS 获得</a>。我们会尽最大努力为这些内部版本提供支持。
+      </p>
+    </desc>
+  </descriptions>
+  <resources>
+    <git remote="https://github.com/OSInside/kiwi-suse-doc.git"/>
+    <locale lang="en-us" sitemap="false">
+      <branch>master</branch>
+      <subdir>doc/build</subdir>
+      <deliverable id="app.kiwi-9.dc-kiwi" type="dc">
+        <dc file="DC-kiwi">
+          <format epub="0" html="1" pdf="1" single-html="1"/>
+        </dc>
+      </deliverable>
+    </locale>
+  </resources>
+</docset>

src/docbuild/config/xml/data/config.d/categories.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<categories xmlns:xi="http://www.w3.org/2001/XInclude">
+  <xi:include href="categories/en-us.xml"/>
+  <xi:include href="categories/de-de.xml"/>
+  <xi:include href="categories/es-es.xml"/>
+  <xi:include href="categories/fr-fr.xml"/>
+  <xi:include href="categories/ja-jp.xml"/>
+  <xi:include href="categories/ko-kr.xml"/>
+  <xi:include href="categories/pt-br.xml"/>
+  <xi:include href="categories/zh-cn.xml"/>
+</categories>

src/docbuild/config/xml/data/config.d/categories/de-de.xml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<category lang="de-de">
+  <language linkend="cat.about" title="Über"/>
+  <language linkend="cat.deployment" title="Bereitstellung"/>
+  <language linkend="cat.initial-config" title="Erstmalige Konfiguration"/>
+  <language linkend="cat.update-upgrade" title="Update &amp; Upgrade"/>
+  <language linkend="cat.administration" title="Administration"/>
+  <language linkend="cat.container-virtualization" title="Container und Virtualisierung"/>
+  <language linkend="cat.product-usage" title="Verwendung des Produkts"/>
+  <language linkend="cat.security-compliance" title="Sicherheit und Konformität"/>
+  <language linkend="cat.tuning-performance" title="Tuning &amp; Leistung"/>
+  <language linkend="cat.solution-doc" title="Dokumentation zur Lösung"/>
+  <language linkend="cat.additional-doc" title="Weitere Dokumentation"/>
+  <language linkend="cat.best-practices" title="Bewährte Methoden"/>
+</category>