Re: [docs] [PATCH 03/10] docs: show a prompt on commands the reader is meant to type

[Trevor Woerner <twoerner@gmail.com>]

On Tue 2026-09-22 @ 02:19:59 PM, Antonin Godard wrote:
> Hi,
> 
> On Tue Sep 22, 2026 at 4:03 AM CEST, Trevor Woerner via lists.yoctoproject.org wrote:
> > Most command blocks in the manuals start their lines with "$", but a
> > scattering of them do not, and those read as a file listing rather than
> > as something to run. Give them the prompt the surrounding pages already
> > use.
> >
> > Transcripts take a prompt on their opening line alone. Two things that
> > matter only once a line is a command go with that: a bare "$" at the end,
> > the prompt returning after the command finished, and a trailing "\" on a
> > Windows path, which a shell reads as a continuation into the output.
> >
> > AI-Generated: codex/claude-opus 5 (xhigh)
> > Signed-off-by: Trevor Woerner <twoerner@gmail.com>
> > ---
> >  documentation/brief-yoctoprojectqs/index.rst  |  2 +-
> >  .../contributor-guide/recipe-style-guide.rst  |  2 +-
> >  .../contributor-guide/submit-changes.rst      | 60 +++++++++----------
> >  .../dev-manual/creating-fragments.rst         |  4 +-
> >  documentation/dev-manual/debugging.rst        |  1 -
> >  documentation/dev-manual/devtool.rst          |  8 +--
> >  documentation/dev-manual/disk-space.rst       |  4 +-
> >  documentation/dev-manual/hashequivserver.rst  |  2 +-
> >  .../dev-manual/limiting-resources.rst         |  2 +-
> >  documentation/dev-manual/new-recipe.rst       |  6 +-
> >  documentation/dev-manual/packages.rst         |  2 +-
> >  .../dev-manual/python-development-shell.rst   |  1 -
> >  documentation/dev-manual/qemu.rst             |  8 +--
> >  documentation/dev-manual/start.rst            |  2 +-
> >  documentation/dev-manual/wayland.rst          |  6 +-
> >  documentation/kernel-dev/common.rst           |  3 -
> >  .../migration-guides/migration-2.1.rst        |  4 +-
> >  .../migration-guides/migration-2.5.rst        |  4 +-
> >  .../migration-guides/migration-4.0.rst        |  2 +-
> >  .../migration-guides/migration-5.3.rst        | 10 ++--
> >  .../migration-guides/release-notes-4.2.rst    |  2 +-
> >  .../migration-guides/release-notes-5.3.rst    |  2 +-
> >  documentation/ref-manual/classes.rst          |  8 +--
> >  .../ref-manual/devtool-reference.rst          |  2 -
> >  documentation/ref-manual/fragments.rst        | 16 ++---
> >  documentation/ref-manual/qa-checks.rst        |  4 +-
> >  documentation/ref-manual/variables.rst        |  6 +-
> >  .../test-manual/reproducible-builds.rst       |  2 +-
> >  documentation/test-manual/runtime-testing.rst |  4 +-
> >  29 files changed, 86 insertions(+), 93 deletions(-)
> >
> > diff --git a/documentation/brief-yoctoprojectqs/index.rst b/documentation/brief-yoctoprojectqs/index.rst
> > index f7e4606f1f7b..e138df6c9351 100644
> > --- a/documentation/brief-yoctoprojectqs/index.rst
> > +++ b/documentation/brief-yoctoprojectqs/index.rst
> > @@ -373,7 +373,7 @@ layer>`:
> >  
> >      First, clone the layer next to the other layers::
> >  
> > -      git clone -b &DISTRO_NAME_NO_CAP; https://git.yoctoproject.org/meta-raspberrypi ../layers/meta-raspberrypi
> > +      $ git clone -b &DISTRO_NAME_NO_CAP; https://git.yoctoproject.org/meta-raspberrypi ../layers/meta-raspberrypi
> >  
> >  #.  **Add Your Layer to the Layer Configuration File:** Before you can use
> >      it, you must add the layer and its dependencies to your :ref:`structure-build-conf-bblayers.conf`
> > diff --git a/documentation/contributor-guide/recipe-style-guide.rst b/documentation/contributor-guide/recipe-style-guide.rst
> > index 84c6bb14e8b0..fe12a8e6d826 100644
> > --- a/documentation/contributor-guide/recipe-style-guide.rst
> > +++ b/documentation/contributor-guide/recipe-style-guide.rst
> > @@ -436,7 +436,7 @@ By default, patches created with ``git format-patch`` have a `Git` version signa
> >  To avoid having a `Git` signature at the end of generated or updated patches,
> >  you can use `Git` configuration settings::
> >  
> > -   git config --global format.signature ""
> > +   $ git config --global format.signature ""
> 
> I would take the opportunity to use the "console" lexer here, instead of using
> the default one:
> 
> .. code-block:: console
> 
>    $ git config --global format.signature ""
> 
> Applies to patch 01/10 too, this one, and maybe the other patches.

I am working on a large patchset (which I'm calling "flip") to implement
the decision that was made to set *bitbake* as the default in conf.py
and then tag everything else that is not bitbake. It is big because
around 750 blocks need a label added, on top of the 277 that already
carry one.

The flip will switch these, and others, to *console* or to whatever
each block needs, one patch per manual. I would prefer to keep the two
operations, docs-fixes and flip, separate rather than intermingling them
as I go.

But, before I can send flip, I need to send my "lexers" patchset first
:-)


ideally:
docs-fixes → lexers → flip → conventions (reader and author facing)

I sent the reader-facing conventions page first by mistake; it was my
goal, and I had not realised how much would need fixing before
everything it says is true. Now that it is applied, the page is slightly
ahead of the manuals. It says a line beginning with "#" is a comment,
while kernel-dev still runs "# dmesg | less" as root [1]; and it says
commands are shown with the prompt that runs them, while
recipe-style-guide still has an unprompted "git config --global
format.signature" [2]. Those two patches are what close the gap.

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

> Antonin