Adjust repo layout for fit the format of docs-spec-template

Makefile

@@ -10,12 +10,17 @@ all: $(NAME).pdf
 clean:
 	rm -f $(NAME).pdf
 
-$(NAME).pdf: $(NAME).adoc $(wildcard *.adoc) resources/themes/risc-v_spec-pdf.yml
+docs-resources/README.md:
+	git submodule update --init
+
+docs-resources/themes/riscv-pdf.yml: docs-resources/README.md
+
+$(NAME).pdf: $(NAME).adoc $(wildcard *.adoc) docs-resources/themes/riscv-pdf.yml
 	asciidoctor-pdf \
 	    -a compress \
 	    -a date="$(DATE)" \
 	    -a monthyear="$(MONTHYEAR)" \
-	    -a pdf-style=resources/themes/risc-v_spec-pdf.yml \
-	    -a pdf-fontsdir=resources/fonts \
+	    -a pdf-style=docs-resources/themes/riscv-pdf.yml \
+	    -a pdf-fontsdir=docs-resources/fonts \
 	    -v \
 	    $< -o $@

docs-resources/README.md

@@ -0,0 +1,195 @@
+# RISC-V Documentation Resources
+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](https://github.com/riscv/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:
+
+1. Update the directory structure to reference the docs-resources, (this) repository.
+2. Update the main AsciiDoc source file to include new variables needed for build.
+3. Update the `Makefile` to build using the new resources.
+
+## Updating the directory structure
+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](https://git-scm.com/book/en/v2/Git-Tools-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.
+
+## Updating the main AsciiDoc source file
+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.
+
+## Updating the `Makefile`
+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-style=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”.
+
+## Additional items to consider for the document
+
+### License and copyright statements
+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 markings
+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:http://riscv.org/spec-state[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: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.
+    ====
+    ```
+* 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:http://riscv.org/spec-state[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:http://riscv.org/spec-state[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:http://riscv.org/spec-state[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.
+    ====
+    ```
+
+ # Additional information
+ For additional information, see the [docs-dev-guide/example.pdf](https://github.com/riscv/docs-dev-guide/blob/main/example.pdf) or reach out to 
+ [email protected].

docs-resources/fonts/OFL-M.txt

@@ -0,0 +1,93 @@
+Copyright 2011 The Montserrat Project Authors (https://github.com/JulietaUla/Montserrat)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.