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

[Trevor Woerner <twoerner@gmail.com>]

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]
> -=-=-=-=-=-=-=-=-=-=-=-
>