[PATCH v1 2/3] doc: develop: Fix typos and wording in gdb.rst

[Alexander Dahl]

Hello Lothar,

Am Wed, Nov 20, 2024 at 11:11:23AM +0100 schrieb Lothar Rubusch:
> Hi, thank you all! This is outstanding, such a fast feedback! As I
> also just ran a tool over the texts, adjusted formatting and
> reverted/accepted some changes manually to my knowledge (I'm not a
> native speaker). Please, could you clarify the following?

What about mentioning the tool in the commit message then?

> 
> On Wed, Nov 20, 2024 at 8:15 AM Alexander Dahl <ada at thorsis.com> wrote:
> >
> > Hello Lothar,
> >
> > Am Tue, Nov 19, 2024 at 10:28:36PM +0000 schrieb Lothar Rubusch:
> > > Fix some typos and duplicate words in gdb.rst.
> > >
> > > Signed-off-by: Lothar Rubusch <l.rubusch at gmail.com>
> > > ---
> > >  doc/develop/gdb.rst | 14 +++++++-------
> > >  1 file changed, 7 insertions(+), 7 deletions(-)
> > >
> > > diff --git a/doc/develop/gdb.rst b/doc/develop/gdb.rst
> > > index 4e359c7f22..dc38435227 100644
> > > --- a/doc/develop/gdb.rst
> > > +++ b/doc/develop/gdb.rst
> > > @@ -8,12 +8,12 @@ Using a JTAG adapter it is possible to debug a running U-Boot with GDB.
> > >  A common way is to connect a debug adapter to the JTAG connector of your
> > >  board, run a GDB server, connect GDB to the GDB server, and use GDB as usual.
> > >
> > > -Similarly QEMU can provide a GDB server.
> > > +Similarly, QEMU can provide a GDB server.
> > >
> > >  Preparing build
> > >  ---------------
> > >
> > > -Building U-Boot with with reduced optimization (-Og) and without link time
> > > +Building U-Boot with reduced optimization (-Og) and without link time
> >
> > ack
> >
> > >  optimization is recommended for easier debugging::
> > >
> > >      CONFIG_CC_OPTIMIZE_FOR_DEBUG=y
> > > @@ -24,8 +24,8 @@ Otherwise build, install, and run U-Boot as usual.
> > >  Using OpenOCD as GDB server
> > >  ---------------------------
> > >
> > > -`OpenOCD <https://openocd.org/>`_ is an open source tool supporting hardware
> > > -debug probes, and providing a GDB server. It is readily available in major Linux
> > > +`OpenOCD <https://openocd.org/>`_ is an open-source tool supporting hardware
> > > +debug probes and provide a GDB server. It is readily available in major Linux
> >
> > NACK.  It would read "OpenOCD is a tool supporting x and provide y"
> > now.  This is most probably wrong?
> 
> I'm not sure if I got the point. If you can't find the time to answer,
> I'll simply revert this entire change and leave it as is, no prob.
> So, change 1) is "open source" to "open-source"; change 2) is a
> removal of the comma; and change 3) "providing" -> "provide". Do I
> understand you correctly, change 1) could be ok, where change 2) is to
> be left as is, and also change 3) has to be as is?

I have no strong opinion on 1).
I'm not sure about the comma in 2).

Let me explain 3) although I'm no native speaker as well.

You could split the previous sentence in two like this:

  OpenOCD is an open source tool supporting hardware debug probes.
  OpenOCD is an open source tool providing a GDB server.

After your change the first part stays the same, the second part
becomes:

  OpenOCD is an open source tool provide a GDB server.

or

  OpenOCD provide a GDB server.

It depends on how you interpret what parts the "and" connects (or
which redundant part can be omitted), but both variants sound just
wrong.  So if you can not convince us this is a real style improvement
in correct language, leave it as is.

Personally I think automated tools can help detecting language issues,
but the patch author should review changes carefully before sending
them to other developers.  ;-)

Greets
Alex

> 
> > >  distributions or you can build it from source.
> > >
> > >  Here is example of starting OpenOCD on Debian using a J-Link adapter and a
> > > @@ -124,7 +124,7 @@ with the command *bdinfo*:
> > >      Early malloc usage: cd8 / 2000
> > >
> > >  Look out for the line starting with *relocaddr* which has the address
> > > -you need, ``0x27f7a000`` in this case.
> > > +You need, ``0x27f7a000`` in this case.
> >
> > NACK.  These are not two sentences but one, containing "the address you
> > need".  Splitting that makes no sense.
> 
> Agree. This was already meantioned.