Can we say something a little more specific for people that don't already know what this means?

I'm not really sure what to say. Really if someone wants more detail it's the info in boot(8).

This isn't entirely true. As with all things, it's stupidly complex when, perhaps, it shouldn't be.

So /boot.config (and the alternative /boot/config) is searched for: gptzfsboot, isoboot, boot2, and gptboot on x86. This means it's only used for BIOS (or CSM -- Compatibility Support Module in EFI speak) booting.

However, boot1.efi, on all platforms, looks at it also.

So:

For UFS root:
On MBR booting, it looks on the 'a' partition of the selected slice.
For GPT booting, it looks directly on the boot partition.
For EFI booting, it looks at on the root partition.

For ZFS root:
It looks in the same dataset (I think that's the right unit, or maybe boot environment) that it's booting off of.

For BIOS booting, it sets just the command line args to control dual console, serial console, etc. /boot/loader then converts these to boot_XXXX=yes variables to make them have an effect. You cannot set env variables this way, however. It also does that weird BIOS number thing for alternate files to load.

For EFI booting with boot1.efi, it passes the whole file to /boot/loader.efi which interprets both the command line args as well as foo=bar to set loader environment variables. You cannot name an alternate file to load, like you can with BIOS loading. loader.efi, when in the ESP, won't look at this file.

Given we're removing boot1.efi soon, I don't know if it makes sense to document it all...

Clear as mud, eh?

also boot.8 really needs a lot of love, here's but one example:

interface
         The type of controller to boot from.  Note that the
         controller is required to have BIOS support since the
         BIOS services are used to load the boot file image.

         The supported interfaces are:

         ad    ST506, IDE, ESDI, RLL disks on a WD100[2367] or
               lookalike controller
         fd    5 1/4" or 3 1/2" High density floppies
         da    SCSI disk on any supported SCSI controller

We've never supported ST506, ESDI, RLL disks. It should just be 'ATA disks' here to avoid confusion. and we should remove fd here, etc etc boot(8) is very out of date. FreeBSD has never had a proper WD100x driver as those interfaces were already legacy when the project was born...

Also also, we should note this can only load /boot/loader and nothing else. It cannot be used to load the kernel directly.

Maybe something along the lines of "not EFI" would help to clarify what "legacy" means?

I'm also not sure about the first-stage / second-stage bit.... gptboot, gptzfsboot, isoboot and boot2 are all second-stage loaders, I think, though we've never been super clear about that in our docs.

So I'm not sure what's best here, just had to brain-dump all those details...

Maybe something along the lines of "not EFI" would help to clarify what "legacy" means?

Even then as @imp points out boot1.efi parses it, so Configuration file for the legacy (non-UEFI) boot blocks and boot1.efi(8), but that's probably too long.

So /boot.config (and the alternative /boot/config)

Hrmph, it looks like the code generally tries PATH_CONFIG (/boot/config) first followed by PATH_DOTCONFIG (/boot.config) so arguably /boot.config should be documented as the alternate. This page talks about the a slice which is not applicable to several of the loaders that parse boot.config.

Mainly I want to convey that on a contemporary system this file is likely of no interest.

2025 surely.

Updated locally.