Merge pull request #4 from accemic/albert/publish-spec-pdf

Publish spec PDF via GitHub Release; stop committing the PDF

Author: accemic

.github/workflows/pdf.yml

@@ -2,15 +2,18 @@ name: spec-pdf
 
 on:
   push:
-    paths:
-      - 'spec/**'
-      - '.github/workflows/pdf.yml'
+    branches: [main]
+    tags: ['v*']
   pull_request:
     paths:
       - 'spec/**'
       - '.github/workflows/pdf.yml'
   workflow_dispatch:
 
+# Allow the release step to create releases and upload assets.
+permissions:
+  contents: write
+
 jobs:
   build-pdf:
     runs-on: ubuntu-latest
@@ -31,10 +34,23 @@ jobs:
             -a attribute-missing=warn \
             --failure-level=ERROR \
             spec/tn-ctxp-format.adoc \
-            -o spec/tn-ctxp-format.pdf
+            -o tn-ctxp-format.pdf
 
-      - uses: actions/upload-artifact@v4
+      - name: Upload PDF as build artifact
+        uses: actions/upload-artifact@v4
         with:
           name: tn-ctxp-format-pdf
-          path: spec/tn-ctxp-format.pdf
+          path: tn-ctxp-format.pdf
           if-no-files-found: error
+
+      # On a version tag (e.g. v1.1.0), publish the PDF as a release asset.
+      # The stable "latest" link is:
+      #   https://github.com/<owner>/<repo>/releases/latest/download/tn-ctxp-format.pdf
+      - name: Publish PDF to GitHub Release
+        if: startsWith(github.ref, 'refs/tags/v')
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" tn-ctxp-format.pdf \
+            --title "$GITHUB_REF_NAME" --generate-notes \
+          || gh release upload "$GITHUB_REF_NAME" tn-ctxp-format.pdf --clobber

.gitignore

@@ -1,3 +1,6 @@
 *.pyc
 __pycache__/
 .venv/
+
+# Generated locally; published via the spec-pdf release workflow
+tn-ctxp-format.pdf

README.adoc

@@ -11,7 +11,9 @@ This repository aims to be a *publication-quality* reference for the CTXP format
 * Canonical, curated examples
 * A small linter to keep examples consistent
 
-The authoritative specification is included in link:spec/tn-ctxp-format.pdf[`spec/tn-ctxp-format.pdf`]. 
+*Specification (PDF):* download the latest release —
+https://github.com/accemic/C-Trace-eXPort-format/releases/latest/download/tn-ctxp-format.pdf[*tn-ctxp-format.pdf*].
+The AsciiDoc source lives in link:spec/[`spec/`].
 
 == Quick start
 
@@ -46,28 +48,22 @@ for the full set of curated example traces and explanations.
 
 == Documentation
 
-The authoritative format specification is in link:spec/tn-ctxp-format.pdf[`spec/tn-ctxp-format.pdf`].
+The authoritative format specification is the PDF published as a *GitHub Release* asset:
+https://github.com/accemic/C-Trace-eXPort-format/releases/latest/download/tn-ctxp-format.pdf[`tn-ctxp-format.pdf` (latest release)].
 
 Its AsciiDoc source lives in link:spec/[`spec/`] (link:spec/tn-ctxp-format.adoc[`tn-ctxp-format.adoc`]
 + link:spec/ctxp-format.adoc[`ctxp-format.adoc`] + diagrams under link:spec/images/[`spec/images/`]).
-The PDF is regenerated by the `spec-pdf` GitHub Action on every change under `spec/`; to build it
-locally:
+The `spec-pdf` GitHub Action builds and validates the PDF on every change under `spec/`, and
+publishes it as a release asset when a `v*` tag is pushed. To build it locally:
 
 [source,sh]
 ----
 gem install asciidoctor-pdf rouge
-asciidoctor-pdf spec/tn-ctxp-format.adoc -o spec/tn-ctxp-format.pdf
+asciidoctor-pdf spec/tn-ctxp-format.adoc -o tn-ctxp-format.pdf
 ----
 
-Diagrams: the editable sources are the `*.drawio.svg` files (drawn with https://draw.io[draw.io]).
-The PDF embeds the `*.drawio.png` next to them, because asciidoctor-pdf does not render the
-draw.io SVG format cleanly. Regenerate the PNGs after editing a diagram, e.g.:
-
-[source,sh]
-----
-inkscape spec/images/<name>.drawio.svg --export-type=png \
-  --export-filename=spec/images/<name>.drawio.png --export-dpi=192
-----
+Diagrams are the `*.drawio.png` files under link:spec/images/[`spec/images/`], exported from
+https://draw.io[draw.io] (asciidoctor-pdf does not render the draw.io SVG format cleanly).
 
 == Tooling (Accemic)
 
@@ -91,7 +87,7 @@ If you want to evaluate or integrate CTXP tooling, please contact us:
 
 == License / attribution / acknowledgement
 
-The included technical note (`spec/tn-ctxp-format.pdf`) states it is licensed under
-Creative Commons Attribution 4.0 International (CC BY 4.0). See the PDF for details.
+The CTXP technical note states it is licensed under
+Creative Commons Attribution 4.0 International (CC BY 4.0). See the spec for details.
 
 The CTXP format was developed as part of the TRISTAN project, a European Union research initiative involving 46 partners to advance the RISC-V ecosystem. See https://tristan-project.eu/ for more information.