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

[Lothar Rubusch]

On Wed, Nov 20, 2024 at 11:26 AM Alexander Dahl <ada at thorsis.com> wrote:
>
> 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.

Thank you so much. I understand. My question was actually just about
confirmation,
and more about keeping 1) or not. Since 2) and 3) are pretty clear.
Sorry, I was not clear.

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

Agree.

Best,
L