fix: integrate all ocis helper changes into the docs

antora-extensions/prerelease-attribute.js

@@ -0,0 +1,64 @@
+'use strict'
+
+/**
+ * Set the AsciiDoc attribute `page-component-version-is-prerelease` on every page
+ * of a component version that is marked `prerelease` in its antora.yml.
+ *
+ * Antora derives `page-component-version-is-latest` from the content catalog but
+ * has no counterpart for the prerelease flag (see computePageAttrs() in
+ * @antora/asciidoc-loader/lib/load-asciidoc.js), so content cannot ask "am I the
+ * dev line?" without hard-coding the version number -- which then rots at every
+ * version rollover. This extension closes that gap by reading the flag off the
+ * component version object in the content catalog, the same source Antora itself
+ * uses for `latest`, and exposing it to pages, partials and nav files:
+ *
+ *   ifdef::page-component-version-is-prerelease[]
+ *   This documents a version that is still in development.
+ *   endif::[]
+ *
+ * The attribute is also visible to the UI templates as
+ * `page.attributes.[component-version-is-prerelease]` (the page composer drops the
+ * `page-` prefix when it builds the UI model).
+ *
+ * Value semantics follow Antora's `page-component-version-is-latest`: the
+ * attribute is set to the empty string when the version is a prerelease and is
+ * absent otherwise -- it is a flag for ifdef/ifndef, not a label. Use
+ * `page-component-display-version` for the visible marker (`8.3 (dev)` here).
+ *
+ * Because the attribute is derived, it is authoritative: if an antora.yml sets it
+ * by hand on a version that is NOT a prerelease, the value is dropped and a
+ * warning logged, so a stale hand-written flag cannot outlive the release it was
+ * added for.
+ */
+const ATTRIBUTE = 'page-component-version-is-prerelease'
+
+module.exports.register = function () {
+  const logger = this.getLogger('prerelease-attribute-extension')
+
+  this.once('contentClassified', ({ contentCatalog, siteAsciiDocConfig }) => {
+    contentCatalog.getComponents().forEach((component) => {
+      component.versions.forEach((componentVersion) => {
+        // NOTE when a component descriptor defines no AsciiDoc attributes of its
+        // own, componentVersion.asciidoc IS the shared siteAsciiDocConfig object
+        // (classify-content.js returns it unchanged). Never mutate it in place --
+        // that would leak this component version's flag into every other one.
+        const asciidoc = componentVersion.asciidoc || siteAsciiDocConfig || {}
+        const isPrerelease = !!componentVersion.prerelease
+        if (!isPrerelease && !(asciidoc.attributes && ATTRIBUTE in asciidoc.attributes)) return
+        const attributes = Object.assign({}, asciidoc.attributes)
+        if (isPrerelease) {
+          attributes[ATTRIBUTE] = ''
+        } else {
+          delete attributes[ATTRIBUTE]
+          logger.warn(
+            'Removed hand-set %s from %s@%s: the version is not marked prerelease in its antora.yml.',
+            ATTRIBUTE,
+            componentVersion.version || '~',
+            componentVersion.name
+          )
+        }
+        componentVersion.asciidoc = Object.assign({}, asciidoc, { attributes })
+      })
+    })
+  })
+}

content/ocis/8.0/antora.yml

@@ -71,4 +71,8 @@ asciidoc:
     ocis_services_env_var_deltas_path: '/services/general-info/envvars/env-var-deltas/'
 
     # used in depl-examples
-    download-gh-directory-url: https://download-directory.github.io
+    download-gh-directory-url: 'https://download-directory.github.io'
+
+    # the url to download ocis
+    # note that this is inactive but required in the migration section for upgrading old binaries which do not longer exist. 
+    ocis-downloadpage-url: 'https://download.owncloud.com/ocis/ocis'

content/ocis/8.0/modules/admin/pages/deployment/general/general-info.adoc

@@ -630,7 +630,7 @@ This is the local path the where Infinite Scale stores all data except the confi
 This is the local path where the Infinite Scale configuration is stored. When listing the content, you must see the file `ocis.yaml`. See the important information when using xref:docker-volumes[Docker Volumes].
 
 * `<ocis-version>` +
-The Infinite Scale version used like `latest` or `{ocis-actual-version}` or ... .
+The Infinite Scale version used like `latest` or `{page-component-latest-version}` or ... .
 +
 --
 [source,bash]

content/ocis/8.0/modules/admin/partials/depl-examples/ubuntu-compose/shared-setup.adoc

@@ -250,7 +250,7 @@ NOTE: The client that downloads the example is not the server that you upload to
 
 NOTE: The client from which you download the example via a browser and upload it using `scp` must have access to the server and have the `scp` application installed.
 
-To download and extract the necessary deployment example footnote:[Derived from the {compose_url}{compose_version}{compose_final_path}/{ocis_wopi}/[{ocis_wopi}, window=_blank] developer example], *open a browser* and enter the following URL. Note that this link also contains patches for release: `{ocis-actual-version}`.
+To download and extract the necessary deployment example footnote:[Derived from the {compose_url}{compose_version}{compose_final_path}/{ocis_wopi}/[{ocis_wopi}, window=_blank] developer example], *open a browser* and enter the following URL. Note that this link also contains patches for release: `{page-component-version}`.
 
 //[source,url,subs="attributes+,+macros"]
 //----

content/ocis/8.1/antora.yml

@@ -7,45 +7,19 @@ nav:
 
 asciidoc:
   attributes:
-    # with antora 3.2, there will be new attributes `antora-component-version` and `antora-component-name`
-    # the ones used below need to be replaced when antora has been updated to 3.2
-    # https://gitlab.com/antora/antora/-/merge_requests/1048/diffs
-    latest-ocis-version: {page-component-version}   # do not change, this is the value of the version key
-    previous-ocis-version: {page-component-version} # do not change, this is the value of the version key
-
-    # must be removed when antora 3.2 has been updated, because this is then an intrinsic attribute
-    # the branched value is the value for the production release like 'next' or '7.1'
-    antora-component-version: '8.1'
-
     # used to define the include path for services without trailing /
     # note that any changes of this path also need adjustment in
     # https://github.com/owncloud/ocis-charts/tree/master/charts/ocis/docs
     s-path: 'deployment/services/s-list'
 
     # the name of the sub directory that defines the sources folder used in the compose deployment examples
-    ocis_wopi: ocis_full
-
-    # note that service_url_component is used for services ONLY
-    # service_url_component will be used to assemble the url for services to include content (tables)
-    # sourced from the ocis repo.
-    # 'docs' for the next branch or 'docs-stable-7.2' for a production branch
-    service_url_component: 'docs-stable-8.1'
-
-    # defines the url path component when accessing the ocis repo for versioned data includes or examples
-    # 'master' for the next branch or 'stable-7.2' for a production branch
-    # example: {compose_url}{ocis_repo_url_component}{compose_final_path}
-    ocis_repo_url_component: 'stable-8.1'
-
-    # this always points to the latest stable branch such as 'stable-7.2'
-    # this branch also includes patches if any
-    # used for links where you would else download from master but the content better comes from stable
-    ocis_repo_url_stable: 'stable-8.1'
+    ocis_wopi: 'ocis_full'
 
-    # service_tab_text will be used as tab text shown for the tables in services only
-    # note when literally changing the word 'master' to something else, you also must adapt 'env-and-yaml.adoc'.
-    # this does not apply to branched releases using semver, only to the master branch!
-    # 'master' for the next branch or '7.2.0' for a production branch including patch releases like `7.2.1'
-    service_tab_text: '8.1.0'
+    ocis_helpers: 'ocis_helpers'   # note the preceding 'example$' (family coordinate) cant be used as part of the attribute
+    ocis_helpers_adoc: '{ocis_helpers}/adoc/'
+    ocis_helpers_env_var_deltas: '{ocis_helpers}/env_var_deltas/'
+    ocis_helpers_extended: '{ocis_helpers}/extended/'
+    ocis_helpers_yaml: '{ocis_helpers}/yaml/'
 
     # this is the first part of the name for envvars between major versions that will be added or removed
     # example for full name: 7.0.0-7.1.0-added.adoc or 7.0.0-7.1.0-removed.adoc
@@ -54,21 +28,20 @@ asciidoc:
 
     # set attributes defining path components which will be assembled in the document
     compose_url: 'https://github.com/owncloud/ocis/tree/'
-    compose_raw_url: 'https://raw.githubusercontent.com/owncloud/ocis/'
+    compose_raw_url: 'https://raw.githubusercontent.com/owncloud/ocis/refs/heads/'
     compose_final_path: '/deployments/examples'
 
-    # production and rolling have separate paths when it comes to download from docker
-    docker_ocis_prod_url: https://hub.docker.com/r/owncloud/ocis
-    docker_ocis_rolling_url: https://hub.docker.com/r/owncloud/ocis-rolling
-
     # only used in deployment/services via partials/env-and-yaml.adoc
     # static path components, used to assemble the final path dependent on service_url_component to include services
-    ocis_services_raw_url: 'https://raw.githubusercontent.com/owncloud/ocis/'
-    ocis_services_final_path: '/services/_includes/'
+    ocis_services_raw_url: 'https://raw.githubusercontent.com/owncloud/ocis/refs/heads/'
 
-    # only used in deployment/services/env-var-changes.adoc
-    # static path component, used to assemble the final path
-    ocis_services_env_var_deltas_path: '/services/general-info/envvars/env-var-deltas/'
+    # production and rolling have separate paths when it comes to download from docker
+    docker_ocis_prod_url: 'https://hub.docker.com/r/owncloud/ocis'
+    docker_ocis_rolling_url: 'https://hub.docker.com/r/owncloud/ocis-rolling'
 
     # used in depl-examples
-    download-gh-directory-url: https://download-directory.github.io
+    download-gh-directory-url: 'https://download-directory.github.io'
+
+    # the url to download ocis
+    # note that this is inactive but required in the migration section for upgrading old binaries which do not longer exist. 
+    ocis-downloadpage-url: 'https://download.owncloud.com/ocis/ocis'

content/ocis/8.1/modules/admin/pages/depl-examples/ubuntu-compose/ubuntu-compose-hetzner.adoc

@@ -23,7 +23,7 @@ IMPORTANT: By choosing https://www.hetzner.com[Hetzner] for our cloud deployment
 
 NOTE: With the minimum configuration available on Hetzner, you can start with about €4/month for a cloud driven Infinite Scale deployment. Note that prices are subject to changes and only intended for informational purposes.
 
-NOTE: This guide references the latest {version-type} version of Infinite Scale.
+NOTE: This guide references the latest stable version of Infinite Scale.
 
 NOTE: With this setup, each deployment only contains one instance of Infinite Scale.
 

content/ocis/8.1/modules/admin/pages/depl-examples/ubuntu-compose/ubuntu-compose-prod.adoc

@@ -25,7 +25,7 @@ toc::[]
 
 IMPORTANT: *There are several decisions and steps that need to be taken when setting up and configuring the server. We strongly recommend that you read the manual and not just try to copy and paste commands.*
 
-NOTE: This guide references the latest {version-type} version of Infinite Scale.
+NOTE: This guide references the latest stable version of Infinite Scale.
 
 NOTE: With this setup, each deployment only contains one instance of Infinite Scale.
 

content/ocis/8.1/modules/admin/pages/deployment/general/general-info.adoc

@@ -630,7 +630,7 @@ This is the local path the where Infinite Scale stores all data except the confi
 This is the local path where the Infinite Scale configuration is stored. When listing the content, you must see the file `ocis.yaml`. See the important information when using xref:docker-volumes[Docker Volumes].
 
 * `<ocis-version>` +
-The Infinite Scale version used like `latest` or `{ocis-actual-version}` or ... .
+The Infinite Scale version used like `latest` or `{page-component-latest-version}` or ... .
 +
 --
 [source,bash]

content/ocis/8.1/modules/admin/pages/deployment/services/env-var-changes.adoc

@@ -1,17 +1,14 @@
 # Changed Environment Variables in Versions
 :toc: right
-:description: This page contains tables with added and removed environment variables between Infinite Scale version 7.3.0 and 8.0.0.
+:description: This page contains tables with added and removed environment variables between Infinite Scale version 8.0.0 and 8.1.0.
 :page-aliases: ROOT:deployment/services/env-var-changes.adoc
 
-:source_path: {ocis_services_raw_url}{service_url_component}{ocis_services_env_var_deltas_path}
-
 ////
 to be set in antora.yml
 
-ocis_services_raw_url:             https://raw.githubusercontent.com/owncloud/ocis/
-service_url_component:             docs || docs-stable-8.0
-ocis_services_env_var_deltas_path: /services/general-info/envvars/env-var-deltas/
-env_var_delta_name:                7.3.0-8.0.0
+ocis_helpers:                example$ocis_helpers
+ocis_helpers_env_var_deltas: {ocis_helpers}/env_var_deltas/
+env_var_delta_name:          8.3.0-8.2.0
 ////
 
 == Introduction
@@ -25,16 +22,16 @@ env_var_delta_name:                7.3.0-8.0.0
 Added::
 +
 --
-include::{source_path}{env_var_delta_name}-added.adoc[]
+include::example${ocis_helpers_env_var_deltas}{env_var_delta_name}-added.adoc[]
 --
 Removed::
 +
 --
-include::{source_path}{env_var_delta_name}-removed.adoc[]
+include::example${ocis_helpers_env_var_deltas}{env_var_delta_name}-removed.adoc[]
 --
 Deprecated::
 +
 --
-include::{source_path}{env_var_delta_name}-deprecated.adoc[]
+include::example${ocis_helpers_env_var_deltas}{env_var_delta_name}-deprecated.adoc[]
 --
 ====

content/ocis/8.1/modules/admin/pages/deployment/services/env-vars-special-scope.adoc

@@ -13,7 +13,6 @@ Examples:
 * The extended environment variable `OCIS_CONFIG_DIR` can be used with `ocis init`.
 * The special environment variable `OCIS_RUN_SERVICES` defines services to start when the container is started.
 
-
 == Special Environment Variables
 
 // these envvars cant be gathered automatically and must be maintained manually. they change very rarely!
@@ -24,23 +23,20 @@ The following environment variables are only available when using a developer ve
 
 include::partial$deployment/services/env-and-yaml.adoc[tag=special_envvars]
 
-
 == Extended Environment Variables
 
 ////
-IMPORTANT: extended envvars currently do not have an extended_deprecation.adoc file. handled in the include.
+IMPORTANT: extended envvars currently do not have an extended_deprecation.adoc file. this is handled in the include.
 
-note that if a description of an extended envvar missing or strange looking envvars present, you need to fix this in:
-https://github.com/owncloud/ocis/blob/master/docs/helpers/extended_vars.yaml
-see the readme.md file in that folder.
+note that if a description of an extended envvar missing or strange looking envvars present,
+you need to fix this via the ocis_helper executable in this repo. see the readme of the helper for details.
 ////
 
 :service_name: extended
 
 Note, see the xref:deployment/services/registry.adoc[Registry] documentation for details on the Micro Registry and their available settings.
 
-include::partial$deployment/services/env-and-yaml.adoc[tag=envvars-only]
-
+include::partial$deployment/services/env-and-yaml.adoc[tag=extended-only]
 
 == Global Environment Variables
 
@@ -50,4 +46,4 @@ include::partial$deployment/services/env-and-yaml.adoc[tag=envvars-only]
 
 Note that the descriptions of these environment variables may differ depending on the service context.
 
-include::partial$deployment/services/env-and-yaml.adoc[tag=envvars-only]
+include::partial$deployment/services/env-and-yaml.adoc[tag=global-only]

content/ocis/8.1/modules/admin/pages/deployment/services/s-list/policies.adoc

@@ -164,12 +164,12 @@ The policies service contains a set of preconfigured example policies. See the d
 
 [tabs]
 ====
-{service_tab_text}::
+{tab_text}::
 +
 --
 {compose_url}{compose_version}{compose_final_path}[Rego policies deployment example directory,window=_blank]
 
-Using git branch name: `{compose_version}`, to point to the latest stable version that also includes patches
+Using git branch name: `{compose_version}`, to point to the latest stable version that also includes patches.
 --
 ====
 

content/ocis/8.1/modules/admin/pages/deployment/webui/webui-theming.adoc

@@ -42,7 +42,12 @@ Some theme keys are mandatory, like the `common.shareRoles` settings. Such manda
 
 == Configuring a Theme
 
-.Sourced from https://github.com/owncloud/ocis/blob/{compose_version}{web_assets_path}theme.json[GitHub, _window=blank]
+:configuring_add_on_text:
+ifdef::page-component-version-is-prerelease[]
+:configuring_add_on_text: from the latest stable version.
+endif::[]
+
+.Sourced from https://github.com/owncloud/ocis/blob/{compose_version}{web_assets_path}theme.json[GitHub, _window=blank] {configuring_add_on_text}
 [source,json]
 ----
 include::{ocis_services_raw_url}{compose_version}{web_assets_path}theme.json[]

content/ocis/8.1/modules/admin/pages/deployment/wopi/wopi.adoc

@@ -73,7 +73,7 @@ image::deployment/wopi/wopi-overview.svg[WOPI Overview Diagram,width=500]
 +
 [tabs]
 ====
-{service_tab_text}::
+{tab_text}::
 +
 --
 {compose_url}{compose_version}{compose_final_path}/{ocis_wopi}[Docker compose `ocis_full` deployment example directory,window=_blank]

content/ocis/8.1/modules/admin/pages/index.adoc

@@ -71,4 +71,4 @@ Configuration of Infinite Scale might be quite different to what you are used to
 
 == End-User License Agreement (EULA)
 
-ownCloud provides an EULA to clarify, among various topics, who can use this software and which conditions apply to the groups of users defined. See the actual {compose_raw_url}{compose_version}/assets/End-User-License-Agreement-for-ownCloud-Infinite-Scale.pdf[EULA] for details.
+ownCloud provides an EULA to clarify, among various topics, who can use this software and which conditions apply to the groups of users defined. See the actual {compose_raw_url}{ocis_git_version}/assets/End-User-License-Agreement-for-ownCloud-Infinite-Scale.pdf[EULA] for details.

content/ocis/8.1/modules/admin/partials/depl-examples/ubuntu-compose/shared-setup.adoc

@@ -250,7 +250,14 @@ NOTE: The client that downloads the example is not the server that you upload to
 
 NOTE: The client from which you download the example via a browser and upload it using `scp` must have access to the server and have the `scp` application installed.
 
-To download and extract the necessary deployment example footnote:[Derived from the {compose_url}{compose_version}{compose_final_path}/{ocis_wopi}/[{ocis_wopi}, window=_blank] developer example], *open a browser* and enter the following URL. Note that this link also contains patches for release: `{ocis-actual-version}`.
+:note_text:
+ifdef::page-component-version-is-prerelease[]
+:note_text: There is no download for the ocis development version for stability reasons. The latest stable release {page-component-latest-version} is used instead.
+endif::[]
+
+{note_text}
+
+To download and extract the necessary deployment example footnote:[Derived from the {compose_url}{compose_version}{compose_final_path}/{ocis_wopi}/[{ocis_wopi}, window=_blank] developer example], *open a browser* and enter the following URL. Note that this link also contains patches, if any, for the stable release branch: `{compose_version}`.
 
 //[source,url,subs="attributes+,+macros"]
 //----
@@ -329,7 +336,7 @@ Add a valid response eMail address for Letsencrypt, see the note below.
 Set the CAServer to staging, see the note below.
 
 * `OCIS_DOCKER_IMAGE` +
-Check that the correct image type is selected ({version-type}).
+Check that the correct image type is selected.
 
 * `OCIS_DOMAIN`, `COLLABORA_DOMAIN` and/or `ONLYOFFICE_DOMAIN` +
 Set the domain names as defined in xref:domain-names[Domain Names].
@@ -649,14 +656,10 @@ docker volume rm {ocis_wopi}_ocis-config {ocis_wopi}_ocis-data
 
 === Updating
 
-// for testing only
-//:version-type: rolling
-//:version-type: production
-
 Infinite Scale::
 +
 --
-ifeval::["{version-type}" == "rolling"]
+ifdef::page-component-version-is-prerelease[]
 For Infinite Scale rolling releases, the following steps are essential to avoid breaking the setup. This is because rolling releases depend on all updates being done in sequence.
 
 When new versions of Infinite Scale are available, you *may* skip any version between the one you are currently running and the latest available rolling release for internal update reasons. All versions must be downloaded and launched at once. For more details, see https://owncloud.dev/ocis/release_roadmap/#updating-and-overlap[Updating and Overlap] in the developer documentation.
@@ -682,7 +685,7 @@ Note that we recommend manually checking to see if the deployment source has cha
 
 endif::[]
 
-ifeval::["{version-type}" != "rolling"]
+ifndef::page-component-version-is-prerelease[]
 
 Follow these steps to update between production releases: