Convert markup and build to asciidoctor

.github/workflows/CI.yml

@@ -0,0 +1,48 @@
+# Copyright 2021-2026 The Khronos Group Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+# GitHub CI file for Data Format spec
+# See .gitlab-ci.yml for non-Actions comments and step dependencies.
+
+name: CI
+
+# Controls when the action will run.
+on:
+  # Triggers the workflow on push or manual dispatch
+  push:
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+  # When a pull request is opened from a local branch or fork
+  pull_request:
+
+jobs:
+  license-check:
+    name: Verify repository license compliance
+    runs-on: ubuntu-latest
+    container: khronosgroup/docker-images@sha256:f1ca671f3bdb10ad49e238b9bf28853088a21af49504498fc9084c9b4fea4762
+
+    steps:
+      - uses: actions/checkout@v5
+      - name: REUSE license checker
+        run: reuse lint
+
+  spec-generate:
+    name: Build the Data Format specification
+    runs-on: ubuntu-latest
+    container: khronosgroup/docker-images@sha256:f1ca671f3bdb10ad49e238b9bf28853088a21af49504498fc9084c9b4fea4762
+
+    steps:
+      - uses: actions/checkout@v5
+      - name: Build the Data Format specification
+        run: make html pdf
+      - name: Package generated spec
+        # https://github.com/actions/upload-artifact#limitations
+        # upload-artifact would upload many different files individually to
+        # GitHub, which can take a lot of time.
+        # Tar it to upload just one large file instead.
+        run: tar -cvf spec-outputs.tar out
+      - name: Archive generated spec
+        uses: actions/upload-artifact@v7
+        with:
+          name: spec-outputs
+          path: spec-outputs.tar

.gitlab-ci.yml

@@ -0,0 +1,42 @@
+# Copyright 2018-2026 The Khronos Group Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+# Gitlab CI file for Data Format spec
+
+# All stages use the same Docker image, so there are no prerequisites
+# Refer to the container by its SHA instead of the name, to prevent
+# caching problems when updating the image.
+# image: khronosgroup/docker-images:asciidoctor-spec.202506
+image: khronosgroup/docker-images@sha256:f1ca671f3bdb10ad49e238b9bf28853088a21af49504498fc9084c9b4fea4762
+
+# Specify which gitlab runner to use
+default:
+  tags:
+    - khrmedium
+
+# Verify repository license compliance
+license-check:
+  stage: build
+  before_script:
+    # Nothing, all prerequisites are in the Docker image
+  script:
+    - reuse lint
+  allow_failure: false
+
+# Build the Data Format specification in HTML and PDF form
+spec-generate:
+  stage: build
+  before_script:
+    # Nothing, all prerequisites are in the Docker image
+  script:
+    - NODE_PATH="/usr/lib/node_modules"
+    - export NODE_PATH
+    # Build the core-only spec, to catch some incorrect ifdef errors
+    - ./makeSpec -clean -spec core -genpath gencore QUIET= -j${nproc} -Otarget html manhtmlpages
+    # Build the HTML and PDF specs
+    - make html pdf
+  artifacts:
+    when: always
+    paths:
+      - out/
+    expire_in: 1 week

BUILD.adoc

@@ -0,0 +1,211 @@
+// Copyright 2014-2026 The Khronos Group Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+= Khronos^(TM) Data Format Specification Build Instructions and Notes
+:toc2:
+:toclevels: 2
+
+ifdef::env-github[]
+:note-caption: :information_source:
+endif::[]
+
+
+NEW == Building the Specification
+
+The build system relies on
+link:http://www.methods.co.nz/asciidoc/index.html[asciidoc], which is
+available as part of many Linux distributions.
+The PDF build subsequently depends on
+link:http://dblatex.sourceforge.net[dblatex].
+
+All forms of the specification may be built with a simple `make`
+or `make all` command, with an output into the `out` directory.
+
+Use `make pdf` to build just the PDF specification.
+
+Use `make html` to build the HTML version of the specification
+without inline images, which are accessed from the `out` directory;
+this is smaller than the `inlinehtml` version.
+
+Use `make inlinehtml` to create the HTML and then generate a version
+with inlined images, allowing it to be transferred as a single
+file; note that the HTML still relies on access to
+link:http://www.mathjax.org[MathJax] and is therefore not completely
+stand-alone.
+This build option requires PERL.
+Since the inline HTML file is very large, `make compressedinlinehtml`
+produces a gzip-compressed version of the output.
+
+`make header` copies the header file into the `out/headers` directory.
+
+`make clean` removes the contents out `out` and temporary files.
+
+
+
+[[intro]]
+== Introduction
+
+This README describes how to build the Data Format Specification and other
+related targets.
+
+It documents how to set up your build environment, build steps and targets,
+and contains some troubleshooting advice.
+
+
+[[building]]
+== Building the Spec
+
+First, clone the Khronos GitHub repository containing the Data Format
+Specification to your local Linux, Windows, or Mac PC.
+The repository is located at https://github.com/KhronosGroup/DataFormat/ .
+
+Next, install all the necessary build tools (see <<depends,Software
+Dependencies>> below).
+If you are using the <<depends-docker, Khronos-Provided Docker Image>>,
+which we strongly recommend, two ways to build using the image are:
+
+    $ # assuming a Linux docker host
+    $ scripts/runDocker
+
+    $ # assuming a Linux podman host
+    $ scripts/runPodman
+
+executed from the specification repository root.
+
+`runDocker` runs the Docker image with the cloned repository mounted under
+/spec and accesses it as a specified user (set to your own user and group
+ID), so that it does not get filled with files owned by another user.
+The script leaves you inside a bash shell in the running image.
+Execute the commands:
+
+    $ cd /spec
+    $ make clean html pdf
+
+to build HTML5 and PDF specification outputs for the Data Format 1.3
+Specification.
+
+There are many other ways of using the image, including inside a Continuous
+Integration pipeline; locally with persistent Docker volume storage of the
+repository; and so on.
+
+If you are not using our Docker image to build with, and you have a
+<<depends-nondocker, Non-Docker Build Environment>> with the entire
+toolchain installed, you can just invoke the same `make` commands from the
+repository root.
+
+[NOTE]
+====
+You can modify the `runDocker` script to change the `docker` command-line
+options, but it is important to always use the Docker image specified in
+that script, so you have the latest version of the spec toolchain.
+====
+
+[NOTE]
+====
+  * The `pdf` target takes a long time to run.
+    The `html` target just generates the HTML output, which is often all
+    that is needed for spec bugfixes not involving extensions.
+====
+
+These targets generate  output documents in the directory
+specified by the Makefile variable `$(OUTDIR)` (by default, `out/`).
+
+Data Format Specification::
+  * `html` -- Single-file HTML5 in `$(OUTDIR)/html/dataformat.html`, and KaTeX
+    dependency in $(OUTDIR)/katex
+  * `pdf` -- PDF in `$(OUTDIR)/pdf/dataformat.pdf`
+
+
+=== Images Used in the Specification
+
+All images used in the specification are in the `images/` directory in the
+SVG or PNG format.
+We recommend using Inkscape to modify or create new images, due to problems
+using SVG files created by some other tools; especially in the PDF builds.
+
+
+[[styles]]
+== Our Stylesheets
+
+We use an HTML stylesheet `config/khronos.css` derived from the
+https://asciidoctor.org/docs/produce-custom-themes-using-asciidoctor-stylesheet-factory/[Asciidoctor
+stylesheet factory] "`colony`" theme, with the default Arial font family
+replaced by the sans-serif https://en.wikipedia.org/wiki/Noto_fonts[Noto
+font family].
+
+
+[[depends]]
+== Software Dependencies
+
+This section describes the software components used by the Data Format
+specification toolchain.
+
+
+[[depends-docker]]
+=== Khronos-Provided Docker Image
+
+Khronos has published a Docker image containing a Debian Linux distribution
+with the entire toolchain preinstalled.
+
+We will occasionally update this image if needed, and we recommend people
+needing to build from this repository use the Docker image.
+
+Docker installation is beyond the scope of this document.
+Refer to link:https://docs.docker.com/get-docker/[the Docker website] for
+information about installing Docker on Linux, Windows, and MacOS X.
+
+Another way to execute the Docker image is using the open source podman
+container tool.
+See link:https://podman.io/get-started[the Podman website] for information
+about installing podman on Linux, Windows, and MacOS X.
+
+The build image is *named* `khronosgroup/docker-images:asciidoctor-spec`.
+However, due to local and CI caching problems when this image is updated on
+dockerhub, we use the SHA256 of the latest image update, rather than the
+image name.
+The SHA256 can be determined from
+
+    $ git grep -h sha256: .gitlab-ci.yml
+
+which will print a line like
+
+    image: khronosgroup/docker-images@sha256:5e021da240f12121f064d2135e06320c021ac231c9ae8abbf6205b6130deb58b
+
+Everything following `image: ` is the <imagename> to use.
+The first time you try to run a container with this <imagename>, as is done
+by the `runDocker` and `runPodman` scripts described above under <<building,
+Building the Spec>>, the image will be pulled from Dockerhub and cached
+locally on your machine.
+
+This image is used to build Specification output documents or other Makefile
+targets.
+
+[NOTE]
+====
+When we update the image on Dockerhub, it is to add new components or update
+versions of components used in the specification toolchain.
+To save space, you may want to periodically purge old images using `docker
+images` and `docker rmi -f`.
+====
+
+
+[[depends-nondocker]]
+=== Non-Docker Build Environments
+
+We do not actively support building outside of our Docker image, but it is
+straightforward to reproduce our toolchain in a Debian (or similar APT-based
+Linux) distribution by executing the same steps as the
+link:https://github.com/KhronosGroup/DockerContainers/blob/main/asciidoctor-spec.Dockerfile[Dockerfile]
+used to build our Docker image.
+
+It should be possible to apply the same steps in a Windows Subsystem for
+Linux (WSL2) environment on Windows 10, as well.
+
+[NOTE]
+====
+While you do not have to use our Docker image, we cannot support every
+possible build environment.
+The Docker image is a straightforward way to build the specification in most
+modern desktop environments, without needing to install and update the spec
+toolchain yourself.
+====

CODE_OF_CONDUCT.adoc

@@ -0,0 +1,10 @@
+// Copyright 2018-2026 The Khronos Group Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+= Code of Conduct
+
+A reminder that this repository is managed by the Khronos Group.
+Interactions here should follow the
+https://www.khronos.org/about/code-of-conduct[Khronos Code of Conduct],
+which prohibits aggressive or derogatory language. Please keep the
+discussion friendly and civil.

CONTRIBUTING.adoc

@@ -0,0 +1,39 @@
+// Copyright 2020-2026 The Khronos Group Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+= Contributing
+
+Contributions to the DataFormat repository are welcome.
+
+Contributions may be in the form of Issues proposing a change, or Pull
+Requests containing fixes for, or additions to:
+
+  * Specification text and other documentation
+  * Specification scripting / build toolchains and related infrastructure
+
+Please keep contributions focused on solving a single issue or bug.
+
+
+== Copyright Notice and License Template
+
+If you are adding a new file, it must be under one of the following
+licenses:
+
+  * Creative Commons Attribution 4.0 International, for specification text
+    (for example, link:dataformat.adoc[`dataformat.adoc])
+  * Apache 2.0, for all other changes (for example,
+    link:scripts/runDocker[`runDocker`])
+
+We use a short license in each file consisting of just the copyright
+statement and the SPDX license identifier of the license applying to that
+file, and link to the full license text from
+link:LICENSE.adoc[`LICENSE.adoc`].
+
+
+== Contributor License Agreement
+
+When you propose a pull request, you must execute the
+link:https://www.khronos.org/legal/Khronos_mixed_repository_CLA[Khronos
+Mixed Repository Contributor License Agreement], to confirm you own your
+work and are granting Khronos the necessary permissions to redistribute it
+under our licenses.