diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..cde1eb5 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "docs-resources"] + path = docs-resources + url = https://github.com/riscv/docs-resources.git diff --git a/Makefile b/Makefile index a5a8568..eb082ee 100644 --- a/Makefile +++ b/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 $< diff --git a/README.md b/README.md index f70b5b0..dbe4a44 100644 --- a/README.md +++ b/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 +``` diff --git a/docs-resources b/docs-resources new file mode 160000 index 0000000..6a2d5b1 --- /dev/null +++ b/docs-resources @@ -0,0 +1 @@ +Subproject commit 6a2d5b1f929e0e25df0c832b522ed1fc0c78e325 diff --git a/riscv-platform-spec.adoc b/riscv-platform-spec.adoc index 7e81436..6264ab8 100644 --- a/riscv-platform-spec.adoc +++ b/riscv-platform-spec.adoc @@ -8,18 +8,51 @@ = RISC-V Platform Specification :author: RISC-V Platform Horizontal Subcommittee (RISC-V Platform HSC) :email: tech-unixplatformspec@lists.riscv.org +: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[] diff --git a/riscv-platform-spec.pdf b/riscv-platform-spec.pdf index 5c76a77..1aea123 100644 Binary files a/riscv-platform-spec.pdf and b/riscv-platform-spec.pdf differ diff --git a/riscv-platform-spec.yml b/riscv-platform-spec.yml deleted file mode 100644 index ce00e22..0000000 --- a/riscv-platform-spec.yml +++ /dev/null @@ -1,8 +0,0 @@ -extends: default -image: - align: center -caption: - align: center -table: - caption: - side: bottom