[doc] Use consistent spelling/capitalization of names
Consistently use the following spelling for document formats,
programming languages, and names:
- Markdown
- Hjson
- JSON
- Verilog
- HTML
- GitHub
- CSS
- Python
Also avoid abbreviations:
- repo -> repository
Signed-off-by: Philipp Wagner <phw@lowrisc.org>
diff --git a/doc/rm/comportability_specification/index.md b/doc/rm/comportability_specification/index.md
index d068955..54e5fd1 100644
--- a/doc/rm/comportability_specification/index.md
+++ b/doc/rm/comportability_specification/index.md
@@ -56,9 +56,9 @@
// SPDX-License-Identifier: Apache-2.0
```
-The project has adopted [Hjson](https://hjson.org) for json files, extending json to allow comments.
+The project has adopted [Hjson](https://hjson.org) for JSON files, extending JSON to allow comments.
Thus the Hjson files can include the header above.
-If pure json must be used for some reason, the "SPDX-License-Identifier:" can be added as the first key after the opening "{".
+If pure JSON must be used for some reason, the "SPDX-License-Identifier:" can be added as the first key after the opening "{".
Tools developed by the project should accept and ignore this key.
### Coding Style
diff --git a/doc/rm/hjson_usage_style.md b/doc/rm/hjson_usage_style.md
index 477a0ba..5322aa7 100644
--- a/doc/rm/hjson_usage_style.md
+++ b/doc/rm/hjson_usage_style.md
@@ -7,7 +7,7 @@
### Summary
Json files are used to provide input data to many of the tools.
-The preference is to use [Hjson](https://hjson.org/), which is a variation of regular json that is easier to write.
+The preference is to use [Hjson](https://hjson.org/), which is a variation of regular JSON that is easier to write.
In particular it allows the quote marks to be left off the key names, it allows a single string to be quoted with triple quote marks and flow over multiple lines (which is often needed in text descriptions) and it allows comments using the # or // style.
This guide covers the enhancements provided by Hjson that are used in the project along with a recommended style.
@@ -42,8 +42,8 @@
## Hjson file format
-Hjson is a variation of regular json that is easier to write.
-There are parsers in a number of languages and the tools make extensive used of the `hjson` package provided for Python3.
+Hjson is a variation of regular JSON that is easier to write.
+There are parsers in a number of languages and the tools make extensive used of the `hjson` package provided for Python 3.
A full description can be found on the [Hjson website](https://hjson.org/), but the main features that make it convenient are that it keeps files cleaner by allowing the quote marks to be left off the key names, it enables long descriptive text by allowing a single string to flow over multiple lines and it allows comments using the # or // style.
For example:
@@ -84,7 +84,7 @@
}
```
-In cases where the file may need to be parsed by a standard json parser the comments must be omitted, but the SPDX license information should be provided as a top-level key/value using pure json syntax and ignored by any tool.
+In cases where the file may need to be parsed by a standard JSON parser the comments must be omitted, but the SPDX license information should be provided as a top-level key/value using pure JSON syntax and ignored by any tool.
```json {.good}
@@ -102,7 +102,7 @@
Single entries are of the form `key: "value"` Keys must be alphanumeric strings and should not be in quotes.
(Hjson allows this.
-The quotes may be included as an exception to the style guide if there is an expectation that the file needs to be parsed with a more traditional json parser.)
+The quotes may be included as an exception to the style guide if there is an expectation that the file needs to be parsed with a more traditional JSON parser.)
The valid keys for each tool are described in the tool documentation.
The style is for a simple value to be in quotes (even if it is a number) and the tool should manage any type conversions.
diff --git a/doc/rm/markdown_usage_style.md b/doc/rm/markdown_usage_style.md
index d137d0b..35f9f98 100644
--- a/doc/rm/markdown_usage_style.md
+++ b/doc/rm/markdown_usage_style.md
@@ -7,9 +7,9 @@
### Summary
Markdown files are used to write most documentation.
-The main markdown tool is [Hugo](https://gohugo.io).
+The main Markdown tool is [Hugo](https://gohugo.io).
-The markdown processing is done using the `build_docs.py` tool in the `util` directory.
+The Markdown processing is done using the `build_docs.py` tool in the `util` directory.
As with all style guides the intention is to:
@@ -43,10 +43,10 @@
### Line length
-There are two acceptable styles for line wrapping in markdown files:
+There are two acceptable styles for line wrapping in Markdown files:
1. Wrap lines at under 80 characters.
- This ensures that the source is readable without any markdown processing, but re-wrapping a paragraph after an insertion or deletion tends to cause more diffs when the change is reviewed.
+ This ensures that the source is readable without any Markdown processing, but re-wrapping a paragraph after an insertion or deletion tends to cause more diffs when the change is reviewed.
When making changes to a document using this style consider allowing short lines rather than a full re-wrap after minor edits.
Then occasionally a separate commit can be used that only does re-wrapping of the paragraphs.
This style is recommended for all README files.
@@ -60,7 +60,7 @@
Headings and sections are given ID tags to allow cross references.
The ID is the text of the heading, converted to lower case and with spaces converted to `-`.
-Thus `### Headings and sections` gets the ID `headings-and-sections` and can be referenced using the markdown hyperlink syntax `[link text](#headings-and-sections)`.
+Thus `### Headings and sections` gets the ID `headings-and-sections` and can be referenced using the Markdown hyperlink syntax `[link text](#headings-and-sections)`.
Headings and sections are added to the table of contents.
@@ -84,21 +84,21 @@
### Text Format
-Where possible, please restrict markdown text to the ASCII character set to avoid downstream tool issues.
+Where possible, please restrict Markdown text to the ASCII character set to avoid downstream tool issues.
Unicode may be used when referring to proper names.
### Comments
Comments are rare, but should be used where needed.
-Use the html `<!--` and `-->` as the comment delimiters.
+Use the HTML `<!--` and `-->` as the comment delimiters.
### Markdown file extensions
-The markdown files should use the `.md` file extension.
+The Markdown files should use the `.md` file extension.
## Markdown file format for IP module descriptions
-Typically the markdown file for an IP block follows the same outline.
+Typically the Markdown file for an IP block follows the same outline.
The header instantiates the standard document header and reads the Hjson description of the module.
diff --git a/doc/rm/python_coding_style.md b/doc/rm/python_coding_style.md
index 3f4dcc5..c17bdc5 100644
--- a/doc/rm/python_coding_style.md
+++ b/doc/rm/python_coding_style.md
@@ -67,8 +67,8 @@
### Lint tool
-The `lintpy.py` utility in `util` can be used to check python code.
-It checks all python (`.py`) files that are modified in the local repo and will report problems.
+The `lintpy.py` utility in `util` can be used to check Python code.
+It checks all Python (`.py`) files that are modified in the local repository and will report problems.
Both `yapf` and `isort` checks are run.
Basic lintpy usage is just to run from the util directory.
@@ -90,7 +90,7 @@
```
Errors may be fixed using the same tool to edit the problem file(s) in-place (you may need to refresh the file(s) in your editor after doing this).
-This uses the same set of files as are being checked, so unless the`--file` or `-f` flag is used this will only affect files that have already been modifed (or staged for commit if `-c`is used) and will not fix errors in python files that have not been touched.
+This uses the same set of files as are being checked, so unless the`--file` or `-f` flag is used this will only affect files that have already been modifed (or staged for commit if `-c`is used) and will not fix errors in Python files that have not been touched.
```console
$ cd $REPO_TOP/util
@@ -117,7 +117,7 @@
$ isort file.py
```
-Yapf and isort are python packages and should be installed with pip:
+Yapf and isort are Python packages and should be installed with pip:
```console
$ pip3 install --user yapt
@@ -171,9 +171,9 @@
Do not use tabs.
You should set your editor to emit spaces when you hit the tab key.
-### Executable python tools
+### Executable Python tools
-Tools that can be executed should use `env` to avoid making assumptions about the location of the python interpreter.
+Tools that can be executed should use `env` to avoid making assumptions about the location of the Python interpreter.
Thus they should begin with the line:
```console
@@ -190,5 +190,5 @@
This will provide support for `--help` and `-h` to get usage information.
Every command line program should provide `--version` to provide standard version information.
-This lists the git repositary information for the tool and the version numbers of any python packages that are used.
+This lists the git repositary information for the tool and the version numbers of any Python packages that are used.
The `show_and_exit` routine in `reggen/version.py` can be used to do this.
diff --git a/doc/rm/register_tool/index.md b/doc/rm/register_tool/index.md
index 723fa29..2032370 100644
--- a/doc/rm/register_tool/index.md
+++ b/doc/rm/register_tool/index.md
@@ -3,13 +3,13 @@
---
The register tool is used to construct register documentation, register RTL and header files.
-It is either used stand-alone or by being invoked as part of markdown processing.
+It is either used stand-alone or by being invoked as part of Markdown processing.
## Running standalone regtool.py
-The standalone `regtool.py` is a python3 tool to read configuration and register descriptions in Hjson and generate various output formats.
-Currently it can output html documentation, standard json, compact standard json (whitespace removed), Hjson, verilog RTL and various forms of C header files.
+The standalone `regtool.py` is a Python 3 tool to read configuration and register descriptions in Hjson and generate various output formats.
+Currently it can output HTML documentation, standard JSON, compact standard JSON (whitespace removed), Hjson, Verilog RTL and various forms of C header files.
The standard `--help` and `--version` command line flags are supported to print the usage and version information.
Because the version includes information on libraries (which may be different between systems) reporting the version output is sometimes useful when issues are reported.
@@ -22,12 +22,12 @@
The tool input is an Hjson file containing the Comportable description of the IP block and its registers.
-A description of Hjson (a varient of json) and the recommended style is in the [Hjson Usage and Style Guide]({{< relref "hjson_usage_style.md" >}}).
+A description of Hjson (a variant of JSON) and the recommended style is in the [Hjson Usage and Style Guide]({{< relref "hjson_usage_style.md" >}}).
The tables below describe valid keys for each context.
-It is an error if *required* keys are missing from the input json.
+It is an error if *required* keys are missing from the input JSON.
*Optional* keys may be provided in the input file as needed, as noted in the tables the tool may insert them (with default or computed values) during validation so the output generators do not have to special case them.
-Keys marked as "inserted by tool" should not be in the input json (they will be silently overwritten if they are there), they are derived by the tool during validation of the input and available to the output generators.
+Keys marked as "inserted by tool" should not be in the input JSON (they will be silently overwritten if they are there), they are derived by the tool during validation of the input and available to the output generators.
{{% selfdoc "reggen" %}}
@@ -220,7 +220,7 @@
This section details the register generation for hardware instantiation.
The input to the tool for this generation is the same `.hjson` file described above.
-The output is two verilog files that can be instantiated by a peripheral that follows the [Comportability Guidelines]({{< relref "comportability_specification" >}}).
+The output is two Verilog files that can be instantiated by a peripheral that follows the [Comportability Guidelines]({{< relref "comportability_specification" >}}).
The register generation tool will generate the RTL if it is invoked with the `-r` flag.
The `-t <directory>` flag is used to specify the output directory where the two files will be written.
@@ -626,5 +626,5 @@
## Generating documentation
-The register tool can be used standalone to generate html documentation of the registers.
-However, this is normally done as part of the markdown documentation using the special tags to include the register definition file and insert the configuration and register information.
+The register tool can be used standalone to generate HTML documentation of the registers.
+However, this is normally done as part of the Markdown documentation using the special tags to include the register definition file and insert the configuration and register information.
diff --git a/doc/rm/topgen_tool.md b/doc/rm/topgen_tool.md
index cc6f459..f83cf44 100644
--- a/doc/rm/topgen_tool.md
+++ b/doc/rm/topgen_tool.md
@@ -106,8 +106,8 @@
configurations
--top-only If defined, the tool generates top RTL only
--xbar-only If defined, the tool generates crossbar RTLs only
- --plic-only If defined, the tool generates RV_PLIC RTL and hjson only
- --hjson-only If defined, the tool generates complete hjson only
+ --plic-only If defined, the tool generates RV_PLIC RTL and Hjson only
+ --hjson-only If defined, the tool generates complete Hjson only
--top_ral, -r If set, the tool generates top level RAL model for DV
```
