[PATCH v3 00/10] docs: editorial repairs to the examples

[Trevor Woerner <twoerner@gmail.com>]

These are repairs to the examples themselves. No block is given a
language and no block changes how it is highlighted; what changes is the
text of the examples. Each commit stands on its own: a reader is better
served by every one of them whether or not anything else in this area
lands.

They also clear the way for a later series that states the language of
each code block. A block cannot say it is a console session without a
prompt, or C with a bare "..." in place of the code it omits, or anything
at all while it holds more than one file under a single "::". These
remove exactly those obstacles.

  1. a preamble on the root prompts written as a bare "#", which the
     rest already carry
  2. the copy button reduced to the command, for every prompt shape
     rather than just "$ "
  3. a prompt on the command blocks the prose says to run, and on
     transcripts only the opening line, plus dropping the bare trailing
     "$" a returning prompt leaves behind
  4. elided code written as a comment in the language around it
  5. placeholders the reader must replace put in angle brackets
  6. real accounts and home directories replaced with /home/user
  7. kernel metadata examples split so each block holds one file, with
     the filename moved to the block's caption
  8. the ARCHIVER_MODE varflag examples given comments BitBake can parse,
     since a "#" after a value is not an inline comment
  9. "partition" dropped as a wic kickstart command; wic has rejected it
     since the pykickstart parser was replaced in 2016
 10. a list continuation indented, so its "::" stops swallowing the
     paragraph and the note beneath it

The first three are related, and the third has been under discussion.
The great majority of command blocks already carry a prompt, so patch 3
finishes a convention rather than proposing one, and patches 1 and 2
remove the cost that convention imposes on a reader.

A command run on the target takes the full user@machine:path prompt,
mirroring the root prompt beside it, and one run on the build host takes
a bare "$" unless its working directory is part of the instruction. The
copy button and a mouse selection already handle both forms, so which
prompt a block carries does not change what copying it gives you.

Patch 2 is the substance: copybutton_prompt_text was the literal "$ ",
so on a block prompted any other way nothing matched, and sphinx-
copybutton then falls back to copying every line, prompt, and output
alike. That took in the root prompts, the Windows sessions in
dev-manual/start.rst, and the pydevshell session, so the pattern now
names each prompt shape the manuals use. A mouse selection is left
alone, so it still takes the output; that is deliberate, and was your
call on the v1 thread.

Patch 1 comes first because patch 2 treats "#" as a prompt only when a
preamble precedes it. That is not a shortcut: a bare "#" opens a root
prompt, a comment, and a line of program output alike, and the manuals
use it for output and for comments far more often than for a prompt.
Giving the stragglers the preamble the rest already use makes the rule
true rather than approximate.

Every commit builds with zero warnings under -W, which is the Makefile
default, and each was built on its own rather than only at the tip.
sphinx-lint over the touched files is unchanged from master-next.
changes in v3:
 - patches 9 and 10 are back. You applied them on 2026-09-22 and the
   master-next rewind of 2026-09-23 took them out again, so they are
   unapplied; re-sending rather than risk losing them
 - patch 1 also prompts the kernel-dev "make scripts" block Quentin
   spotted
 - patch 2's comment is a third of the length and no longer contradicts
   itself about scope, and a ">>> " alternative covers the one Python
   interpreter example
 - patch 2 gains a "(gdb) " alternative. The console lexer already marks
   that prompt, so a selection skipped it while the button copied it;
   the two now agree on the one block where they still differed
 - patch 3 prompts the weston block, which had none, and gives the
   commands run on the target the full user@machine:path prompt rather
   than a bare "$"
 - patch 5 leaves the DMARC From: header alone. Nothing in it is for the
   reader to replace, so it needed neither a placeholder nor anonymising
 - patch 5 writes the git config name as <firstname> <lastname>, and
   says the SRCREV values are commit SHAs
 - patch 6 leaves the prompt on the setup-layers example. Its command is
   a relative path, so the working directory in the prompt is what says
   where it runs
 - patch 8 separates each comment from the setting above it

changes in v2:
 - rebased on master-next, which is where it now applies; the one
   conflict was the ARCHIVER_MODE block, where d5216e3fd4be had already
   removed the srpm varflag
 - patch 2 no longer touches the stylesheet: a mouse selection keeps the
   output, and only the copy button is changed
 - patch 7 takes the theme's whole font stack for the caption
 - patch 1 uses a generic root@machine prompt where the surrounding text
   names no board

Signed-off-by: Trevor Woerner <twoerner@gmail.com>

Trevor Woerner (10):
  docs: give the root prompts a preamble
  docs: copy only the command from a console block
  docs: show a prompt on commands the reader is meant to type
  docs: write an elided passage as a comment
  docs: mark the placeholders in examples
  docs: remove real accounts from the examples
  kernel-dev: give each example block one thing to hold
  ref-manual: put the ARCHIVER_MODE comments on their own lines
  ref-manual: drop "partition" as a wic kickstart command
  dev-manual: indent a list continuation so the code block ends

 documentation/brief-yoctoprojectqs/index.rst  |   2 +-
 documentation/bsp-manual/bsp.rst              |   4 +-
 documentation/conf.py                         |  19 ++-
 .../contributor-guide/recipe-style-guide.rst  |   2 +-
 .../contributor-guide/submit-changes.rst      |  63 ++++----
 .../dev-manual/creating-fragments.rst         |   4 +-
 documentation/dev-manual/debugging.rst        |  13 +-
 documentation/dev-manual/devtool.rst          |   8 +-
 documentation/dev-manual/disk-space.rst       |   4 +-
 documentation/dev-manual/hashequivserver.rst  |   2 +-
 documentation/dev-manual/layers.rst           |  10 +-
 .../dev-manual/limiting-resources.rst         |   2 +-
 documentation/dev-manual/new-recipe.rst       |   6 +-
 documentation/dev-manual/packages.rst         |   4 +-
 .../dev-manual/python-development-shell.rst   |   1 -
 documentation/dev-manual/qemu.rst             |  10 +-
 documentation/dev-manual/start.rst            |   2 +-
 .../dev-manual/upgrading-recipes.rst          |  18 +--
 documentation/dev-manual/wayland.rst          |   8 +-
 documentation/dev-manual/wic.rst              |  44 +++---
 documentation/kernel-dev/advanced.rst         | 139 ++++++++++--------
 documentation/kernel-dev/common.rst           |  41 +++---
 .../migration-guides/migration-2.1.rst        |   4 +-
 .../migration-guides/migration-2.5.rst        |   4 +-
 .../migration-guides/migration-3.2.rst        |   2 +-
 .../migration-guides/migration-4.0.rst        |   2 +-
 .../migration-guides/migration-5.2.rst        |  16 +-
 .../migration-guides/migration-5.3.rst        |  10 +-
 .../migration-guides/release-notes-4.2.rst    |   2 +-
 .../migration-guides/release-notes-5.3.rst    |   2 +-
 documentation/overview-manual/concepts.rst    |   2 +-
 documentation/profile-manual/usage.rst        |   4 +-
 documentation/ref-manual/classes.rst          |   8 +-
 .../ref-manual/devtool-reference.rst          |  10 +-
 documentation/ref-manual/faq.rst              |   6 +-
 documentation/ref-manual/fragments.rst        |  16 +-
 documentation/ref-manual/kickstart.rst        |   9 +-
 documentation/ref-manual/qa-checks.rst        |   4 +-
 documentation/ref-manual/variables.rst        |  43 ++++--
 documentation/sdk-manual/extensible.rst       |   6 +-
 .../sphinx-static/theme_overrides.css         |  28 ++++
 .../test-manual/reproducible-builds.rst       |   2 +-
 documentation/test-manual/runtime-testing.rst |   4 +-
 43 files changed, 326 insertions(+), 264 deletions(-)

-- 
2.50.0.173.g8b6f19ccfc3a