* [PATCH v3 01/10] docs: give the root prompts a preamble
2026-09-24 17:28 [PATCH v3 00/10] docs: editorial repairs to the examples Trevor Woerner
@ 2026-09-24 17:28 ` Trevor Woerner
2026-09-24 17:28 ` [PATCH v3 02/10] docs: copy only the command from a console block Trevor Woerner
` (8 subsequent siblings)
9 siblings, 0 replies; 11+ messages in thread
From: Trevor Woerner @ 2026-09-24 17:28 UTC (permalink / raw)
To: docs; +Cc: Quentin Schulz
A bare "#" starting a line is a root prompt, a comment, and a line of
program output all at once, and nothing can tell them apart. Most root
prompts in the manuals already carry a preamble naming the machine, and
the stragglers are what make the distinction unreliable.
Add the preamble the others already use: the machine the surrounding
steps name, or a generic "machine" where they name none.
AI-Generated: codex/claude-opus 5 (xhigh)
Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
changes in v3:
- the kernel-dev "make scripts" block is prompted too, with its working
directory in the second prompt
changes in v2:
- rebased on master-next
- the SystemTap example uses a generic root@machine prompt; the two
kernel-dev ones keep qemux86, which the surrounding steps name
---
documentation/kernel-dev/common.rst | 8 ++++----
documentation/profile-manual/usage.rst | 2 +-
2 files changed, 5 insertions(+), 5 deletions(-)
diff --git a/documentation/kernel-dev/common.rst b/documentation/kernel-dev/common.rst
index 2a65055e2a44..65bd3d0d1f46 100644
--- a/documentation/kernel-dev/common.rst
+++ b/documentation/kernel-dev/common.rst
@@ -722,7 +722,7 @@ the ":ref:`kernel-dev/common:getting ready to develop using ``devtool```" Sectio
.. code-block:: none
- # dmesg | less
+ root@qemux86:~# dmesg | less
You should see
the results of your ``printk`` statements as part of the output
@@ -878,7 +878,7 @@ Section.
.. code-block:: none
- # dmesg | less
+ root@qemux86:~# dmesg | less
You should see the results of your
``printk`` statements as part of the output when you scroll down the
@@ -1554,8 +1554,8 @@ directory. Next, ``make`` the scripts:
.. code-block:: none
- # cd /usr/src/kernel
- # make scripts
+ root@machine:~# cd /usr/src/kernel
+ root@machine:/usr/src/kernel# make scripts
Because all SDK image recipes include ``dev-pkgs``, the
``kernel-dev`` packages will be installed as part of the SDK image and
diff --git a/documentation/profile-manual/usage.rst b/documentation/profile-manual/usage.rst
index dc34fa36c487..4efaa6d10fce 100644
--- a/documentation/profile-manual/usage.rst
+++ b/documentation/profile-manual/usage.rst
@@ -1801,7 +1801,7 @@ probe, you'd just install SystemTap on the system you want to probe,
and directly run the probe on that system e.g. assuming the name of the
file containing the above text is ``trace_open.stp``::
- # stap trace_open.stp
+ root@machine:~# stap trace_open.stp
What SystemTap does under the covers to run this probe is 1) parse and
convert the probe to an equivalent "C" form, 2) compile the "C" form
--
2.50.0.173.g8b6f19ccfc3a
^ permalink raw reply related [flat|nested] 11+ messages in thread* [PATCH v3 02/10] docs: copy only the command from a console block
2026-09-24 17:28 [PATCH v3 00/10] docs: editorial repairs to the examples Trevor Woerner
2026-09-24 17:28 ` [PATCH v3 01/10] docs: give the root prompts a preamble Trevor Woerner
@ 2026-09-24 17:28 ` Trevor Woerner
2026-09-24 17:28 ` [PATCH v3 03/10] docs: show a prompt on commands the reader is meant to type Trevor Woerner
` (7 subsequent siblings)
9 siblings, 0 replies; 11+ messages in thread
From: Trevor Woerner @ 2026-09-24 17:28 UTC (permalink / raw)
To: docs
The copy button matches the literal "$ " prompt, so on a block prompted
any other way it matches nothing and falls back to copying every line,
prompt, and output included. Match a pattern covering each prompt shape
the manuals use instead, so the button gives the command alone whatever
the prompt looks like.
AI-Generated: codex/claude-opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
changes in v3:
- the comment is shorter and no longer contradicts itself about scope
- a ">>> " alternative covers the one Python interpreter example
- a "(gdb) " alternative. The console lexer already marks that prompt,
so a selection skipped it while the button copied it; the two now
agree
changes in v2:
- dropped the stylesheet change, so a mouse selection keeps the output
- the comment now says this governs the copy button only, and only
reaches a block the console lexer has read
---
documentation/conf.py | 19 ++++++++++++++++++-
1 file changed, 18 insertions(+), 1 deletion(-)
diff --git a/documentation/conf.py b/documentation/conf.py
index 48d28a686807..d2252d5ab966 100644
--- a/documentation/conf.py
+++ b/documentation/conf.py
@@ -242,4 +242,21 @@ intersphinx_mapping = {
# -- sphinx_copybutton configuration -----------------------------------------
# sphinx-copybutton configuration
-copybutton_prompt_text = "$ "
+# Applies to the copy button only; a mouse selection is untouched.
+# Not scoped to console blocks, so every alternative has to be safe in a
+# BitBake or configuration example too.
+# No rule for a bare "#": it opens a comment, a root prompt, and a
+# line of program output alike.
+copybutton_prompt_text = "|".join((
+ r"^(?:\S+[@:]\S*)?\$\s+", # "$ ", and "user@host:~$ "
+ r"^\S+[@:]\S*#\s+", # "root@machine:~# ", a root prompt
+ r"^[A-Za-z]:\\[^>]*>\s*", # "C:\WINDOWS\system32>", cmd.exe
+ r"^DISKPART>\s*", # diskpart prints a prompt of its own
+ r"^pydevshell>\s+", # bitbake -c pydevshell
+ r"^>>> ", # a Python interpreter session
+ r"^\(gdb\)\s+", # a gdb session
+))
+copybutton_prompt_is_regexp = True
+copybutton_only_copy_prompt_lines = True
+copybutton_remove_prompts = True
+copybutton_line_continuation_character = "\\"
--
2.50.0.173.g8b6f19ccfc3a
^ permalink raw reply related [flat|nested] 11+ messages in thread* [PATCH v3 03/10] docs: show a prompt on commands the reader is meant to type
2026-09-24 17:28 [PATCH v3 00/10] docs: editorial repairs to the examples Trevor Woerner
2026-09-24 17:28 ` [PATCH v3 01/10] docs: give the root prompts a preamble Trevor Woerner
2026-09-24 17:28 ` [PATCH v3 02/10] docs: copy only the command from a console block Trevor Woerner
@ 2026-09-24 17:28 ` Trevor Woerner
2026-09-24 17:28 ` [PATCH v3 04/10] docs: write an elided passage as a comment Trevor Woerner
` (6 subsequent siblings)
9 siblings, 0 replies; 11+ messages in thread
From: Trevor Woerner @ 2026-09-24 17:28 UTC (permalink / raw)
To: docs
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 removals go
with it, because both only matter once a line is a command: a bare "$"
at the end, which is 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>
---
changes in v3:
- the weston command is prompted; it had none
- commands run on the target take the full user@machine:path prompt,
mirroring the root prompt, rather than a bare "$"
changes in v2:
- rebased on master-next; no other change
---
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 | 8 +--
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, 87 insertions(+), 94 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 ""
.. note::
Patches generated or updated by ``devtool`` are created with no signature.
diff --git a/documentation/contributor-guide/submit-changes.rst b/documentation/contributor-guide/submit-changes.rst
index 574a92cd3465..e60f8ca7ace3 100644
--- a/documentation/contributor-guide/submit-changes.rst
+++ b/documentation/contributor-guide/submit-changes.rst
@@ -57,20 +57,20 @@ Set up Git
The first thing to do is to install Git packages. Here is an example
on Debian and Ubuntu::
- sudo apt install git-core git-email
+ $ sudo apt install git-core git-email
Then, you need to set a name and e-mail address that Git will
use to identify your commits::
- git config --global user.name "Ada Lovelace"
- git config --global user.email "ada.lovelace@gmail.com"
+ $ git config --global user.name "Ada Lovelace"
+ $ git config --global user.email "ada.lovelace@gmail.com"
By default, Git adds a signature line at the end of patches containing the Git
version. We suggest to remove it as it doesn't add useful information.
Remove it with the following command::
- git config --global format.signature ""
+ $ git config --global format.signature ""
Clone the Git repository for the component to modify
----------------------------------------------------
@@ -79,8 +79,8 @@ After identifying the component to modify as described in the
":doc:`/contributor-guide/identify-component`" section, clone the
corresponding Git repository. Here is an example for OpenEmbedded-Core::
- git clone https://git.openembedded.org/openembedded-core
- cd openembedded-core
+ $ git clone https://git.openembedded.org/openembedded-core
+ $ cd openembedded-core
Create a new branch
-------------------
@@ -177,7 +177,7 @@ to add the upgraded version.
is to look for prefixes used in previous commits touching the
same files or directories::
- git log --oneline <paths>
+ $ git log --oneline <paths>
#. For the commit description, provide detailed information
that describes what you changed, why you made the change, and the
@@ -278,7 +278,7 @@ Here is the general procedure on how to create patches to be sent through email:
For this purpose, a good solution is to store the cover letter contents
in the branch itself::
- git branch --edit-description
+ $ git branch --edit-description
This will open a text editor to fill in the description for your
changes. This description can be updated when necessary and will
@@ -334,19 +334,19 @@ functional testing of the changes will be performed by ``patchtest``. Currently,
it only supports testing patches for ``openembedded-core`` branches. To setup,
perform the following::
- pip install -r meta/lib/patchtest/requirements.txt
- source oe-init-build-env
- bitbake-layers add-layer ../meta-selftest
+ $ pip install -r meta/lib/patchtest/requirements.txt
+ $ source oe-init-build-env
+ $ bitbake-layers add-layer ../meta-selftest
Once these steps are complete and you have generated your patch files,
you can run ``patchtest`` like so::
- patchtest --patch <patch_name>
+ $ patchtest --patch <patch_name>
Alternatively, if you want ``patchtest`` to iterate over and test
multiple patches stored in a directory, you can use::
- patchtest --directory <directory_name>
+ $ patchtest --directory <directory_name>
By default, ``patchtest`` uses its own modules' file paths to determine what
repository and test suite to check patches against. If you wish to test
@@ -354,7 +354,7 @@ patches against a repository other than ``openembedded-core`` and/or use
a different set of tests, you can use the ``--repodir`` and ``--testdir``
flags::
- patchtest --patch <patch_name> --repodir <path/to/repo> --testdir <path/to/testdir>
+ $ patchtest --patch <patch_name> --repodir <path/to/repo> --testdir <path/to/testdir>
Finally, note that ``patchtest`` is designed to test patches in a standalone
way, so if your patches are meant to apply on top of changes made by
@@ -396,11 +396,11 @@ through a direct SMTP configuration in your Git ``~/.gitconfig`` file.
Here are the settings for letting ``git send-email`` send e-mail through your
regular STMP server, using a Google Mail account as an example::
- git config --global sendemail.smtpserver smtp.gmail.com
- git config --global sendemail.smtpserverport 587
- git config --global sendemail.smtpencryption tls
- git config --global sendemail.smtpuser ada.lovelace@gmail.com
- git config --global sendemail.smtppass = XXXXXXXX
+ $ git config --global sendemail.smtpserver smtp.gmail.com
+ $ git config --global sendemail.smtpserverport 587
+ $ git config --global sendemail.smtpencryption tls
+ $ git config --global sendemail.smtpuser ada.lovelace@gmail.com
+ $ git config --global sendemail.smtppass = XXXXXXXX
These settings will appear in the ``.gitconfig`` file in your home directory.
@@ -463,7 +463,7 @@ Sending Patches via Email
At this stage, you are ready to send your patches via email. Here's the
typical usage of ``git send-email``::
- git send-email --to <mailing-list-address> *.patch
+ $ git send-email --to <mailing-list-address> *.patch
Then, review each subject line and list of recipients carefully, and then
allow the command to send each message.
@@ -476,7 +476,7 @@ or any layer other than :oe_git:`openembedded-core </openembedded-core/>`,
please add the appropriate prefix so that it is clear which layer the patch is intended
to be applied to::
- git format-patch --subject-prefix="meta-oe][PATCH" ...
+ $ git format-patch --subject-prefix="meta-oe][PATCH" ...
.. note::
@@ -488,13 +488,13 @@ to be applied to::
Here's a command you can use if you just have one patch in your
branch::
- git send-email --to <mailing-list-address> -1
+ $ git send-email --to <mailing-list-address> -1
If you have multiple patches and a cover letter, you can send
patches for all the commits between the reference branch
and the tip of your branch::
- git send-email --cover-letter --cover-from-description=auto --to <mailing-list-address> -M <ref-branch>
+ $ git send-email --cover-letter --cover-from-description=auto --to <mailing-list-address> -M <ref-branch>
See the `git send-email manual page <https://git-scm.com/docs/git-send-email>`__
for details.
@@ -517,7 +517,7 @@ author name. The following will ensure that your e-mails have an additional
maintainers accepting your patches don't have to fix commit author information
manually::
- git config --global sendemail.from "linus.torvalds@kernel.org"
+ $ git config --global sendemail.from "linus.torvalds@kernel.org"
The ``sendemail.from`` should match your ``user.email`` setting,
which appears in the ``Signed-off-by`` line of your commits.
@@ -530,12 +530,12 @@ with ``git send-email``, you can use Git configuration settings.
- To set the right mailing list address for a given repository::
- git config --local sendemail.to openembedded-devel@lists.openembedded.org
+ $ git config --local sendemail.to openembedded-devel@lists.openembedded.org
- If the mailing list requires a subject prefix for the layer
(this only works when the repository only contains one layer)::
- git config --local format.subjectprefix "meta-something][PATCH"
+ $ git config --local format.subjectprefix "meta-something][PATCH"
Using Scripts to Push a Change Upstream and Request a Pull
==========================================================
@@ -597,7 +597,7 @@ have been followed:
enter the following command to bring up a short list of all
commits against a specific file::
- git shortlog -- filename
+ $ git shortlog -- filename
Just provide the name of the file for which you are interested. The
information returned is not ordered by history but does include a
@@ -719,7 +719,7 @@ follows:
``git format-patch``, for example to submit a patch to the
"&DISTRO_NAME_NO_CAP_MINUS_ONE;" branch use::
- git format-patch --subject-prefix='&DISTRO_NAME_NO_CAP_MINUS_ONE;][PATCH' ...
+ $ git format-patch --subject-prefix='&DISTRO_NAME_NO_CAP_MINUS_ONE;][PATCH' ...
Taking Patch Review into Account
================================
@@ -745,7 +745,7 @@ without the reported issues.
A single patch can be amended using ``git commit --amend``, and multiple
patches can be easily reworked and reordered through an interactive Git rebase::
- git rebase -i <ref-branch>
+ $ git rebase -i <ref-branch>
See `this tutorial <https://hackernoon.com/beginners-guide-to-interactive-rebasing-346a3f9c3a6d>`__
for practical guidance about using Git interactive rebasing.
@@ -755,7 +755,7 @@ sending the revised patch to mark the new iteration as ``[PATCH v2]``,
``[PATCH v3]``, etc as appropriate. This can be done by passing the ``-v``
argument to ``git format-patch`` with a version number::
- git format-patch -v2 <ref-branch>
+ $ git format-patch -v2 <ref-branch>
After generating updated patches (v2, v3, and so on) via ``git
diff --git a/documentation/dev-manual/creating-fragments.rst b/documentation/dev-manual/creating-fragments.rst
index 8dabd599f13f..cd87341e9a51 100644
--- a/documentation/dev-manual/creating-fragments.rst
+++ b/documentation/dev-manual/creating-fragments.rst
@@ -86,7 +86,7 @@ For now, our fragment exists and is listed by the
enable this fragment, use the :ref:`ref-bitbake-config-build-enable-fragment`
command::
- bitbake-config-build enable-fragment meta-custom/custom-fragment
+ $ bitbake-config-build enable-fragment meta-custom/custom-fragment
.. note::
@@ -143,4 +143,4 @@ configuration file:
You can then use the :ref:`ref-bitbake-config-build-enable-fragment` command to
set a value to the ``CUSTOM_VARIABLE`` variable::
- bitbake-config-build enable-fragment custom-builtin-fragment/somevalue
+ $ bitbake-config-build enable-fragment custom-builtin-fragment/somevalue
diff --git a/documentation/dev-manual/debugging.rst b/documentation/dev-manual/debugging.rst
index 4995ba73f06b..0f6e9d1d7e85 100644
--- a/documentation/dev-manual/debugging.rst
+++ b/documentation/dev-manual/debugging.rst
@@ -821,7 +821,6 @@ missing dependency clearly visible at the end::
^
compilation terminated.
make: *** [tools/snep-send.o] Error 1
- $
Creating a Patch for the Fix
diff --git a/documentation/dev-manual/devtool.rst b/documentation/dev-manual/devtool.rst
index 242ea9dd9942..471134da8629 100644
--- a/documentation/dev-manual/devtool.rst
+++ b/documentation/dev-manual/devtool.rst
@@ -548,7 +548,7 @@ the two modes:
- To work on the source code of a recipe another instance of VSCode is
started in the recipe's workspace. Example::
- code build/workspace/sources/my-recipe
+ $ code build/workspace/sources/my-recipe
This instance of VSCode uses plugins that are useful for the development
of the application. ``devtool ide-sdk`` generates the necessary
@@ -720,9 +720,9 @@ the two modes:
VSCode. First of all we need a folder containing a CMake project.
For this example, let's create a CMake project and start VSCode::
- mkdir kit-test
- echo "project(foo VERSION 1.0)" > kit-test/CMakeLists.txt
- code kit-test
+ $ mkdir kit-test
+ $ echo "project(foo VERSION 1.0)" > kit-test/CMakeLists.txt
+ $ code kit-test
If there is a CMake project in the workspace, cross-compilation is
supported:
diff --git a/documentation/dev-manual/disk-space.rst b/documentation/dev-manual/disk-space.rst
index 5516f793e301..ee02b267081c 100644
--- a/documentation/dev-manual/disk-space.rst
+++ b/documentation/dev-manual/disk-space.rst
@@ -33,7 +33,7 @@ disk space. However, only the most recent ones are likely to be reused.
The following command is a quick way to purge all the cache files which
haven't been used for a least a specified number of days::
- find build/sstate-cache -type f -mtime +$DAYS -delete
+ $ find build/sstate-cache -type f -mtime +$DAYS -delete
The above command relies on the fact that BitBake touches the sstate cache
files as it accesses them, when it has write access to the cache.
@@ -49,7 +49,7 @@ requires a full build environment to be available and doesn't work well
covering multiple releases. It won't work either on limited environments
such as BSD based NAS::
- sstate-cache-management.py --remove-duplicated --cache-dir=sstate-cache
+ $ sstate-cache-management.py --remove-duplicated --cache-dir=sstate-cache
This command will ask you to confirm the deletions it identifies.
Run ``sstate-cache-management.py`` for more details about this script.
diff --git a/documentation/dev-manual/hashequivserver.rst b/documentation/dev-manual/hashequivserver.rst
index 75b77c30b944..0a67e79b66bc 100644
--- a/documentation/dev-manual/hashequivserver.rst
+++ b/documentation/dev-manual/hashequivserver.rst
@@ -22,7 +22,7 @@ the :term:`BitBake` repository, which can be found :oe_git:`here </bitbake>`.
To start a basic Hash Equivalence server, one could simply run::
- ./bin/bitbake-hashserv
+ $ ./bin/bitbake-hashserv
This will take all of the default options of the script, which are already
sufficient to start a local server.
diff --git a/documentation/dev-manual/limiting-resources.rst b/documentation/dev-manual/limiting-resources.rst
index 892b0069accf..93c20c44c36e 100644
--- a/documentation/dev-manual/limiting-resources.rst
+++ b/documentation/dev-manual/limiting-resources.rst
@@ -104,7 +104,7 @@ details.
#. Then, start a heavy-load build, for example::
- bitbake virtual/kernel -c compile -f
+ $ bitbake virtual/kernel -c compile -f
You can stop the build at anytime with Control + C.
diff --git a/documentation/dev-manual/new-recipe.rst b/documentation/dev-manual/new-recipe.rst
index f43fc2be3f4c..a23a796f5a40 100644
--- a/documentation/dev-manual/new-recipe.rst
+++ b/documentation/dev-manual/new-recipe.rst
@@ -106,19 +106,19 @@ Here are some syntax examples:
- Use this syntax to generate a recipe based on source. Once generated,
the recipe resides in the existing source code layer::
- recipetool create -o OUTFILE source
+ $ recipetool create -o OUTFILE source
- Use this syntax to generate a recipe using code that
you extract from source. The extracted code is placed in its own layer
defined by :term:`EXTERNALSRC`::
- recipetool create -o OUTFILE -x EXTERNALSRC source
+ $ recipetool create -o OUTFILE -x EXTERNALSRC source
- Use this syntax to generate a recipe based on source. The options
direct ``recipetool`` to generate debugging information. Once generated,
the recipe resides in the existing source code layer::
- recipetool create -d -o OUTFILE source
+ $ recipetool create -d -o OUTFILE source
Locating and Using a Similar Recipe
-----------------------------------
diff --git a/documentation/dev-manual/packages.rst b/documentation/dev-manual/packages.rst
index 0271cca10cc9..8cd90b9f25b1 100644
--- a/documentation/dev-manual/packages.rst
+++ b/documentation/dev-manual/packages.rst
@@ -176,7 +176,7 @@ work against a common, shared package feed, you have a single PR Service
running and it is connected to each building system. For this scenario,
you need to start the PR Service using the ``bitbake-prserv`` command::
- bitbake-prserv --host ip --port port --start
+ $ bitbake-prserv --host ip --port port --start
In addition to
hand-starting the service, you need to update the
diff --git a/documentation/dev-manual/python-development-shell.rst b/documentation/dev-manual/python-development-shell.rst
index 07563043232c..034100ae8799 100644
--- a/documentation/dev-manual/python-development-shell.rst
+++ b/documentation/dev-manual/python-development-shell.rst
@@ -25,7 +25,6 @@ functions::
pydevshell> d.delVar("FOO")
pydevshell> d.getVar("FOO")
pydevshell> bb.build.exec_func("do_unpack", d)
- pydevshell>
See the ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:functions you can call from within python`"
section in the BitBake User Manual for details about available functions.
diff --git a/documentation/dev-manual/qemu.rst b/documentation/dev-manual/qemu.rst
index 514a72fc528a..6d092b2d2034 100644
--- a/documentation/dev-manual/qemu.rst
+++ b/documentation/dev-manual/qemu.rst
@@ -65,7 +65,7 @@ available. Follow these general steps to run QEMU:
initializes the toolchain. For example, the following commands run
the initialization script from the default ``poky_sdk`` directory::
- . poky_sdk/environment-setup-core2-64-poky-linux
+ $ . poky_sdk/environment-setup-core2-64-poky-linux
#. *Ensure the Artifacts are in Place:* You need to be sure you have a
pre-built kernel that will boot in QEMU. You also need the target
@@ -227,15 +227,15 @@ using an NFS server.
- To start the NFS share::
- runqemu-export-rootfs start file-system-location
+ $ runqemu-export-rootfs start file-system-location
- To stop the NFS share::
- runqemu-export-rootfs stop file-system-location
+ $ runqemu-export-rootfs stop file-system-location
- To restart the NFS share::
- runqemu-export-rootfs restart file-system-location
+ $ runqemu-export-rootfs restart file-system-location
QEMU CPU Compatibility Under KVM
================================
diff --git a/documentation/dev-manual/start.rst b/documentation/dev-manual/start.rst
index c7d0fe3dab8d..73b7d9501ae4 100644
--- a/documentation/dev-manual/start.rst
+++ b/documentation/dev-manual/start.rst
@@ -423,7 +423,7 @@ your Yocto Project build host:
replace the PackageFamilyName and your user on the following path
to find your VHDX file::
- ls C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\
+ C:\WINDOWS\system32> ls C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState
Mode LastWriteTime Length Name
-a---- 3/14/2020 9:52 PM 57418973184 ext4.vhdx
diff --git a/documentation/dev-manual/wayland.rst b/documentation/dev-manual/wayland.rst
index 5e333b6265f4..ec8ed86c1c60 100644
--- a/documentation/dev-manual/wayland.rst
+++ b/documentation/dev-manual/wayland.rst
@@ -80,11 +80,11 @@ the CLI, you need to do the following after your image is built:
#. Run these commands to export ``XDG_RUNTIME_DIR``::
- mkdir -p /tmp/$USER-weston
- chmod 0700 /tmp/$USER-weston
- export XDG_RUNTIME_DIR=/tmp/$USER-weston
+ user@machine:~$ mkdir -p /tmp/$USER-weston
+ user@machine:~$ chmod 0700 /tmp/$USER-weston
+ user@machine:~$ export XDG_RUNTIME_DIR=/tmp/$USER-weston
#. Launch Weston in the shell::
- weston
+ user@machine:~$ weston
diff --git a/documentation/kernel-dev/common.rst b/documentation/kernel-dev/common.rst
index 65bd3d0d1f46..6e67156bedc5 100644
--- a/documentation/kernel-dev/common.rst
+++ b/documentation/kernel-dev/common.rst
@@ -75,7 +75,6 @@ section:
$ bitbake-layers create-layer ../layers/meta-mylayer
NOTE: Starting bitbake server...
Add your new layer with 'bitbake-layers add-layer ../layers/meta-mylayer'
- $
.. note::
@@ -98,7 +97,6 @@ section:
$ cd bitbake-builds/build
$ bitbake-layers add-layer ../../meta-mylayer
NOTE: Starting bitbake server...
- $
#. *Build the Clean Image:* The final step in preparing to work on the
kernel is to build an initial image using ``bitbake``::
@@ -194,7 +192,6 @@ section:
$ cd bitbake-builds/build
$ bitbake-layers add-layer ../../meta-mylayer
NOTE: Starting bitbake server ...
- $
#. *Create a Local Copy of the Kernel Git Repository:* You can find Git
repositories of supported Yocto Project kernels organized under
diff --git a/documentation/migration-guides/migration-2.1.rst b/documentation/migration-guides/migration-2.1.rst
index 473dd10ff121..987464f4d77f 100644
--- a/documentation/migration-guides/migration-2.1.rst
+++ b/documentation/migration-guides/migration-2.1.rst
@@ -46,8 +46,8 @@ not specify the final expand parameter to calls that do specify the
parameter. You can run the following ``sed`` command at the base of a
layer to make this change::
- sed -e 's:\(\.getVar([^,()]*\)):\1, False):g' -i `grep -ril getVar *`
- sed -e 's:\(\.getVarFlag([^,()]*,[^,()]*\)):\1, False):g' -i `grep -ril getVarFlag *`
+ $ sed -e 's:\(\.getVar([^,()]*\)):\1, False):g' -i `grep -ril getVar *`
+ $ sed -e 's:\(\.getVarFlag([^,()]*,[^,()]*\)):\1, False):g' -i `grep -ril getVarFlag *`
.. note::
diff --git a/documentation/migration-guides/migration-2.5.rst b/documentation/migration-guides/migration-2.5.rst
index 8e182cd2bc4a..70946b5e11b4 100644
--- a/documentation/migration-guides/migration-2.5.rst
+++ b/documentation/migration-guides/migration-2.5.rst
@@ -138,11 +138,11 @@ BitBake Changes
:ref:`ref-classes-archiver` classes). There is a BitBake option to complete this for
any arbitrary task. For example::
- bitbake <target> -c fetchall
+ $ bitbake <target> -c fetchall
should now be replaced with::
- bitbake <target> --runall=fetch
+ $ bitbake <target> --runall=fetch
.. _migration-2.5-python-and-python3-changes:
diff --git a/documentation/migration-guides/migration-4.0.rst b/documentation/migration-guides/migration-4.0.rst
index c8c2b856d91c..31ce15a9cafc 100644
--- a/documentation/migration-guides/migration-4.0.rst
+++ b/documentation/migration-guides/migration-4.0.rst
@@ -256,7 +256,7 @@ Miscellaneous changes
- The Python development shell (previously known as ``devpyshell``) feature has been
renamed to ``pydevshell``. To start it you should now run::
- bitbake <target> -c pydevshell
+ $ bitbake <target> -c pydevshell
- The ``packagegroups-core-full-cmdline-libs`` packagegroup is no longer produced, as
libraries should normally be brought in via dependencies. If you have any references
diff --git a/documentation/migration-guides/migration-5.3.rst b/documentation/migration-guides/migration-5.3.rst
index 38c7d6771667..e5521d94b59f 100644
--- a/documentation/migration-guides/migration-5.3.rst
+++ b/documentation/migration-guides/migration-5.3.rst
@@ -83,16 +83,16 @@ How to make those adjustments without tedious manual editing
The following sed command can be used to remove S = "${WORKDIR}/git
across a whole layer::
- sed -i "/^S = \"\${WORKDIR}\/git\"/d" `find . -name '*.bb' -o -name '*.inc' -o -name '*.bbclass'`
+ $ sed -i "/^S = \"\${WORKDIR}\/git\"/d" `find . -name '*.bb' -o -name '*.inc' -o -name '*.bbclass'`
Then, the following command can tweak the remaining :term:`S` assignments to
refer to :term:`UNPACKDIR` instead of :term:`WORKDIR`::
- sed -i "s/^S = \"\${WORKDIR}\//S = \"\${UNPACKDIR}\//g" `find . -name '*.bb' -o -name '*.inc' -o -name '*.bbclass'`
+ $ sed -i "s/^S = \"\${WORKDIR}\//S = \"\${UNPACKDIR}\//g" `find . -name '*.bb' -o -name '*.inc' -o -name '*.bbclass'`
The first change can introduce a lot of consecutive empty lines, so those can be removed with::
- sed -i -z -E 's/([ \t\f\v\r]*\n){3,}/\n\n/g' `find . -name '*.bb' -o -name '*.inc'`
+ $ sed -i -z -E 's/([ \t\f\v\r]*\n){3,}/\n\n/g' `find . -name '*.bb' -o -name '*.inc'`
BitBake Git fetcher ``tag`` parameter
@@ -312,11 +312,11 @@ The following classes have been removed in this release:
#. Use the specific FIT image recipe rather than the base kernel recipe.
For example, instead of::
- bitbake linux-yocto
+ $ bitbake linux-yocto
the FIT image is now build by::
- bitbake linux-yocto-fitimage
+ $ bitbake linux-yocto-fitimage
For custom kernel recipes, creating a corresponding custom FIT image recipe
is usually a good approach.
diff --git a/documentation/migration-guides/release-notes-4.2.rst b/documentation/migration-guides/release-notes-4.2.rst
index f50ef180ac66..3586622edca9 100644
--- a/documentation/migration-guides/release-notes-4.2.rst
+++ b/documentation/migration-guides/release-notes-4.2.rst
@@ -173,7 +173,7 @@ New Features / Enhancements in 4.2
command, which allowed to spot and fix a regression in the
``quilt`` ptest::
- yocto_testresults_query.py regression-report 4.2_M1 4.2_M2
+ $ yocto_testresults_query.py regression-report 4.2_M1 4.2_M2
See this `blog post about regression detection
<https://bootlin.com/blog/continuous-integration-in-yocto-improving-the-regressions-detection/>`__.
diff --git a/documentation/migration-guides/release-notes-5.3.rst b/documentation/migration-guides/release-notes-5.3.rst
index 8a564716f319..311a9a94718a 100644
--- a/documentation/migration-guides/release-notes-5.3.rst
+++ b/documentation/migration-guides/release-notes-5.3.rst
@@ -466,7 +466,7 @@ New Features / Enhancements in |yocto-ver|
- The script can now run compressed images with snapshot mode. For
example, with :term:`IMAGE_FSTYPES` containing ``ext4.zst``, you can run::
- runqemu snapshot ext4.zst <image-recipe>
+ $ runqemu snapshot ext4.zst <image-recipe>
- Add support for the ``erofs`` filesystem.
diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index cbad93e8a38d..7b67ae8cc6b3 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -366,7 +366,7 @@ To do so, create a recipe for your program, for example using
make it inherit the :ref:`ref-classes-cargo` and
:ref:`ref-classes-cargo-update-recipe-crates` and run::
- bitbake -c update_crates recipe
+ $ bitbake -c update_crates recipe
This creates a ``recipe-crates.inc`` file that you can include in your
recipe::
@@ -1372,7 +1372,7 @@ The simplest example for building a FIT image is to add::
to the machine :term:`configuration file` and to execute::
- bitbake linux-yocto-fitimage
+ $ bitbake linux-yocto-fitimage
This results in a ``fitImage`` file deployed to the :term:`DEPLOY_DIR_IMAGE`
directory and a ``linux-yocto-fitimage`` package which can be installed.
@@ -1386,7 +1386,7 @@ lines to the machine configuration file::
The FIT image, this time including the RT kernel, is built again by calling::
- bitbake linux-yocto-fitimage
+ $ bitbake linux-yocto-fitimage
For other kernels provided by other layers, the same approach would work.
However, it is usually more intuitive to add a custom FIT image recipe next to
@@ -3864,7 +3864,7 @@ build.
Example usage::
- bitbake -c generate_vex openssl
+ $ bitbake -c generate_vex openssl
.. _ref-classes-waf:
diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst
index d2e80611a994..4aa95d8e0499 100644
--- a/documentation/ref-manual/devtool-reference.rst
+++ b/documentation/ref-manual/devtool-reference.rst
@@ -461,7 +461,6 @@ Here is an example that resets the workspace directory that contains the
$ devtool reset mtr
NOTE: Cleaning sysroot for recipe mtr...
NOTE: Leaving source tree /home/scottrif/bitbake-builds/build/workspace/sources/mtr as-is; if you no longer need it then please delete it manually
- $
.. _devtool-finish-working-on-a-recipe:
@@ -634,7 +633,6 @@ to create and add the ``mtr_0.86.bb`` recipe to the ``workspace`` directory::
$ devtool status
mtr:/home/scottrif/bitbake-builds/build/workspace/sources/mtr (/home/scottrif/bitbake-builds/build/workspace/recipes/mtr/mtr_0.86.bb)
- $
.. _devtool-search-for-available-target-recipes:
diff --git a/documentation/ref-manual/fragments.rst b/documentation/ref-manual/fragments.rst
index e5cd9fc436c1..c5640b826eae 100644
--- a/documentation/ref-manual/fragments.rst
+++ b/documentation/ref-manual/fragments.rst
@@ -72,25 +72,25 @@ command, you can determine which fragments can be enabled for your build.
For example, the following command would enable the
:ref:`ref-fragments-core-yocto-sstate-mirror-cdn` fragment::
- bitbake-config-build enable-fragment core/yocto/sstate-mirror-cdn
+ $ bitbake-config-build enable-fragment core/yocto/sstate-mirror-cdn
.. note::
Multiple fragments can be enabled at once with the same command::
- bitbake-config-build enable-fragment <fragment1> <fragment2> ...
+ $ bitbake-config-build enable-fragment <fragment1> <fragment2> ...
:term:`Built-in fragments <Built-in Fragment>` are enabled the same way, and
their values are defined from the command-line directly. For example, the
following command sets the ``qemuarm64`` :term:`MACHINE` through the
:ref:`ref-fragments-builtin-core-machine` fragment::
- bitbake-config-build enable-fragment machine/qemuarm64
+ $ bitbake-config-build enable-fragment machine/qemuarm64
This fragment can be overridden from the command-line by setting it to another
value, for example::
- bitbake-config-build enable-fragment machine/qemux86-64
+ $ bitbake-config-build enable-fragment machine/qemux86-64
In the above example, the new value of :term:`MACHINE` is now equal to
``qemux86-64``.
@@ -118,18 +118,18 @@ command. The list of enabled fragments can be obtained with
For example, the following command disables the
:ref:`ref-fragments-core-yocto-sstate-mirror-cdn` fragment::
- bitbake-config-build disable-fragment core/yocto/sstate-mirror-cdn
+ $ bitbake-config-build disable-fragment core/yocto/sstate-mirror-cdn
Likewise, :term:`Built-in Fragments <Built-in Fragment>` are disabled the
same way. For example, this would disable the ``machine/qemuarm64`` fragment::
- bitbake-config-build disable-fragment machine/qemuarm64
+ $ bitbake-config-build disable-fragment machine/qemuarm64
.. note::
Multiple fragments can be disabled at once with the same command::
- bitbake-config-build disable-fragment <fragment1> <fragment2>
+ $ bitbake-config-build disable-fragment <fragment1> <fragment2>
.. _ref-bitbake-config-build-disable-all-fragments:
@@ -142,7 +142,7 @@ currently enabled fragments. The list of enabled fragments can be obtained with
This command is run without arguments::
- bitbake-config-build disable-all-fragments
+ $ bitbake-config-build disable-all-fragments
Core Fragments
==============
diff --git a/documentation/ref-manual/qa-checks.rst b/documentation/ref-manual/qa-checks.rst
index 8e1ce4438c79..14e3632ce6b8 100644
--- a/documentation/ref-manual/qa-checks.rst
+++ b/documentation/ref-manual/qa-checks.rst
@@ -573,14 +573,14 @@ patched file to still compile without errors.
Use the ``devtool`` command as explained by the warning. First, unpack the
source into devtool workspace::
- devtool modify <recipe>
+ $ devtool modify <recipe>
This will apply all of the patches, and create new commits out of them in
the workspace --- with the patch context updated.
Then, replace the patches in the recipe layer::
- devtool finish --force-patch-refresh <recipe> <layer_path>
+ $ devtool finish --force-patch-refresh <recipe> <layer_path>
The patch updates then need be reviewed (preferably with a side-by-side diff
tool) to ensure they are indeed doing the right thing i.e.:
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 1c0864d8720e..c050c422bffc 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -967,7 +967,7 @@ system and gives an overview of their function and contents.
Use the following format to export the variable to the BitBake
environment::
- export BBSERVER=localhost:$port
+ $ export BBSERVER=localhost:$port
By default, :term:`BBSERVER` also appears in :term:`BB_BASEHASH_IGNORE_VARS`.
Consequently, :term:`BBSERVER` is excluded from checksum and dependency
@@ -9357,7 +9357,7 @@ system and gives an overview of their function and contents.
You can obtain the signature of all the tasks for the recipe ``bc`` using::
- bitbake -S none bc
+ $ bitbake -S none bc
Then you can look at files in ``build/tmp/stamps/<arch>/bc`` and look for
files like: ``<PV>.do_compile.sigdata.09772aa4532512baf96d433484f27234d4b7c11dd9cda0d6f56fa1b7ce6f25f0``.
@@ -9514,7 +9514,7 @@ system and gives an overview of their function and contents.
This file requires permissions set to ``400`` or ``600`` to prevent
other users from reading the file::
- chmod 600 "$HOME/.netrc"
+ $ chmod 600 "$HOME/.netrc"
Another method to configure the username and password is from the URL
in :term:`SOURCE_MIRROR_URL` directly, with the ``user`` and ``pswd``
diff --git a/documentation/test-manual/reproducible-builds.rst b/documentation/test-manual/reproducible-builds.rst
index 892f7b9c8f0d..4e39cf3f79d8 100644
--- a/documentation/test-manual/reproducible-builds.rst
+++ b/documentation/test-manual/reproducible-builds.rst
@@ -89,7 +89,7 @@ it always depends upon the paths it is built in.
To run our automated selftest, as we use in our CI on the Autobuilder, you can
run::
- oe-selftest -r reproducible.ReproducibleTests.test_reproducible_builds
+ $ oe-selftest -r reproducible.ReproducibleTests.test_reproducible_builds
This defaults to including a ``world`` build so, if other layers are added, it
would also run the tests for recipes in the additional layers. Different build
diff --git a/documentation/test-manual/runtime-testing.rst b/documentation/test-manual/runtime-testing.rst
index 55c19900f439..5a7193f015b4 100644
--- a/documentation/test-manual/runtime-testing.rst
+++ b/documentation/test-manual/runtime-testing.rst
@@ -326,7 +326,7 @@ You can start the tests automatically or manually:
Next, build your image. If the image successfully builds, the
tests run::
- bitbake core-image-sato
+ $ bitbake core-image-sato
- *Manually running tests:* To manually run the tests, first globally
inherit the :ref:`ref-classes-testimage` class by editing your
@@ -336,7 +336,7 @@ You can start the tests automatically or manually:
Next, use BitBake to run the tests::
- bitbake -c testimage image
+ $ bitbake -c testimage image
All test files reside in ``meta/lib/oeqa/runtime/cases`` in
:term:`OpenEmbedded-Core (OE-Core)`. A test name maps
--
2.50.0.173.g8b6f19ccfc3a
^ permalink raw reply related [flat|nested] 11+ messages in thread* [PATCH v3 04/10] docs: write an elided passage as a comment
2026-09-24 17:28 [PATCH v3 00/10] docs: editorial repairs to the examples Trevor Woerner
` (2 preceding siblings ...)
2026-09-24 17:28 ` [PATCH v3 03/10] docs: show a prompt on commands the reader is meant to type Trevor Woerner
@ 2026-09-24 17:28 ` Trevor Woerner
2026-09-24 17:28 ` [PATCH v3 05/10] docs: mark the placeholders in examples Trevor Woerner
` (5 subsequent siblings)
9 siblings, 0 replies; 11+ messages in thread
From: Trevor Woerner @ 2026-09-24 17:28 UTC (permalink / raw)
To: docs; +Cc: Quentin Schulz
Several examples stand in for code they leave out with a bare "..." or a
column of dots on a line of their own. Neither is valid in the language
around it, so the example cannot say what language it is without also
saying something false about itself.
Use a comment instead, in whatever language the example is written in,
and say in it what was left out. The ellipsis on its own raises a
question - what is missing here, and does it matter? - that a few words
can answer at no cost to the reader.
AI-Generated: codex/claude-opus 5 (xhigh)
Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
changes in v3:
- none
changes in v2:
- rebased on master-next; no other change
---
documentation/bsp-manual/bsp.rst | 4 +---
documentation/kernel-dev/common.rst | 14 +++++++-------
documentation/migration-guides/migration-3.2.rst | 2 +-
documentation/overview-manual/concepts.rst | 2 +-
4 files changed, 10 insertions(+), 12 deletions(-)
diff --git a/documentation/bsp-manual/bsp.rst b/documentation/bsp-manual/bsp.rst
index dd613326942a..93af13f789d1 100644
--- a/documentation/bsp-manual/bsp.rst
+++ b/documentation/bsp-manual/bsp.rst
@@ -561,9 +561,7 @@ statements from the Raspberry Pi ``conf/layer.conf`` file::
# Additional license directories.
LICENSE_PATH += "${LAYERDIR}/files/custom-licenses"
- .
- .
- .
+ # ... and so on for the rest of the file ...
This file simply makes :term:`BitBake` aware of the recipes and configuration
directories. The file must exist so that the OpenEmbedded build system can
diff --git a/documentation/kernel-dev/common.rst b/documentation/kernel-dev/common.rst
index 6e67156bedc5..3de61cab08d6 100644
--- a/documentation/kernel-dev/common.rst
+++ b/documentation/kernel-dev/common.rst
@@ -681,9 +681,9 @@ the ":ref:`kernel-dev/common:getting ready to develop using ``devtool```" Sectio
printk("*************************************\n");
if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
- .
- .
- .
+ /*
+ * ... remaining code unchanged ...
+ */
#. *Build the Updated Kernel Source:* To build the updated kernel
source, use ``devtool``::
@@ -817,9 +817,9 @@ Section.
printk("*************************************\n");
if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
- .
- .
- .
+ /*
+ * ... remaining code unchanged ...
+ */
#. *Stage and Commit Your Changes:* Use standard Git commands to stage
and commit the changes you just made::
@@ -1598,7 +1598,7 @@ looks much like the one provided with the ``hello-mod`` template::
modules_install:
$(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install
- ...
+ # ... remaining rules ...
The important point to note here is the :term:`KERNEL_SRC` variable. The
:ref:`ref-classes-module` class sets this variable and the :term:`KERNEL_PATH`
diff --git a/documentation/migration-guides/migration-3.2.rst b/documentation/migration-guides/migration-3.2.rst
index 5cb958e75047..a037e6f51c53 100644
--- a/documentation/migration-guides/migration-3.2.rst
+++ b/documentation/migration-guides/migration-3.2.rst
@@ -100,7 +100,7 @@ This also applies when conditionally adding packages to :term:`PACKAGES` where
those packages have dependencies, for example (from the ``alsa-plugins`` recipe)::
PACKAGES += "${@bb.utils.contains('PACKAGECONFIG', 'pulseaudio', 'alsa-plugins-pulseaudio-conf', '', d)}"
- ...
+ # ... elsewhere in the same recipe ...
RDEPENDS_${PN}-pulseaudio-conf += "\
${MLPREFIX}libasound-module-conf-pulse \
${MLPREFIX}libasound-module-ctl-pulse \
diff --git a/documentation/overview-manual/concepts.rst b/documentation/overview-manual/concepts.rst
index 3bf672c78387..1e9c6d3a6f0b 100644
--- a/documentation/overview-manual/concepts.rst
+++ b/documentation/overview-manual/concepts.rst
@@ -2193,7 +2193,7 @@ accomplished using fakeroot.
``virtual/fakeroot-native:do_populate_sysroot``, giving the following::
fakeroot do_mytask () {
- ...
+ # ... steps to perform task here ...
}
do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot"
--
2.50.0.173.g8b6f19ccfc3a
^ permalink raw reply related [flat|nested] 11+ messages in thread* [PATCH v3 05/10] docs: mark the placeholders in examples
2026-09-24 17:28 [PATCH v3 00/10] docs: editorial repairs to the examples Trevor Woerner
` (3 preceding siblings ...)
2026-09-24 17:28 ` [PATCH v3 04/10] docs: write an elided passage as a comment Trevor Woerner
@ 2026-09-24 17:28 ` Trevor Woerner
2026-09-24 17:28 ` [PATCH v3 06/10] docs: remove real accounts from the examples Trevor Woerner
` (4 subsequent siblings)
9 siblings, 0 replies; 11+ messages in thread
From: Trevor Woerner @ 2026-09-24 17:28 UTC (permalink / raw)
To: docs
Values the reader is expected to replace are written as though they were
literal. "arch-gdb" reads like a command that exists, a Git SRC_URI
example reads like a URL and a pair of revisions worth copying, and the
git-config examples give an account name and address that are somebody
else's. Put them in the angle brackets the manuals already use for the
purpose.
Two corrections go with them: the directory placeholder in the GDB
example described itself at length rather than naming the thing, and the
smtppass example carried a stray "=". Since git config takes a name and
then a value, that "=" was the value, and the password behind it an
argument git config reads as a pattern.
AI-Generated: codex/claude-opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
changes in v3:
- the DMARC From: header is left as it was; nothing in it is for the
reader to replace
- the git config name is written <firstname> <lastname>
- the SRCREV values say they are commit SHAs
- the SMTP server is a placeholder too, and the prose names
smtp.gmail.com as the Google Mail value rather than the block
changes in v2:
- rebased on master-next; no other change
---
.../contributor-guide/submit-changes.rst | 15 ++++++++-------
documentation/dev-manual/debugging.rst | 8 ++++----
documentation/migration-guides/migration-5.2.rst | 16 ++++++++--------
documentation/ref-manual/devtool-reference.rst | 2 +-
documentation/ref-manual/variables.rst | 2 +-
5 files changed, 22 insertions(+), 21 deletions(-)
diff --git a/documentation/contributor-guide/submit-changes.rst b/documentation/contributor-guide/submit-changes.rst
index e60f8ca7ace3..589545074907 100644
--- a/documentation/contributor-guide/submit-changes.rst
+++ b/documentation/contributor-guide/submit-changes.rst
@@ -62,8 +62,8 @@ on Debian and Ubuntu::
Then, you need to set a name and e-mail address that Git will
use to identify your commits::
- $ git config --global user.name "Ada Lovelace"
- $ git config --global user.email "ada.lovelace@gmail.com"
+ $ git config --global user.name "<firstname> <lastname>"
+ $ git config --global user.email "<email>"
By default, Git adds a signature line at the end of patches containing the Git
version. We suggest to remove it as it doesn't add useful information.
@@ -394,13 +394,14 @@ Mail Transport Agent (MTA) such as ``msmtp``, ``sendmail``, or
through a direct SMTP configuration in your Git ``~/.gitconfig`` file.
Here are the settings for letting ``git send-email`` send e-mail through your
-regular STMP server, using a Google Mail account as an example::
+regular STMP server, such as ``smtp.gmail.com`` for a Google Mail
+account::
- $ git config --global sendemail.smtpserver smtp.gmail.com
+ $ git config --global sendemail.smtpserver <smtp server>
$ git config --global sendemail.smtpserverport 587
$ git config --global sendemail.smtpencryption tls
- $ git config --global sendemail.smtpuser ada.lovelace@gmail.com
- $ git config --global sendemail.smtppass = XXXXXXXX
+ $ git config --global sendemail.smtpuser <email>
+ $ git config --global sendemail.smtppass <password>
These settings will appear in the ``.gitconfig`` file in your home directory.
@@ -517,7 +518,7 @@ author name. The following will ensure that your e-mails have an additional
maintainers accepting your patches don't have to fix commit author information
manually::
- $ git config --global sendemail.from "linus.torvalds@kernel.org"
+ $ git config --global sendemail.from "<email>"
The ``sendemail.from`` should match your ``user.email`` setting,
which appears in the ``Signed-off-by`` line of your commits.
diff --git a/documentation/dev-manual/debugging.rst b/documentation/dev-manual/debugging.rst
index 0f6e9d1d7e85..8412c997a51e 100644
--- a/documentation/dev-manual/debugging.rst
+++ b/documentation/dev-manual/debugging.rst
@@ -810,7 +810,7 @@ be visible. In this case, there is a missing dependency for the ``neard``
Makefile target. Here is some abbreviated, sample output with the
missing dependency clearly visible at the end::
- i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/scott-lenovo/......
+ i586-poky-linux-gcc -m32 -march=i586 --sysroot=<path/to/sysroot>
.
.
.
@@ -1114,11 +1114,11 @@ debugger.
After running gdbserver on the target, you need to run Gdb on the
host and configure it and connect to the target. Use these commands::
- $ cd directory-holding-the-debugfs-directory
- $ arch-gdb
+ $ cd <debugfs-directory>
+ $ <arch>-gdb
(gdb) set sysroot debugfs
(gdb) set substitute-path /usr/src/debug debugfs/usr/src/debug
- (gdb) target remote IP-of-target:1234
+ (gdb) target remote <IP-of-target>:1234
At this
point, everything should automatically load (i.e. matching binaries,
diff --git a/documentation/migration-guides/migration-5.2.rst b/documentation/migration-guides/migration-5.2.rst
index 77a11fe27047..0c888136494e 100644
--- a/documentation/migration-guides/migration-5.2.rst
+++ b/documentation/migration-guides/migration-5.2.rst
@@ -193,9 +193,9 @@ The support for having multiple Git revisions per URL in :term:`SRC_URI` was
removed from BitBake, which means the following syntax is not supported
anymore::
- SRC_URI = "git://some.host/somepath;bareclone=1;branch=branchX,branchY;name=nameX,nameY"
- SRCREV_nameX = "xxxxxxxxxxxxxxxxxxxx"
- SRCREV_nameY = "yyyyyyyyyyyyyyyyyyyy"
+ SRC_URI = "git://<some.host>/<somepath>;bareclone=1;branch=<branchX>,<branchY>;name=<nameX>,<nameY>"
+ SRCREV_<nameX> = "<revision SHA for nameX>"
+ SRCREV_<nameY> = "<revision SHA for nameY>"
This was rarely used in the core repositories because it would only ever make
sense for bare clones (the ``bareclone=1`` :term:`SRC_URI` option) where recipes
@@ -205,10 +205,10 @@ places.
If one of your recipes is using this mechanism, you can split the code source
fetching into two separate entries::
- SRC_URI = "git://some.host/somepath;bareclone=1;branch=branchX;name=nameX \
- git://some.host/somepath;bareclone=1;branch=branchY;name=nameY"
- SRCREV_nameX = "xxxxxxxxxxxxxxxxxxxx"
- SRCREV_nameY = "yyyyyyyyyyyyyyyyyyyy"
+ SRC_URI = "git://<some.host>/<somepath>;bareclone=1;branch=<branchX>;name=<nameX> \
+ git://<some.host>/<somepath>;bareclone=1;branch=<branchY>;name=<nameY>"
+ SRCREV_<nameX> = "<revision SHA for nameX>"
+ SRCREV_<nameY> = "<revision SHA for nameY>"
Git fetcher: Branch parameter now required in :term:`SRC_URI`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -216,7 +216,7 @@ Git fetcher: Branch parameter now required in :term:`SRC_URI`
The ``branch`` parameter is now required when specifying a Git repository in
:term:`SRC_URI`, for example::
- SRC_URI = "git://some.host/somepath;branch=branchX"
+ SRC_URI = "git://<some.host>/<somepath>;branch=<branchX>"
A missing ``branch`` parameter used to produce a warning, and will now produce
an error.
diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst
index 4aa95d8e0499..62c3b707b9ff 100644
--- a/documentation/ref-manual/devtool-reference.rst
+++ b/documentation/ref-manual/devtool-reference.rst
@@ -474,7 +474,7 @@ This is roughly equivalent to the ``devtool update-recipe`` command followed by
the ``devtool reset`` command. The changes must have been committed to the git
repository created by ``devtool``. Here is an example::
- $ devtool finish recipe /path/to/custom/layer
+ $ devtool finish <recipe> <path/to/custom/layer>
.. _devtool-building-your-recipe:
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index c050c422bffc..7ba5c48fd8ed 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -162,7 +162,7 @@ system and gives an overview of their function and contents.
ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is the default.
ARCHIVER_MODE[src] = "configured" # Uses configured source files.
ARCHIVER_MODE[diff] = "1" # Uses patches between do_unpack and do_patch.
- ARCHIVER_MODE[diff-exclude] ?= "file file ..." # Lists files and directories to exclude from diff.
+ ARCHIVER_MODE[diff-exclude] ?= "<file> <file> ..." # Lists files and directories to exclude from diff.
ARCHIVER_MODE[dumpdata] = "1" # Uses environment data.
ARCHIVER_MODE[recipe] = "1" # Uses recipe and include files.
--
2.50.0.173.g8b6f19ccfc3a
^ permalink raw reply related [flat|nested] 11+ messages in thread* [PATCH v3 06/10] docs: remove real accounts from the examples
2026-09-24 17:28 [PATCH v3 00/10] docs: editorial repairs to the examples Trevor Woerner
` (4 preceding siblings ...)
2026-09-24 17:28 ` [PATCH v3 05/10] docs: mark the placeholders in examples Trevor Woerner
@ 2026-09-24 17:28 ` Trevor Woerner
2026-09-24 17:28 ` [PATCH v3 07/10] kernel-dev: give each example block one thing to hold Trevor Woerner
` (3 subsequent siblings)
9 siblings, 0 replies; 11+ messages in thread
From: Trevor Woerner @ 2026-09-24 17:28 UTC (permalink / raw)
To: docs
Examples across the manuals carry the account names of the people who
wrote them, in home directory paths and in a shell prompt that also
names a machine. Use "/home/user" and a bare "$", which is what the rest
of the manuals already do.
Two are left as they are: the autobuilder's service account, whose
paths are about autobuilder output rather than somebody's machine, and
a prompt whose command is a relative path, where the working directory
the prompt carries is what says where the command runs.
AI-Generated: codex/claude-opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
changes in v3:
- the setup-layers prompt keeps its path, which is what says where the
relative command runs
changes in v2:
- rebased on master-next; no other change
---
documentation/dev-manual/debugging.rst | 4 +-
documentation/dev-manual/layers.rst | 10 ++---
documentation/dev-manual/qemu.rst | 2 +-
.../dev-manual/upgrading-recipes.rst | 18 ++++----
documentation/dev-manual/wic.rst | 44 +++++++++----------
documentation/kernel-dev/common.rst | 16 +++----
documentation/profile-manual/usage.rst | 2 +-
.../ref-manual/devtool-reference.rst | 6 +--
documentation/ref-manual/faq.rst | 6 +--
documentation/ref-manual/variables.rst | 8 ++--
documentation/sdk-manual/extensible.rst | 6 +--
11 files changed, 61 insertions(+), 61 deletions(-)
diff --git a/documentation/dev-manual/debugging.rst b/documentation/dev-manual/debugging.rst
index 8412c997a51e..62e19a6c8a28 100644
--- a/documentation/dev-manual/debugging.rst
+++ b/documentation/dev-manual/debugging.rst
@@ -144,7 +144,7 @@ helpful during debugging.
Variables that are exported to the environment are preceded by
``export`` in the output of ``bitbake-getvar``. See the following example::
- export CC="i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/ulf/poky/build/tmp/sysroots/qemux86"
+ export CC="i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/user/poky/build/tmp/sysroots/qemux86"
Shell functions and tasks can also be inspected with the same mechanism::
@@ -522,7 +522,7 @@ task dependency mechanisms.
.. code-block:: none
- WARNING: /home/ulf/openembedded-core/meta/recipes-sato/matchbox-desktop/matchbox-desktop_2.1.bb.do_compile is tainted from a forced run
+ WARNING: /home/user/openembedded-core/meta/recipes-sato/matchbox-desktop/matchbox-desktop_2.1.bb.do_compile is tainted from a forced run
The purpose of the warning is to let you know that the work directory
diff --git a/documentation/dev-manual/layers.rst b/documentation/dev-manual/layers.rst
index 185a63feb700..5c8bf32b41fc 100644
--- a/documentation/dev-manual/layers.rst
+++ b/documentation/dev-manual/layers.rst
@@ -916,11 +916,11 @@ shows the layers that are in your :ref:`structure-build-conf-bblayers.conf` file
NOTE: Starting bitbake server...
layer path priority
==============================================================================================
- meta /home/scottrif/bitbake-builds/layers/openembedded-core/meta 5
- meta-poky /home/scottrif/bitbake-builds/layers/meta-yocto/meta-poky 5
- meta-yocto-bsp /home/scottrif/bitbake-builds/layers/meta-yocto/meta-yocto-bsp 5
- workspace /home/scottrif/bitbake-builds/build/workspace 99
- meta-scottrif /home/scottrif/bitbake-builds/build/meta-scottrif 6
+ meta /home/user/bitbake-builds/layers/openembedded-core/meta 5
+ meta-poky /home/user/bitbake-builds/layers/meta-yocto/meta-poky 5
+ meta-yocto-bsp /home/user/bitbake-builds/layers/meta-yocto/meta-yocto-bsp 5
+ workspace /home/user/bitbake-builds/build/workspace 99
+ meta-scottrif /home/user/bitbake-builds/build/meta-scottrif 6
Adding the layer to this file
enables the build system to locate the layer during the build.
diff --git a/documentation/dev-manual/qemu.rst b/documentation/dev-manual/qemu.rst
index 6d092b2d2034..d7e0b2f2f44f 100644
--- a/documentation/dev-manual/qemu.rst
+++ b/documentation/dev-manual/qemu.rst
@@ -151,7 +151,7 @@ available. Follow these general steps to run QEMU:
determines the QEMU architecture (`MACHINE`) to be "qemux86-64" and
the root filesystem type to be "vmdk"::
- $ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86-64.wic.vmdk
+ $ runqemu /home/user/vm/core-image-minimal-qemux86-64.wic.vmdk
Switching Between Consoles
==========================
diff --git a/documentation/dev-manual/upgrading-recipes.rst b/documentation/dev-manual/upgrading-recipes.rst
index 0bdc1351ec7f..f4b9df241093 100644
--- a/documentation/dev-manual/upgrading-recipes.rst
+++ b/documentation/dev-manual/upgrading-recipes.rst
@@ -244,12 +244,12 @@ script. For example, suppose you use the ``nano.bb`` recipe from the
``meta-oe`` layer in the ``meta-openembedded`` repository. For this
example, assume that the layer has been cloned into following area::
- /home/scottrif/bitbake-builds/layers/meta-openembedded
+ /home/user/bitbake-builds/layers/meta-openembedded
The following command from your :term:`Build Directory` adds the layer to
your build configuration (i.e. ``${BUILDDIR}/conf/bblayers.conf``)::
- $ bitbake-layers add-layer /home/scottrif/bitbake-builds/layers/meta-openembedded/meta-oe
+ $ bitbake-layers add-layer /home/user/bitbake-builds/layers/meta-openembedded/meta-oe
NOTE: Starting bitbake server...
Parsing recipes: 100% |##########################################| Time: 0:00:55
Parsing of 1431 .bb files complete (0 cached, 1431 parsed). 2040 targets, 56 skipped, 0 masked, 0 errors.
@@ -265,7 +265,7 @@ directory automatically upgrades the recipe for you::
$ devtool upgrade nano -V 2.9.3
NOTE: Starting bitbake server...
- NOTE: Creating workspace layer in /home/scottrif/bitbake-builds/build/workspace
+ NOTE: Creating workspace layer in /home/user/bitbake-builds/build/workspace
Parsing recipes: 100% |##########################################| Time: 0:00:46
Parsing of 1431 .bb files complete (0 cached, 1431 parsed). 2040 targets, 56 skipped, 0 masked, 0 errors.
NOTE: Extracting current version source...
@@ -277,8 +277,8 @@ directory automatically upgrades the recipe for you::
NOTE: Executing RunQueue Tasks
NOTE: Tasks Summary: Attempted 74 tasks of which 72 didn't need to be rerun and all succeeded.
Adding changed files: 100% |#####################################| Time: 0:00:00
- NOTE: Upgraded source extracted to /home/scottrif/bitbake-builds/build/workspace/sources/nano
- NOTE: New recipe is /home/scottrif/bitbake-builds/build/workspace/recipes/nano/nano_2.9.3.bb
+ NOTE: Upgraded source extracted to /home/user/bitbake-builds/build/workspace/sources/nano
+ NOTE: New recipe is /home/user/bitbake-builds/build/workspace/recipes/nano/nano_2.9.3.bb
.. note::
@@ -300,7 +300,7 @@ newly upgraded recipe::
.
NOTE: Executing SetScene Tasks
NOTE: Executing RunQueue Tasks
- NOTE: nano: compiling from external source tree /home/scottrif/bitbake-builds/build/workspace/sources/nano
+ NOTE: nano: compiling from external source tree /home/user/bitbake-builds/build/workspace/sources/nano
NOTE: Tasks Summary: Attempted 520 tasks of which 304 didn't need to be rerun and all succeeded.
Within the ``devtool upgrade`` workflow, you can
@@ -321,9 +321,9 @@ directory::
Parsing of 1432 .bb files complete (1431 cached, 1 parsed). 2041 targets, 56 skipped, 0 masked, 0 errors.
NOTE: Adding new patch 0001-nano.bb-Stuff-I-changed-when-upgrading-nano.bb.patch
NOTE: Updating recipe nano_2.9.3.bb
- NOTE: Removing file /home/scottrif/bitbake-builds/layers/meta-openembedded/meta-oe/recipes-support/nano/nano_2.7.4.bb
- NOTE: Moving recipe file to /home/scottrif/bitbake-builds/layers/meta-openembedded/meta-oe/recipes-support/nano
- NOTE: Leaving source tree /home/scottrif/bitbake-builds/build/workspace/sources/nano as-is; if you no longer need it then please delete it manually
+ NOTE: Removing file /home/user/bitbake-builds/layers/meta-openembedded/meta-oe/recipes-support/nano/nano_2.7.4.bb
+ NOTE: Moving recipe file to /home/user/bitbake-builds/layers/meta-openembedded/meta-oe/recipes-support/nano
+ NOTE: Leaving source tree /home/user/bitbake-builds/build/workspace/sources/nano as-is; if you no longer need it then please delete it manually
Using the ``devtool finish`` command cleans up the workspace and creates a patch
diff --git a/documentation/dev-manual/wic.rst b/documentation/dev-manual/wic.rst
index c13655f8730a..9161122d3166 100644
--- a/documentation/dev-manual/wic.rst
+++ b/documentation/dev-manual/wic.rst
@@ -520,13 +520,13 @@ file:
./mkefidisk-201804191017-sda.direct
The following build artifacts were used to create the image(s):
- ROOTFS_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs
- BOOTIMG_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
- KERNEL_DIR: /home/stephano/yocto/build/tmp-glibc/deploy/images/qemux86
- NATIVE_SYSROOT: /home/stephano/yocto/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native
+ ROOTFS_DIR: /home/user/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs
+ BOOTIMG_DIR: /home/user/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
+ KERNEL_DIR: /home/user/yocto/build/tmp-glibc/deploy/images/qemux86
+ NATIVE_SYSROOT: /home/user/yocto/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native
INFO: The image(s) were created using OE kickstart file:
- /home/stephano/yocto/openembedded-core/files/wic/mkefidisk.wks
+ /home/user/yocto/openembedded-core/files/wic/mkefidisk.wks
The previous example shows the easiest way to create an image by running
in cooked mode and supplying a kickstart file and the "-e" option to
@@ -590,8 +590,8 @@ the lines that specify the target disk from which to boot:
.. code-block:: console
- $ cp /home/stephano/yocto/openembedded-core/files/wic/directdisk-gpt.wks \
- /home/stephano/yocto/openembedded-core/files/wic/directdisksdb-gpt.wks
+ $ cp /home/user/yocto/openembedded-core/files/wic/directdisk-gpt.wks \
+ /home/user/yocto/openembedded-core/files/wic/directdisksdb-gpt.wks
Next, the example modifies the ``directdisksdb-gpt.wks`` file and
changes all instances of "``--ondisk sda``" to "``--ondisk sdb``". The
@@ -625,13 +625,13 @@ Computing (nuc) :term:`MACHINE`:
./directdisksdb-gpt-201710090938-sdb.direct
The following build artifacts were used to create the image(s):
- ROOTFS_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs
- BOOTIMG_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
- KERNEL_DIR: /home/stephano/yocto/build/tmp-glibc/deploy/images/qemux86
- NATIVE_SYSROOT: /home/stephano/yocto/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native
+ ROOTFS_DIR: /home/user/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs
+ BOOTIMG_DIR: /home/user/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
+ KERNEL_DIR: /home/user/yocto/build/tmp-glibc/deploy/images/qemux86
+ NATIVE_SYSROOT: /home/user/yocto/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native
INFO: The image(s) were created using OE kickstart file:
- /home/stephano/yocto/openembedded-core/files/wic/directdisksdb-gpt.wks
+ /home/user/yocto/openembedded-core/files/wic/directdisksdb-gpt.wks
Continuing with the example, you can now directly ``dd`` the image to a
USB stick, or whatever media for which you built your image, and boot
@@ -655,22 +655,22 @@ default output directory, which is the current directory:
.. code-block:: console
- $ wic create test.wks -o /home/stephano/testwic \
- --rootfs-dir /home/stephano/yocto/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/rootfs \
- --bootimg-dir /home/stephano/yocto/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share \
- --kernel-dir /home/stephano/yocto/build/tmp/deploy/images/qemux86 \
- --native-sysroot /home/stephano/yocto/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native
+ $ wic create test.wks -o /home/user/testwic \
+ --rootfs-dir /home/user/yocto/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/rootfs \
+ --bootimg-dir /home/user/yocto/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share \
+ --kernel-dir /home/user/yocto/build/tmp/deploy/images/qemux86 \
+ --native-sysroot /home/user/yocto/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native
INFO: Creating image(s)...
INFO: The new image(s) can be found here:
- /home/stephano/testwic/test-201710091445-sdb.direct
+ /home/user/testwic/test-201710091445-sdb.direct
The following build artifacts were used to create the image(s):
- ROOTFS_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs
- BOOTIMG_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
- KERNEL_DIR: /home/stephano/yocto/build/tmp-glibc/deploy/images/qemux86
- NATIVE_SYSROOT: /home/stephano/yocto/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native
+ ROOTFS_DIR: /home/user/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs
+ BOOTIMG_DIR: /home/user/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
+ KERNEL_DIR: /home/user/yocto/build/tmp-glibc/deploy/images/qemux86
+ NATIVE_SYSROOT: /home/user/yocto/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native
INFO: The image(s) were created using OE kickstart file:
test.wks
diff --git a/documentation/kernel-dev/common.rst b/documentation/kernel-dev/common.rst
index 3de61cab08d6..c478e64d6577 100644
--- a/documentation/kernel-dev/common.rst
+++ b/documentation/kernel-dev/common.rst
@@ -1250,32 +1250,32 @@ Here is sample output from the :ref:`ref-tasks-kernel_configcheck` task:
---------- CONFIG_X86_TSC -----------------
Config: CONFIG_X86_TSC
- From: /home/scottrif/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc-cpu.cfg
+ From: /home/user/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc-cpu.cfg
Requested value: CONFIG_X86_TSC=y
Actual value:
---------- CONFIG_X86_BIGSMP -----------------
Config: CONFIG_X86_BIGSMP
- From: /home/scottrif/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
- /home/scottrif/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
+ From: /home/user/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
+ /home/user/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
Requested value: # CONFIG_X86_BIGSMP is not set
Actual value:
---------- CONFIG_NR_CPUS -----------------
Config: CONFIG_NR_CPUS
- From: /home/scottrif/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
- /home/scottrif/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc.cfg
- /home/scottrif/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
+ From: /home/user/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
+ /home/user/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc.cfg
+ /home/user/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
Requested value: CONFIG_NR_CPUS=8
Actual value: CONFIG_NR_CPUS=1
---------- CONFIG_SCHED_SMT -----------------
Config: CONFIG_SCHED_SMT
- From: /home/scottrif/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
- /home/scottrif/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
+ From: /home/user/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
+ /home/user/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
Requested value: CONFIG_SCHED_SMT=y
Actual value:
diff --git a/documentation/profile-manual/usage.rst b/documentation/profile-manual/usage.rst
index 4efaa6d10fce..7fdbe41da5e7 100644
--- a/documentation/profile-manual/usage.rst
+++ b/documentation/profile-manual/usage.rst
@@ -322,7 +322,7 @@ debug packages once built can be found in ``build/tmp/deploy/rpm/*``
on the host system. Find the ``busybox-dbg-...rpm`` file and copy it
to the target. For example::
- [trz@empanada core2]$ scp /home/trz/yocto/crownbay-tracing-dbg/build/tmp/deploy/rpm/core2_32/busybox-dbg-1.20.2-r2.core2_32.rpm root@192.168.1.31:
+ $ scp /home/user/yocto/crownbay-tracing-dbg/build/tmp/deploy/rpm/core2_32/busybox-dbg-1.20.2-r2.core2_32.rpm root@192.168.1.31:
busybox-dbg-1.20.2-r2.core2_32.rpm 100% 1826KB 1.8MB/s 00:01
Now install the debug RPM on the target::
diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst
index 62c3b707b9ff..c8ca7bad8c9c 100644
--- a/documentation/ref-manual/devtool-reference.rst
+++ b/documentation/ref-manual/devtool-reference.rst
@@ -460,7 +460,7 @@ Here is an example that resets the workspace directory that contains the
$ devtool reset mtr
NOTE: Cleaning sysroot for recipe mtr...
- NOTE: Leaving source tree /home/scottrif/bitbake-builds/build/workspace/sources/mtr as-is; if you no longer need it then please delete it manually
+ NOTE: Leaving source tree /home/user/bitbake-builds/build/workspace/sources/mtr as-is; if you no longer need it then please delete it manually
.. _devtool-finish-working-on-a-recipe:
@@ -612,7 +612,7 @@ You can create a workspace layer anywhere by supplying a pathname with
the command. The following command creates a new workspace layer named
"new-workspace"::
- $ devtool create-workspace /home/scottrif/new-workspace
+ $ devtool create-workspace /home/user/new-workspace
.. _devtool-get-the-status-of-the-recipes-in-your-workspace:
@@ -632,7 +632,7 @@ Here is sample output after using
to create and add the ``mtr_0.86.bb`` recipe to the ``workspace`` directory::
$ devtool status
- mtr:/home/scottrif/bitbake-builds/build/workspace/sources/mtr (/home/scottrif/bitbake-builds/build/workspace/recipes/mtr/mtr_0.86.bb)
+ mtr:/home/user/bitbake-builds/build/workspace/sources/mtr (/home/user/bitbake-builds/build/workspace/recipes/mtr/mtr_0.86.bb)
.. _devtool-search-for-available-target-recipes:
diff --git a/documentation/ref-manual/faq.rst b/documentation/ref-manual/faq.rst
index f8e047e27fed..3646286a6e0c 100644
--- a/documentation/ref-manual/faq.rst
+++ b/documentation/ref-manual/faq.rst
@@ -461,11 +461,11 @@ and related variables. To better understand this, consider the following
two paths (artificially broken across lines for readability) where the
first is relatively normal and the second is not::
- /home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/
+ /home/user/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/
1.2.8-r0/sysroot-destdir/usr/bin
- /home/maxtothemax/poky-bootchart2/build/tmp/work/x86_64-linux/
- zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/
+ /home/user/poky-bootchart2/build/tmp/work/x86_64-linux/
+ zlib-native/1.2.8-r0/sysroot-destdir/home/user/poky-bootchart2/
build/tmp/sysroots/x86_64-linux/usr/bin
Even if the paths look unusual, they both are correct --- the first for
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 7ba5c48fd8ed..ce17d713f399 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -888,10 +888,10 @@ system and gives an overview of their function and contents.
Here is an example::
BBLAYERS = " \
- /home/scottrif/bitbake-builds/layers/meta \
- /home/scottrif/bitbake-builds/layers/meta-poky \
- /home/scottrif/bitbake-builds/layers/meta-yocto-bsp \
- /home/scottrif/bitbake-builds/layers/meta-mykernel \
+ /home/user/bitbake-builds/layers/meta \
+ /home/user/bitbake-builds/layers/meta-poky \
+ /home/user/bitbake-builds/layers/meta-yocto-bsp \
+ /home/user/bitbake-builds/layers/meta-mykernel \
"
This example enables four layers, one of which is a custom,
diff --git a/documentation/sdk-manual/extensible.rst b/documentation/sdk-manual/extensible.rst
index 0eb9eda8d82a..8b8034707eab 100644
--- a/documentation/sdk-manual/extensible.rst
+++ b/documentation/sdk-manual/extensible.rst
@@ -149,7 +149,7 @@ architecture. The example assumes the SDK installer is located in
Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.5
==========================================================================
Enter target directory for SDK (default: poky_sdk):
- You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed [Y/n]? Y
+ You are about to install the SDK to "/home/user/poky_sdk". Proceed [Y/n]? Y
Extracting SDK..............done
Setting it up...
Extracting buildtools...
@@ -162,7 +162,7 @@ architecture. The example assumes the SDK installer is located in
done
SDK has been successfully set up and is ready to be used.
Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
- $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux
+ $ . /home/user/poky_sdk/environment-setup-core2-64-poky-linux
.. note::
@@ -197,7 +197,7 @@ script is for an IA-based target machine using i586 tuning:
.. code-block:: console
- $ cd /home/scottrif/poky_sdk
+ $ cd /home/user/poky_sdk
$ source environment-setup-core2-64-poky-linux
SDK environment now set up; additionally you may now run devtool to perform development tasks.
Run devtool --help for further details.
--
2.50.0.173.g8b6f19ccfc3a
^ permalink raw reply related [flat|nested] 11+ messages in thread* [PATCH v3 07/10] kernel-dev: give each example block one thing to hold
2026-09-24 17:28 [PATCH v3 00/10] docs: editorial repairs to the examples Trevor Woerner
` (5 preceding siblings ...)
2026-09-24 17:28 ` [PATCH v3 06/10] docs: remove real accounts from the examples Trevor Woerner
@ 2026-09-24 17:28 ` Trevor Woerner
2026-09-24 17:28 ` [PATCH v3 08/10] ref-manual: put the ARCHIVER_MODE comments on their own lines Trevor Woerner
` (2 subsequent siblings)
9 siblings, 0 replies; 11+ messages in thread
From: Trevor Woerner @ 2026-09-24 17:28 UTC (permalink / raw)
To: docs; +Cc: Quentin Schulz
Several kernel metadata examples put a filename label inside the block,
and some go on to hold more than one file, in more than one language,
under a single "::". A block shaped that way is not any one language, so
it can only ever be shown unhighlighted.
Split them into a block each, dedent what is left, and move the
filename to the code-block caption, which keeps it attached to the block
it names and renders it inside the block's frame. The theme centres a
caption in italics, which reads as prose, so it is restyled to look like
the filename it is.
AI-Generated: codex/claude-opus 5 (xhigh)
Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de> # rST
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
changes in v3:
- none
changes in v2:
- the caption takes the theme's whole font stack; the shortened copy
dropped Liberation Mono, which is why it rendered in a different face
---
documentation/kernel-dev/advanced.rst | 139 ++++++++++--------
.../sphinx-static/theme_overrides.css | 28 ++++
2 files changed, 104 insertions(+), 63 deletions(-)
diff --git a/documentation/kernel-dev/advanced.rst b/documentation/kernel-dev/advanced.rst
index 321033b7bd49..ecd0137fa5fd 100644
--- a/documentation/kernel-dev/advanced.rst
+++ b/documentation/kernel-dev/advanced.rst
@@ -216,24 +216,28 @@ used with the ``linux-yocto-4.12`` kernel as defined outside of the
recipe space (i.e. ``yocto-kernel-cache``). This Metadata consists of
two files: ``smp.scc`` and ``smp.cfg``. You can find these files in the
``cfg`` directory of the ``yocto-4.12`` branch in the
-``yocto-kernel-cache`` Git repository::
+``yocto-kernel-cache`` Git repository.
+
+.. code-block::
+ :caption: cfg/smp.scc
+
+ define KFEATURE_DESCRIPTION "Enable SMP for 32 bit builds"
+ define KFEATURE_COMPATIBILITY all
- cfg/smp.scc:
- define KFEATURE_DESCRIPTION "Enable SMP for 32 bit builds"
- define KFEATURE_COMPATIBILITY all
+ kconf hardware smp.cfg
- kconf hardware smp.cfg
+.. code-block::
+ :caption: cfg/smp.cfg
- cfg/smp.cfg:
- CONFIG_SMP=y
- CONFIG_SCHED_SMT=y
- # Increase default NR_CPUS from 8 to 64 so that platform with
- # more than 8 processors can be all activated at boot time
- CONFIG_NR_CPUS=64
- # The following is needed when setting NR_CPUS to something
- # greater than 8 on x86 architectures, it should be automatically
- # disregarded by Kconfig when using a different arch
- CONFIG_X86_BIGSMP=y
+ CONFIG_SMP=y
+ CONFIG_SCHED_SMT=y
+ # Increase default NR_CPUS from 8 to 64 so that platform with
+ # more than 8 processors can be all activated at boot time
+ CONFIG_NR_CPUS=64
+ # The following is needed when setting NR_CPUS to something
+ # greater than 8 on x86 architectures, it should be automatically
+ # disregarded by Kconfig when using a different arch
+ CONFIG_X86_BIGSMP=y
You can find general information on configuration
fragment files in the ":ref:`kernel-dev/common:creating configuration fragments`" section.
@@ -278,36 +282,39 @@ kernel as defined outside of the recipe space (i.e.
in the ``patches/build`` directory of the ``yocto-4.12`` branch in the
``yocto-kernel-cache`` Git repository.
-The following listings show the ``build.scc`` file and part of the
-``modpost-mask-trivial-warnings.patch`` file::
+.. code-block::
+ :caption: patches/build/build.scc
- patches/build/build.scc:
- patch arm-serialize-build-targets.patch
- patch powerpc-serialize-image-targets.patch
- patch kbuild-exclude-meta-directory-from-distclean-processi.patch
+ patch arm-serialize-build-targets.patch
+ patch powerpc-serialize-image-targets.patch
+ patch kbuild-exclude-meta-directory-from-distclean-processi.patch
- # applied by kgit
- # patch kbuild-add-meta-files-to-the-ignore-li.patch
+ # applied by kgit
+ # patch kbuild-add-meta-files-to-the-ignore-li.patch
- patch modpost-mask-trivial-warnings.patch
- patch menuconfig-check-lxdiaglog.sh-Allow-specification-of.patch
+ patch modpost-mask-trivial-warnings.patch
+ patch menuconfig-check-lxdiaglog.sh-Allow-specification-of.patch
- patches/build/modpost-mask-trivial-warnings.patch:
- From bd48931bc142bdd104668f3a062a1f22600aae61 Mon Sep 17 00:00:00 2001
- From: Paul Gortmaker <paul.gortmaker@windriver.com>
- Date: Sun, 25 Jan 2009 17:58:09 -0500
- Subject: [PATCH] modpost: mask trivial warnings
+and part of the patch it names:
- Newer HOSTCC will complain about various stdio fcns because
- .
- .
- .
- char *dump_write = NULL, *files_source = NULL;
- int opt;
- --
- 2.10.1
+.. code-block::
+ :caption: patches/build/modpost-mask-trivial-warnings.patch
- generated by cgit v0.10.2 at 2017-09-28 15:23:23 (GMT)
+ From bd48931bc142bdd104668f3a062a1f22600aae61 Mon Sep 17 00:00:00 2001
+ From: Paul Gortmaker <paul.gortmaker@windriver.com>
+ Date: Sun, 25 Jan 2009 17:58:09 -0500
+ Subject: [PATCH] modpost: mask trivial warnings
+
+ Newer HOSTCC will complain about various stdio fcns because
+ .
+ .
+ .
+ char *dump_write = NULL, *files_source = NULL;
+ int opt;
+ --
+ 2.10.1
+
+ generated by cgit v0.10.2 at 2017-09-28 15:23:23 (GMT)
The description file can
include multiple patch statements where each statement handles a single
@@ -325,16 +332,18 @@ Features
Features are complex kernel Metadata types that consist of configuration
fragments, patches, and possibly other feature description files. As an
-example, consider the following generic listing::
+example, consider the following generic listing:
+
+.. code-block::
+ :caption: features/myfeature.scc
- features/myfeature.scc
- define KFEATURE_DESCRIPTION "Enable myfeature"
+ define KFEATURE_DESCRIPTION "Enable myfeature"
- patch 0001-myfeature-core.patch
- patch 0002-myfeature-interface.patch
+ patch 0001-myfeature-core.patch
+ patch 0002-myfeature-interface.patch
- include cfg/myfeature_dependency.scc
- kconf non-hardware myfeature.cfg
+ include cfg/myfeature_dependency.scc
+ kconf non-hardware myfeature.cfg
This example shows how the ``patch`` and ``kconf`` commands are used as well
as how an additional feature description file is included with the
@@ -873,17 +882,19 @@ new branch as the :term:`KBRANCH` to use for the board as follows::
KBRANCH = "mynewbranch"
Another method is to use the ``branch`` command in the BSP
-description::
+description:
- mybsp.scc:
- define KMACHINE mybsp
- define KTYPE standard
- define KARCH i386
- include standard.scc
+.. code-block::
+ :caption: mybsp.scc
- branch mynewbranch
+ define KMACHINE mybsp
+ define KTYPE standard
+ define KARCH i386
+ include standard.scc
+
+ branch mynewbranch
- include mybsp-hw.scc
+ include mybsp-hw.scc
If you find yourself with numerous branches, you might consider using a
hierarchical branching system similar to what the Yocto Linux Kernel Git
@@ -925,18 +936,20 @@ that have to be regularly updated. The Yocto Project Linux kernel tools
provide for this with the ``git merge`` command.
To merge a feature branch into a BSP, insert the ``git merge`` command
-after any ``branch`` commands::
+after any ``branch`` commands:
- mybsp.scc:
- define KMACHINE mybsp
- define KTYPE standard
- define KARCH i386
- include standard.scc
+.. code-block::
+ :caption: mybsp.scc
+
+ define KMACHINE mybsp
+ define KTYPE standard
+ define KARCH i386
+ include standard.scc
- branch mynewbranch
- git merge myfeature
+ branch mynewbranch
+ git merge myfeature
- include mybsp-hw.scc
+ include mybsp-hw.scc
SCC Description File Reference
==============================
diff --git a/documentation/sphinx-static/theme_overrides.css b/documentation/sphinx-static/theme_overrides.css
index f9e067239b8e..3912872e1890 100644
--- a/documentation/sphinx-static/theme_overrides.css
+++ b/documentation/sphinx-static/theme_overrides.css
@@ -107,6 +107,34 @@ section#welcome-to-the-yocto-project-documentation p.caption {
display: none;
}
+/* A code-block caption names the file the block came from, so it
+ should read as a filename rather than as prose, and sit on the block
+ it titles rather than floating above it. */
+.rst-content .literal-block-wrapper .code-block-caption {
+ font-style: normal;
+ font-family: SFMono-Regular, Menlo, Monaco, Consolas,
+ Liberation Mono, Courier New, Courier, monospace;
+ font-size: 80%;
+ text-align: left;
+ color: #e6edf3;
+ background: #2b3137;
+ padding: .45em .9em;
+ margin: 0;
+ line-height: 1.5;
+ border-radius: 4px 4px 0 0;
+}
+
+.rst-content .literal-block-wrapper .code-block-caption .headerlink {
+ color: #93a1ad;
+}
+
+/* No gap and no doubled border between a caption and its block. */
+.rst-content .literal-block-wrapper .code-block-caption + div[class^=highlight] {
+ margin-top: 0;
+ border-top: none;
+ border-radius: 0 0 4px 4px;
+}
+
@media screen {
.wy-nav-content {
max-width: 1000px;
--
2.50.0.173.g8b6f19ccfc3a
^ permalink raw reply related [flat|nested] 11+ messages in thread* [PATCH v3 08/10] ref-manual: put the ARCHIVER_MODE comments on their own lines
2026-09-24 17:28 [PATCH v3 00/10] docs: editorial repairs to the examples Trevor Woerner
` (6 preceding siblings ...)
2026-09-24 17:28 ` [PATCH v3 07/10] kernel-dev: give each example block one thing to hold Trevor Woerner
@ 2026-09-24 17:28 ` Trevor Woerner
2026-09-24 17:28 ` [PATCH v3 09/10] ref-manual: drop "partition" as a wic kickstart command Trevor Woerner
2026-09-24 17:28 ` [PATCH v3 10/10] dev-manual: indent a list continuation so the code block ends Trevor Woerner
9 siblings, 0 replies; 11+ messages in thread
From: Trevor Woerner @ 2026-09-24 17:28 UTC (permalink / raw)
To: docs; +Cc: Quentin Schulz
BitBake has no inline comments. A "#" after a value is not stripped and
does not end the statement: the parser simply fails to match the line, so
each of these varflag examples would be rejected outright if copied into
a configuration file.
Move each explanation to the line above the setting it describes, which
parses and reads the same.
AI-Generated: codex/claude-opus 5 (xhigh)
Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
changes in v3:
- a blank line separates each comment from the setting above it
changes in v2:
- the srpm varflag is no longer in this block, having been removed
upstream in d5216e3fd4be
---
documentation/ref-manual/variables.rst | 27 +++++++++++++++++++-------
1 file changed, 20 insertions(+), 7 deletions(-)
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index ce17d713f399..8f6f4e5998d5 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -158,13 +158,26 @@ system and gives an overview of their function and contents.
original source, configured source, and so forth by employing the
following variable flags (varflags)::
- ARCHIVER_MODE[src] = "original" # Uses original (unpacked) source files.
- ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is the default.
- ARCHIVER_MODE[src] = "configured" # Uses configured source files.
- ARCHIVER_MODE[diff] = "1" # Uses patches between do_unpack and do_patch.
- ARCHIVER_MODE[diff-exclude] ?= "<file> <file> ..." # Lists files and directories to exclude from diff.
- ARCHIVER_MODE[dumpdata] = "1" # Uses environment data.
- ARCHIVER_MODE[recipe] = "1" # Uses recipe and include files.
+ # Uses original (unpacked) source files.
+ ARCHIVER_MODE[src] = "original"
+
+ # Uses patched source files. This is the default.
+ ARCHIVER_MODE[src] = "patched"
+
+ # Uses configured source files.
+ ARCHIVER_MODE[src] = "configured"
+
+ # Uses patches between do_unpack and do_patch.
+ ARCHIVER_MODE[diff] = "1"
+
+ # Lists files and directories to exclude from diff.
+ ARCHIVER_MODE[diff-exclude] ?= "<file> <file> ..."
+
+ # Uses environment data.
+ ARCHIVER_MODE[dumpdata] = "1"
+
+ # Uses recipe and include files.
+ ARCHIVER_MODE[recipe] = "1"
For information on how the variable works, see the
``meta/classes/archiver.bbclass`` file in :term:`OpenEmbedded-Core
--
2.50.0.173.g8b6f19ccfc3a
^ permalink raw reply related [flat|nested] 11+ messages in thread* [PATCH v3 09/10] ref-manual: drop "partition" as a wic kickstart command
2026-09-24 17:28 [PATCH v3 00/10] docs: editorial repairs to the examples Trevor Woerner
` (7 preceding siblings ...)
2026-09-24 17:28 ` [PATCH v3 08/10] ref-manual: put the ARCHIVER_MODE comments on their own lines Trevor Woerner
@ 2026-09-24 17:28 ` Trevor Woerner
2026-09-24 17:28 ` [PATCH v3 10/10] dev-manual: indent a list continuation so the code block ends Trevor Woerner
9 siblings, 0 replies; 11+ messages in thread
From: Trevor Woerner @ 2026-09-24 17:28 UTC (permalink / raw)
To: docs
The kickstart reference documents "partition" as a synonym for "part".
wic does not accept it: its parser registers only part, bootloader, and
include, so a .wks line beginning "partition" fails with an
invalid-choice error.
The synonym was real while wic used a bundled pykickstart, whose command
table mapped both spellings to one handler. Replacing that with a parser
carrying only the options wic uses kept "part" alone, and the manual was
not updated to match.
AI-Generated: codex/claude-opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
changes in v3:
- back in the series: applied on 2026-09-22, then unapplied by the
master-next rewind
---
documentation/ref-manual/kickstart.rst | 9 ++++-----
documentation/ref-manual/variables.rst | 2 +-
2 files changed, 5 insertions(+), 6 deletions(-)
diff --git a/documentation/ref-manual/kickstart.rst b/documentation/ref-manual/kickstart.rst
index e7cba555a6e1..14aff6025f18 100644
--- a/documentation/ref-manual/kickstart.rst
+++ b/documentation/ref-manual/kickstart.rst
@@ -16,14 +16,13 @@ modifications to reflect Wic capabilities. You can see the original
documentation for those commands at the following link:
https://pykickstart.readthedocs.io/en/latest/kickstart-docs.html
-Command: part or partition
-==========================
+Command: part
+=============
-Either of these commands creates a partition on the system and uses the
+This command creates a partition on the system and uses the
following syntax::
part [mntpoint]
- partition [mntpoint]
If you do not
provide mntpoint, Wic creates a partition but does not mount it.
@@ -54,7 +53,7 @@ Here is an example that uses "/" as the mountpoint. The command uses
part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
Here is a list that describes other supported options you can use with
-the ``part`` and ``partition`` commands:
+the ``part`` command:
- ``--size``: The minimum partition size. Specify as an integer value
optionally followed by one of the units "k" / "K" for kibibyte,
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 8f6f4e5998d5..5339721f48b9 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -4587,7 +4587,7 @@ system and gives an overview of their function and contents.
When using Wic tool, beware that a second overhead factor is also applied.
This overhead value is defined by the ``--overhead-factor`` option, which
defaults to "1.3" when omitted. See the
- :ref:`ref-manual/kickstart:command: part or partition` chapter in
+ :ref:`ref-manual/kickstart:command: part` chapter in
:doc:`/ref-manual/kickstart` for details.
:term:`IMAGE_PKGTYPE`
--
2.50.0.173.g8b6f19ccfc3a
^ permalink raw reply related [flat|nested] 11+ messages in thread* [PATCH v3 10/10] dev-manual: indent a list continuation so the code block ends
2026-09-24 17:28 [PATCH v3 00/10] docs: editorial repairs to the examples Trevor Woerner
` (8 preceding siblings ...)
2026-09-24 17:28 ` [PATCH v3 09/10] ref-manual: drop "partition" as a wic kickstart command Trevor Woerner
@ 2026-09-24 17:28 ` Trevor Woerner
9 siblings, 0 replies; 11+ messages in thread
From: Trevor Woerner @ 2026-09-24 17:28 UTC (permalink / raw)
To: docs
The second line of the enumerated item is not indented, so the item ends
after its first line and the "::" opens a literal block at the top level.
Everything more indented then belongs to it: the assignment, the paragraph
explaining what packageformat may be, and the note beneath them. They
render as preformatted text inside the code box, and the note loses its
admonition styling.
AI-Generated: codex/claude-opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
changes in v3:
- back in the series: applied on 2026-09-22, then unapplied by the
master-next rewind
---
documentation/dev-manual/packages.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/documentation/dev-manual/packages.rst b/documentation/dev-manual/packages.rst
index 8cd90b9f25b1..380d806be041 100644
--- a/documentation/dev-manual/packages.rst
+++ b/documentation/dev-manual/packages.rst
@@ -561,7 +561,7 @@ to use. In your configuration, you use the
variable to specify the format:
#. Select the desired package format as follows from your
-:ref:`structure-build-conf-local.conf` or distro :term:`configuration file`::
+ :ref:`structure-build-conf-local.conf` or distro :term:`configuration file`::
PACKAGE_CLASSES ?= "package_packageformat"
--
2.50.0.173.g8b6f19ccfc3a
^ permalink raw reply related [flat|nested] 11+ messages in thread