Documentation Clean Up

docs/manual/developer/01_introduction.md

@@ -62,9 +62,9 @@ In order to keep the project scalable, we divide the project into separate areas
 Those areas are going to be segmented by
 
 - Products (RHEL, Ubuntu, …) - make it easy to develop content of a product that doesn't influence the other content or the build system.
-- Product-specific profiles (PSPs s.a. Firefox STIG, Ubuntu CIS, …) and respective control files - make it easy for SMEs that only want to assign rules to profiles without going into details.
+- Product-specific profiles (PSPs), e.g. Firefox STIG, Ubuntu CIS, …, and respective control files - make it easy for SMEs that only want to assign rules to profiles without going into details.
 - Shared resources
-  - Product-independent profiles (PIPs s.a. ANSSI, HIPAA, PCI-DSS, …) and respective control files - ensure that PIP development benefits the whole community instead of cluttering the content with “if product in [...]”.
+  - Product-independent profiles (PIPs), e.g. ANSSI, HIPAA, PCI-DSS, …, and respective control files - ensure that PIP development benefits the whole community instead of cluttering the content with “if product in [...]”.
   - Build system - decisions upon architecture of the build system impact build time, project capabilities, and can also move maintenance costs.
   - Test-related code - ensure that tests have the greatest coverage as possible, but that don't waste time and don't suffer from false positives.
   - Other - rules only loosely coupled to products, templates, CPEs etc. Same principles that apply to PIPs apply for the shared content as well.
@@ -144,7 +144,7 @@ All issues and pull requests for product removal must use the [product-removal](
 #### Organizational administration
 
 - Keeping track of the decomposition: Maintainer file, readme?
-- Area of effect: Github org and project settings
+- Area of effect: GitHub org and project settings
 - Guidelines: Project rules are followed or adapted to changing conditions.
   Decisions are made when a project wants to join the ComplianceAsCode organization.
 
@@ -155,9 +155,9 @@ All issues and pull requests for product removal must use the [product-removal](
 
 TLDR: 6 non-trivial PRs within 6 months => merge rights for 1 year since the last activity.
 
-Contributors can ask for merge rights by opening a Github issue using the `Request Merge Rights` issue template.
+Contributors can ask for merge rights by opening a GitHub issue using the `Request Merge Rights` issue template.
 1. The issue must contain the following:
-    1. The Github ID of the user
+    1. The GitHub username of the applicant
     1. The Reasoning for the requested merge rights
     1. The links for PRs
 
@@ -173,13 +173,13 @@ Loss of merge rights:
 
 Standard acquisition of merge rights:
 - Merit: Anybody who submits 6 non-trivial PRs that get merged in a period no longer than 6 months is entitled to get such rights, and is encouraged to ask for them.
-- Renewal: When a person reapplies for merge rights less than a year after losing them, it is possible to satisfy formal conditions by submitting non-trivial PRs or non-trivial reviews -- 3 of those in 3 months.
+- Renewal: When a person reapplies for merge rights less than a year after losing them, it is possible to satisfy formal conditions by submitting non-trivial PRs or non-trivial reviews — 3 of those in 3 months.
 
 The project maintainers decide about granting or strip of rights and about exceptions to the procedure e.g. when an applicant has deep prior experience with the project.
 
 
 #### Organizations
 
-Aside from an organization (s.a. a company or an institution) being composed of individuals with individual rights, other developers associated with the organization may get “backup” merge rights or organization administration rights.
+Aside from an organization (i.e., a company or an institution) being composed of individuals with individual rights, other developers associated with the organization may get “backup” merge rights or organization administration rights.
 Those rights can be granted for a period of 12 months and their renewal can be requested.
 These rights can only be used in cases when regular developers aren't available and the organization needs to get their things through.

docs/manual/developer/05_tools_and_utilities.md

@@ -106,7 +106,7 @@ Optionally, provide a path to a CaC root and destination YAML file:
                                --output /tmp/rule_dirs.json
 ```
 
-### `utils/fix_rules.py` -- automatically fix-up rules
+### `utils/fix_rules.py` – automatically fix-up rules
 
 `utils/fix_rules.py` includes various sub-commands for automatically fixing
 common problems in rules.
@@ -165,7 +165,7 @@ Example for `sle15` product:
 ```
 
 
-### `utils/autoprodtyper.py` -- automatically add product to `prodtype`
+### `utils/autoprodtyper.py` – automatically add product to `prodtype`
 
 When building a profile for a new product version (such as forking
 `ubuntu1804` into `ubuntu2004`), it is helpful to be able to build a
@@ -193,7 +193,7 @@ For example:
 Note that it is generally good practice to commit all changes prior to running
 one of these commands and then commit the results separately.
 
-### `utils/refchecker.py` -- automatically check `rule.yml` for references
+### `utils/refchecker.py` – automatically check `rule.yml` for references
 
 This utility checks all `rule.yml` referenced from a given profile for the
 specified reference.  Unlike `build-scripts/profile_tool.py`, which operates
@@ -218,7 +218,7 @@ product-independent.
 
 Note that this utility does not modify the rule directories at all.
 
-### `utils/mod_prodtype.py` -- programmatically modify prodtype in `rule.yml`
+### `utils/mod_prodtype.py` – programmatically modify prodtype in `rule.yml`
 
 `utils/mod_prodtype.py` is a command-based utility for modifying `rule.yml`
 files. It supports the following sub-commands:
@@ -259,7 +259,7 @@ For an example of `remove`:
     $ ./utils/mod_prodtype.py accounts_passwords_pam_tally2 remove ubuntu1604 ubuntu1804 ubuntu2004
 ````
 
-### `utils/mod_checks.py` and `utils/mod_fixes.py` -- programmatically modify check and fix applicability
+### `utils/mod_checks.py` and `utils/mod_fixes.py` – programmatically modify check and fix applicability
 
 These two utilities have identical usage. Both modifies the platform/product
 applicability of various files (either OVAL or hardening content), similar to
@@ -333,7 +333,7 @@ For an example of `make_shared`:
     $ ./utils/mod_fixes.py clean_components_post_updating bash make_shared sle12
 ```
 
-### `utils/create_scap_delta_tailoring.py` - Create tailoring files for rules not covered by other content
+### `utils/create_scap_delta_tailoring.py` – Create tailoring files for rules not covered by other content
 
 The goal of this tool is to create a tailoring file that enable rules that are not covered by other SCAP content and disables rules that are covered by the given content.
 It supports the following arguments:
@@ -359,7 +359,7 @@ To execute:
     $ ./utils/create_scap_delta_tailoring.py -p rhel8 -b stig -m shared/references/disa-stig-rhel8-v1r4-xccdf-scap.xml
 ```
 
-### `utils/compare_ds.py` - Compare two data streams (can also compare XCCDFs)
+### `utils/compare_ds.py` – Compare two data streams (can also compare XCCDFs)
 
 This script compares two data streams or two benchmarks and generates a diff output.
 It can show what changed in rules, for example in description, references and remediation scripts.
@@ -407,7 +407,7 @@ Generate the HTML diffs:
     $ for f in $(ls compare_ds-diffs/); do diff2html -i file -t $f -F "html/$f.html" "compare_ds-diffs/$f"; done
 ```
 
-### `utils/compare_results.py` - Compare to two ARF result files
+### `utils/compare_results.py` – Compare to two ARF result files
 
 The goal of this script is to compare the result of two ARF files.
 It will show what rules are missing, different, and the same between the two files.
@@ -438,7 +438,7 @@ To execute:
     $ ./utils/compare_results.py ssg_results.xml disa_results.xml
 ```
 
-### `utils/import_srg_spreadsheet.py` - Import changes made to an SRG Spreadsheet into the project
+### `utils/import_srg_spreadsheet.py` – Import changes made to an SRG Spreadsheet into the project
 
 This script will import changes from a SRG export spreadsheet.
 This script is designed to be run then each file reviewed carefully before being committed.
@@ -459,7 +459,7 @@ To execute:
     $ ./utils/import_srg_spreadsheet.py --changed 20220811_submission.xlsx --current build/cac_stig_output.xlsx -p rhel9
 ```
 
-## Profiling the buildsystem
+## Profiling the Build System
 
 The goal of `utils/build_profiler.sh` and `utils/build_profiler_report.py` is to help developers measure and compare build times of a single product or a group of products and determine what impact their changes had on the speed of the buildsystem.
 Both of these tools shouldn't be invoked alone but rather through the build_product script by using the -p|--profiling switch.
@@ -470,7 +470,7 @@ The intended usage is:
     $ ./build_product <products> -p|--profiling
 ```
 
-### `utils/build_profiler.sh` -- Handle directory structure for profiling files and invokes other script
+### `utils/build_profiler.sh` &ndash; Handle directory structure for profiling files and invokes other script
 
 The goal of this tool is to create the directory structure necessary for the profiling system and create a new numbered logfile, as well as invoking the `utils/build_profiler_report.py` and subsequently generating an interactive HTML file using webtreenode.
 
@@ -493,7 +493,7 @@ To execute:
     $ ./build_profiler.sh <product_string>
 ```
 
-### `utils/build_profiler_report.py` -- Parse a ninja file and display report to user
+### `utils/build_profiler_report.py` &ndash; Parse a ninja file and display report to user
 
 The goal of this tool is to generate a report about differences in build times, both a text version in the terminal and a webtreenode version that is later converted into an interactive HTML report.
 
@@ -521,7 +521,7 @@ To execute:
 
 ## Other Scripts
 
-### Compare Two SRG Spreadsheets - `utils/srg_diff.py`
+### `utils/srg_diff.py` &ndash; Compare Two SRG Spreadsheets
 
 This script will output an HTML page that compares two SRG exports.
 This script should help with reviewing changes created by `utils/import_srg_spreadsheet.py` script.
@@ -541,7 +541,7 @@ Example:
     Wrote output to build/diff.html.
 ```
 
-### Convert shorthand OVAL to a full OVAL - `utils/shorthand_to_oval.py`
+### `utils/shorthand_to_oval.py` &ndash; Convert shorthand OVAL to a full OVAL
 
 This script converts (resolved) shorthand OVAL files to a valid OVAL file.
 
@@ -556,7 +556,7 @@ $ utils/shorthand_to_oval.py build/rhel9/checks/oval/accounts_tmout.xml oval.xml
 $ oscap oval eval oval.xml
 ```
 
-### Ensure Control Files and Rules Are Consistent - `utils/controlrefcheck.py`
+### `utils/controlrefcheck.py` &ndash; Ensure Control Files and Rules Are Consistent
 
 This script helps ensure that control files and rules files are in sync.
 The script takes in what product, control, and reference you are looking for.
@@ -569,7 +569,7 @@ To execute:
 $ ./utils/controlrefcheck.py rhel9 cis_rhel9 cis
 ```
 
-### Ensure Files Follow EOF Style - `utils/check_eof.py`
+### `utils/check_eof.py` - Ensure Files Follow EOF Style
 
 This script checks files of specific extensions (see `EXTENSIONS` in the script for the full list) to ensure that the files end with new line as required by the [style guide](https://complianceascode.readthedocs.io/en/latest/manual/developer/04_style_guide.html).
 This script can be used to fix files that don't have a newline at the end if the `--fix` flag is passed to the script.
@@ -580,7 +580,7 @@ By default, the script just outputs a list of files are non-compliant.
  $ ./utils/check_eof.py ssg linux_os utils tests products shared docs apple_os applications build-scripts cmake Dockerfiles
  ```
 
-### Generating CIS Control Files - `utils/generate_profile.py`
+### `utils/generate_profile.py` &ndash; Generating CIS Control Files
 
 This script accepts a CIS benchmark spreadsheet (XLSX) and outputs a profile,
 section, or rule. This is primarily useful for contributors maintaining
@@ -653,7 +653,7 @@ The `PLACEHOLDER` values must be filled in later, ideally when the rules are
 provided for each control.
 
 
-### Compare ComplianceAsCode versions - `utils/compare_versions.py`
+### `utils/compare_versions.py` &ndash; Compare ComplianceAsCode versions
 
 Show differences between two ComplianceAsCode versions.
 Lists added or removed rules, profiles, changes in profile composition and changes in remediations and platforms.

docs/manual/developer/06_contributing_with_content.md

@@ -637,7 +637,7 @@ fixes with the following commands:
     fix. See the description of `replace` under `mod_prodtype.py` for
     more information about the format of a replacement.
 
-This utility requires an up to date JSON tree created by
+This utility requires an up-to-date JSON tree created by
 `rule_dir_json.py`.
 
 #### `utils/add_platform_rule.py`

docs/manual/developer/08_content_tests.md

@@ -20,10 +20,11 @@ To add a script to be checked with mypy use the `mypy_test` macro in `tests/CMak
 ## SCAPVal
 We use [SCAPVal](https://csrc.nist.gov/Projects/scap-validation-program/Validation-Test-Content) to valid our content.
 Since a separate download is required this test is disabled by default.
-A working Java installation is also required to SCAPVal to work.
-To enable this test the following options will need to passed to cmake:
+A working Java installation is also required for SCAPVal to work.
+To enable this test pass following options to cmake:
 
 * `-DENABLE_SCAPVAL13:BOOL=ON` - This enables SCAPVal
-* `-DSCAPVAL_PATH='/opt/scapval/SCAP-Content-Validation-Tool-1.3.5/scapval-1.3.5.jar'`
+* `-DSCAPVAL_PATH='/opt/scapval/SCAP-Content-Validation-Tool-1.3.5/scapval-1.3.5.jar'` - This provides the path to the SCAPVal jar.
+You will need to replace `/opt/scapval/SCAP-Content-Validation-Tool-1.3.5/scapval-1.3.5.jar` with the actual path the SCAPVAL jar on your system.
 
 SCAPVal can be run with ctest using the following command `ctest -R 'scapval' --output-on-failure`.

docs/release_process.md

@@ -6,8 +6,8 @@ How to Perform An Upstream Release (GitHub)
 In line with this release process documentation, there is a script designed to automate the tasks described in this document as much as possible.
 While any task can be performed manually, it is highly recommended to use the `release_helper.py` script during the release process in order to increase the efficiency and be less prone to errors.
 
-The script interacts with the Github API, so an [API token](https://github.com/settings/tokens) is required for most tasks.
-Instructions for generating a Github API token can be found directly in the [Github documentation](https://docs.github.com/), but some hints are also provided by the script.
+The script interacts with the GitHub API, so an [API token](https://github.com/settings/tokens) is required for most tasks.
+Instructions for generating a GitHub API token can be found directly in the [GitHub documentation](https://docs.github.com/), but some hints are also provided by the script.
 
 The `release_helper.py` script can also be used to check the current status of the project regarding releases:
 
@@ -143,7 +143,7 @@ Using `release_helper.py` script:
         - https://gitter.im/Compliance-As-Code-The/content
     - SCAP Security Guide Mail List
         - scap-security-guide@lists.fedorahosted.org
-    - Github Discussion
+    - GitHub Discussion
         - https://github.com/ComplianceAsCode/content/discussions/new?category=announcements
         - Reference: https://github.com/ComplianceAsCode/content/discussions/9859
     - Here is an example message that could be used as reference:
@@ -215,7 +215,7 @@ Below are listed a few approaches how to do it.
     ```
     stab_base=$(git merge-base master stabilization-v0.1.65)
     git checkout -b my_fix $stab_base
-    # Do the fix, commit, push and create two PRs through the Github Web Interface.
+    # Do the fix, commit, push and create two PRs through the GitHub Web Interface.
     # One PR should targeting **master** and the other targeting the **stabilization** branch.
     ```
 
@@ -312,7 +312,7 @@ Using `release_helper.py` script:
     - SCAP Security Guide and OpenSCAP Mail Lists
         - scap-security-guide@lists.fedorahosted.org
         - open-scap-list@redhat.com
-    - Github Discussion
+    - GitHub Discussion
         - https://github.com/ComplianceAsCode/content/discussions/new?category=announcements
     - Twitter
         - https://twitter.com/openscap