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

["Antonin Godard" <antonin.godard@bootlin.com>]

On Tue Sep 22, 2026 at 3:39 AM CEST, Trevor Woerner via lists.yoctoproject.org wrote:
> 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.
>
> Add a page stating them, in the sidebar beside the other top-level
> entries, so it is reachable from every manual.
>
> AI-Generated: codex/claude-opus 5 (xhigh)
> Signed-off-by: Trevor Woerner <twoerner@gmail.com>
> ---
> Changes in v2:
> - The page is a document in its own right, reached from a toctree in
>   documentation/index.rst, rather than included into each manual's index.
>   This is Antonin's suggestion and it is the better shape: the page
>   appears in the sidebar of every manual, so a reader meets it wherever
>   they are, and the diff touches two files rather than fifteen.
> - Retitled "Documentation Conventions", which is short enough for the
>   sidebar and matches "Documentation Downloads" beside it. The old title
>   said "this document", which no longer describes a standalone page.
> - The example showing that a leading "#" is a comment is tagged text
>   rather than console. Pygments' console lexer reads a leading "#" as a
>   root prompt and lexes the rest of the line as bash, so v1 rendered that
>   line as a prompt running a command, with the word "command" coloured as
>   a shell builtin - the opposite of what the sentence above it says.
> - Added an opening sentence saying the conventions apply throughout the
>   documentation, since the page is now landed on directly rather than
>   read at the end of a manual.
>
> The wording of both sections is unchanged.
>
>  documentation/conventions.rst | 55 +++++++++++++++++++++++++++++++++++
>  documentation/index.rst       |  7 +++++
>  2 files changed, 62 insertions(+)
>  create mode 100644 documentation/conventions.rst
>
> diff --git a/documentation/conventions.rst b/documentation/conventions.rst
> new file mode 100644
> index 000000000000..469ad5879b51
> --- /dev/null
> +++ b/documentation/conventions.rst
> @@ -0,0 +1,55 @@
> +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
> +
> +=========================
> +Documentation Conventions
> +=========================
> +
> +These conventions apply throughout the Yocto Project documentation.
> +
> +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

s/build host/:term:`build host`/

> +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:

s/build host/:term:`build host`/

> +.. code-block:: console
> +
> +   root@qemux86-64:~# gdb /bin/cat

How about "root@machine:~# " instead? I would rather have a generic machine to
use throughout the documentation than a real example. Unless the context in
which the documentation is written makes sense for a specific machine, of
course. But we should at least have a default name for generic target command
examples.

> +
> +Within an example, a line beginning with ``#`` is a comment rather than a
> +command:
> +
> +.. code-block:: text

Sadly the "console" lexer does not interpret lines starting with "# " as
comments. Would it make sense to use the "shell" lexer instead, in these cases
where commands and comments are mixed?

Antonin