new file mode 100644
@@ -0,0 +1,36 @@
+.. SPDX-License-Identifier: CC-BY-2.5
+
+=========================
+Documentation Conventions
+=========================
+
+These conventions apply throughout this manual.
+
+Placeholders
+============
+
+Text enclosed in angle brackets is a placeholder. Replace it, including the
+brackets, with a value of your own:
+
+.. code-block:: console
+
+ $ tail -F tmp/log/cooker/<machine>/console-latest.log
+
+Here, ``<machine>`` stands for the machine you are building for. 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
+========
+
+A command you run at a shell is shown with the ``$`` prompt that runs it.
+The prompt is not part of the command; do not type it:
+
+.. code-block:: console
+
+ $ bitbake -c clean foo
+
+Where a command is shown with its output, the prompt is what separates the
+two: the prompted line is what you type and the rest is what BitBake
+printed.
@@ -27,6 +27,13 @@ BitBake User Manual
genindex
releases
+.. toctree::
+ :maxdepth: 1
+ :caption: Documentation Conventions
+ :hidden:
+
+ conventions
+
----
.. include:: <xhtml1-lat1.txt>
The manual uses angle brackets for placeholders and a prompt to mark a command, and says so nowhere. A reader can only infer both. Add a page stating them, in the sidebar beside the other top-level entries, so it is reachable from any page of the manual. AI-Generated: codex/claude-opus 5 (xhigh) Signed-off-by: Trevor Woerner <twoerner@gmail.com> --- Applies to: bitbake, on top of master. Paths under doc/. Destination: bitbake-devel@lists.openembedded.org In reply to: <20260831031444.4070152-1-twoerner@gmail.com> Changes in v2: - The page is a document in its own right, reached from a toctree in doc/index.rst, rather than included at the foot of the main page. That was the part you objected to, and the sidebar entry means a reader meets it from any page rather than only from the front one. - Retitled "Documentation Conventions", short enough for the sidebar. - The examples are the manual's own. v1 shared a file with the yocto-docs patch and so illustrated itself with core-image-minimal, "sudo apt install gawk" and a root prompt on a qemux86-64 target, none of which this manual contains or is about. The placeholder example is now the <machine> already used in BB_PRESSURE_MAX_* , and the command example is a bitbake invocation. - The root prompt and sudo sections are gone. Measured over the manual: every console block prompts with "$", there are no root prompts at all, and "sudo" appears once. Documenting a convention the manual does not use is what "not related to BitBake itself" looked like in practice. doc/conventions.rst | 36 ++++++++++++++++++++++++++++++++++++ doc/index.rst | 7 +++++++ 2 files changed, 43 insertions(+) create mode 100644 doc/conventions.rst