[PATCH] doc: document the conventions used in the manual

[Trevor Woerner <twoerner@gmail.com>]

The manual uses angle brackets for placeholders and a prompt to mark a
command, and says so nowhere. A reader can only infer both.

AI-Generated: codex/claude opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
 doc/conventions.rst | 53 +++++++++++++++++++++++++++++++++++++++++++++
 doc/index.rst       |  2 ++
 2 files changed, 55 insertions(+)
 create mode 100644 doc/conventions.rst

diff --git a/doc/conventions.rst b/doc/conventions.rst
new file mode 100644
index 000000000000..ab020113d046
--- /dev/null
+++ b/doc/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/doc/index.rst b/doc/index.rst
index 9f2a9067d385..d9547e1c723d 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -29,6 +29,8 @@ BitBake User Manual
 
 ----
 
+.. include:: /conventions.rst
+
 .. include:: <xhtml1-lat1.txt>
 
 | BitBake Community
-- 
2.50.0.173.g8b6f19ccfc3a