Adopt the RISC-V documentation format (#73)

.gitmodules

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

Makefile

@@ -3,9 +3,13 @@
 #
 
 ASCIIDOCTOR = asciidoctor
+ASCIIDOCTOR_PDF = $(ASCIIDOCTOR)-pdf
 DITAA = ditaa
 IMAGES = pcie-topology.png
 PLATFORM_SPEC = riscv-platform-spec
+RISCV_DIR = docs-resources
+RISCV_YML = $(RISCV_DIR)/themes/riscv-pdf.yml
+RISCV_FONTS = $(RISCV_DIR)/fonts/
 PANDOC = pandoc
 PARTS = changelog.adoc contributors.adoc introduction.adoc licensing.adoc
 
@@ -22,8 +26,13 @@ $(PLATFORM_SPEC).md: $(PLATFORM_SPEC).xml
 $(PLATFORM_SPEC).xml: $(PLATFORM_SPEC).adoc
 	$(ASCIIDOCTOR) -d book -b docbook $<
 
-$(PLATFORM_SPEC).pdf: $(PLATFORM_SPEC).adoc $(IMAGES) $(PLATFORM_SPEC).yml
-	$(ASCIIDOCTOR) -d book -r asciidoctor-pdf -a pdf-style=$(PLATFORM_SPEC).yml -b pdf $<
+$(PLATFORM_SPEC).pdf: $(PLATFORM_SPEC).adoc $(IMAGES) $(RISCV_YML)
+	$(ASCIIDOCTOR_PDF) \
+	-a toc \
+	-a compress \
+	-a pdf-style=$(RISCV_YML) \
+	-a pdf-fontsdir=$(RISCV_FONTS) \
+	-o $@ $<
 
 $(PLATFORM_SPEC).html: $(PLATFORM_SPEC).adoc $(IMAGES)
 	$(ASCIIDOCTOR) -d book -b html $<

README.md

@@ -28,9 +28,43 @@ and PDF versions of the current spec
 * **README.md** => this file
 * ```riscv-platform-spec.adoc``` => the spec in asciidoc format; there are
 several subsidiary asciidoc files that get included by this file.
+* ```docs-resources``` => Git Submodule with the RISC-V documentation theme, 
+fonts, etc.  for building the document
 
 # Repository Branches
 * All development occurs on ```main```; no content on main is to be
 considered TSC-approved content.
 * TSC-approved content will be clearly marked as such.
 
+# Dependencies
+The PDF built in this project uses AsciiDoctor (Ruby). For more information
+on AsciiDoctor, specification guidelines, or building locally, see the 
+[RISC-V Documentation Developer Guide](https://github.com/riscv/docs-dev-guide).
+
+# Cloning the project
+This project uses 
+[GitHub Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) 
+to include the RISC-V 
+[docs-resources project](https://github.com/riscv/docs-resources)
+to achieve a common look and feel.
+
+When cloning this repository for the first time, you must either use 
+`git clone --recurse-submodules` or execute `git submodule init` and 
+`git submodule update` after the clone to populate the `docs-resources` 
+directory. Failure to clone the submodule, will result in the PDF build 
+fail with an error message like the following:
+
+```
+$ make
+asciidoctor-pdf \
+-a toc \
+-a compress \
+-a pdf-style=docs-resources/themes/riscv-pdf.yml \
+-a pdf-fontsdir=docs-resources/fonts \
+--failure-level=ERROR \
+-o profiles.pdf profiles.adoc
+asciidoctor: ERROR: could not locate or load the built-in pdf theme `docs-resources/themes/riscv-pdf.yml'; reverting to default theme
+No such file or directory - notoserif-regular-subset.ttf not found in docs-resources/fonts
+  Use --trace for backtrace
+make: *** [Makefile:7: profiles.pdf] Error 1
+```

riscv-platform-spec.adoc

@@ -8,18 +8,51 @@
 = RISC-V Platform Specification
 :author: RISC-V Platform Horizontal Subcommittee (RISC-V Platform HSC) 
 :email: [email protected]
+:company: RISC-V
 :revnumber: 0.3-draft
 :revdate: December 2021
+:revremark: This document is in Development state.  Change should be expected.
+:url-riscv: http://riscv.org
 :doctype: book
+:preface-title: Preamble
+:colophon:
+:appendix-caption: Appendix
+:title-logo-image: image:docs-resources/images/risc-v_logo.svg[pdfwidth=3.25in,align=center]
+// Settings:
+:experimental:
+:reproducible:
+:WaveDromEditorApp: wavedrom-cli
+:icons: font
+:lang: en
+:listing-caption: Listing
 :sectnums:
 :sectnumlevels: 5
 :xrefstyle: short
-:toc: macro
+:toc: left
 :toclevels: 5
+:source-highlighter: pygments
+ifdef::backend-pdf[]
+:source-highlighter: coderay
+endif::[]
+:data-uri:
+:hide-uri-scheme:
+:stem: latexmath
+:footnote:
+:xrefstyle: short
 
 // table of contents
 toc::[]
 
+// Preamble
+[WARNING]
+.This document is in the link:http://riscv.org/spec-state[Development state]
+====
+Assume everything can change. This draft specification 
+will change before being accepted as standard, so 
+implementations made to this draft specification will 
+likely not conform to the future standard.
+====
+
 // document copyright and licensing information
 include::licensing.adoc[]