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

[PATCH v2] 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.

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

diff --git a/doc/conventions.rst b/doc/conventions.rst
new file mode 100644
index 000000000000..a10795d456b3
--- /dev/null
+++ b/doc/conventions.rst
@@ -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.
diff --git a/doc/index.rst b/doc/index.rst
index 9f2a9067d385..0a2bd9ce2ecf 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -27,6 +27,13 @@ BitBake User Manual
    genindex
    releases
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Documentation Conventions
+   :hidden:
+
+   conventions
+
 ----
 
 .. include:: <xhtml1-lat1.txt>
-- 
2.50.0.173.g8b6f19ccfc3a

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

[Antonin Godard]

On Tue Sep 22, 2026 at 3:55 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.
>
> Add a page stating them, in the sidebar beside the other top-level
> entries, so it is reachable from any page of the manual.

A similar patch was sent to yocto-docs[1]. Let's hold off this one until the
definitive version in yocto-docs is merged, please.

[1]: https://lore.kernel.org/r/20260922013912.55583-1-twoerner@gmail.com

Thanks,
Antonin