boot loaders: gpart confusion (was: cannot boot: ZFS: unsupported feature" com.klarasystems:vdev_zaps_v2)

April 2021, <https://www.freebsd.org/releases/13.0R/> release notes:

> … To update old ESP partitions, users should stop using the gpart(8) 
> utility. …
>

On 10/12/2024 17:10, Dag-Erling Smørgrav wrote:
> … upgrade your boot loader as described in the gpart manual page or the ZFS chapter of the FreeBSD handbook:
>
>    https://docs.freebsd.org/en/books/handbook/book/#zfs-zpool-upgrade

The Handbook may be a source of confusion.

In the ZFS chapter, the warning under 
<https://docs.freebsd.org/en/books/handbook/zfs/#zfs-zpool-upgrade> states:

> For systems using EFI to boot, execute the following command:
>
> # gpart bootcode -p /boot/boot1.efifat -i 1 ada1


<https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=261212> (January 2022):

> 261212 – Update the ZFS chapter of the FreeBSD Handbook, and other 
> OpenZFS-related pages


Another possible source of confusion: for gpart(8), are the examples at 
<https://man.freebsd.org/cgi/man.cgi?query=gpart&sektion=8&manpath=FreeBSD+14.2-RELEASE#EXAMPLES> 
outdated?

Compare with 
<https://man.freebsd.org/cgi/man.cgi?query=gpart&sektion=8&manpath=FreeBSD+14.2-RELEASE#EXAMPLES> 
for loader.efi(8).