2024-01-18-installkernel-merge: improve clarity

- explicitly say that installkernel is called by make install
- explicitly say that users of GRUB are expected to enable the grub USE flag
- add instructions for retaining the traditional /boot layout for users of
other bootloaders
- explicitly say that Unified Kernel Images may be wanted to semi-automate
EFI stub booting

Signed-off-by: Andrew Ammerlaan <andrewammerlaan@gentoo.org>

1 files changed, 23 insertions, 7 deletions

diff --git a/2024-01-18-installkernel-merge/2024-01-18-installkernel-merge.en.txt b/2024-01-18-installkernel-merge/2024-01-18-installkernel-merge.en.txt
index aaf7884..991c95d 100644
--- a/2024-01-18-installkernel-merge/2024-01-18-installkernel-merge.en.txt
+++ b/2024-01-18-installkernel-merge/2024-01-18-installkernel-merge.en.txt
@@ -1,15 +1,18 @@
 Title: Merging of installkernel-gentoo and installkernel-systemd
 Author: Andrew Ammerlaan <andrewammerlaan@gentoo.org>
 Posted: 2024-01-18
-Revision: 2
+Revision: 3
 News-Item-Format: 2.0
 Display-If-Installed: sys-kernel/installkernel
 Display-If-Installed: sys-kernel/installkernel-gentoo
 Display-If-Installed: sys-kernel/installkernel-systemd
 Display-If-Installed: sys-kernel/installkernel-systemd-boot
 
-The functionalities of sys-kernel/installkernel-gentoo and
-sys-kernel/installkernel-systemd have been merged into sys-kernel/installkernel.
+/sbin/installkernel is a script called by the kernels 'make install' as well
+as by the distribution kernels post install phase. It was previously provided
+by sys-kernel/installkernel-gentoo or sys-kernel/installkernel-systemd. The
+functionalities of these two packages have now been merged into
+sys-kernel/installkernel.
 
 sys-kernel/installkernel now provides the systemd USE flag to switch between
 the traditional installkernel (formerly sys-kernel/installkernel-gentoo) and
@@ -30,13 +33,16 @@ User Action Required (GRUB users)
 Previously sys-kernel/installkernel-gentoo provided kernel installation
 automation for users of GRUB via USE=grub. The new sys-kernel/installkernel
 provides the same functionality, which now works with both the traditional
-installkernel and systemd's kernel-install. In principle no user action is
-required unless users wish to explicitly choose either the traditional
+installkernel and systemd's kernel-install. Users of GRUB should check that
+the "grub" USE flag is enabled to ensure that systemd's kernel-install uses
+the correct layout that grub-mkconfig understands.
+
+Users of GRUB may wish to explicitly choose either the traditional
 installkernel or systemd's kernel-install, in which case they may do so
 via USE=-/+systemd.
 
 sys-kernel/installkernel is renamed from sys-kernel/installkernel-gentoo,
-therefore no user action is required to upgrade.
+therefore no user action is required to upgrade to the new package.
 
 
 User Action Required (systemd-boot users)
@@ -69,6 +75,16 @@ plugins should either ensure that the same kernel installation method will be
 used after upgrading to >=sys-kernel/installkernel-14 (via USE=+/-systemd) or
 migrate these custom plugins (details are on the wiki [1]).
 
+Users of bootloaders other then GRUB or systemd-boot may want to retain the
+traditional /boot layout. They may do so by either:
+- disabling the "systemd" USE flag, or
+- when the "systemd" USE flag is enabled, enabling the "grub" USE flag as well.
+- when the "systemd" USE flag is enabled, setting "layout=grub" in
+/etc/kernel/install.conf
 
-[1] https://wiki.gentoo.org/wiki/Installkernel
+Users who wish to use EFI stub booting may be interested in building an
+Unified Kernel Image[2] by enabling the "ukify" and "uki" USE flags. This will
+automatically install a bootable EFI executable to the EFI system partition.
 
+[1] https://wiki.gentoo.org/wiki/Installkernel
+[2] https://wiki.gentoo.org/wiki/Unified_kernel_image