This repository (repo) contains the resources needed to build docs with the RISC-V themes, fonts, and logos.
Specification repos created after January 2022 are generally created from the docs-spec-template repository and will have all the requisites parts included in a basic document.
Older repos can be updated with 3 basic steps:
- Update the directory structure to reference the docs-resources, (this) repository.
- Update the main AsciiDoc source file to include new variables needed for build.
- Update the
Makefileto build using the new resources.
The three main directories in this repo contain various components of the RISC-V documentation
template. The docs-resources/images/ directory has artwork like the RISC-V logo. The docs-resources/fonts/
directory contains the necessary fonts. And, the docs-resources/themes/ directory contains the YAML file
for configuring the document.
In order to be able to link a repo with this project, you must use
Git Submodules. While there are many ways to do this,
we will take the simplest approach and use the submodule defaults,
placing a docs-resources/ directory in the repo head. This can be accomplished by executing
the following command in the top project directory (assuming http access):
git submodule add https://github.com/riscv/docs-resources.git
This command will create a docs-resources/ directory when completed. Additionally, the git status
command should show new files of docs-resources and either a new or modified file of .gitmodules
depending upon whether Git Submodules are already in use in the project.
Note: The use of Submodules creates a “link” in Git between projects that are tied to specific commit id. This provides “safety” for the including projects by making sure that they don’t inadvertently get broken. However, it creates an additional maintenance responsibility to intermittently rebase the link and verify that nothing has been broken. Project maintainers need to understand this and plan accordingly.
From the Makefile, find the main AsciiDoc file that is used to build the project.
It usually has the same base name as the .pdf which is generated.
Open this file and ensure that the following variables are added to top the document:
// These variables need customization for the specification
:description: Short, text description of spec…
:revdate: Month day, Year
:revnumber: X.Y.Z
:revremark: This document is in Development state. Change should be expected.
// These variables should not require customization
:company: RISC-V
: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
:toclevels: 5
:toc: left
:source-highlighter: pygments
ifdef::backend-pdf[]
:source-highlighter: coderay
endif::[]
:data-uri:
:hide-uri-scheme:
:stem: latexmath
:footnote:
:xrefstyle: short
The variables in the first section above should be visited and updated as appropriate. Additionally, any variables which already exist in the document should be evaluated for the better value, which most likely is the template value specified above for anything in the document.
Typical build invocations for basic AsciiDoc builds look like this:
%.pdf: %.adoc
asciidoctor-pdf $<
To build using the RISC-V template, this statement needs to look like this:
%.pdf: %.adoc
asciidoctor-pdf \
-a toc \
-a compress \
-a pdf-theme=docs-resources/themes/riscv-pdf.yml \
-a pdf-fontsdir=docs-resources/fonts \
-o $@ $<
Note: if you want to include a bibliography, you can include a “-r asciidoctor-bibtex” statement. Likewise, to use various diagramming capabilities, you can include “-r asciidoctor-diagram”.
While making updates to documents, ensure that a License statement is included near the front of the document, preferably in the Preamble. The Asciidoc text for this should look something like this:
[NOTE]
.Copyright and licensure:
====
This work is licensed under a
link:http://creativecommons.org/licenses/by/4.0/[Creative Commons Attribution 4.0 International License].
This work is Copyright 2022 by RISC-V International.
====
Document state should be reflected in the :revmark: variable and be contained in
an in-document admonition statement near the front of the document (Preface or Preamble).
The recommended values for :revmark: and the front matter admonition based on the document
state are as follows:
- For Discussion Document state, use:
:revmark: This document is in Discussion state. Change should be expected.- Formal admonition text:
[WARNING] .This document is in the link:https://lf-riscv.atlassian.net/wiki/display/HOME/Specification+States[Discussion state] ==== Assume everything can change. This document is not complete yet and was created only for the purpose of conversation outside of the document. ====
- For Development state, use:
:revmark: This document is in Development state. Change should be expected.- Formal admonition text:
[WARNING] .This document is in the link:https://lf-riscv.atlassian.net/wiki/display/HOME/Specification+States[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. ====
- For Stable state, use:
:revmark: This document is in Stable state. Assume it may change.- Formal admonition text:
[WARNING] .This document is in the link:https://lf-riscv.atlassian.net/wiki/display/HOME/Specification+States[Stable state] ==== Assume anything could still change, but limited change should be expected. ====
- For Frozen state, use:
:revmark: This document is in Frozen state. Change is extremely unlikely.- Formal admonition text:
[WARNING] .This document is in the link:https://lf-riscv.atlassian.net/wiki/display/HOME/Specification+States[Frozen state] ==== Change is extremely unlikely. A high threshold will be used, and a change will only occur because of some truly critical issue being identified during the public review cycle. Any other desired or needed changes can be the subject of a follow-on new extension. ====
- For Ratified state, use:
:revmark: This document is in Ratified state. No changes are allowed.- Formal admonition text:
[WARNING] .This document is in the link:https://lf-riscv.atlassian.net/wiki/display/HOME/Specification+States[Ratified state] ==== No changes are allowed. Any desired or needed changes can be the subject of a follow-on new extension. Ratified extensions are never revised. ====
The following fonts are included (linked to their source):
- (Atkinson Hyperlegible)[https://www.brailleinstitute.org/freefont] release 2020-0514 distributed under the terms of the (Open Font License)[https://braileinstitute.app.box.com/s/rin3vzegmcy7sil28yfqslz2r5etv5nl] (archived 2024-11-08)
- (Fira Code)[https://github.com/tonsky/FiraCode] release 6.2 distributed under the terms of the (SIL Open Font License 1.1)[https://github.com/tonsky/FiraCode/blob/master/LICENSE] (archived 2024-11-08)
The license files are also included in the fonts directory for reference.
For additional information, see the docs-dev-guide/example.pdf or reach out to [email protected].
