Merge pull request #91 from riscv-non-isa/asciidoc

Move spec to AsciiDoc

Author: IainCRobertson

.github/workflows/build-pdf.yml

@@ -0,0 +1,73 @@
+name: Create Specification Document
+
+# The workflow is triggered by pull request, push to main, and manual dispatch.
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Release version, e.g. X.Y.Z:'
+        required: true
+        type: string
+      revision_mark: 
+          description: 'Set revision mark as Draft, Release or Stable:'
+          required: true
+          type: string
+          default: 'Draft'
+      prerelease:
+        description: 'Tag as a pre-release?'
+        required: false
+        type: boolean
+        default: true
+      draft:
+        description: 'Create release as a draft?'
+        required: false
+        type: boolean
+        default: false
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    # Step 1: Checkout the repository
+    - name: Checkout repository
+      uses: actions/checkout@v3
+      with:
+        submodules: 'recursive'
+
+    # Step 2: Pull the latest RISC-V Docs container image
+    - name: Pull Container
+      run: docker pull riscvintl/riscv-docs-base-container-image:latest
+
+    # Step 3: Build Files
+    - name: Build Files
+      run: make
+      env:
+        VERSION: v${{ github.event.inputs.version }}
+        REVMARK: ${{ github.event.inputs.revision_mark }}
+
+    # Step 4: Upload the built PDF files as a single artifact
+    - name: Upload Build Artifacts
+      uses: actions/upload-artifact@v3
+      with:
+        name: Build Artifacts
+        path: ${{ github.workspace }}/*.pdf
+        retention-days: 30
+      
+    # Create Release
+    - name: Create Release
+      uses: softprops/action-gh-release@v1
+      with:
+        files: ${{ github.workspace }}/*.pdf
+        tag_name: v${{ github.event.inputs.version }}
+        name: Release ${{ github.event.inputs.version }}
+        draft: ${{ github.event.inputs.draft }}
+        prerelease: ${{ github.event.inputs.prerelease }}
+      env:
+        GITHUB_TOKEN: ${{ secrets.GHTOKEN }}
+      if: github.event_name == 'workflow_dispatch' 
+      # This condition ensures this step only runs for workflow_dispatch events.

.github/workflows/build.yaml

@@ -1 +1,4 @@
 vc.tex
+.vscode
+*.pdf
+stem*.svg

.gitignore

@@ -0,0 +1,3 @@
+[submodule "docs-resources"]
+	path = docs-resources
+	url = https://github.com/riscv/docs-resources.git

.gitmodules

@@ -1,35 +1,62 @@
-# Variables
-SPEC_TEX := riscv-trace-spec
-SPEC_PDF := $(SPEC_TEX).pdf
-INCLUDES_TEX := introduction.tex branchTrace.tex exampleAlgorithm.tex filtering.tex timestamping.tex ingressPort.tex payload.tex dataTracePayload.tex control.tex preamble.tex riscv-trace-spec.tex decoder.tex discovery.tex exampleCodeSnippets.tex fragmentCodeAndTransport.tex future.tex
+# Makefile for RISC-V Doc Template
+#
+# This work is licensed under the Creative Commons Attribution-ShareAlike 4.0
+# International License. To view a copy of this license, visit
+# http://creativecommons.org/licenses/by-sa/4.0/ or send a letter to
+# Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
+#
+# SPDX-License-Identifier: CC-BY-SA-4.0
+#
+# Description:
+# 
+# This Makefile is designed to automate the process of building and packaging 
+# the Doc Template for RISC-V Extensions.
 
-# Main Targets
-all: $(SPEC_PDF)
+#DATE ?= $(shell date +%Y-%m-%d)
+#VERSION ?= v0.0.0
+#REVMARK ?= Draft
+DOCKER_RUN := docker run --rm -v ${PWD}:/build -w /build \
+riscvintl/riscv-docs-base-container-image:latest
 
-publish: $(SPEC_PDF)
-	cp $< $(SPEC_TEX)-`git rev-parse --abbrev-ref HEAD`.`git rev-parse --short HEAD`.pdf
+HEADER_SOURCE := header.adoc
+PDF_RESULT := riscv-trace-spec-asciidoc.pdf
+
+
+ASCIIDOCTOR_PDF := asciidoctor-pdf
+OPTIONS := --trace \
+           -a compress \
+           -a mathematical-format=svg \
+           --failure-level=ERROR
+REQUIRES := --require=asciidoctor-diagram \
+            --require=asciidoctor-mathematical
+#			--require=~/bin/pdf-converter-colophon-placement.rb
+#--require=asciidoctor-bibtex \
+
+.PHONY: all build clean build-container build-no-container
+
+all: build
+
+build: 
+	@echo "Checking if Docker is available..."
+	@if command -v docker >/dev/null 2>&1 ; then \
+		echo "Docker is available, building inside Docker container..."; \
+		$(MAKE) build-container; \
+	else \
+		echo "Docker is not available, building without Docker..."; \
+		$(MAKE) build-no-container; \
+	fi
+
+build-container:
+	@echo "Starting build inside Docker container..."
+	$(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)"
+	@echo "Build completed successfully inside Docker container."
+
+build-no-container:
+	@echo "Starting build..."
+	$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)
+	@echo "Build completed successfully."
 
 clean:
-	rm -f $(SPEC_PDF) *.aux *.toc *.log *.idx *.ilg *.ind *.lof *.lot *.out *.pdf
-
-# Recipe for building the PDF
-$(SPEC_PDF): $(SPEC_TEX).tex $(INCLUDES_TEX) vc.tex
-	echo $(SPEC_TEX)
-	pdflatex -shell-escape $< && makeindex $(SPEC_TEX) && pdflatex -shell-escape $<
-
-# Recipe for generating vc.tex with Git version control information
-vc.tex: .git/logs/HEAD
-	echo "%%% This file is generated by Makefile." > vc.tex
-	echo "%%% Do not edit this file!\n%%%" >> vc.tex
-	git log -1 --format="format:\
-	    \\gdef\\GITHash{%H}\
-	    \\gdef\\GITAbrHash{%h}\
-	    \\gdef\\GITAuthorDate{%ad}\
-	    \\gdef\\GITAuthorName{%an}" >> vc.tex
-
-# Recipe for generating changelog.tex from Git logs
-changelog.tex: .git/logs/HEAD Makefile
-	echo "%%% This file is generated by Makefile." > changelog.tex
-	echo "%%% Do not edit this file!\n%%%" >> changelog.tex
-	git log --no-merges --date=short --pretty="format:vhEntry{%h}{%ad}{%an}{%s}" | \
-	    sed -e "s,\\\\,{\\\\textbackslash},g" -e "s,[_#^],\\\\&,g" -e s/^/\\\\/ >> changelog.tex
+	@echo "Cleaning up generated files..."
+	rm -f $(PDF_RESULT)
+	@echo "Cleanup completed."