Skip to content

Commit c8f3e94

Browse files
tomschrtomschr
committed
Fix#187: Refactor product schema
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. * `<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 logic 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. * 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>` * 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` * 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
1 parent b7e5328 commit c8f3e94

16 files changed

Lines changed: 3298 additions & 926 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -289,3 +289,4 @@ audit_reports/
289289
git_repos/
290290
.DS_Store
291291
lean_audit.txt
292+
output/

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

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Portal Configuration
2+
3+
This directory contains:
4+
5+
* A RELAX NG schema (`src/docbuild/config/xml/data/product-config-schema.rnc`).
6+
It's the successor of the previous Docserv product schema.
7+
* An example `config.d` directory.
8+
9+
## File structure
10+
11+
The `config.d` directory contains several subdirectories
12+
13+
```text
14+
config.d/
15+
├── categories/
16+
│ ├── [... more languages ...]
17+
│ ├── de-de.xml
18+
│ └── en-us.xml
19+
├── cloudnative/
20+
│ ├── [... similar to sles/... ]
21+
│ └── cloudnative.xml
22+
├── portal.xml
23+
└── sles/
24+
├── desc
25+
│ ├── [... more languages ...]
26+
│ ├── descriptions.xml
27+
│ ├── de-de.xml
28+
│ └── en-us.xml
29+
├── docsets
30+
│ ├── [... more docsets ...]
31+
│ └── 16.0.xml
32+
└── sles.xml
33+
```
34+
35+
* `config.d/`: the configuration directory with all portal configuration
36+
* `categories/`: A directory that contains all categories.
37+
* `portal.xml`: The main entry file which references all categories and
38+
product configuration.
39+
* `sles/sles.xml`: The main product configuration for SLES.
40+
* `sles/desc/`: contains all language specific
41+
* `sles/docsets/`: contains all docsets of a product.
42+
Depending on the complexity of the product, this may not always be
43+
needed. For SLES, it would probably useful.
44+
45+
## Creating combined config
46+
47+
```shell
48+
xmllint --xinclude \
49+
--output src/docbuild/config/xml/data/stitchfile.xml \
50+
src/docbuild/config/xml/data/config.d/portal.xml
51+
```
52+
53+
54+
## Additional Sources
55+
56+
https://confluence.suse.com/x/0QB5e

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<?xml-model href="file:../portal-config-schema.rnc" type="application/relax-ng-compact-syntax"?>
3+
<categories xmlns:xi="http://www.w3.org/2001/XInclude">
4+
<xi:include href="categories/en-us.xml" />
5+
<xi:include href="categories/de-de.xml" />
6+
</categories>

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

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
<?xml-model href="file:../../portal-config-schema.rnc" type="application/relax-ng-compact-syntax"?>
2+
3+
<category lang="de-de">
4+
<language id="about" title="Über" />
5+
<language id="deployment" title="Deployment" />
6+
<language id="inital-config" title="Initiale Konfiguration" />
7+
<!-- ... more entries ... -->
8+
</category>

‎src/docbuild/config/xml/data/config.d/categories/en-us.xml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
<?xml-model href="file:../../portal-config-schema.rnc" type="application/relax-ng-compact-syntax"?>
2+
3+
<category lang="en-us">
4+
<language id="about" title="About" />
5+
<language id="deployment" title="Deployment" />
6+
<language id="inital-config" title="Initial configuration" />
7+
<!-- ... more entries ... -->
8+
</category>

‎src/docbuild/config/xml/data/config.d/cloudnative/cloudnative.xml‎

Whitespace-only changes.

‎src/docbuild/config/xml/data/config.d/portal.xml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<?xml-model href="file:../portal-config-schema.rnc" type="application/relax-ng-compact-syntax"?>
3+
<portal xmlns:xi="http://www.w3.org/2001/XInclude" schemaversion="7.0">
4+
5+
<xi:include href="categories.xml" />
6+
7+
<productfamilies>
8+
<item id="linux">Linux</item>
9+
<item id="cn">Cloud Native</item>
10+
<item id="suse-edge">SUSE Edge</item>
11+
<item id="suse-ai">SUSE AI</item>
12+
</productfamilies>
13+
<series>
14+
<item id="pas">Products &amp; Solutions</item>
15+
<item id="sbp">SUSE Best Practices</item>
16+
<item id="trd">Technical References</item>
17+
<item id="rn">Release Notes</item>
18+
</series>
19+
20+
<xi:include href="sles/sles.xml" />
21+
22+
</portal>

‎src/docbuild/config/xml/data/config.d/sles/16.0.xml‎

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<?xml-model href="../../../portal-config-schema.rnc" type="application/relax-ng-compact-syntax"?>
3+
<docset setid="16.0" lifecycle="supported">
4+
<version>16.0</version>
5+
<canonical>sles/16.0</canonical>
6+
7+
<!--<descriptions>
8+
</descriptions>-->
9+
10+
<resources>
11+
<git remote="https://github.com/SUSE/doc-modular.git"/>
12+
<locale lang="en-us">
13+
<branch>maintenance/SLE16.0</branch>
14+
<!--************************ about ************************-->
15+
<deliverable category="about" type="dc">
16+
<git remote="https://github.com/SUSE/doc-modular.git"/>
17+
<dc>DC-SLE-comparison</dc>
18+
<format html="1" pdf="1" single-html="0"/>
19+
</deliverable>
20+
<deliverable category="about">
21+
<dc>DC-SLE-differences-faq</dc>
22+
<format html="1" pdf="1" single-html="0"/>
23+
</deliverable>
24+
<deliverable category="about">
25+
<dc>DC-SLE-packages-lifecycle</dc>
26+
<format html="1" pdf="1" single-html="0"/>
27+
</deliverable>
28+
<deliverable category="about">
29+
<dc>DC-SLE-os-identification</dc>
30+
<format html="1" pdf="1" single-html="0"/>
31+
</deliverable>
32+
<!--**************** deployement ****************-->
33+
<deliverable category="deployment">
34+
<dc>DC-SLES-x86-64-agama-based-installation</dc>
35+
<format html="1" pdf="1" single-html="0"/>
36+
</deliverable>
37+
<deliverable category="deployment">
38+
<dc>DC-SLES-s390-agama-based-installation</dc>
39+
<format html="1" pdf="1" single-html="0"/>
40+
</deliverable>
41+
<deliverable category="deployment">
42+
<dc>DC-SLES-ppc-agama-based-installation</dc>
43+
<format html="1" pdf="1" single-html="0"/>
44+
</deliverable>
45+
<deliverable category="deployment">
46+
<dc>DC-SLES-x86-64-agama-automated-installation</dc>
47+
<format html="1" pdf="1" single-html="0"/>
48+
</deliverable>
49+
<deliverable category="deployment">
50+
<dc>DC-SLES-PXE-server</dc>
51+
<format html="1" pdf="1" single-html="0"/>
52+
</deliverable>
53+
<deliverable category="deployment">
54+
<dc>DC-SLES-deployment-pxe-client</dc>
55+
<format html="1" pdf="1" single-html="0"/>
56+
</deliverable>
57+
<!--***************** update-upgrade *****************-->
58+
<deliverable category="update-upgrade">
59+
<dc>DC-SLES-klp</dc>
60+
<format html="1" pdf="1" single-html="0"/>
61+
</deliverable>
62+
<deliverable category="update-upgrade">
63+
<dc>DC-SLES-ulp</dc>
64+
<format html="1" pdf="1" single-html="0"/>
65+
</deliverable>
66+
<deliverable category="update-upgrade">
67+
<dc>DC-SLES-upgrading</dc>
68+
<format html="1" pdf="1" single-html="0"/>
69+
</deliverable>
70+
<!--*************** administration ***************-->
71+
<deliverable category="administration">
72+
<dc>DC-SLES-Ansible</dc>
73+
<format html="1" pdf="1" single-html="0"/>
74+
</deliverable>
75+
<deliverable category="administration">
76+
<dc>DC-SLES-ansible-roles</dc>
77+
<format html="1" pdf="1" single-html="0"/>
78+
</deliverable>
79+
<deliverable category="administration">
80+
<dc>DC-SLES-cockpit</dc>
81+
<format html="1" pdf="1" single-html="0"/>
82+
</deliverable>
83+
<deliverable category="administration">
84+
<dc>DC-SLES-copy-file-rsync</dc>
85+
<format html="1" pdf="1" single-html="0"/>
86+
</deliverable>
87+
<deliverable category="administration">
88+
<dc>DC-SLES-gnome-remote-desktop</dc>
89+
<format html="1" pdf="1" single-html="0"/>
90+
</deliverable>
91+
<deliverable category="administration">
92+
<dc>DC-SLES-networkmanager-nmcli</dc>
93+
<format html="1" pdf="1" single-html="0"/>
94+
</deliverable>
95+
<deliverable category="administration">
96+
<dc>DC-SLES-ntp-time-synchronization</dc>
97+
<format html="1" pdf="1" single-html="0"/>
98+
</deliverable>
99+
<deliverable category="administration">
100+
<dc>DC-SLES-predictable-naming</dc>
101+
<format html="1" pdf="1" single-html="0"/>
102+
</deliverable>
103+
<deliverable category="administration">
104+
<dc>DC-SLES-snapper-basics</dc>
105+
<format html="1" pdf="1" single-html="0"/>
106+
</deliverable>
107+
<deliverable category="administration">
108+
<dc>DC-SLES-subnet-manager</dc>
109+
<format html="1" pdf="1" single-html="0"/>
110+
</deliverable>
111+
<deliverable category="administration">
112+
<dc>DC-SLES-sudo-run-commands-as-superuser</dc>
113+
<format html="1" pdf="1" single-html="0"/>
114+
</deliverable>
115+
<deliverable category="administration">
116+
<dc>DC-SLES-supportconfig</dc>
117+
<format html="1" pdf="1" single-html="0"/>
118+
</deliverable>
119+
<deliverable category="administration">
120+
<dc>DC-SLES-systemd-basics</dc>
121+
<format html="1" pdf="1" single-html="0"/>
122+
</deliverable>
123+
<deliverable category="administration">
124+
<dc>DC-SLES-systemd-timers</dc>
125+
<format html="1" pdf="1" single-html="0"/>
126+
</deliverable>
127+
<!--*************** container-virtualization ***************-->
128+
<deliverable category="container-virtualization">
129+
<dc>DC-SLES-apache-tomcat-cloud</dc>
130+
<format html="1" pdf="1" single-html="0"/>
131+
</deliverable>
132+
<deliverable category="container-virtualization">
133+
<dc>DC-SLES-virtualization</dc>
134+
<format html="1" pdf="1" single-html="0"/>
135+
</deliverable>
136+
<deliverable category="container-virtualization">
137+
<dc>DC-SLES-virtualization-disk-cache</dc>
138+
<format html="1" pdf="1" single-html="0"/>
139+
</deliverable>
140+
<deliverable category="container-virtualization">
141+
<dc>DC-SLES-virtualization-io</dc>
142+
<format html="1" pdf="1" single-html="0"/>
143+
</deliverable>
144+
<deliverable category="container-virtualization">
145+
<dc>DC-SLES-virtualization-libvirt</dc>
146+
<format html="1" pdf="1" single-html="0"/>
147+
</deliverable>
148+
<deliverable category="container-virtualization">
149+
<dc>DC-SLES-virtualization-qemu</dc>
150+
<format html="1" pdf="1" single-html="0"/>
151+
</deliverable>
152+
<deliverable category="container-virtualization">
153+
<dc>DC-SLES-virtualization-spice-removal</dc>
154+
<format html="1" pdf="1" single-html="0"/>
155+
</deliverable>
156+
<deliverable category="container-virtualization">
157+
<dc>DC-SLES-virtualization-support</dc>
158+
<format html="1" pdf="1" single-html="0"/>
159+
</deliverable>
160+
<deliverable category="container-virtualization">
161+
<dc>DC-SLES-vm-host-network-multihome-setup</dc>
162+
<format html="1" pdf="1" single-html="0"/>
163+
</deliverable>
164+
<!--****************** product-usage ******************-->
165+
<deliverable category="product-usage">
166+
<dc>DC-SLES-GNOME-getting-started</dc>
167+
<format html="1" pdf="1" single-html="0"/>
168+
</deliverable>
169+
<deliverable category="product-usage">
170+
<dc>DC-SLES-valkey</dc>
171+
<format html="1" pdf="1" single-html="0"/>
172+
</deliverable>
173+
<!--*************** security-compliance ***************-->
174+
<deliverable category="security-compliance">
175+
<dc>DC-SLES-intro-firewalld</dc>
176+
<format html="1" pdf="1" single-html="0"/>
177+
</deliverable>
178+
<deliverable category="security-compliance">
179+
<dc>DC-SLES-SELinux</dc>
180+
<format html="1" pdf="1" single-html="0"/>
181+
</deliverable>
182+
<deliverable category="security-compliance">
183+
<dc>DC-SLES-sudo-configure-superuser-privileges</dc>
184+
<format html="1" pdf="1" single-html="0"/>
185+
</deliverable>
186+
<!--*********tuning-performance******-->
187+
<deliverable category="tuning-performance">
188+
<dc>DC-SAP-saptune</dc>
189+
<format html="1" pdf="1" single-html="0"/>
190+
</deliverable>
191+
</locale>
192+
193+
<locale lang="de-de">
194+
<branch>main</branch>
195+
<deliverable>
196+
<dc>DC-foo</dc>
197+
<format html="1"/>
198+
</deliverable>
199+
</locale>
200+
</resources>
201+
202+
<external>
203+
<link category="about" gated="false">
204+
<url href="http://example.com" format="html"/>
205+
<url href="http://example.com/doc.pdf" format="pdf"/>
206+
<!-- Cardinality: + -->
207+
<descriptions>
208+
<desc lang="en-us">
209+
<title> </title>
210+
<p>...</p>
211+
</desc>
212+
<!-- more <desc> for other languages -->
213+
</descriptions>
214+
</link>
215+
</external>
216+
</docset>

‎src/docbuild/config/xml/data/config.d/sles/desc/de-de.xml‎

Whitespace-only changes.

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

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<?xml-model href="../../../portal-config-schema.rnc" type="application/relax-ng-compact-syntax"?>
3+
<desc lang="en-us">
4+
<title>THE platform for your business-critical apps in any environment</title>
5+
<p>
6+
A multimodal operating system that paves the way for IT transformation in the
7+
software-defined era.
8+
</p>
9+
<p>
10+
The modern and modular OS helps simplify multimodal IT, makes traditional IT
11+
infrastructure efficient and provides an engaging platform for developers.
12+
As a result, you can easily deploy and transition business-critical workloads
13+
across on-premise and public cloud environments.
14+
</p>
15+
<p>
16+
SUSE Linux Enterprise Server, based on latest SUSE Linux Enterprise, is another
17+
example of our open approach helping you optimize and modernize your multimodal
18+
IT infrastructure.
19+
</p>
20+
</desc>

0 commit comments

Comments
 (0)