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

[Trevor Woerner <twoerner@gmail.com>]

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