[PATCH 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 and a mouse selection both 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 and a
     bare "$"
  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.

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. Selection had the opposite defect: it
took the output along with the commands, which the button never did.

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 origin/master.

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                         |  21 ++-
 .../contributor-guide/recipe-style-guide.rst  |   2 +-
 .../contributor-guide/submit-changes.rst      |  62 ++++----
 .../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           |  12 +-
 .../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          |   6 +-
 documentation/dev-manual/wic.rst              |  44 +++---
 documentation/kernel-dev/advanced.rst         | 139 ++++++++++--------
 documentation/kernel-dev/common.rst           |  37 +++--
 .../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        |  40 +++--
 documentation/sdk-manual/extensible.rst       |   6 +-
 .../sphinx-static/theme_overrides.css         |  36 +++++
 .../test-manual/reproducible-builds.rst       |   2 +-
 documentation/test-manual/runtime-testing.rst |   4 +-
 43 files changed, 329 insertions(+), 263 deletions(-)

-- 
2.50.0.173.g8b6f19ccfc3a