Re: [PATCH 0/1] docs: Fix numerous minor mistakes in grub.info

[Daniel Kiper]

On Thu, Apr 16, 2020 at 05:39:02PM +0200, Hans Ulrich Niedermann wrote:
> On Thu, 16 Apr 2020 16:27:02 +0200
> Daniel Kiper <address@hidden> wrote:
>
> > On Thu, Apr 16, 2020 at 03:03:43PM +0200, Hans Ulrich Niedermann
> > wrote:
> > > This patch does not change the intended meaning of the text
> > > and only touches about the first 1300 of about 7000 lines
> > > in docs/grub.texi. If there is interest in picking up this
> > > patch, I intend to read through the rest of grub.texi as
> > > well to find more of these easy fixes while adding remarks
> > > for bigger issues which require actual text changes.
> > >
> > > Then, I can start (with some help) addressing the issues
> > > pointed to by these remarks like undocumented commands,
> > > renamed commands, wrong and outdated instructions, remarks
> > > about a future which has become present a long time ago, etc.
> >
> > It sounds like very interesting project! Nice to hear that you are
> > taking a stab at it. I have a few comments.
>
> > First of all, I will ask
> > a few native speakers to make a review of your work.
>
> While I have noticed and fixed a number of mistakes non-native speakers
> make relatively frequently (such as the missing articles). However, I am
> *not* a native speaker myself and will doubtlessly make some mistakes of
> my own. My goal is for the text to contain fewer mistakes after my
> changes, while hoping for zero.
>
> > Then I want to
> > ask you to continue your work on docs/grub.texi.
>
> docs/grub.texi is what I want to start with.

Great!

> > If you want to go
> > deeper in this I would like to ask you to take a look at additional
> > documents like docs/grub-dev.texi or Multiboot and Multiboot2
> > specifications (you can find both of them in multiboot and multiboot
> > branches of the GRUB git repository).
>
> I already have multiboot and multiboot2 in my sights, as writing a bit
> of an example kernel for multiboot and multiboot2 is what made me
> notice the current deficiencies in grub.texi (such as missing
> documentation for @command{module2}).

Nice!

By the way, I saw your patches for Multiboot and Multiboot2 specs.
I will take closer look at them next week.

> Regarding grub-dev.texi, I would not have the faintest idea about what
> to change there apart from simple language fixes.
>
> grub-dev.texi looks to me to be very much something to be written by
> the core maintainers, describing what they want. I am really new to
> grub development, so I have no idea whatsoever about that. Being a grub
> user for a decade going on two does not help here at all.

If you do not feel fully comfortable with grub-dev.texi then simple
language fixes are enough for me.

> > Of course I would prefer if you
> > work on one document at a time. This should ease our cooperation.
>
> It should also ease the load on my brain.
>
> > Last but not least, some lines in these documents are very long. I
> > would like to have them wrapped at around 80th column to ease
> > reading. If you could do that in separate patch that would be
> > perfect. I think that this should be last step in doing docs cleanups.
>
> I'll try to remember that for the last patch.
>
> > ...and if you could finish this work, at least for docs/grub.texi and
> > docs/grub-dev.texi, before the 2.06 release that would be fantastic...
>
> I have no idea what the grub release schedule is, what "2.06 release"
> might mean when translated to a calendar date (2020-05-01? some time in
> autumn 2020? some time in 2021?), and when and what a next release
> might be. However, I am certain this will take a few weeks at the very
> least to finish.

I am planning the release no later than June. However, we have some
delay. So, it may slip a few weeks. Anyway, at this point I think the
most important are changes to the docs/grub.texi. So, please focus on
them if you can.

Thank you for doing this work!

Daniel