diff --git a/.github/workflows/pdf.yml b/.github/workflows/pdf.yml index 846e373..8b80c53 100644 --- a/.github/workflows/pdf.yml +++ b/.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///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 diff --git a/.gitignore b/.gitignore index 74b74f3..f14600a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,6 @@ *.pyc __pycache__/ .venv/ + +# Generated locally; published via the spec-pdf release workflow +tn-ctxp-format.pdf diff --git a/README.adoc b/README.adoc index 5c75d14..64eb5ea 100644 --- a/README.adoc +++ b/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/.drawio.svg --export-type=png \ - --export-filename=spec/images/.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. diff --git a/spec/tn-ctxp-format.pdf b/spec/tn-ctxp-format.pdf deleted file mode 100644 index 88d5b15..0000000 Binary files a/spec/tn-ctxp-format.pdf and /dev/null differ