[PATCH 1/5] doc: user: barebox: improved and consistent markup for console examples

[PATCH 1/5] doc: user: barebox: improved and consistent markup for console examples

[Enrico Jörns]

This removes some unexpected highlighting, like for 'done' in the 'git
clone' output.

* Consistently use 'console' type for console output.
  'sh' is for shell scripts.
* Prefix all commands with prompt symbol "$", to have proper
  highlighting of variables, etc.
  Sphinx will ensure the resulting HTML lines are still copy+pastable.

Signed-off-by: Enrico Jörns <ejo@pengutronix.de>
---
 Documentation/user/barebox.rst | 66 +++++++++++++++++-----------------
 1 file changed, 34 insertions(+), 32 deletions(-)

diff --git a/Documentation/user/barebox.rst b/Documentation/user/barebox.rst
index 338c2f5d03..983ebdee91 100644
--- a/Documentation/user/barebox.rst
+++ b/Documentation/user/barebox.rst
@@ -16,7 +16,7 @@ https://www.barebox.org/download/
 Development versions of barebox are accessible via Git. A local repository clone
 can be checked out as follows:
 
-.. code-block:: sh
+.. code-block:: console
 
   $ git clone git://git.pengutronix.de/git/barebox.git
   Cloning into 'barebox'...
@@ -34,7 +34,7 @@ barebox, this is the right branch to send patches against.
 If you want to see which patches are already selected for the next release,
 you can look at the ``next`` branch:
 
-.. code-block:: sh
+.. code-block:: console
 
   $ git checkout -b next origin/remotes/next
 
@@ -66,17 +66,17 @@ in your $PATH, just the prefix.
 
 Either export ``ARCH`` and ``CROSS_COMPILE`` once before working on barebox:
 
-.. code-block:: sh
+.. code-block:: console
 
-  export ARCH=arm
-  export CROSS_COMPILE=/path/to/arm-cortexa8-linux-gnueabihf-
-  make ...
+  $ export ARCH=arm
+  $ export CROSS_COMPILE=/path/to/arm-cortexa8-linux-gnueabihf-
+  $ make ...
 
 or add them to each invocation of the ``make`` command:
 
-.. code-block:: sh
+.. code-block:: console
 
-  ARCH=arm CROSS_COMPILE=/path/to/arm-cortexa8-linux-gnueabihf- make ...
+  $ ARCH=arm CROSS_COMPILE=/path/to/arm-cortexa8-linux-gnueabihf- make ...
 
 For readability, ARCH/CROSS_COMPILE are skipped from the following examples.
 
@@ -87,23 +87,23 @@ All configuration files can be found under the ``arch/${ARCH}/configs/``
 directory. For an overview of possible Make targets for your architecture,
 type:
 
-.. code-block:: sh
+.. code-block:: console
 
-  make help
+  $ make help
 
 Your output from ``make help`` will be based on the architecture you've
 selected via the ``ARCH`` variable. So if, for example, you had selected:
 
-.. code-block:: sh
+.. code-block:: console
 
-  export ARCH=mips
+  $ export ARCH=mips
 
 your help output would represent all of the generic (architecture-independent)
 targets, followed by the MIPS-specific ones:
 
-.. code-block:: sh
+.. code-block:: console
 
-  make [ARCH=mips] help
+  $ make [ARCH=mips] help
   ...
   ... list of generic targets ...
   ...
@@ -122,16 +122,16 @@ can't find your board in the list, it may be supported by one of the multi-board
 configs. As an example, this is the case for tegra_v7_defconfig and imx_v7_defconfig.
 Select your config with ``make <yourboard>_defconfig``:
 
-.. code-block:: sh
+.. code-block:: console
 
-  make imx_v7_defconfig
+  $ make imx_v7_defconfig
 
 The configuration can be further customized with one of the configuration frontends
 with the most popular being ``menuconfig``:
 
-.. code-block:: sh
+.. code-block:: console
 
-  make menuconfig
+  $ make menuconfig
 
 barebox uses the same configuration and build system as Linux (Kconfig,
 Kbuild), so you can use all the kernel config targets you already know, e.g.
@@ -149,9 +149,9 @@ Once you check out your barebox source directory, and before you do any
 configuration or building, set the environment variable ``KBUILD_OUTPUT``
 to point to your intended output directory, as in:
 
-.. code-block:: sh
+.. code-block:: console
 
-  export KBUILD_OUTPUT=.../my_barebox_build_directory
+  $ export KBUILD_OUTPUT=.../my_barebox_build_directory
 
 From that point on, all of the ``make`` commands you run in your source
 directory will generate their output in your specified output directory.
@@ -174,9 +174,9 @@ Compilation
 After barebox has been :ref:`configured <configuration>` it can be compiled
 simply with:
 
-.. code-block:: sh
+.. code-block:: console
 
-  make
+  $ make
 
 The resulting binary varies depending on the board barebox is compiled for.
 Without :ref:`multi_image` support the ``barebox-flash-image`` link will point
@@ -320,10 +320,12 @@ In addition to these barebox also builds host and target tools that are useful
 outside of barebox build: e.g. to manipulate the environment or to load an
 image over a boot ROM's USB recovery protocol. These tools may link against
 libraries, which are detected using ``PKG_CONFIG`` and ``CROSS_PKG_CONFIG``
-for native and cross build respectively. Their default values are::
+for native and cross build respectively. Their default values are:
+
+.. code-block:: console
 
-  PKG_CONFIG=pkg-config
-  CROSS_PKG_CONFIG=${CROSS_COMPILE}pkg-config
+  $ PKG_CONFIG=pkg-config
+  $ CROSS_PKG_CONFIG=${CROSS_COMPILE}pkg-config
 
 These can be overridden using environment or make variables.
 
@@ -340,9 +342,9 @@ about ``libusb-1.0``. This config won't build any target tools.
 
 .. code-block:: console
 
-  export ARCH=sandbox
-  make hosttools_defconfig
-  make scripts
+  $ export ARCH=sandbox
+  $ make hosttools_defconfig
+  $ make scripts
 
 Target Tools
 ^^^^^^^^^^^^
@@ -355,7 +357,7 @@ use. Example:
 
 .. code-block:: console
 
-  export ARCH=sandbox CROSS_COMPILE=aarch64-linux-gnu-
-  export CROSS_PKG_CONFIG=pkg-config
-  make targettools_defconfig
-  make scripts
+  $ export ARCH=sandbox CROSS_COMPILE=aarch64-linux-gnu-
+  $ export CROSS_PKG_CONFIG=pkg-config
+  $ make targettools_defconfig
+  $ make scripts
-- 
2.39.5

[PATCH 2/5] doc: user: devicetree: fix indentation and typo

[Enrico Jörns]

Signed-off-by: Enrico Jörns <ejo@pengutronix.de>
---
 Documentation/user/devicetree.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/user/devicetree.rst b/Documentation/user/devicetree.rst
index 9f46eee4ea..ea2945ab2b 100644
--- a/Documentation/user/devicetree.rst
+++ b/Documentation/user/devicetree.rst
@@ -86,7 +86,7 @@ overlays to.
 .. note:: Compiling a device tree discards label information by default. To be able
  to use phandles into the base device tree from inside an overlay, pass to dtc the
  ``-@`` option when compiling the base device tree.
-   This will populate ``/__symbols__`` in the base device tree.
+ This will populate ``/__symbols__`` in the base device tree.
 
  Having ``__fixups__`` in the overlay, but no ``__symbols__`` in the base device
  tree is not allowed: ``ERROR: of_resolver: __symbols__ missing from base devicetree``.
@@ -96,7 +96,7 @@ Device tree overlays on the live tree
 
 While the live tree can be patched by board code, barebox does not
 detect any changes to the live tree. To let the overlays have any effect, board
-code must make sure the live tree is patched before the devices are instanciated
+code must make sure the live tree is patched before the devices are instantiated
 from it.
 
 The ``CONFIG_OF_OVERLAY_LIVE`` option will need to be enabled to generate
-- 
2.39.5

[PATCH 3/5] doc: user: barebox: add markup for release scheme and update dates

[Enrico Jörns]

Makes the documentation look a bit more 2025ish.

Signed-off-by: Enrico Jörns <ejo@pengutronix.de>
---
 Documentation/user/barebox.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/user/barebox.rst b/Documentation/user/barebox.rst
index 983ebdee91..710af0d43f 100644
--- a/Documentation/user/barebox.rst
+++ b/Documentation/user/barebox.rst
@@ -5,9 +5,9 @@ Getting barebox
 ---------------
 
 barebox is released on a monthly basis. The version numbers use the format
-YYYY.MM.N, so 2014.06.0 is the monthly release for June 2014. Stable releases
+``YYYY.MM.N``, so ``2025.05.0`` is the monthly release for May 2025. Stable releases
 are done as needed to fix critical problems and are indicated by incrementing
-the suffix (for example 2014.06.1).
+the suffix (for example ``2025.05.1``).
 
 All releases can be downloaded from:
 
-- 
2.39.5

[PATCH 4/5] doc: conf.py: update copyright from 2022 to 2025

[Enrico Jörns]

Signed-off-by: Enrico Jörns <ejo@pengutronix.de>
---
 Documentation/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 5fb8b07c38..9b1aa26ef9 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -44,7 +44,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'barebox'
-copyright = u'2014–2022, The barebox project'
+copyright = u'2014–2025, The barebox project'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
-- 
2.39.5

[PATCH 5/5] doc: user: booting-linux: fix double code-block markup

[Enrico Jörns]

Signed-off-by: Enrico Jörns <ejo@pengutronix.de>
---
 Documentation/user/booting-linux.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/user/booting-linux.rst b/Documentation/user/booting-linux.rst
index 6c8d25a96c..2c23815c9f 100644
--- a/Documentation/user/booting-linux.rst
+++ b/Documentation/user/booting-linux.rst
@@ -163,7 +163,7 @@ setting the ``global.boot.default`` variable to ``mmc`` and then calling
 
 Especially for development, it can be useful to override only parts of
 the images used in a boot. To do so, set ``CONFIG_BOOT_OVERRIDE=y``
-and configure the overrides as arguments to the ``boot`` command::
+and configure the overrides as arguments to the ``boot`` command:
 
 .. code-block:: sh
 
-- 
2.39.5

Re: [PATCH 1/5] doc: user: barebox: improved and consistent markup for console examples

[Sascha Hauer]

On Tue, 27 May 2025 08:26:28 +0200, Enrico Jörns wrote:
> This removes some unexpected highlighting, like for 'done' in the 'git
> clone' output.
> 
> * Consistently use 'console' type for console output.
>   'sh' is for shell scripts.
> * Prefix all commands with prompt symbol "$", to have proper
>   highlighting of variables, etc.
>   Sphinx will ensure the resulting HTML lines are still copy+pastable.
> 
> [...]

Applied, thanks!

[1/5] doc: user: barebox: improved and consistent markup for console examples
      https://git.pengutronix.de/cgit/barebox/commit/?id=2681997ede77 (link may not be stable)
[2/5] doc: user: devicetree: fix indentation and typo
      https://git.pengutronix.de/cgit/barebox/commit/?id=2a18f3f6eb0a (link may not be stable)
[3/5] doc: user: barebox: add markup for release scheme and update dates
      https://git.pengutronix.de/cgit/barebox/commit/?id=b166f4244218 (link may not be stable)
[4/5] doc: conf.py: update copyright from 2022 to 2025
      https://git.pengutronix.de/cgit/barebox/commit/?id=c80080e091a2 (link may not be stable)
[5/5] doc: user: booting-linux: fix double code-block markup
      https://git.pengutronix.de/cgit/barebox/commit/?id=854a8b2b7a83 (link may not be stable)

Best regards,
-- 
Sascha Hauer <s.hauer@pengutronix.de>