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

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

[Trevor Woerner]

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

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

[Antonin Godard]

Hi,

On Mon Aug 31, 2026 at 5:14 AM CEST, Trevor Woerner via lists.yoctoproject.org wrote:
> The manual uses angle brackets for placeholders and a prompt to mark a
> command, and says so nowhere. A reader can only infer both.

This only adds the document at the bottom of the main page, which I don't think
is a proper place for it. We should either have a section dedicated to this, or
make this a separate document (similar to standards.md in yocto-docs).

I'm leaning towards a separate document (named "standards.md"?), because these
instructions are not related to Bitbake itself. This document should be easily
found though, so perhaps we should mention it in the main README, under the
Contributing section.

Thanks,
Antonin