Seeking Help: grub man pages not reproducible

[Chris Lamb]

Hey kpcyrd,

> The problem now is that `grub-install.8` is a snapshot of that help-text from
> the build-system, including the system specific defaults that might be
> different on the users system.
>
> I'm calling this a design issue because this means grub is shipping
> incorrect man pages on some systems:
>
>     % man grub-install | rg 'available  targets'
>           install  GRUB  for  TARGET  platform  [default=i386-pc];
> available  targets: arm-coreboot, arm-efi,
>     % grub-install --help | rg 'available targets'
>                      [default=x86_64-efi]; available targets:
>
> Any ideas?

Just to zoom out for a second, manual pages that embed properties of
the build system (via the output --help or analogous mechanism) is
surprisingly common. I have addressed 100s of similar (if not
identical issues) in Debian over the years, although this has
something of an observation bias to it. These issues are very easy to
locate in the output of diffoscope and, as low hanging fruit, they
might have been addressed before others. :)

Perhaps the most common property that leaks into manpages is the
number of CPUs the build system. This typically ends up in the manual
page because the number of CPUs is often used for some default amount
of concurrency (e.g. "--num-threads=X [default: 16]").

I mention this in particular as I believe the most user-friendly and
upstream acceptable approach to autodetected values like this is to
patch the output of --help with fixed values that indicate that they are
autodetected. For example, "--num-threads=X [default: num cpus]" or
"default: autodetected", instead of the actual number.  (*)

In fact, I believe I could make a case that some fixed "autodetected"
string is superior. After all, it conveys, completely accurately, that
the value is autodetected and not some seemingly arbitrary number

So for Grub here I would probably experiment with patching the
"x86_64-efi" bit with some kind of fixed, metasyntactic variable that
makes the best sense in context. "CURRENT", "<current>" might be a
place to start, but the answer will _always_ come from looking at
the manpage as a whole and seeing what best fits the scenario and
trying to put yourself in the mindset of a user reading the output in a
rush and just trying to get something done.

Hope that braindump helps...


 (*) Of course, sometimes this requires more patching to make it
     actually autodetected by the runtime. Sometimes --help will claim
     it is autodetected, but the value was actually detected long ago
     on some _build_ system and then fixed. (Which can be interesting
     if you build system has 128 CPUs and you then run it on some
     poor embedded device....)


Best wishes,

--
      o
    ⬋   ⬊      Chris Lamb
   o     o     reproducible-builds.org 💠
    ⬊   ⬋
      o