[PATCH] docs: document the conventions used in the manuals

[Trevor Woerner <twoerner@gmail.com>]

The manuals use angle brackets for placeholders and a prompt to mark a
command, and say so nowhere. A reader can only infer both, and one
example reads as advice to paste a line that will not parse.

Include the new section from every manual, the way the boilerplate is
included, so each is self-contained.

AI-Generated: codex/claude opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
 documentation/brief-yoctoprojectqs/index.rst |  2 +
 documentation/bsp-manual/index.rst           |  2 +
 documentation/contributor-guide/index.rst    |  2 +
 documentation/conventions.rst                | 53 ++++++++++++++++++++
 documentation/dev-manual/index.rst           |  2 +
 documentation/kernel-dev/index.rst           |  2 +
 documentation/migration-guides/index.rst     |  2 +
 documentation/overview-manual/index.rst      |  2 +
 documentation/profile-manual/index.rst       |  2 +
 documentation/ref-manual/index.rst           |  2 +
 documentation/sdk-manual/index.rst           |  2 +
 documentation/security-manual/index.rst      |  2 +
 documentation/security-reference/index.rst   |  2 +
 documentation/test-manual/index.rst          |  2 +
 documentation/toaster-manual/index.rst       |  2 +
 15 files changed, 81 insertions(+)
 create mode 100644 documentation/conventions.rst

diff --git a/documentation/brief-yoctoprojectqs/index.rst b/documentation/brief-yoctoprojectqs/index.rst
index 4adec9714f2f..6c0e56d9660c 100644
--- a/documentation/brief-yoctoprojectqs/index.rst
+++ b/documentation/brief-yoctoprojectqs/index.rst
@@ -502,4 +502,6 @@ information including the website, wiki pages, and user manuals:
    section in the Yocto Project Reference Manual provides a
    comprehensive list of all related links and other user documentation.
 
+.. include:: /conventions.rst
+
 .. include:: /boilerplate.rst
diff --git a/documentation/bsp-manual/index.rst b/documentation/bsp-manual/index.rst
index 37469184e269..4229730080da 100644
--- a/documentation/bsp-manual/index.rst
+++ b/documentation/bsp-manual/index.rst
@@ -12,4 +12,6 @@ Yocto Project Board Support Package (BSP) Manual
 
    bsp
 
+.. include:: /conventions.rst
+
 .. include:: /boilerplate.rst
diff --git a/documentation/contributor-guide/index.rst b/documentation/contributor-guide/index.rst
index b374cc1c43ec..39104259785b 100644
--- a/documentation/contributor-guide/index.rst
+++ b/documentation/contributor-guide/index.rst
@@ -23,4 +23,6 @@ this.
    recipe-style-guide
    submit-changes
 
+.. include:: /conventions.rst
+
 .. include:: /boilerplate.rst
diff --git a/documentation/conventions.rst b/documentation/conventions.rst
new file mode 100644
index 000000000000..ab020113d046
--- /dev/null
+++ b/documentation/conventions.rst
@@ -0,0 +1,53 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+=================================
+Conventions used in this document
+=================================
+
+Placeholders
+============
+
+Text enclosed in angle brackets is a placeholder. Replace it, including the
+brackets, with a value of your own:
+
+.. code-block:: none
+
+   SRCREV:pn-<recipe> = "${AUTOREV}"
+
+Here, ``<recipe>`` stands for the name of your recipe. A placeholder is
+never text to be copied as it stands, and an example containing one will
+not work until every placeholder in it has been replaced.
+
+Commands and prompts
+====================
+
+Commands are shown with the prompt that runs them, and the prompt is not
+part of the command. Do not type it.
+
+A ``$`` introduces a command you run as your normal user:
+
+.. code-block:: console
+
+   $ bitbake core-image-minimal
+
+Where a command needs administrative privileges on your build host, it is
+shown with ``sudo`` rather than with a root prompt:
+
+.. code-block:: console
+
+   $ sudo apt install gawk
+
+A full prompt ending in ``#`` introduces a command run as ``root``, usually
+on a target machine rather than on your build host:
+
+.. code-block:: console
+
+   root@qemux86-64:~# gdb /bin/cat
+
+Within an example, a line beginning with ``#`` is a comment rather than a
+command:
+
+.. code-block:: console
+
+   # This is a comment, not a command to run as root.
+   $ bitbake core-image-minimal
diff --git a/documentation/dev-manual/index.rst b/documentation/dev-manual/index.rst
index 0e1aa89586d6..2a405b418f0c 100644
--- a/documentation/dev-manual/index.rst
+++ b/documentation/dev-manual/index.rst
@@ -52,4 +52,6 @@ Yocto Project Development Tasks Manual
    sstate-mirrors-setup
    hashequivserver
 
+.. include:: /conventions.rst
+
 .. include:: /boilerplate.rst
diff --git a/documentation/kernel-dev/index.rst b/documentation/kernel-dev/index.rst
index bd20e371e0c2..8a0e104dc4f9 100644
--- a/documentation/kernel-dev/index.rst
+++ b/documentation/kernel-dev/index.rst
@@ -17,4 +17,6 @@ Yocto Project Linux Kernel Development Manual
    maint-appx
    faq
 
+.. include:: /conventions.rst
+
 .. include:: /boilerplate.rst
diff --git a/documentation/migration-guides/index.rst b/documentation/migration-guides/index.rst
index e53215c73b6e..1a7058949b03 100644
--- a/documentation/migration-guides/index.rst
+++ b/documentation/migration-guides/index.rst
@@ -42,4 +42,6 @@ to move to one release of the Yocto Project from the previous one.
    migration-1.4
    migration-1.3
 
+.. include:: /conventions.rst
+
 .. include:: /boilerplate.rst
diff --git a/documentation/overview-manual/index.rst b/documentation/overview-manual/index.rst
index 0061d1a1807d..3b8aa28f0353 100644
--- a/documentation/overview-manual/index.rst
+++ b/documentation/overview-manual/index.rst
@@ -70,4 +70,6 @@ For a comprehensive list of links and other documentation, see the
 Documentation <resources-links-and-related-documentation>`"
 section in the Yocto Project Reference Manual.
 
+.. include:: /conventions.rst
+
 .. include:: /boilerplate.rst
diff --git a/documentation/profile-manual/index.rst b/documentation/profile-manual/index.rst
index 0270932ca0b1..53a87d7bf0bd 100644
--- a/documentation/profile-manual/index.rst
+++ b/documentation/profile-manual/index.rst
@@ -15,4 +15,6 @@ Yocto Project Profiling and Tracing Manual
    usage
    examples
 
+.. include:: /conventions.rst
+
 .. include:: /boilerplate.rst
diff --git a/documentation/ref-manual/index.rst b/documentation/ref-manual/index.rst
index aa1a63e0500b..6b44bb461a80 100644
--- a/documentation/ref-manual/index.rst
+++ b/documentation/ref-manual/index.rst
@@ -28,4 +28,6 @@ Yocto Project Reference Manual
    faq
    resources
 
+.. include:: /conventions.rst
+
 .. include:: /boilerplate.rst
diff --git a/documentation/sdk-manual/index.rst b/documentation/sdk-manual/index.rst
index a5c35cabaed1..d893ec8ed402 100644
--- a/documentation/sdk-manual/index.rst
+++ b/documentation/sdk-manual/index.rst
@@ -18,4 +18,6 @@ Yocto Project Application Development and Software Development Kits (SDK/eSDK) M
    appendix-customizing
    appendix-customizing-standard
 
+.. include:: /conventions.rst
+
 .. include:: /boilerplate.rst
diff --git a/documentation/security-manual/index.rst b/documentation/security-manual/index.rst
index ab1ef445c86c..39ad0ee7a8c1 100644
--- a/documentation/security-manual/index.rst
+++ b/documentation/security-manual/index.rst
@@ -17,5 +17,7 @@ Yocto Project Security Manual
    read-only-rootfs
    sstate-signing
 
+.. include:: /conventions.rst
+
 .. include:: /boilerplate.rst
 
diff --git a/documentation/security-reference/index.rst b/documentation/security-reference/index.rst
index c20a54d1a931..f9b0f0d73777 100644
--- a/documentation/security-reference/index.rst
+++ b/documentation/security-reference/index.rst
@@ -11,4 +11,6 @@ Yocto Project Security Reference
    security-team
    reporting-vulnerabilities
 
+.. include:: /conventions.rst
+
 .. include:: /boilerplate.rst
diff --git a/documentation/test-manual/index.rst b/documentation/test-manual/index.rst
index d365d337ea5b..8f7f9e49a2cc 100644
--- a/documentation/test-manual/index.rst
+++ b/documentation/test-manual/index.rst
@@ -18,4 +18,6 @@ Yocto Project Test Environment Manual
    reproducible-builds
    yocto-project-compatible
 
+.. include:: /conventions.rst
+
 .. include:: /boilerplate.rst
diff --git a/documentation/toaster-manual/index.rst b/documentation/toaster-manual/index.rst
index 3ff4c6913aa4..ca2c38834bbc 100644
--- a/documentation/toaster-manual/index.rst
+++ b/documentation/toaster-manual/index.rst
@@ -15,4 +15,6 @@ Toaster User Manual
    setup-and-use
    reference
 
+.. include:: /conventions.rst
+
 .. include:: /boilerplate.rst
-- 
2.50.0.173.g8b6f19ccfc3a