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

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

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

On Tue 2026-09-22 @ 10:09:41 AM, Antonin Godard wrote:
> 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`/

Agreed on both above.

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

Agreed; this should be the default.

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

*shell* loses the "$" prompt, *console* loses the comment; therefore
*text* is the least wrong... for now. I have a set of lexer patches and
a set of re-tagging patches (neither yet sent) that together fix this.
*text* is not the final answer: it is the right one until those land,
and the best one if they never do.

NOTE: this conventions (v2) page only becomes completely true once the
other patchset (docs-fixes)[1] lands. I was expecting [1] to be
considered first, then conventions-v2.

conventions-v3 is on its way with the above fixes.

> Antonin

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