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.

Include the new section from every manual, the way the boilerplate is
included, so each is self-contained.

AI-Generated: codex/claude opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
 documentation/brief-yoctoprojectqs/index.rst |  2 +
 documentation/bsp-manual/index.rst           |  2 +
 documentation/contributor-guide/index.rst    |  2 +
 documentation/conventions.rst                | 53 ++++++++++++++++++++
 documentation/dev-manual/index.rst           |  2 +
 documentation/kernel-dev/index.rst           |  2 +
 documentation/migration-guides/index.rst     |  2 +
 documentation/overview-manual/index.rst      |  2 +
 documentation/profile-manual/index.rst       |  2 +
 documentation/ref-manual/index.rst           |  2 +
 documentation/sdk-manual/index.rst           |  2 +
 documentation/security-manual/index.rst      |  2 +
 documentation/security-reference/index.rst   |  2 +
 documentation/test-manual/index.rst          |  2 +
 documentation/toaster-manual/index.rst       |  2 +
 15 files changed, 81 insertions(+)
 create mode 100644 documentation/conventions.rst

Hi,

On Mon Aug 31, 2026 at 5:14 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.
>
> Include the new section from every manual, the way the boilerplate is
> included, so each is self-contained.

We already have a standard.md document that explains these kind of things. I
think it would be more appropriate to add these conventions there.

Thanks,
Antonin

On Mon Aug 31, 2026 at 10:18 AM CEST, Antonin Godard wrote:
> Hi,
>
> On Mon Aug 31, 2026 at 5:14 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.
>>
>> Include the new section from every manual, the way the boilerplate is
>> included, so each is self-contained.
>
> We already have a standard.md document that explains these kind of things.

Sorry, s/standard.md/standards.md/.

Antonin

On Mon 2026-08-31 @ 10:18:42 AM, Antonin Godard wrote:
> Hi,
> 
> On Mon Aug 31, 2026 at 5:14 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.
> >
> > Include the new section from every manual, the way the boilerplate is
> > included, so each is self-contained.
> 
> We already have a standard.md document that explains these kind of things. I
> think it would be more appropriate to add these conventions there.

Oh, that's interesting, and I hadn't thought of that.

You know how, whenever you pick up any programming book, there's a
section (usually in the Preface) that shows you what typeface is used
for code (versus prose), how a "Warning" admonition is drawn? That's
what I'm trying to recreate here. A "conventions used in this document"
section that is *reader* facing.

What you're pointing at is a *contributor* facing document. And it's a
good point, something should probably be mentioned there so that
contributors follow the same conventions throughout; it helps make the
document look like it was written by one person.

But I feel that a reader-facing conventions section is still warranted.

> Thanks,
> Antonin

Hi Trevor,

On 8/31/26 3:32 PM, Trevor Woerner via lists.yoctoproject.org wrote:
> On Mon 2026-08-31 @ 10:18:42 AM, Antonin Godard wrote:
>> Hi,
>>
>> On Mon Aug 31, 2026 at 5:14 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.
>>>
>>> Include the new section from every manual, the way the boilerplate is
>>> included, so each is self-contained.
>>
>> We already have a standard.md document that explains these kind of things. I
>> think it would be more appropriate to add these conventions there.
> 
> Oh, that's interesting, and I hadn't thought of that.
> 
> You know how, whenever you pick up any programming book, there's a
> section (usually in the Preface) that shows you what typeface is used
> for code (versus prose), how a "Warning" admonition is drawn? That's
> what I'm trying to recreate here. A "conventions used in this document"
> section that is *reader* facing.
> 

Fair enough.

> What you're pointing at is a *contributor* facing document. And it's a
> good point, something should probably be mentioned there so that
> contributors follow the same conventions throughout; it helps make the
> document look like it was written by one person.
> 
> But I feel that a reader-facing conventions section is still warranted.
> 

I really think we should aim at removing the prompt for all instructions 
that do not actually require one, that is (in my opinion) anything that 
doesn't include the output of the command. Then there should be less 
confusion around what needs to be pasted or not.

I'm also not entirely sure we follow those conventions currently across 
the docs, so maybe there's some additional work to be done to ensure the 
conventions are actually followed.

Cheers,
Quentin

On Mon 2026-09-14 @ 06:39:59 PM, Quentin Schulz wrote:
> Hi Trevor,
> 
> On 8/31/26 3:32 PM, Trevor Woerner via lists.yoctoproject.org wrote:
> > On Mon 2026-08-31 @ 10:18:42 AM, Antonin Godard wrote:
> > > Hi,
> > > 
> > > On Mon Aug 31, 2026 at 5:14 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.
> > > > 
> > > > Include the new section from every manual, the way the boilerplate is
> > > > included, so each is self-contained.
> > > 
> > > We already have a standard.md document that explains these kind of things. I
> > > think it would be more appropriate to add these conventions there.
> > 
> > Oh, that's interesting, and I hadn't thought of that.
> > 
> > You know how, whenever you pick up any programming book, there's a
> > section (usually in the Preface) that shows you what typeface is used
> > for code (versus prose), how a "Warning" admonition is drawn? That's
> > what I'm trying to recreate here. A "conventions used in this document"
> > section that is *reader* facing.
> > 
> 
> Fair enough.
> 
> > What you're pointing at is a *contributor* facing document. And it's a
> > good point, something should probably be mentioned there so that
> > contributors follow the same conventions throughout; it helps make the
> > document look like it was written by one person.
> > 
> > But I feel that a reader-facing conventions section is still warranted.
> > 
> 
> I really think we should aim at removing the prompt for all instructions
> that do not actually require one, that is (in my opinion) anything that
> doesn't include the output of the command. Then there should be less
> confusion around what needs to be pasted or not.
> 
> I'm also not entirely sure we follow those conventions currently across the
> docs, so maybe there's some additional work to be done to ensure the
> conventions are actually followed.

Currently our docs are a combination of both: some code-blocks use
prompts and some don't (regardless of whether output is included). I
would really like to see consistency across all the docs, and would
happily provide as many commits as are required to see this through.

The steps to achieve that (in my opinion) would be:
- have a standard
- adjust to current docs to that standard
- write down the standard
- try to enforce it on future pull requests knowing full well that...
- ... we'll need regular fixup sweeps to bring everything in line

I would much rather see the docs adopt the convention that all
code-blocks that contain things we expect users to type would start with
a prompt on all lines the user types. The prompt isn't just useless
noise at the start of the command, it clearly delineates between things
that are to be run as a regular user versus things that are to be run as
the superuser. For example while most command on the build machine would
be expected to be run as a regular user, many commands run on a target
are performed as the superuser. The prompts '$' and '#' indicate this
clearly to the reader. Secondly, not all code-block blocks are going to
contain console examples, there are other reasons to use code-block and
the prompt would identify which ones are for console interactions and
which aren't. As you mentioned, some console examples are going to show
both what the user is expected to type as well as the output; having a
prompt clearly shows what are commands to type and what is output. For
the sake of uniformity I would rather not have code-block examples that
have and others that don't have prompts. Why make it more confusing?
Things the reader is to type has prompts, regardless of whether output
is included - simple.

As for the "what to copy" issue. Every code-block has a "copy" symbol
that appears in the code-block when you hover over the code-block. If
the code-block contains things to type with prompts and you click on the
copy icon of a code-block, the commands are copied and the prompts are
not. However, if the user highlights what to copy by clicking and
dragging with the mouse, they will get both the commands as well as the
prompts. However, that is configurable! It is possible to configure any
code-block identified as console to not copy the prompts, even when
clicked-and-dragged with the mouse.

With this adjustment, there is no confusion about what to copy and what
not to copy, because it will not be possible to copy the prompt! And, it
can be configured so that if there is any leading preamble before the
prompts, the preamble is not copied either. So, for example, if your
code-block console session looks like:

	some/directory (user)$ ls

And either the user clicks on the in code-block copy icon or they
click and drag with the mouse, all they will copy is the "ls" and
nothing before it.

Having a "how to use this document" section would explain and codify it
into our standards, as well as having an author-facing document that
would give this as an expectation. Review would then be performed
against these documents for consistency.

> Cheers,
> Quentin

On Sat 2026-09-19 @ 02:17:17 AM, Trevor Woerner via lists.yoctoproject.org wrote:
> On Mon 2026-09-14 @ 06:39:59 PM, Quentin Schulz wrote:
> > Hi Trevor,
> > 
> > On 8/31/26 3:32 PM, Trevor Woerner via lists.yoctoproject.org wrote:
> > > On Mon 2026-08-31 @ 10:18:42 AM, Antonin Godard wrote:
> > > > Hi,
> > > > 
> > > > On Mon Aug 31, 2026 at 5:14 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.
> > > > > 
> > > > > Include the new section from every manual, the way the boilerplate is
> > > > > included, so each is self-contained.
> > > > 
> > > > We already have a standard.md document that explains these kind of things. I
> > > > think it would be more appropriate to add these conventions there.
> > > 
> > > Oh, that's interesting, and I hadn't thought of that.
> > > 
> > > You know how, whenever you pick up any programming book, there's a
> > > section (usually in the Preface) that shows you what typeface is used
> > > for code (versus prose), how a "Warning" admonition is drawn? That's
> > > what I'm trying to recreate here. A "conventions used in this document"
> > > section that is *reader* facing.
> > > 
> > 
> > Fair enough.
> > 
> > > What you're pointing at is a *contributor* facing document. And it's a
> > > good point, something should probably be mentioned there so that
> > > contributors follow the same conventions throughout; it helps make the
> > > document look like it was written by one person.
> > > 
> > > But I feel that a reader-facing conventions section is still warranted.
> > > 
> > 
> > I really think we should aim at removing the prompt for all instructions
> > that do not actually require one, that is (in my opinion) anything that
> > doesn't include the output of the command. Then there should be less
> > confusion around what needs to be pasted or not.
> > 
> > I'm also not entirely sure we follow those conventions currently across the
> > docs, so maybe there's some additional work to be done to ensure the
> > conventions are actually followed.
> 
> Currently our docs are a combination of both: some code-blocks use
> prompts and some don't (regardless of whether output is included).

It looks like, across all of the Yocto docs, there are roughly 705
code-blocks that record command-line interactions describing to the
reader what they need to do on the cmdline (aka command blocks).

Of those 705, 631 already carry a prompt, versus at least 74 that don't.
The convention is already in place, we shouldn't be rehashing a decision
that has already been made.

The only things not already in place are the "how to use this document"
preface I'm proposing, the author-facing material naming the convention,
and fixes for the 74 stragglers.

> I
> would really like to see consistency across all the docs, and would
> happily provide as many commits as are required to see this through.
> 
> The steps to achieve that (in my opinion) would be:
> - have a standard
> - adjust to current docs to that standard
> - write down the standard
> - try to enforce it on future pull requests knowing full well that...
> - ... we'll need regular fixup sweeps to bring everything in line
> 
> I would much rather see the docs adopt the convention that all
> code-blocks that contain things we expect users to type would start with
> a prompt on all lines the user types. The prompt isn't just useless
> noise at the start of the command, it clearly delineates between things
> that are to be run as a regular user versus things that are to be run as
> the superuser. For example while most command on the build machine would
> be expected to be run as a regular user, many commands run on a target
> are performed as the superuser. The prompts '$' and '#' indicate this
> clearly to the reader. Secondly, not all code-block blocks are going to
> contain console examples, there are other reasons to use code-block and
> the prompt would identify which ones are for console interactions and
> which aren't. As you mentioned, some console examples are going to show
> both what the user is expected to type as well as the output; having a
> prompt clearly shows what are commands to type and what is output. For
> the sake of uniformity I would rather not have code-block examples that
> have and others that don't have prompts. Why make it more confusing?
> Things the reader is to type has prompts, regardless of whether output
> is included - simple.
> 
> As for the "what to copy" issue. Every code-block has a "copy" symbol
> that appears in the code-block when you hover over the code-block. If
> the code-block contains things to type with prompts and you click on the
> copy icon of a code-block, the commands are copied and the prompts are
> not. However, if the user highlights what to copy by clicking and
> dragging with the mouse, they will get both the commands as well as the
> prompts. However, that is configurable! It is possible to configure any
> code-block identified as console to not copy the prompts, even when
> clicked-and-dragged with the mouse.
> 
> With this adjustment, there is no confusion about what to copy and what
> not to copy, because it will not be possible to copy the prompt! And, it
> can be configured so that if there is any leading preamble before the
> prompts, the preamble is not copied either. So, for example, if your
> code-block console session looks like:
> 
> 	some/directory (user)$ ls
> 
> And either the user clicks on the in code-block copy icon or they
> click and drag with the mouse, all they will copy is the "ls" and
> nothing before it.
> 
> Having a "how to use this document" section would explain and codify it
> into our standards, as well as having an author-facing document that
> would give this as an expectation. Review would then be performed
> against these documents for consistency.
> 
> > Cheers,
> > Quentin

> 
> -=-=-=-=-=-=-=-=-=-=-=-
> Links: You receive all messages sent to this group.
> View/Reply Online (#10553): https://lists.yoctoproject.org/g/docs/message/10553
> Mute This Topic: https://lists.yoctoproject.org/mt/121008467/900817
> Group Owner: docs+owner@lists.yoctoproject.org
> Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [twoerner@gmail.com]
> -=-=-=-=-=-=-=-=-=-=-=-
>

Hi,

On Sat Sep 19, 2026 at 8:17 AM CEST, Trevor Woerner wrote:
> On Mon 2026-09-14 @ 06:39:59 PM, Quentin Schulz wrote:
[...]
> having a
> prompt clearly shows what are commands to type and what is output. For
> the sake of uniformity I would rather not have code-block examples that
> have and others that don't have prompts.

I agree.

>
> As for the "what to copy" issue. Every code-block has a "copy" symbol
> that appears in the code-block when you hover over the code-block. If
> the code-block contains things to type with prompts and you click on the
> copy icon of a code-block, the commands are copied and the prompts are
> not. However, if the user highlights what to copy by clicking and
> dragging with the mouse, they will get both the commands as well as the
> prompts. However, that is configurable! It is possible to configure any
> code-block identified as console to not copy the prompts, even when
> clicked-and-dragged with the mouse.

Do you have a working solution for this?

[...]
> Having a "how to use this document" section would explain and codify it
> into our standards, as well as having an author-facing document that
> would give this as an expectation. Review would then be performed
> against these documents for consistency.

Rather than having a document included everywhere, I would rather have a
dedicated section for it in the docs so it is less invasive . It appears in the
sidebar, so a user always sees it too (for HTML docs).

Here's what I have in mind (note the shorter title so it fits in the sidebar):

diff --git a/documentation/index.rst b/documentation/index.rst
index 4bfc40bef..72e51a445 100644
--- a/documentation/index.rst
+++ b/documentation/index.rst
@@ -116,3 +116,10 @@ Release notes and migration guides for the different Yocto Project releases.
    :hidden:
 
    downloads
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Documentation Conventions
+   :hidden:
+
+   conventions
diff --git a/documentation/conventions.rst b/documentation/conventions.rst
new file mode 100644
index 000000000..65061d1a9
--- /dev/null
+++ b/documentation/conventions.rst
@@ -0,0 +1,18 @@
+=========================
+Documentation Conventions
+=========================
+
+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.
+
+...

Thanks,
Antonin

On Mon 2026-09-21 @ 04:34:35 PM, Antonin Godard wrote:
> Hi,
> 
> On Sat Sep 19, 2026 at 8:17 AM CEST, Trevor Woerner wrote:
> > On Mon 2026-09-14 @ 06:39:59 PM, Quentin Schulz wrote:
> [...]
> > having a
> > prompt clearly shows what are commands to type and what is output. For
> > the sake of uniformity I would rather not have code-block examples that
> > have and others that don't have prompts.
> 
> I agree.
> 
> >
> > As for the "what to copy" issue. Every code-block has a "copy" symbol
> > that appears in the code-block when you hover over the code-block. If
> > the code-block contains things to type with prompts and you click on the
> > copy icon of a code-block, the commands are copied and the prompts are
> > not. However, if the user highlights what to copy by clicking and
> > dragging with the mouse, they will get both the commands as well as the
> > prompts. However, that is configurable! It is possible to configure any
> > code-block identified as console to not copy the prompts, even when
> > clicked-and-dragged with the mouse.
> 
> Do you have a working solution for this?

Yes (to follow).

> [...]
> > Having a "how to use this document" section would explain and codify it
> > into our standards, as well as having an author-facing document that
> > would give this as an expectation. Review would then be performed
> > against these documents for consistency.
> 
> Rather than having a document included everywhere, I would rather have a
> dedicated section for it in the docs so it is less invasive . It appears in the
> sidebar, so a user always sees it too (for HTML docs).

That works for me; I have a v2 prepared.

> Here's what I have in mind (note the shorter title so it fits in the sidebar):
> 
> diff --git a/documentation/index.rst b/documentation/index.rst
> index 4bfc40bef..72e51a445 100644
> --- a/documentation/index.rst
> +++ b/documentation/index.rst
> @@ -116,3 +116,10 @@ Release notes and migration guides for the different Yocto Project releases.
>     :hidden:
>  
>     downloads
> +
> +.. toctree::
> +   :maxdepth: 1
> +   :caption: Documentation Conventions
> +   :hidden:
> +
> +   conventions
> diff --git a/documentation/conventions.rst b/documentation/conventions.rst
> new file mode 100644
> index 000000000..65061d1a9
> --- /dev/null
> +++ b/documentation/conventions.rst
> @@ -0,0 +1,18 @@
> +=========================
> +Documentation Conventions
> +=========================
> +
> +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.
> +
> +...
> 
> Thanks,
> Antonin