From 5e32691215bf8969773e48a8296bd19ffc01b81c Mon Sep 17 00:00:00 2001 From: Kevin Broch Date: Tue, 7 May 2024 21:49:42 -0700 Subject: [PATCH] examples of various block types and how prefixed caption labels works relates to #40 Signed-off-by: Kevin Broch --- Makefile | 84 +++++++++++++++++++++++++ projects/listings/listings-ex.adoc | 99 ++++++++++++++++++++++++++++++ 2 files changed, 183 insertions(+) create mode 100644 Makefile create mode 100644 projects/listings/listings-ex.adoc diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..6f35e2e --- /dev/null +++ b/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." diff --git a/projects/listings/listings-ex.adoc b/projects/listings/listings-ex.adoc new file mode 100644 index 0000000..b3177bd --- /dev/null +++ b/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