Merge pull request #41 from riscv-admin/dev/kbroch/listings

examples of various block types and how prefixed caption labels works

Makefile

@@ -0,0 +1,84 @@
+# 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.
+
+DOCS := \
+	projects/listings/listings-ex.adoc
+
+DATE ?= $(shell date +%Y-%m-%d)
+VERSION ?= v0.0.0
+REVMARK ?= Draft
+ifneq ($(SKIP_DOCKER),true)
+	DOCKER_CMD := docker run --rm -v ${PWD}:/build -w /build \
+	riscvintl/riscv-docs-base-container-image:latest \
+	/bin/sh -c
+	DOCKER_QUOTE := "
+endif
+
+BUILD_DIR := build
+
+DOCS_PDF := $(DOCS:%.adoc=%.pdf)
+DOCS_HTML := $(DOCS:%.adoc=%.html)
+
+XTRA_ADOC_OPTS :=
+ASCIIDOCTOR_PDF := asciidoctor-pdf
+ASCIIDOCTOR_HTML := asciidoctor
+OPTIONS := --trace \
+           -a compress \
+           -a mathematical-format=svg \
+           -a revnumber=${VERSION} \
+           -a revremark=${REVMARK} \
+           -a revdate=${DATE} \
+           $(XTRA_ADOC_OPTS) \
+		   -D build \
+           --failure-level=ERROR
+REQUIRES := --require=asciidoctor-diagram \
+			--require=asciidoctor-lists \
+            --require=asciidoctor-mathematical
+
+.PHONY: all build clean build-container build-no-container build-docs
+
+all: build
+
+build-docs: $(DOCS_PDF) $(DOCS_HTML)
+
+%.pdf: %.adoc
+	$(DOCKER_CMD) $(DOCKER_QUOTE) $(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) $< $(DOCKER_QUOTE)
+
+%.html: %.adoc
+	$(DOCKER_CMD) $(DOCKER_QUOTE) $(ASCIIDOCTOR_HTML) $(OPTIONS) $(REQUIRES) $< $(DOCKER_QUOTE)
+
+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..."
+	$(MAKE) build-docs
+	@echo "Build completed successfully inside Docker container."
+
+build-no-container:
+	@echo "Starting build..."
+	$(MAKE) SKIP_DOCKER=true build-docs
+	@echo "Build completed successfully."
+
+clean:
+	@echo "Cleaning up generated files..."
+	rm -rf $(BUILD_DIR)
+	@echo "Cleanup completed."

projects/listings/listings-ex.adoc

@@ -0,0 +1,99 @@
+# Examples of configuring prefixed caption labels
+:toc: left
+:toclevels: 4
+:appendix-caption: Appendix
+:example-caption: Example
+:figure-caption: Figure
+:listing-caption: Listing
+:table-caption: Table
+
+[preface]
+== List of listings
+list-of::listing[hide_empty_section=true, enhanced_rendering=true]
+
+[preface]
+== List of examples
+list-of::examples[hide_empty_section=true, enhanced_rendering=true]
+
+[preface]
+== List of literals
+list-of::literals[hide_empty_section=true, enhanced_rendering=true]
+
+## Overview
+
+You can configure how AsciiDoc https://docs.asciidoctor.org/asciidoc/latest/blocks/add-title/#captioned-titles[ adds a prefixed caption label].  Example would be "Figure" for figures or images and "Table" for tables.
+
+This doc will explore those uses with the hope of defining how it might be done for RISC-V specs.
+
+## Block examples
+
+https://docs.asciidoctor.org/asciidoc/latest/blocks/#block-style[AsciiDoc doc] explaining these examples in more detail.  Also https://docs.asciidoctor.org/asciidoc/latest/blocks/delimited/[delimited blocks]
+
+
+### Block examples using delimiters
+
+.example of an example block with delimiters
+====
+body of example block example
+====
+
+.example of a source listing block with delimiters
+[source,ruby]
+----
+puts "Hello, World!"
+----
+
+.example of a quote block with delimiters
+____
+body of quote
+____
+
+.example of sidebar block with delimiters
+****
+body of sidebar block example
+****
+
+.example of a literal block with delimiters
+....
+body of literal block example
+....
+
+### Block examples from paragraphs
+
+.example of an example block from paragraph
+[example]
+body of example block example
+
+.example of a listing block from paragraph
+[source, shell]
+echo "Hello World"
+
+.example of a quote block from paragraph
+[quote]
+body of quote
+
+### Generic delimiter with label
+
+[literal]
+--
+body
+
+of
+
+literal
+--
+
+### Redefine the prefixed caption label
+
+:listing-caption: Local Listing
+.example of a source listing block redefined prefix caption label
+[source,ruby]
+----
+puts "Hello, World!"
+----
+
+## Findings
+
+* asciidoctor-lists extension doesn't generate lists-of-examples
+* three different ways to create a block type
+* you can redefine the prefixed caption label but this probably isn't a good idea