Doc spelling grammar tweaks

docs/conf.py

@@ -150,7 +150,6 @@ def add_target_and_index(self, name: tuple[_FullNameStr, _Ident], sig: str, sign
             self.state.document.note_explicit_target(signode)
 
         dom = cast(SchematicDomain, self.env.get_domain('schematic'))
-        print(f'Saving {self.objtype} {fullname}')
         assert self.objtype in ('property', 'mapping')
         dom.data['objects'][fullname] = {
             'parent': _dotpath(self.env),
@@ -391,7 +390,6 @@ def find_obj(self, node: addnodes.pending_xref, name: str) -> _SchematicEntry |
         else:
             partials = [name]
         for cand in partials:
-            print('Looking for fullnamed object:', cand)
             found = self.data['objects'].get(cand)
             if found is not None:
                 return found
@@ -400,7 +398,6 @@ def find_obj(self, node: addnodes.pending_xref, name: str) -> _SchematicEntry |
 
     def resolve_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder, typ: Literal['mapping', 'prop'],
                      target: str, node: addnodes.pending_xref, contnode: Element):
-        ident = f'{typ}:{target}'
         ent: _SchematicEntry | None
         ent = self.find_obj(node, target)
         if ent is None:

docs/crs/index.rst

@@ -51,7 +51,7 @@ Briefly, `CRS` concerns itself with the following high-level concepts:
 
     An acronym for :strong:`C`\ ompile-\ :strong:`R`\ eady :strong:`S`\ ource.
     CRS is a set of file formats and `JSON` schemas that describe a way to
-    destribute software in source-code format, ready to be given to any
+    distribute software in source-code format, ready to be given to any
     compatible compiler without further configuration or code generation.
 
     .. seealso:: :doc:`index`

docs/design.rst

@@ -183,7 +183,7 @@ No Arbitrary |#include| Directories
 ===================================
 
 Only ``src/`` and ``include/`` will ever be used as the basis for
-`header resolution <header search path>` while building a project, so all
+:term:`header resolution <header search path>` while building a project, so all
 |#include| directives should be relative to those directories. Refer to
 :ref:`libs.source-kinds`.
 
@@ -199,5 +199,5 @@ every library in that dependency tree will be compiled with an identical set of
 options. Refer to the :doc:`guide/toolchains` page for more information.
 
 Currently, the only exception to this rules is for flags that control compiler
-warnings: Dependencies will be compiled without adding any warnings flags, while
-the main project will be compiled with warnings enabled by default.
+diagnostics: Dependencies will be compiled without adding any warnings flags,
+while the main project will be compiled with warnings enabled by default.

docs/dev/reqs.rst

@@ -13,10 +13,11 @@ Build Requirements
 Building |bpt| has a simple set of requirements:
 
 - **Python 3.7** or newer to run the bootstrap/CI scripts.
-- A C++ compiler that has rudimentary support for several C++20 features,
-  including Concepts. Newer releases of Visual C++ that ship with **VS 2019**
-  will be sufficient on Windows, as will **GCC 10** with ``-std=c++20`` and
-  ``-fcoroutines`` on other platforms.
+- A C++ compiler that has rudimentary support for several C++20 features. Newer
+  releases of Visual C++ that ship with **VS 2019** will be sufficient on
+  Windows, as will **GCC 10** with ``-std=c++20`` and ``-fcoroutines`` on other
+  platforms. **Note:** Using newer compiler versions may cause trouble as they
+  are untested, but adding support for these systems is planned.
 - On Linux, the OpenSSL headers are needed. This can be installed through the
   ``libssl-dev`` package on Debian/Ubuntu or ``openss-devel`` +
   ``openssl-static`` on RedHat systems. (For Windows, the |bpt| repository ships

docs/dev/testing.rst

@@ -13,7 +13,7 @@ within the :doc:`Poetry virtual environment <env>`::
 Note that individual tests can take between a few seconds and a few minutes to
 execute, so it may be useful to execute only a subset of the tests based on the
 functionality you want to test. Refer to
-`the pytest documentation <https://docs.pytest.org/en/latest/>` for more
+`the pytest documentation <https://docs.pytest.org/en/latest/>`_ for more
 information about using and executing ``pytest``. If you are running the full
 test suite, you may also want to pass the ``-n`` argument with a number of
 parallel jobs to execute.

docs/guide/build-deps.rst

@@ -27,7 +27,7 @@ is not generated globally**: It is generated on a per-build basis as part of the
 build process. The manifest will describe in build-system-agnostic terms how to
 include and link against as set of libraries generated by a build.
 
-|bpt| has first-class support for generating this index. The ``build-deps``
+|bpt| has first-class support for generating this file. The ``build-deps``
 subcommand of |bpt| will download and build a set of dependencies, and places
 a `JSON` file that can be used to import the built results.
 
@@ -50,9 +50,9 @@ Declaring Dependencies in a File
 `dependency specifiers <dependency specifier>` as command line arguments, but it
 may be useful to specify those requirements in a file.
 
-``bpt build-deps`` accepts a YAML file describing the dependencies of a project
-as well. The only required property in the file is the ``dependencies`` key.
-(The presence of any other key is an error.)
+``bpt build-deps`` accepts a `YAML` file describing the dependencies of a
+project as well. The only required property in the file is the ``dependencies``
+key. (The presence of any other key is an error.)
 
 Here is a simple dependencies file that declares a single requirement:
 

docs/guide/cmake.rst

@@ -6,7 +6,7 @@ Using |bpt| in a CMake Project
 .. default-role:: term
 
 One of |bpt|'s primary goals is to inter-operate with other build systems
-cleanly. Because of `CMakes <CMake>` ubiquity, |bpt| includes built-in support
+cleanly. Because of `CMake's <CMake>` ubiquity, |bpt| includes built-in support
 for emitting files that can be imported into CMake.
 
 .. seealso::
@@ -51,11 +51,10 @@ Like with |bpt|, CMake wants us to explicitly declare how our build targets
 *use* other libraries. When we ``include()`` the generated CMake file, it will
 generate ``IMPORTED`` targets that can be linked against.
 
-In |bpt| (and in libman), a library is identified by a combination of
-*namespace* and *name*, joined together with a slash ``/`` character. This
-*qualified name* of a library is decided by the original package author, and
-should be documented. In the case of ``neo-sqlite3``, the only library is
-``neo/sqlite3``.
+In |bpt|, a library is identified by a combination of *namespace* and *name*,
+joined together with a slash ``/`` character. This *qualified name* of a library
+is decided by the original package author, and should be documented. In the case
+of ``neo-sqlite3``, the only library is ``neo/sqlite3``.
 
 When the generated import file imports a library, it creates a qualified name
 using a double-colon "``::``" instead of a slash. As such, our ``neo/sqlite3``

docs/guide/deps.rst

@@ -193,6 +193,12 @@ Besides requiring that a candidate for dependency resolution meet the version
 requirements, the candidate must also provide all of the libraries named by the
 :cpp:`using` specifier on the dependency statement.
 
+.. note::
+
+  If you omit the :cpp:`using` specifier, it is equivalent to :cpp:`using` a
+  library with the same name as the package. (This would be the
+  `default library` of the package.)
+
 .. default-role:: math
 
 A Simple Example

docs/guide/terms.rst

@@ -34,6 +34,10 @@ This page documents miscellaneous terminology used throughout |bpt| and `CRS`.
     JSON data cannot contain comments. The order of keys within a JSON object is
     not significant.
 
+  JSON5
+
+    A superset of `JSON` that permits comments, single-quote strings, multi-line
+    strings, trailing commas, and bare identifier keys.
 
   YAML
 

docs/guide/toolchains.rst

@@ -1,4 +1,4 @@
-.. highlight:: js
+.. highlight:: yaml
 .. default-domain:: schematic
 .. default-role:: schematic:prop
 
@@ -37,15 +37,14 @@ effectively in your project.
 Passing a Toolchain
 *******************
 
-In |bpt|, the default format of a toolchain is that of a single JSON5 file
-that describes the entire toolchain. When running a build for a project, the
-|bpt| executable will look in a few locations for a default toolchain, and
+In |bpt|, the default format of a toolchain is that of a single :term:`YAML`
+file that describes the entire toolchain. When running a build for a project,
+the |bpt| executable will look in a few locations for a default toolchain, and
 generate an error if no default toolchain file is found (Refer to
-:ref:`toolchains.default`). A different toolchain can be provided by passing
-the toolchain file for the |--toolchain| (or ``-t``) option on the command
-line::
+:ref:`toolchains.default`). A different toolchain can be provided by passing the
+toolchain file for the |--toolchain| (or ``-t``) option on the command line::
 
-    $ bpt build -t my-toolchain.json5
+    $ bpt build -t my-toolchain.yaml
 
 Alternatively, you can pass the name of a built-in toolchain. See below.
 
@@ -106,16 +105,16 @@ The following directories are searched, in order:
 
 #. ``$pwd/`` - If the working directory contains a toolchain file, it will be
    used as the default.
-#. ``$bpt_config_dir/`` - Searches for a toolchain file in |bpt|'s user-local
+#. ``<bpt_config_dir>/`` - Searches for a toolchain file in |bpt|'s user-local
    configuration directory (see below).
-#. ``$user_home/`` - Searches for a toolchain file at the root of the current
+#. ``<user_home>/`` - Searches for a toolchain file at the root of the current
    user's home directory. (``$HOME`` on Unix-like systems, and ``$PROFILE`` on
    Windows.)
 
-In each directory, it will search for ``toolchain.json5``, ``toolchain.jsonc``,
-or ``toolchain.json``.
+In each directory, it will search for ``toolchain.yaml``, ``toolchain.json5``,
+``toolchain.jsonc``, or ``toolchain.json``.
 
-The ``$bpt_config_dir`` directory is the |bpt| subdirectory of the user-local
+The ``<bpt_config_dir>`` directory is the |bpt| subdirectory of the user-local
 configuration directory.
 
 The user-local config directory is ``$XDG_CONFIG_DIR`` or ``~/.config`` on
@@ -184,14 +183,21 @@ Flags for linking executables can be specified with
     }
 
 
+.. note::
+
+  Command/flag list settings are subject to shell-like string splitting. String
+  splitting can be suppressed by using an array instead of a string. Refer:
+  :ref:`tc-splitting-note`.
+
 .. _toolchains.opt-ref:
 
 Toolchain Option Reference
 **************************
 
+.. _tc-splitting-note:
 
 Understanding Flags and Shell Parsing
--------------------------------------
+=====================================
 
 Many of the |bpt| toolchain parameters accept argument lists or shell-string
 lists. If such an option is given a single string, then that string is split
@@ -217,6 +223,10 @@ Despite splitting strings as-if they were shell commands, |bpt| does nothing
 else shell-like. It does not expand environment variables, nor does it expand
 globs and wildcards.
 
+
+Toolchain Options Schema
+========================
+
 .. mapping:: ToolchainOptions
 
   .. property:: compiler_id
@@ -248,7 +258,7 @@ globs and wildcards.
   .. property:: cxx_compiler
     :optional:
 
-    :type: string
+    :type: :ts:`string`
 
     Names/paths of the C and C++ compilers, respectively.
 
@@ -271,6 +281,8 @@ globs and wildcards.
   .. property:: cxx_version
     :optional:
 
+    :type: :ts:`string`
+
     Specify the language versions for C and C++, respectively. By default, |bpt|
     will not set any language version. Using this option requires that the
     :prop:`~ToolchainOptions.compiler_id` be specified (Or the
@@ -303,6 +315,7 @@ globs and wildcards.
     ``/std:c++latest``. **Beware** that this is an unstable setting value that
     could change the major language version in a future MSVC update.
 
+
   .. property:: warning_flags
     :optional:
 
@@ -323,7 +336,7 @@ globs and wildcards.
 
     .. seealso::
 
-      Refer to :prop:`AdvancedToolchainOptions.base_warning_flags` for more
+      Refer to :prop:`~AdvancedToolchainOptions.base_warning_flags` for more
       information.
 
 
@@ -378,13 +391,13 @@ globs and wildcards.
 
       Generates debug information embedded in the compiled binaries.
 
-    :option split:
+    :option "split":
 
       Generates debug information in a separate file from the compiled binaries.
 
       .. note::
 
-        ``"split"`` with GCC requires that the compiler support the
+        ``"split"`` with GCC/Clang requires that the compiler support the
         ``-gsplit-dwarf`` option.
 
     :option true: Same as :ts:`"embedded"`
@@ -427,7 +440,7 @@ globs and wildcards.
 
     .. note::
 
-      On GNU-like compilers, setting :prop:`ToolchainOptions.runtime.static` to
+      On GNU-like compilers, setting :prop:`~ToolchainOptions.runtime.static` to
       |true| does not generate a static executable: it only statically links the
       runtime and standard library. To generate a static executable, the
       ``-static`` option should be added to ``link_flags``.
@@ -571,10 +584,14 @@ Advanced Options Reference
 
       The placeholder for the output path for the executable file.
 
+    :placeholder [flags]:
+
+      Placeholder for options specified using `~ToolchainOptions.link_flags`.
+
     :default: |default-inferred-from-compiler_id|:
 
       - If |compiler_id| is |msvc|, then
-        ``<cxx_compiler> /nologo /EHsc [in] /Fe[out]``
+        ``<cxx_compiler> /nologo /EHsc [in] /Fe[out] [flags]``
       - If |compiler_id| is |gnu| or |clang|, then
         ``<cxx_compiler> -fPIC [in] -pthread -o[out] [flags]``
       - If |compiler_id| is unset, then this property must be specified.

docs/howto/cmake.rst

@@ -79,13 +79,13 @@ for now.
 The basic signature of the ``pmm(BPT)`` command looks like this::
 
   pmm(BPT [DEP_FILES [filepaths...]]
-          [DEPENDS [dependencies...]]
+          [DEPENDENCIES [dependencies...]]
           [TOOLCHAIN file-or-id])
 
-The most straightforward usage is to use only the ``DEPENDS`` argument. For
+The most straightforward usage is to use only the ``DEPENDENCIES`` argument. For
 example, if we want to import `{fmt} <https://fmt.dev>`_::
 
-  pmm(BPT DEPENDS "[email protected]")
+  pmm(BPT DEPENDENCIES "[email protected]")
 
 When CMake executes the ``pmm(BPT ...)`` line above, PMM will download the
 appropriate |bpt| executable for your platform, generate
@@ -140,7 +140,7 @@ In all, this is our final ``CMakeLists.txt``:
   project(MYApplication VERSION 2.1.3)
 
   include(tools/pmm.cmake)
-  pmm(BPT DEPENDS [email protected])
+  pmm(BPT DEPENDENCIES [email protected])
 
   add_executable(my-application app.cpp)
   target_link_libraries(my-application PRIVATE fmt::fmt)
@@ -153,7 +153,7 @@ Changing Compile Options
 :doc:`toolchains </guide/toolchains>`. PMM supports specifying a toolchain using
 the ``TOOLCHAIN`` argument::
 
-  pmm(BPT DEPENDS [email protected] TOOLCHAIN my-toolchain.json5)
+  pmm(BPT DEPENDENCIES [email protected] TOOLCHAIN my-toolchain.json5)
 
 Of course, writing a separate toolchain file just for your dependencies can be
 tedious. For this reason, PMM will write a toolchain file on-the-fly when it