Re: 119 grub commands not documented in grub.texi

[Daniel Kiper]

Hi Hans,

On Sat, Apr 18, 2020 at 12:53:12PM +0200, Hans Ulrich Niedermann wrote:
> Hi,
>
> I have noticed that there are two commands documented in grub.texi
> which appear not to occur anywhere within the grub source code:
> 'pxe_unload' and 'uppermem'.
>
>     @node pxe_unload
>     @subsection pxe_unload
>
>     @deffn Command pxe_unload
>     Unload the PXE environment (@pxref{Network}).
>
>     This command is only available on PC BIOS systems.
>     @end deffn
>
> However, judging from the source code ("git grep pxe_unload"),
> pxe_unload is not available at all, so the documentation is wrong when
> it claims that the command were available on PC BIOS systems.
>
> Should 'pxe_unload' be removed from grub.texi, or does it need a notice
> that there are plans to implement it?

If it is not implemented please drop it.

> Regarding 'uppermem', there is only
>
>     @node uppermem
>     @subsection uppermem
>
>     This command is not yet implemented for GRUB 2, although it is planned.
>
> This may be a valid state for the "uppermem" command.

Probably it is a remnant from ancient times. Please drop it too.

> So far for those two commands.
>
> Then, a bit more surprisingly, there appear to be 119 (yes, more than
> 100) grub commands which are registered within the grub source code but
> are not documented within grub.texi.
>
>   * When do I count a command as documented in grub.texi?
>     Every @node/@subsection in a "@section * commands" of
>     "@chapter Commands".
>
>   * What do I count as a command registered within grub source?
>     Whatever string appears as the first argument in a call to any of
>     the following functions:
>
>       * grub_register_command
>       * grub_register_command_p1
>       * grub_register_extcmd

At first sight it makes sense...

> Some of these undocumented commands look like they could be relatively
> easily be grouped into a @section and described there (e.g. the 'break',
> 'continue', 'exit', 'return' commands for a group of shell like
> commands, maybe together with '[').

OK...

> I am absolutely certain that I will not find the time to write useful
> documentation for a significant portion of these undocumented commands
> within the grub 2.06 release timeframe (i.e. until June 2020), or even
> just determine which ones I think actually need to or should be
> documented publically.

Sure thing! This can be long term effort if you want to do that.

> So if someone wants their favourite commands documented for 2.06, they
> will need to write that documentation themselves. I will just try to
> add tentative documentation for @command{module2} and
> @command{multiboot2} so that booting of a multiboot2 kernel will at
> least be mentioned in grub.texi at all.

Works for me...

> If you want me to, I can submit a patch for the check-commands.py

I cannot find check-commands.py, anyway...

> script to autogenerate a list of undocumented commands which should be
> documented which can then be auto-included in grub.texi and appear in
> the generated 'grub.info'. This would give a reader of the grub manual
> at least the knowledge that those command actually exist, and could be
> coupled with a call for help documenting those commands right inside
> grub.texi itself.

That would be perfect. Especially if it appears in 2.06 release.

Thank you for doing this work!

Daniel