Schema changes for 7.0 (i.e. next major) release

bin/docserv-createconfig

@@ -164,9 +164,9 @@ def generate_config(args, git_url, branches, version=SCHEMAVERSION):
                         branch = "trans/%s" % tmp
                 etree.SubElement(lang, "branch").text = branch
                 etree.SubElement(lang, "subdir").text = FIXME
-        # TODO: add external/links as comments
-        # externallinks = etree.SubElement(docset, "external")
-        # etree.SubElement(externallinks, "link", href=FIXME).text = "SOME DESCRIPTION"
+        # TODO: add weblinks/links as comments
+        # weblinks = etree.SubElement(docset, "weblinks")
+        # etree.SubElement(weblinks, "link", href=FIXME).text = "SOME DESCRIPTION"
 
     tree = etree.ElementTree(root)
     configfile = os.path.join(os.getcwd(), "{}.xml".format(args.productid))

config/product-config/docserv2.xml

@@ -36,13 +36,13 @@
 
     </builddocs>
 
-    <external>
+    <weblinks>
       <link linkid="change-log">
         <language lang="en-us" default="1" title="Change log">
           <url format="html" href="https://github.com/openSUSE/docserv/blob/main/CHANGELOG.md"/>
         </language>
       </link>
-    </external>
+    </weblinks>
 
   </docset>
 

config/product-config/example_product.xml

@@ -138,15 +138,15 @@
 
     </builddocs>
 
-    <internal>
+    <crossrefs>
       <ref product="example_product" category="another_example"/>
       <ref product="example_product" docset="1.0"/>
       <ref product="example_product" docset="1.0" dc="DC-example-admin"/>
       <ref product="example_product" docset="1.0" dc="DC-example-all" subdeliverable="book.admin"/>
       <ref product="example_product" docset="1.0" link="release-notes"/>
-    </internal>
+    </crossrefs>
 
-    <external>
+    <weblinks>
       <link linkid="rn">
         <language lang="en-us" default="1" title="Release Notes">
           <url format="html" href="https://www.example.org/1"/>
@@ -167,7 +167,7 @@
           <url format="html" href="https://www.example.org/3"/>
         </language>
       </link>
-    </external>
+    </weblinks>
 
   </docset>
 
@@ -207,7 +207,7 @@
 
     </builddocs>
 
-    <external>
+    <weblinks>
       <link linkid="release-notes">
         <language lang="en-us" default="1" title="Release Notes">
           <url format="html" href="https://www.example.org/1/"/>
@@ -223,7 +223,7 @@
           <url format="pdf" href="https://www.example.org/2"/>
         </language>
       </link>
-    </external>
+    </weblinks>
 
   </docset>
 

docs/adoc/config-product.adoc

@@ -43,17 +43,17 @@ A very reduced example of a product configuration file may look like this:
         </deliverable>
       </language>
     </builddocs>
-    <internal>
+    <crossrefs>
       <ref product="example-product"/>
-    </internal>
-    <external>
+    </crossrefs>
+    <weblinks>
       <link linkid="rn">
         <language lang="en-us" default="1" title="Extra document">
           <url format="html" href="https://www.example.org/1"/>
           <url format="pdf" href="https://www.example.org/1.pdf"/>
         </language>
       </link>
-    </external>
+    </weblinks>
   </docset>
 
 </product>
@@ -138,10 +138,10 @@ The optional `@navigation` attribute of docsets defines whether to create naviga
 {ds2} will automatically create ZIP archives of these documents.
 +
 However, to update the navigational pages for such documents, the documents need to remain buildable within {ds2}, even if the product is no longer supported.
-* `<internal/>`: References to {ds2} navigational pages or documents defined elsewhere in the product configuration.
+* `<crossrefs/>`: References to {ds2} navigational pages or documents defined elsewhere in the product configuration.
 {ds2} will extract the URL and metadata such as the document title from their original context in the product configuration.
 
-* `<external/>`: References to documents created outside of {ds2}.
+* `<weblinks/>`: References to documents created outside of {ds2}.
 Such documents can be located anywhere on the internet.
 They can also be located on the same host as {ds2}-created documents, placed in such a way that they do not interfere with the directory structure created by {ds2}.
 URLs and document titles of such documents must be defined manually.
@@ -200,21 +200,21 @@ Within a `<deliverable/>` element of a non-default `<language/>` element, the nu
 
 
 [#config-product-external-reference]
-### References to documents not generated within {ds2}, `<external/>`
+### References to documents not generated within {ds2}, `<weblinks/>`
 
-The `<external/>` element collects links to documents that are not generated using {ds2}.
+The `<weblinks/>` element collects links to documents that are not generated using {ds2}.
 {ds2} makes no effort to ensure availability of such documents, meaning all links to them must be checked manually.
 Such documents can be co-hosted along with {ds2} or be on another host altogether.
 
-For each required document, add a `<link/>` element to the `<external/>` element.
+For each required document, add a `<link/>` element to the `<weblinks/>` element.
 A `<link/>` can reference documents in multiple formats and multiple languages.
 The primary language (`<language default="true"/>`) must be listed first.
 
 
 [#config-product-internal-reference]
-### {ds2}-internal references, `<internal/>`
+### {ds2}-internal references, `<crossrefs/>`
 
-Within the `<internal/>` element, reference documents already defined elsewhere in the {ds2} configuration.
+Within the `<crossrefs/>` element, reference documents already defined elsewhere in the {ds2} configuration.
 Document references (using the `<ref/>` element) will inherit all properties of the original document, such as available formats and languages and reduce duplication.
 You can also reference related product pages within this element.
 
@@ -256,9 +256,9 @@ Likewise, within a `<builddocs/>` section, the `@lang` attributes' values of `<l
 
 * DC file names (`<dc/>` attributes) must be unique within the `<language/>` that contains them.
 After removing the `DC-` prefix, DC file names are used as path components.
-These identifiers can be used for `<internal/>` references to generated documents.
-* `<link linkid="__[ID]__"/>` is an optional identifier for `<external/>` links.
-These identifiers can be used for `<internal/>` references to such links.
+These identifiers can be used for `<crossrefs/>` references to generated documents.
+* `<link linkid="__[ID]__"/>` is an optional identifier for `<weblinks/>` links.
+These identifiers can be used for `<crossrefs/>` references to such links.
 
 * URLs referenced within external links (`<link/>`) elements must be unique within the context of the docset they are used in.
 

share/build-navigation/build-navigation-json.xsl

@@ -405,8 +405,8 @@
           select="( builddocs/language[@default = 'true']/deliverable[not(subdeliverable)][not(@category)] |
                     builddocs/language[@default = 'true']/deliverable/subdeliverable[not(@category)] )"
           mode="generate-docset-json"/>
-        <xsl:apply-templates select="internal/ref[not(@category)]" mode="generate-docset-json"/>
-        <xsl:apply-templates select="external/link[not(@category)]" mode="generate-docset-json"/>
+        <xsl:apply-templates select="crossrefs/ref[not(@category)]" mode="generate-docset-json"/>
+        <xsl:apply-templates select="weblinks/link[not(@category)]" mode="generate-docset-json"/>
       </xsl:variable>
       <xsl:variable name="documents">
         <xsl:call-template name="dedupe-documents">
@@ -436,8 +436,8 @@
           select="( $node/builddocs/language[@default = 'true']/deliverable[not(subdeliverable)][contains(concat(' ', @category,' '), $categoryid)] |
                     $node/builddocs/language[@default = 'true']/deliverable/subdeliverable[contains(concat(' ',@category,' '), $categoryid)] )"
           mode="generate-docset-json"/>
-        <xsl:apply-templates select="$node/internal/ref[contains(concat(' ',@category,' '), $categoryid)]" mode="generate-docset-json"/>
-        <xsl:apply-templates select="$node/external/link[contains(concat(' ',@category,' '), $categoryid)]" mode="generate-docset-json"/>
+        <xsl:apply-templates select="$node/crossrefs/ref[contains(concat(' ',@category,' '), $categoryid)]" mode="generate-docset-json"/>
+        <xsl:apply-templates select="$node/weblinks/link[contains(concat(' ',@category,' '), $categoryid)]" mode="generate-docset-json"/>
       </xsl:variable>
       <xsl:variable name="documents">
         <xsl:call-template name="dedupe-documents">
@@ -724,7 +724,7 @@
     </xsl:choose>
   </xsl:template>
 
-  <xsl:template match="internal/ref" mode="generate-docset-json">
+  <xsl:template match="crossrefs/ref" mode="generate-docset-json">
     <xsl:variable name="product" select="@product"/>
     <xsl:variable name="docset" select="@docset"/>
     <xsl:variable name="dc" select="@dc"/>
@@ -740,7 +740,7 @@
 
     <xsl:choose>
       <xsl:when test="$link != ''">
-        <xsl:apply-templates select="(//product[@productid = $product]/docset[@setid = $docset]/external/link[@linkid = $link])[1]" mode="generate-docset-json">
+        <xsl:apply-templates select="(//product[@productid = $product]/docset[@setid = $docset]/weblinks/link[@linkid = $link])[1]" mode="generate-docset-json">
           <xsl:with-param name="titleformat" select="$titleformat"/>
         </xsl:apply-templates>
       </xsl:when>
@@ -840,7 +840,7 @@
     </xsl:if>
   </xsl:template>
 
-  <xsl:template match="external/link" mode="generate-docset-json">
+  <xsl:template match="weblinks/link" mode="generate-docset-json">
     <xsl:param name="docset-title-inject" select="0"/>
 
     <xsl:variable name="injected-title">

share/validate-product-config/checks/check-duplicated-format-in-extralinks.sh

@@ -5,14 +5,14 @@
 
 file=$1
 
-links=$($starlet sel -t -v "count(//language[parent::link/parent::external])" $file)
+links=$($starlet sel -t -v "count(//language[parent::link/parent::weblinks])" $file)
 for link in $(seq 1 "$links"); do
-  current_id=$($starlet sel -t -v '(//language[parent::link/parent::external])['"$link"']/url[1]/@href' $file | sort)
-  formats=$($starlet sel -t -v '(//language[parent::link/parent::external])['"$link"']/url/@format' $file | sort)
+  current_id=$($starlet sel -t -v '(//language[parent::link/parent::weblinks])['"$link"']/url[1]/@href' $file | sort)
+  formats=$($starlet sel -t -v '(//language[parent::link/parent::weblinks])['"$link"']/url/@format' $file | sort)
   uniqueformats=$(echo -e "$formats" | sort -u)
   [[ ! "$formats" == "$uniqueformats" ]] && \
   echo -e \
-    "For the link with the URL \"$current_id\", some of the values of format attributes in url elements are duplicated. Check for occurrences of the following duplicated format attribute(s) in the link \"$current_id\": "$(comm -2 -3 <(echo -e "$formats") <(echo -e "$uniqueformats") | tr '\n' ' ')".\n---"
+    "For the link with the URL \"$current_id\", some of the values of format attributes in url elements are duplicated. Check for occurrences of the following duplicated format attribute(s) in the web link \"$current_id\": "$(comm -2 -3 <(echo -e "$formats") <(echo -e "$uniqueformats") | tr '\n' ' ')".\n---"
 done
 
 exit 0

share/validate-product-config/checks/check-duplicated-linkid.sh

@@ -6,13 +6,13 @@
 
 file=$1
 
-externals=$($starlet sel -t -v "count(//external)" $file)
+externals=$($starlet sel -t -v "count(//weblinks)" $file)
 
 for external in $(seq 1 $externals); do
-  linkids=$($starlet sel -t -v '(//external)['"$external"']/link/@linkid' $file | sort)
+  linkids=$($starlet sel -t -v '(//weblinks)['"$external"']/link/@linkid' $file | sort)
   uniquelinkids=$(echo -e "$linkids" | sort -u)
 
-  curdocset=$($starlet sel -t -v '(//external)['"$external"']/ancestor::docset/@setid' $file)
+  curdocset=$($starlet sel -t -v '(//weblinks)['"$external"']/ancestor::docset/@setid' $file)
 
   [[ ! "$linkids" == "$uniquelinkids" ]] && \
     echo -e \

share/validate-product-config/checks/check-duplicated-url-in-extralinks.sh

@@ -4,17 +4,17 @@
 
 file=$1
 
-externallinks_sections=$($starlet sel -t -v "count(//external)" $file)
+externallinks_sections=$($starlet sel -t -v "count(//weblinks)" $file)
 for externallinks_section in $(seq 1 "$externallinks_sections"); do
-  current_id=$($starlet sel -t -v '(//external)['"$externallinks_section"']/ancestor::docset/@setid' $file)
+  current_id=$($starlet sel -t -v '(//weblinks)['"$externallinks_section"']/ancestor::docset/@setid' $file)
   # FIXME: The removal of http(s):// here is a bit unkosher -- especially
   # since we don't add it back at the end before displaying the result to
   # the user.
-  urls=$($starlet sel -t -v '(//external)['"$externallinks_section"']/descendant::url/@href' $file | sed -r 's%^https?://%%' | sort)
+  urls=$($starlet sel -t -v '(//weblinks)['"$externallinks_section"']/descendant::url/@href' $file | sed -r 's%^https?://%%' | sort)
   uniqueurls=$(echo -e "$urls" | sort -u)
   [[ ! "$urls" == "$uniqueurls" ]] && \
   echo -e \
-    "Within the external links section of docset $current_id, some URLs are duplicated. Check for occurrences of the following duplicated URL(s) within the external links of docset \"$current_id\": "$(comm -2 -3 <(echo -e "$urls") <(echo -e "$uniqueurls") | tr '\n' ' ')".\n---"
+    "Within the external links section of docset $current_id, some URLs are duplicated. Check for occurrences of the following duplicated URL(s) within the web links of docset \"$current_id\": "$(comm -2 -3 <(echo -e "$urls") <(echo -e "$uniqueurls") | tr '\n' ' ')".\n---"
 done
 
 exit 0

share/validate-product-config/checks/check-lang-code-in-extralinks.sh

@@ -5,14 +5,14 @@
 
 file=$1
 
-links=$($starlet sel -t -v "count(//link[parent::external])" $file)
+links=$($starlet sel -t -v "count(//link[parent::weblinks])" $file)
 for link in $(seq 1 "$links"); do
-  current_id=$($starlet sel -t -v '(//link[parent::external])['"$link"']/language[1]/url[1]/@href' $file | sort)
-  langcodes=$($starlet sel -t -v '(//link[parent::external])['"$link"']/language/@lang' $file | sort)
+  current_id=$($starlet sel -t -v '(//link[parent::weblinks])['"$link"']/language[1]/url[1]/@href' $file | sort)
+  langcodes=$($starlet sel -t -v '(//link[parent::weblinks])['"$link"']/language/@lang' $file | sort)
   uniquelangcodes=$(echo -e "$langcodes" | sort -u)
   [[ ! "$langcodes" == "$uniquelangcodes" ]] && \
   echo -e \
-    "Some of the localized versions of \"$current_id\" have non-unique lang attributes. Check for occurrences of the following duplicated lang attribute(s) in the language elements of link \"$current_id\": "$(comm -2 -3 <(echo -e "$langcodes") <(echo -e "$uniquelangcodes") | tr '\n' ' ')".\n---"
+    "Some of the localized versions of \"$current_id\" have non-unique lang attributes. Check for occurrences of the following duplicated lang attribute(s) in the language elements of web link \"$current_id\": "$(comm -2 -3 <(echo -e "$langcodes") <(echo -e "$uniquelangcodes") | tr '\n' ' ')".\n---"
 done
 
 exit 0

share/validate-product-config/global-check-ref-list.xsl

@@ -51,7 +51,7 @@ all exist. -->
       </xsl:when>
       <xsl:when test="@link and @docset and @product">
         <xsl:if
-          test="not(//product[@productid = $product]/docset[@setid = $docset]/external/link[@linkid = $link])">
+          test="not(//product[@productid = $product]/docset[@setid = $docset]/weblinks/link[@linkid = $link])">
           <xsl:text>Reference (ref) to </xsl:text>
           <xsl:value-of select="concat($product, '/', $docset, '@', $link)"/>
           <xsl:text> failed. Referenced external link does not exist.</xsl:text>
@@ -67,15 +67,6 @@ all exist. -->
           <xsl:text>&#10;---&#10;</xsl:text>
         </xsl:if>
       </xsl:when>
-      <xsl:when test="@product">
-        <xsl:if
-          test="not(//product[@productid = $product])">
-          <xsl:text>Reference (ref) to </xsl:text>
-          <xsl:value-of select="concat($product, '/', $docset)"/>
-          <xsl:text> failed. Referenced product does not exist.</xsl:text>
-          <xsl:text>&#10;---&#10;</xsl:text>
-        </xsl:if>
-      </xsl:when>
       <xsl:otherwise>
         <xsl:text>Reference failed. This issue should have been caught by the RNC validation. This is a docserv-stitch bug.</xsl:text>
         <xsl:text>&#10;---&#10;</xsl:text>