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
_______________________________________________
Grub-devel mailing list
Grub-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/grub-devel
