Support building HTML output

Add support for building the HTML version of the specification. By default `make` will still only build the PDF version; `make pdf` or `make html` will build one or the other, and `make all` will build both. `make all` is run in CI.

I also deduplicated the asciidoc commands a bit, and fixed ctrl-c for the docker builds.

See #8

.github/workflows/build-pdf.yml

@@ -8,7 +8,7 @@ on:
         description: 'Release version, e.g. X.Y.Z:'
         required: true
         type: string
-      revision_mark: 
+      revision_mark:
           description: 'Set revision mark as Draft, Release or Stable:'
           required: true
           type: string
@@ -45,29 +45,33 @@ jobs:
 
     # Step 3: Build Files
     - name: Build Files
-      run: make
+      run: make all
       env:
         VERSION: v${{ github.event.inputs.version }}
         REVMARK: ${{ github.event.inputs.revision_mark }}
 
-    # Step 4: Upload the built PDF files as a single artifact
+    # Step 4: Upload the built PDF and HTML files as a single artifact
     - name: Upload Build Artifacts
       uses: actions/upload-artifact@v3
       with:
         name: Build Artifacts
-        path: ${{ github.workspace }}/build/*.pdf
+        path: |
+          ${{ github.workspace }}/build/*.pdf
+          ${{ github.workspace }}/build/*.html
         retention-days: 30
-      
+
     # Create Release
     - name: Create Release
       uses: softprops/action-gh-release@v1
       with:
-        files: ${{ github.workspace }}/build/*.pdf
+        files: |
+          ${{ github.workspace }}/build/*.pdf
+          ${{ github.workspace }}/build/*.html
         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' 
+      if: github.event_name == 'workflow_dispatch'
       # This condition ensures this step only runs for workflow_dispatch events.

Makefile

@@ -43,8 +43,9 @@ CSVS	    = $(wildcard $(CSV_DIR)/*.csv)
 GEN_DIR     = $(SRC_DIR)/generated
 SCRIPTS_DIR = $(SRC_DIR)/scripts
 
-# Output file
+# Output files
 PDF_RESULT    := $(BUILD_DIR)/riscv-cheri.pdf
+HTML_RESULT   := $(BUILD_DIR)/riscv-cheri.html
 
 # Top asciidoc file of the document
 HEADER_SOURCE := $(SRC_DIR)/riscv-cheri.adoc
@@ -79,11 +80,12 @@ GEN_SRC = $(GEN_DIR)/both_mode_insns_table_body.adoc               \
           $(GEN_DIR)/Zcheri_mode_insns_table_body.adoc             \
           $(GEN_DIR)/Zcheri_purecap_insns_table_body.adoc
 
-# Docker command
-DOCKER = docker run --rm -v $(PWD):/build -w /build $(DOCKER_IMAGE)
+# Docker command. `-it` is necessary so that ctrl-c works.
+DOCKER = docker run -it --rm -v $(PWD):/build -w /build $(DOCKER_IMAGE)
 
 # AsciiDoctor command
-ASCIIDOC_PDF      = asciidoctor-pdf
+ASCIIDOC          = asciidoctor-pdf
+
 ASCIIDOC_OPTIONS  = --trace                                          \
                     -a compress                                      \
                     -a mathematical-format=svg                       \
@@ -102,35 +104,47 @@ ASCIIDOC_REQUIRES = --require=asciidoctor-bibtex       \
                     --require=asciidoctor-diagram      \
                     --require=asciidoctor-mathematical
 
+# File extension to backend map.
+ASCIIDOC_BACKEND_.html = html5
+ASCIIDOC_BACKEND_.pdf  = pdf
+
+# Command to run Asciidoc to build a PDF or HTML document, depending on
+# the output file ($@).
+ASCIIDOC_BUILD_COMMAND = $(ASCIIDOC) \
+                         $(ASCIIDOC_OPTIONS) \
+                         $(ASCIIDOC_REQUIRES) \
+                         $(HEADER_SOURCE) \
+                         --backend=$(ASCIIDOC_BACKEND_$(suffix $@)) \
+                         --out-file=$@
+
 # Convenience targets
-all: $(PDF_RESULT)
+pdf: $(PDF_RESULT)
+html: $(HTML_RESULT)
+all: pdf html
 generate: $(GEN_SRC)
 download: $(CSVS)
 
 $(BUILD_DIR):
 	@echo "  DIR $@"
 	@mkdir -p $@
 
-%.pdf: $(SRCS) $(IMGS) $(GEN_SRC) | $(BUILD_DIR)
+define ASCIIDOC_BUILD_RECIPE
 	@echo "  DOC $@"
 	@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; \
+		$(DOCKER) /bin/sh -c "$(ASCIIDOC_BUILD_COMMAND)" ; \
 	else \
 		echo "Docker is not available, building without Docker..."; \
-		$(MAKE) build-no-container; \
+		$(ASCIIDOC_BUILD_COMMAND) ; \
 	fi
+endef
 
-build-container:
-	@echo "Starting build inside Docker container..."
-	$(DOCKER) /bin/sh -c "$(ASCIIDOC_PDF) $(ASCIIDOC_OPTIONS) $(ASCIIDOC_REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)"
-	@echo "Build completed successfully inside Docker container."
+%.pdf: $(SRCS) $(IMGS) $(GEN_SRC) | $(BUILD_DIR)
+	$(ASCIIDOC_BUILD_RECIPE)
 
-build-no-container:
-	@echo "Starting build..."
-	$(ASCIIDOC_PDF) $(ASCIIDOR_OPTIONS) $(ASCIIDOC_REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)
-	@echo "Build completed successfully."
+%.html: $(SRCS) $(IMGS) $(GEN_SRC) | $(BUILD_DIR)
+	$(ASCIIDOC_BUILD_RECIPE)
 
 # Rule to generate all the src/generated/*.adoc from the downloaded CSVs using a Python script.
 $(GEN_SRC) &: $(CSVS) $(GEN_SCRIPT)
@@ -147,6 +161,6 @@ $(CSVS) &:
 # Clean
 clean:
 	@echo "  CLEAN"
-	@$(RM) -r $(PDF_RESULT) $(GEN_SRC)
+	@$(RM) -r $(PDF_RESULT) $(HTML_RESULT) $(GEN_SRC)
 
 .PHONY: all generate download clean