[2/3] doc: stm32mp1: fix literal block markers (::)

Signed-off-by: Grzegorz Szymaszek <gszymaszek@short.pl>
---
 doc/board/st/stm32mp1.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

On 7/26/24 19:18, Grzegorz Szymaszek wrote:

Thanks for looking at improving this documentation.

Please, provide a commit message.

> Signed-off-by: Grzegorz Szymaszek <gszymaszek@short.pl>
> ---
>   doc/board/st/stm32mp1.rst | 4 ++--
>   1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/doc/board/st/stm32mp1.rst b/doc/board/st/stm32mp1.rst
> index 239e18b5e17..98167e80618 100644
> --- a/doc/board/st/stm32mp1.rst
> +++ b/doc/board/st/stm32mp1.rst
> @@ -265,7 +265,7 @@ Build Procedure
>        # make stm32mp15_defconfig
>        # make DEVICE_TREE=stm32mp157c-ev1-scmi all
>
> -    or without SCMI support
> +    or without SCMI support::

Either use

.. code-block:: bash

or

.. prompt:: bash $

>
>        # export KBUILD_OUTPUT=stm32mp15
>        # make stm32mp15_defconfig

# is the prompt for root. Please, do not suggest to build as root.

Please, do not start lines with a prompt as this does not allow to copy
multiple lines to a terminal. .. prompt:: allows you to display a prompt
which will not be copied. .. code-block:: avoids showing the prompt
which could be seen as distractive.

> @@ -796,7 +796,7 @@ You can update the boot device:
>   When the board is booting for nor0 or nand0,
>   only the MTD partition on the boot devices are available, for example:
>
> -- NOR (nor0 = alt 20, nor1 = alt 26) & NAND (nand0 = alt 27) :
> +- NOR (nor0 = alt 20, nor1 = alt 26) & NAND (nand0 = alt 27)::

ditto

>
>     $> dfu-util -d 0483:5720 -a 21 -D tf-a-stm32mp157c-ev1.stm32
>     $> dfu-util -d 0483:5720 -a 22 -D tf-a-stm32mp157c-ev1.stm32

Why '$>' is used as prompt here? Shouldn't this be '$'?

How about telling the user what dfu-util is and where to find it?
Does it relate to http://dfu-util.sourceforge.net?

Best regards

Heinrich

Hi Heinrich,

thank you for comprehensive review. I'll respond to the specific points
later, but there's one thing I feel I should explain. In this series I
intended to only fix/improve the reStructuredText/HTML syntax and then,
if the changes were approved, I would go with making the actual text
easier to understand, I have some drafts already prepared. So I'm not
sure if fixing, for example, unnecessary root prompts is really in scope
of this changeset.

On Wed, Jul 31, 2024 at 07:15:10AM +0200, Heinrich Schuchardt wrote:
> Please, provide a commit message.

(Two perhaps, not one.) Is it really necessary in case of such trivial
changes? See sending_patches.rst:

> Put a detailed description after the summary and blank line. If the
> summary line is sufficient to describe the change (e.g. it is a trivial
> spelling correction or whitespace update), you can omit the blank line
> and detailed description.


All the best

On Wed, Jul 31, 2024 at 06:11:43PM +0200, Grzegorz Szymaszek wrote:
> Hi Heinrich,
> 
> thank you for comprehensive review. I'll respond to the specific points
> later, but there's one thing I feel I should explain. In this series I
> intended to only fix/improve the reStructuredText/HTML syntax and then,
> if the changes were approved, I would go with making the actual text
> easier to understand, I have some drafts already prepared. So I'm not
> sure if fixing, for example, unnecessary root prompts is really in scope
> of this changeset.

A gentle ping, I'm still unsure how to approach the issue.

> On Wed, Jul 31, 2024 at 07:15:10AM +0200, Heinrich Schuchardt wrote:
> > Please, provide a commit message.
> 
> (Two perhaps, not one.) Is it really necessary in case of such trivial
> changes? See sending_patches.rst:
> 
> > Put a detailed description after the summary and blank line. If the
> > summary line is sufficient to describe the change (e.g. it is a trivial
> > spelling correction or whitespace update), you can omit the blank line
> > and detailed description.

Same here.