Bug#1087356: kernel-install.8: Some remarks about this man page
Bjarni Ingi Gislason
bjarniig at simnet.is
Tue Nov 12 00:53:22 GMT 2024
Package: systemd
Version: 256.7-3
Severity: minor
* What led up to the situation?
Checking for defects with
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z < "man page"
[Use "groff -e ' $' <file>" to find trailing spaces.]
["test-groff" is a script in the repository for "groff"; is not shipped]
(local copy and "troff" slightly changed by me).
[The fate of "test-nroff" was decided in groff bug #55941.]
* What was the outcome of this action?
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':520: string 'an-section-heading'
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':525: macro 'SH'
troff: backtrace: file '<stdin>':309
troff:<stdin>:309: warning: asked for a font family instead of the font itself
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':520: string 'an-section-heading'
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':525: macro 'SH'
troff: backtrace: file '<stdin>':309
troff:<stdin>:309: error: no font family named 'I' exists
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':520: string 'an-section-heading'
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':525: macro 'SH'
troff: backtrace: file '<stdin>':309
troff:<stdin>:309: warning: asked for a font family instead of the font itself
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':520: string 'an-section-heading'
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':525: macro 'SH'
troff: backtrace: file '<stdin>':309
troff:<stdin>:309: error: no font family named 'R' exists
Output from "test-nroff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
troff: backtrace: file '<stdin>':841
troff:<stdin>:841: warning: [page 8, line 54]: cannot break line
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.11.5-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1), LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
Versions of packages systemd depends on:
ii libacl1 2.3.2-2+b1
ii libapparmor1 3.1.7-1+b2
ii libblkid1 2.40.2-9
ii libc6 2.40-3
ii libcap2 1:2.66-5+b1
ii libmount1 2.40.2-9
ii libpam0g 1.5.3-7+b1
ii libseccomp2 2.5.5-1+b2
ii libselinux1 3.7-3
ii libssl3t64 3.3.2-2
ii libsystemd-shared 256.7-3
ii libsystemd0 256.7-3
ii mount 2.40.2-9
Versions of packages systemd recommends:
ii dbus [default-dbus-system-bus] 1.14.10-6
ii libzstd1 1.5.6+dfsg-1+b1
pn linux-sysctl-defaults <none>
pn systemd-cryptsetup <none>
pn systemd-timesyncd | time-daemon <none>
Versions of packages systemd suggests:
ii libcryptsetup12 2:2.7.5-1
ii libgcrypt20 1.11.0-6
ii libidn2-0 2.3.7-2+b1
ii liblz4-1 1.9.4-3+b1
ii liblzma5 5.6.3-1+b1
pn libtss2-rc0t64 <none>
pn libtss2-tcti-device0 <none>
pn polkitd <none>
pn systemd-boot <none>
pn systemd-container <none>
pn systemd-homed <none>
pn systemd-repart <none>
pn systemd-resolved <none>
pn systemd-userdbd <none>
Versions of packages systemd is related to:
pn dbus-user-session <none>
pn dracut <none>
ii initramfs-tools 0.145
pn libnss-systemd <none>
pn libpam-systemd <none>
ii udev 256.7-3
-- no debconf information
-------------- next part --------------
Any program (person), that produces man pages, should check the output
for defects by using (both groff and nroff)
[gn]roff -mandoc -t -ww -b -z -K utf8 <man page>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
So any 'generator' should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
This is just a simple quality control measure.
The 'generator' may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Input text line longer than 80 bytes.
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
Not beginning each input sentence on a new line.
Lines should thus be shorter.
See man-pages(7), item 'semantic newline'.
-.-
The difference between the formatted output of the original and patched file
can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -u <out1> <out2>
and for groff, using
"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - "
instead of 'nroff -mandoc'
Add the option '-t', if the file contains a table.
Read the output of 'diff -u' with 'less -R' or similar.
-.-.
If 'man' (man-db) is used to check the manual for warnings,
the following must be set:
The option "-warnings=w"
The environmental variable:
export MAN_KEEP_STDERR=yes (or any non-empty value)
or
(produce only warnings):
export MANROFFOPT="-ww -b -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-.
Output from "mandoc -T lint kernel-install.8": (possibly shortened list)
mandoc: kernel-install.8:2:27: WARNING: missing date, using "": TH
mandoc: kernel-install.8:23:88: STYLE: input text line longer than 80 bytes: kernel-install \- Ad...
mandoc: kernel-install.8:36:2: WARNING: skipping paragraph macro: PP after SH
mandoc: kernel-install.8:51:213: STYLE: input text line longer than 80 bytes: /etc/kernel/install\...
mandoc: kernel-install.8:54:139: STYLE: input text line longer than 80 bytes: /usr/lib/kernel/inst...
mandoc: kernel-install.8:58:82: STYLE: input text line longer than 80 bytes: /dev/null, disables ...
mandoc: kernel-install.8:65:97: STYLE: input text line longer than 80 bytes: to cause the whole o...
mandoc: kernel-install.8:67:2: WARNING: skipping paragraph macro: PP after SH
mandoc: kernel-install.8:72:226: STYLE: input text line longer than 80 bytes: This command takes a...
mandoc: kernel-install.8:74:88: STYLE: input text line longer than 80 bytes: returns\&. If the la...
mandoc: kernel-install.8:75:165: STYLE: input text line longer than 80 bytes: /usr/lib/modules/\fI...
mandoc: kernel-install.8:94:114: STYLE: input text line longer than 80 bytes: The third argument d...
mandoc: kernel-install.8:96:112: STYLE: input text line longer than 80 bytes: Type #1 entries (the...
mandoc: kernel-install.8:100:127: STYLE: input text line longer than 80 bytes: string is typically ...
mandoc: kernel-install.8:147:191: STYLE: input text line longer than 80 bytes: $BOOT/\fIENTRY\-TOKE...
mandoc: kernel-install.8:150:102: STYLE: input text line longer than 80 bytes: $BOOT/loader/entries...
mandoc: kernel-install.8:197:103: STYLE: input text line longer than 80 bytes: /usr/lib/modules/\&....
mandoc: kernel-install.8:279:116: STYLE: input text line longer than 80 bytes: Shows the various pa...
mandoc: kernel-install.8:306:98: STYLE: input text line longer than 80 bytes: parameters specify t...
mandoc: kernel-install.8:310:2: WARNING: skipping paragraph macro: PP after SH
mandoc: kernel-install.8:326:2: WARNING: skipping paragraph macro: PP after SH
mandoc: kernel-install.8:352:103: STYLE: input text line longer than 80 bytes: Type #1 entry direct...
mandoc: kernel-install.8:365:110: STYLE: input text line longer than 80 bytes: Controls how to name...
mandoc: kernel-install.8:401:173: STYLE: input text line longer than 80 bytes: $KERNEL_INSTALL_CONF...
mandoc: kernel-install.8:411:256: STYLE: input text line longer than 80 bytes: Using the machine ID...
mandoc: kernel-install.8:413:567: STYLE: input text line longer than 80 bytes: partition, or if the...
mandoc: kernel-install.8:427:92: STYLE: input text line longer than 80 bytes: Takes a directory pa...
mandoc: kernel-install.8:429:154: STYLE: input text line longer than 80 bytes: path, including conf...
mandoc: kernel-install.8:436:174: STYLE: input text line longer than 80 bytes: Takes a path to a di...
mandoc: kernel-install.8:463:83: STYLE: input text line longer than 80 bytes: (for the shortest po...
mandoc: kernel-install.8:485:2: WARNING: skipping paragraph macro: PP after SS
mandoc: kernel-install.8:517:120: STYLE: input text line longer than 80 bytes: is set for the plugi...
mandoc: kernel-install.8:520:85: STYLE: input text line longer than 80 bytes: (see below)\&. If no...
mandoc: kernel-install.8:525:185: STYLE: input text line longer than 80 bytes: is set for the plugi...
mandoc: kernel-install.8:530:181: STYLE: input text line longer than 80 bytes: /etc/os\-release\&. ...
mandoc: kernel-install.8:536:193: STYLE: input text line longer than 80 bytes: are often set to the...
mandoc: kernel-install.8:537:83: STYLE: input text line longer than 80 bytes: /etc/kernel/entry\-t...
mandoc: kernel-install.8:539:147: STYLE: input text line longer than 80 bytes: are checked for Boot...
mandoc: kernel-install.8:544:330: STYLE: input text line longer than 80 bytes: is set for the plugi...
mandoc: kernel-install.8:550:216: STYLE: input text line longer than 80 bytes: is set for the plugi...
mandoc: kernel-install.8:618:90: STYLE: input text line longer than 80 bytes: are set for plugins ...
mandoc: kernel-install.8:626:194: STYLE: input text line longer than 80 bytes: is set for plugins t...
mandoc: kernel-install.8:634:2: WARNING: skipping paragraph macro: PP after SS
mandoc: kernel-install.8:639:133: STYLE: input text line longer than 80 bytes: entry\-token, and ot...
mandoc: kernel-install.8:667:114: STYLE: input text line longer than 80 bytes: install\&.conf\&. Va...
mandoc: kernel-install.8:669:2: WARNING: skipping paragraph macro: PP after SH
mandoc: kernel-install.8:670:93: STYLE: input text line longer than 80 bytes: If every executable ...
mandoc: kernel-install.8:672:2: WARNING: skipping paragraph macro: PP after SH
mandoc: kernel-install.8:683:96: STYLE: input text line longer than 80 bytes: Specifies the kernel...
mandoc: kernel-install.8:692:169: STYLE: input text line longer than 80 bytes: Specifies the partia...
mandoc: kernel-install.8:698:150: STYLE: input text line longer than 80 bytes: file contains a path...
mandoc: kernel-install.8:699:127: STYLE: input text line longer than 80 bytes: /usr/lib/modules/\fI...
mandoc: kernel-install.8:703:106: STYLE: input text line longer than 80 bytes: file, the device tre...
mandoc: kernel-install.8:714:157: STYLE: input text line longer than 80 bytes: 90\-uki\-copy\&.inst...
mandoc: kernel-install.8:717:132: STYLE: input text line longer than 80 bytes: $BOOT/EFI/Linux/\fIE...
mandoc: kernel-install.8:719:87: STYLE: input text line longer than 80 bytes: which implement boot...
mandoc: kernel-install.8:728:142: STYLE: input text line longer than 80 bytes: If this file exists ...
mandoc: kernel-install.8:750:83: STYLE: input text line longer than 80 bytes: is read from these f...
mandoc: kernel-install.8:757:302: STYLE: input text line longer than 80 bytes: /etc/kernel/install\...
mandoc: kernel-install.8:762:83: STYLE: input text line longer than 80 bytes: assignments, compati...
mandoc: kernel-install.8:765:145: STYLE: input text line longer than 80 bytes: may be used to overr...
mandoc: kernel-install.8:806:181: STYLE: input text line longer than 80 bytes: Location for install...
mandoc: kernel-install.8:813:154: STYLE: input text line longer than 80 bytes: Location for install...
mandoc: kernel-install.8:822:89: STYLE: input text line longer than 80 bytes: environment variable...
mandoc: kernel-install.8:824:167: STYLE: input text line longer than 80 bytes: from the directory s...
mandoc: kernel-install.8:826:2: WARNING: skipping paragraph macro: PP after SH
mandoc: kernel-install.8:830:81: STYLE: input text line longer than 80 bytes: Nowadays actually CP...
-.-.
Strings longer than 3/4 of a standard line length (80)
Use "\:" to split the string at the end of an output line, for example a
long URLs (web address)
147 $BOOT/\fIENTRY\-TOKEN\fR/\fIKERNEL_VERSION\fR/\fIINITRD\-FILE\fR\&. This can also be used to prepend microcode before the actual initrd\&. It also creates a boot loader entry according to the
150 $BOOT/loader/entries/\fIENTRY\-TOKEN\fR\-\fIKERNEL\-VERSION\fR\&.conf\&. The title of the entry is the
182 $BOOT/EFI/Linux/\fIENTRY\-TOKEN\fR\-\fIKERNEL\-VERSION\fR\&.efi\&.
255 $BOOT/loader/entries/\fIENTRY\-TOKEN\fR\-\fIKERNEL\-VERSION\fR\&.conf\&.
268 $BOOT/EFI/Linux/\fIENTRY\-TOKEN\fR\-\fIKERNEL\-VERSION\fR\&.efi\&.
562 $BOOT/loader/entries/\fIENTRY\-TOKEN\fR\-\fIKERNEL\-VERSION\fR[+\fITRIES\fR]\&.conf, kernel and initrds under
579 $BOOT/EFI/Linux/\fIENTRY\-TOKEN\fR\-\fIKERNEL\-VERSION\fR[+\fITRIES\fR]\&.efi\&.
704 /usr/lib/modules/\fIKERNEL_VERSION\fR/dtb/broadcom/bcm2711\-rpi\-4\-b\&.dtb\&.
715 $BOOT/loader/entries/\fIENTRY\-TOKEN\fR\-\fIKERNEL\-VERSION\fR+\fITRIES\fR\&.conf
717 $BOOT/EFI/Linux/\fIENTRY\-TOKEN\fR\-\fIKERNEL\-VERSION\fR+\fITRIES\fR\&.efi, respectively\&. This is useful for boot loaders such as
836 \%https://uapi-group.org/specifications/specs/boot_loader_specification
841 \%https://uapi-group.org/specifications/specs/discoverable_partitions_specification
-.-.
Wrong distance between sentences in the input file.
Separate the sentences and subordinate clauses; each begins on a new
line. See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").
The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.
Remember coding: Only one command ("sentence") on each (logical) line.
E-mail: Easier to quote exactly the relevant lines.
Generally: Easier to edit the sentence.
Patches: Less unaffected text.
Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
42:here\&. It will usually be one of
51:/etc/kernel/install\&.d/\&. All files are collectively sorted and executed in lexical order, regardless of the directory in which they live\&. However, files with identical filenames replace each other\&. Files in
54:/usr/lib/kernel/install\&.d/\&. This can be used to override a system\-supplied executables with a local file if needed; a symbolic link in
58:/dev/null, disables the executable entirely\&. Executables must have the extension
63:on success\&. It may also return
72:This command takes a kernel version string and a path to a kernel image file as arguments\&. If the former is omitted, specified as an empty string or as "\-" it defaults to the current kernel version, i\&.e\&. the same string
74:returns\&. If the latter is omitted, specified as an empty string or as "\-" defaults to
75:/usr/lib/modules/\fIKERNEL_VERSION\fR/vmlinuz\&. Optionally, one or more initrd images may be specified as well (note that plugins might generate additional ones)\&.
81:(i\&.e\&. the plugins) are called with the following arguments:
96:Type #1 entries (the "entry directory")\&. If other boot loader schemes are used the parameter may be ignored\&.
100:string is typically the machine ID and is supposed to identify the local installation on the system\&. For details see below\&.
145:$BOOT/\fIENTRY\-TOKEN\fR/\fIKERNEL\-VERSION\fR/linux\&. If
147:$BOOT/\fIENTRY\-TOKEN\fR/\fIKERNEL_VERSION\fR/\fIINITRD\-FILE\fR\&. This can also be used to prepend microcode before the actual initrd\&. It also creates a boot loader entry according to the
150:$BOOT/loader/entries/\fIENTRY\-TOKEN\fR\-\fIKERNEL\-VERSION\fR\&.conf\&. The title of the entry is the
197:/usr/lib/modules/\&. This operation is only supported on systems where the kernel image is installed in
211:(i\&.e\&. the plugins) are called with the following arguments:
279:Shows the various paths and parameters configured or auto\-detected\&. In particular shows the values of the various
281:environment variables listed below, as they would be passed to plugins\&. The
290:Shows the various installed kernels\&. This enumerates the subdirectories of
302:command\&. The
306:parameters specify the kernel version and the kernel binary\&. The other two parameters (\fIMAP\fR
320:in turn\&. The first location where
331:Path to the EFI System Partition (ESP)\&. If not specified,
335:are checked in turn\&. It is recommended to mount the ESP to
342:\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[2]\d\s+2\&. If not specified,
344:is checked\&. It is recommended to mount the Extended Boot Loader partition to
355:\fBremove\fR, respectively\&. The directory is named after the entry token, and is placed immediately below the boot root directory\&. When
357:"bls"\&. Defaults to
365:Controls how to name and identify boot loader entries for this kernel installation or deletion\&. Takes one of
376:"b0e793a9baf14b5fa13ecbe84ff637ac")\&. See
382:the entries are named after the OS ID of the running system, i\&.e\&. the
387:"fedora")\&. Similarly, if set to
389:the entries are named after the OS image ID of the running system, i\&.e\&. the
401:$KERNEL_INSTALL_CONF_ROOT/entry\-token) file will be read if it exists, and the stored value used\&. Otherwise if the local machine ID is initialized it is used\&. Otherwise
405:will be used, if set\&. Otherwise,
409:will be used, if set\&. Otherwise a randomly generated machine ID is used\&.
411:Using the machine ID for naming the entries is generally preferable, however there are cases where using the other identifiers is a good option\&. Specifically: if the identification data that the machine ID entails shall not be stored on the (unencrypted)
413:partition, or if the ID shall be generated on first boot and is not known when the entries are prepared\&. Note that using the machine ID has the benefit that multiple parallel installations of the same OS can coexist on the same medium, and they can update their boot loader entries independently\&. When using another identifier (such as the OS ID or the OS image ID), parallel installations of the same OS would try to use the same entry name\&. To support parallel installations, the installer must use a different entry token when adding a second installation\&.
427:Takes a directory path as an argument\&. All paths will be prefixed with the given alternate
429:path, including config search paths\&. This is useful to operate on a system image mounted to the specified directory instead of the host system itself\&.
436:Takes a path to a disk image file or block device node\&. If specified, all operations are applied to the file system in the indicated disk image\&. This option is similar to
437:\fB\-\-root=\fR, but operates on file systems stored in disk images or block devices\&. The disk image should either contain just a file system or a set of file systems within a GPT partition table, following the
438:\m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[3]\d\s+2\&. For further information on supported disk images, see
461:Shows output formatted as JSON\&. Expects one of
473:\fBsystemd.image-policy\fR(7)\&. The policy is enforced when operating on the disk image specified via
474:\fB\-\-image=\fR, see above\&. If not specified defaults to the
476:policy, i\&.e\&. all recognized file systems in the image are used\&.
481:Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
490:will be exported for plugins\&. They may output additional logs in this case\&.
517:is set for the plugins to the desired machine\-id to use\&. It\*(Aqs always a 128\-bit ID\&. Normally it\*(Aqs read from
520:(see below)\&. If not specified via these methods, a fallback value will generated by
525:is set for the plugins to the desired entry "token" to use\&. It\*(Aqs an identifier that shall be used to identify the local installation, and is often the machine ID, i\&.e\&. same as
530:/etc/os\-release\&. The string passed here will be used to name Boot Loader Specification entries, or the directories the kernel image and initial RAM disk images are placed into\&.
536:are often set to the same value, the latter is guaranteed to be a valid 32 character ID in lowercase hexadecimals while the former can be any short string\&. The entry token to use is read from
537:/etc/kernel/entry\-token, if it exists\&. Otherwise a few possible candidates below
539:are checked for Boot Loader Specification Type 1 entry directories, and if found the entry token is derived from that\&. If that is not successful,
544:is set for the plugins to the absolute path of the root directory (mount point, usually) of the hierarchy where boot loader entries, kernel images, and associated resources should be placed\&. This usually is the path where the XBOOTLDR partition or the ESP (EFI System Partition) are mounted, and also conceptually referred to as
545:\fI$BOOT\fR\&. Can be overridden by setting
550:is set for the plugins to specify the installation layout\&. Additional layout names may be defined by convention\&. If a plugin uses a special layout, it\*(Aqs encouraged to declare its own layout name and configure
554:upon initial installation\&. The following values are currently understood:
597:Pick the layout automatically\&. If the kernel is a UKI set layout to
598:\fBuki\fR\&. If not default to
610:Leaving layout blank has the same effect\&. This is the default\&.
618:are set for plugins to select the initrd and/or UKI generator\&. This may be configured as
626:is set for plugins to a path to a directory\&. Plugins may drop files in that directory, and they will be installed as part of the loader entry, based on the file name and extension: Files named
637:\fBkernel\-install\fR\&. When set,
639:entry\-token, and other files will be read from this directory only\&. Note that this path is relative to the host, and in particular
642:is used\&. This means that it is generally
650:\fBkernel\-install\fR\&. The argument is a whitespace\-separated list of paths\&.
667:install\&.conf\&. Variables set in the environment take precedence over the values specified in the config file\&.
683:Specifies the kernel command line to use\&. The first of the files that is found will be used\&.
692:Specifies the partial path to the file containing the device tree blob to install with the kernel and use at boot\&. The first of the files that is found will be used\&.
698:file contains a path, and this path specifies a location relative to the kernel install tree\&. A set of locations is checked, including in particular
699:/usr/lib/modules/\fIKERNEL_VERSION\fR/dtb/, which is the recommended location to place the dtb files under\&. For example, with
714:90\-uki\-copy\&.install\&. If this file exists, a numeric value is read from it and the naming of the generated entry file or UKI is altered to include it as
717:$BOOT/EFI/Linux/\fIENTRY\-TOKEN\fR\-\fIKERNEL\-VERSION\fR+\fITRIES\fR\&.efi, respectively\&. This is useful for boot loaders such as
728:If this file exists it is read and used as "entry token" for this system, i\&.e\&. is used for naming Boot Loader Specification entries\&. See
748:90\-loaderentry\&.install\&. If available,
750:is read from these files and used as the title of the boot menu entry\&. Otherwise,
763:\fBos-release\fR(5)\&. The first of the files that is found will be used\&.
765:may be used to override the search path; see below for details\&. Drop\-in files may also be used to extend the configuration with overrides, see
773:\fIuki_generator=\fR\&. See the Environment variables section above for details\&.
806:Location for installed kernel modules and other kernel related resources\&. For each locally installed kernel a directory named after the kernel version (\fBuname \-r\fR) is kept\&.
813:Location for installed kernel images\&. This is the recommended location for OS package managers to install kernel images into (as applicable), from which
822:environment variable is set, it will override the search path\&. The files will be loaded
824:from the directory specified by the environment variable\&. When the variable is not set, the listed paths are tried in turn, and the first file that exists is used\&.
830:Nowadays actually CPIO archives used as an "initramfs", rather than "initrd". See
-.-.
Split lines longer than 80 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
Line 23, length 88
kernel-install \- Add and remove kernel and initrd images to and from the boot partition
Line 26, length 104
\fBkernel\-install\fR [OPTIONS...] add \fIKERNEL\-VERSION\fR \fIKERNEL\-IMAGE\fR [\fIINITRD\-FILE\fR...]
Line 32, length 112
\fBkernel\-install\fR [OPTIONS...] inspect [\fIKERNEL\-VERSION\fR] [\fIKERNEL\-IMAGE\fR] [\fIINITRD\-FILE\fR...]
Line 51, length 213
/etc/kernel/install\&.d/\&. All files are collectively sorted and executed in lexical order, regardless of the directory in which they live\&. However, files with identical filenames replace each other\&. Files in
Line 54, length 139
/usr/lib/kernel/install\&.d/\&. This can be used to override a system\-supplied executables with a local file if needed; a symbolic link in
Line 58, length 82
/dev/null, disables the executable entirely\&. Executables must have the extension
Line 65, length 97
to cause the whole operation to terminate (executables later in lexical order will be skipped)\&.
Line 70, length 124
\fBadd [[[\fR\fB\fIKERNEL\-VERSION\fR\fR\fB] \fR\fB\fIKERNEL\-IMAGE\fR\fR\fB] [\fR\fB\fIINITRD\-FILE\fR\fR\fB \&.\&.\&.]]\fR
Line 72, length 226
This command takes a kernel version string and a path to a kernel image file as arguments\&. If the former is omitted, specified as an empty string or as "\-" it defaults to the current kernel version, i\&.e\&. the same string
Line 74, length 88
returns\&. If the latter is omitted, specified as an empty string or as "\-" defaults to
Line 75, length 165
/usr/lib/modules/\fIKERNEL_VERSION\fR/vmlinuz\&. Optionally, one or more initrd images may be specified as well (note that plugins might generate additional ones)\&.
Line 87, length 96
add \fIKERNEL\-VERSION\fR $BOOT/\fIENTRY\-TOKEN\fR/\fIKERNEL\-VERSION\fR/ \fIKERNEL\-IMAGE\fR \e
Line 94, length 114
The third argument directly refers to the path where to place kernel images, initrd images and other resources for
Line 96, length 112
Type #1 entries (the "entry directory")\&. If other boot loader schemes are used the parameter may be ignored\&.
Line 100, length 127
string is typically the machine ID and is supposed to identify the local installation on the system\&. For details see below\&.
Line 147, length 191
$BOOT/\fIENTRY\-TOKEN\fR/\fIKERNEL_VERSION\fR/\fIINITRD\-FILE\fR\&. This can also be used to prepend microcode before the actual initrd\&. It also creates a boot loader entry according to the
Line 150, length 102
$BOOT/loader/entries/\fIENTRY\-TOKEN\fR\-\fIKERNEL\-VERSION\fR\&.conf\&. The title of the entry is the
Line 197, length 103
/usr/lib/modules/\&. This operation is only supported on systems where the kernel image is installed in
Line 274, length 128
\fBinspect [[[\fR\fB\fIKERNEL\-VERSION\fR\fR\fB] \fR\fB\fIKERNEL\-IMAGE\fR\fR\fB] [\fR\fB\fIINITRD\-FILE\fR\fR\fB \&.\&.\&.]]\fR
Line 279, length 116
Shows the various paths and parameters configured or auto\-detected\&. In particular shows the values of the various
Line 300, length 97
\fBinstallkernel\fR, this program accepts arguments as specified by the kernel build system\*(Aqs
Line 306, length 98
parameters specify the kernel version and the kernel binary\&. The other two parameters (\fIMAP\fR
Line 342, length 81
\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[2]\d\s+2\&. If not specified,
Line 352, length 103
Type #1 entry directory on the file system containing resources such as kernel and initrd images during
Line 355, length 139
\fBremove\fR, respectively\&. The directory is named after the entry token, and is placed immediately below the boot root directory\&. When
Line 365, length 110
Controls how to name and identify boot loader entries for this kernel installation or deletion\&. Takes one of
Line 401, length 173
$KERNEL_INSTALL_CONF_ROOT/entry\-token) file will be read if it exists, and the stored value used\&. Otherwise if the local machine ID is initialized it is used\&. Otherwise
Line 411, length 256
Using the machine ID for naming the entries is generally preferable, however there are cases where using the other identifiers is a good option\&. Specifically: if the identification data that the machine ID entails shall not be stored on the (unencrypted)
Line 413, length 567
partition, or if the ID shall be generated on first boot and is not known when the entries are prepared\&. Note that using the machine ID has the benefit that multiple parallel installations of the same OS can coexist on the same medium, and they can update their boot loader entries independently\&. When using another identifier (such as the OS ID or the OS image ID), parallel installations of the same OS would try to use the same entry name\&. To support parallel installations, the installer must use a different entry token when adding a second installation\&.
Line 427, length 92
Takes a directory path as an argument\&. All paths will be prefixed with the given alternate
Line 429, length 154
path, including config search paths\&. This is useful to operate on a system image mounted to the specified directory instead of the host system itself\&.
Line 436, length 174
Takes a path to a disk image file or block device node\&. If specified, all operations are applied to the file system in the indicated disk image\&. This option is similar to
Line 437, length 212
\fB\-\-root=\fR, but operates on file systems stored in disk images or block devices\&. The disk image should either contain just a file system or a set of file systems within a GPT partition table, following the
Line 438, length 129
\m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[3]\d\s+2\&. For further information on supported disk images, see
Line 463, length 83
(for the shortest possible output without any redundant whitespace or line breaks),
Line 473, length 102
\fBsystemd.image-policy\fR(7)\&. The policy is enforced when operating on the disk image specified via
Line 517, length 120
is set for the plugins to the desired machine\-id to use\&. It\*(Aqs always a 128\-bit ID\&. Normally it\*(Aqs read from
Line 520, length 85
(see below)\&. If not specified via these methods, a fallback value will generated by
Line 525, length 185
is set for the plugins to the desired entry "token" to use\&. It\*(Aqs an identifier that shall be used to identify the local installation, and is often the machine ID, i\&.e\&. same as
Line 526, length 117
\fI$KERNEL_INSTALL_MACHINE_ID\fR, but might also be a different type of identifier, for example a fixed string or the
Line 530, length 181
/etc/os\-release\&. The string passed here will be used to name Boot Loader Specification entries, or the directories the kernel image and initial RAM disk images are placed into\&.
Line 536, length 193
are often set to the same value, the latter is guaranteed to be a valid 32 character ID in lowercase hexadecimals while the former can be any short string\&. The entry token to use is read from
Line 537, length 83
/etc/kernel/entry\-token, if it exists\&. Otherwise a few possible candidates below
Line 539, length 147
are checked for Boot Loader Specification Type 1 entry directories, and if found the entry token is derived from that\&. If that is not successful,
Line 544, length 330
is set for the plugins to the absolute path of the root directory (mount point, usually) of the hierarchy where boot loader entries, kernel images, and associated resources should be placed\&. This usually is the path where the XBOOTLDR partition or the ESP (EFI System Partition) are mounted, and also conceptually referred to as
Line 550, length 216
is set for the plugins to specify the installation layout\&. Additional layout names may be defined by convention\&. If a plugin uses a special layout, it\*(Aqs encouraged to declare its own layout name and configure
Line 562, length 109
$BOOT/loader/entries/\fIENTRY\-TOKEN\fR\-\fIKERNEL\-VERSION\fR[+\fITRIES\fR]\&.conf, kernel and initrds under
Line 618, length 90
are set for plugins to select the initrd and/or UKI generator\&. This may be configured as
Line 626, length 194
is set for plugins to a path to a directory\&. Plugins may drop files in that directory, and they will be installed as part of the loader entry, based on the file name and extension: Files named
Line 639, length 133
entry\-token, and other files will be read from this directory only\&. Note that this path is relative to the host, and in particular
Line 650, length 81
\fBkernel\-install\fR\&. The argument is a whitespace\-separated list of paths\&.
Line 667, length 114
install\&.conf\&. Variables set in the environment take precedence over the values specified in the config file\&.
Line 670, length 93
If every executable returns 0 or 77, 0 is returned, and a non\-zero failure code otherwise\&.
Line 683, length 96
Specifies the kernel command line to use\&. The first of the files that is found will be used\&.
Line 692, length 169
Specifies the partial path to the file containing the device tree blob to install with the kernel and use at boot\&. The first of the files that is found will be used\&.
Line 698, length 150
file contains a path, and this path specifies a location relative to the kernel install tree\&. A set of locations is checked, including in particular
Line 699, length 127
/usr/lib/modules/\fIKERNEL_VERSION\fR/dtb/, which is the recommended location to place the dtb files under\&. For example, with
Line 703, length 106
file, the device tree blob for the Raspberry Pi 4 Model B would be installed, and the actual file would be
Line 714, length 157
90\-uki\-copy\&.install\&. If this file exists, a numeric value is read from it and the naming of the generated entry file or UKI is altered to include it as
Line 715, length 81
$BOOT/loader/entries/\fIENTRY\-TOKEN\fR\-\fIKERNEL\-VERSION\fR+\fITRIES\fR\&.conf
Line 717, length 132
$BOOT/EFI/Linux/\fIENTRY\-TOKEN\fR\-\fIKERNEL\-VERSION\fR+\fITRIES\fR\&.efi, respectively\&. This is useful for boot loaders such as
Line 719, length 87
which implement boot attempt counting with a counter embedded in the entry file name\&.
Line 728, length 142
If this file exists it is read and used as "entry token" for this system, i\&.e\&. is used for naming Boot Loader Specification entries\&. See
Line 750, length 83
is read from these files and used as the title of the boot menu entry\&. Otherwise,
Line 757, length 302
/etc/kernel/install\&.conf, /run/kernel/install\&.conf, /usr/local/lib/kernel/install\&.conf, /usr/lib/kernel/install\&.conf, /etc/kernel/install\&.conf\&.d/*\&.conf, /run/kernel/install\&.conf\&.d/*\&.conf, /usr/local/lib/kernel/install\&.conf\&.d/*\&.conf, /usr/lib/kernel/install\&.conf\&.d/*\&.conf
Line 762, length 83
assignments, compatible with shell syntax, following the same rules as described in
Line 765, length 145
may be used to override the search path; see below for details\&. Drop\-in files may also be used to extend the configuration with overrides, see
Line 773, length 82
\fIuki_generator=\fR\&. See the Environment variables section above for details\&.
Line 806, length 181
Location for installed kernel modules and other kernel related resources\&. For each locally installed kernel a directory named after the kernel version (\fBuname \-r\fR) is kept\&.
Line 813, length 154
Location for installed kernel images\&. This is the recommended location for OS package managers to install kernel images into (as applicable), from which
Line 822, length 89
environment variable is set, it will override the search path\&. The files will be loaded
Line 824, length 167
from the directory specified by the environment variable\&. When the variable is not set, the listed paths are tried in turn, and the first file that exists is used\&.
Line 827, length 158
\fBmachine-id\fR(5), \fBos-release\fR(5), \fBdepmod\fR(8), \fBsystemd-boot\fR(7), \fBukify\fR(1), \m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[2]\d\s+2
Line 830, length 81
Nowadays actually CPIO archives used as an "initramfs", rather than "initrd". See
Line 841, length 83
\%https://uapi-group.org/specifications/specs/discoverable_partitions_specification
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
kernel-install.8:65:to cause the whole operation to terminate (executables later in lexical order will be skipped)\&.
kernel-install.8:75:/usr/lib/modules/\fIKERNEL_VERSION\fR/vmlinuz\&. Optionally, one or more initrd images may be specified as well (note that plugins might generate additional ones)\&.
kernel-install.8:96:Type #1 entries (the "entry directory")\&. If other boot loader schemes are used the parameter may be ignored\&.
kernel-install.8:413:partition, or if the ID shall be generated on first boot and is not known when the entries are prepared\&. Note that using the machine ID has the benefit that multiple parallel installations of the same OS can coexist on the same medium, and they can update their boot loader entries independently\&. When using another identifier (such as the OS ID or the OS image ID), parallel installations of the same OS would try to use the same entry name\&. To support parallel installations, the installer must use a different entry token when adding a second installation\&.
kernel-install.8:544:is set for the plugins to the absolute path of the root directory (mount point, usually) of the hierarchy where boot loader entries, kernel images, and associated resources should be placed\&. This usually is the path where the XBOOTLDR partition or the ESP (EFI System Partition) are mounted, and also conceptually referred to as
kernel-install.8:806:Location for installed kernel modules and other kernel related resources\&. For each locally installed kernel a directory named after the kernel version (\fBuname \-r\fR) is kept\&.
kernel-install.8:813:Location for installed kernel images\&. This is the recommended location for OS package managers to install kernel images into (as applicable), from which
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':520: string 'an-section-heading'
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':525: macro 'SH'
troff: backtrace: file '<stdin>':309
troff:<stdin>:309: warning: asked for a font family instead of the font itself
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':520: string 'an-section-heading'
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':525: macro 'SH'
troff: backtrace: file '<stdin>':309
troff:<stdin>:309: error: no font family named 'I' exists
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':520: string 'an-section-heading'
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':525: macro 'SH'
troff: backtrace: file '<stdin>':309
troff:<stdin>:309: warning: asked for a font family instead of the font itself
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':520: string 'an-section-heading'
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':525: macro 'SH'
troff: backtrace: file '<stdin>':309
troff:<stdin>:309: error: no font family named 'R' exists
-.-
Output from "test-nroff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
troff: backtrace: file '<stdin>':841
troff:<stdin>:841: warning: [page 8, line 54]: cannot break line
-.-.
Additionally (general):
FSF office address update. See
https://lists.gnu.org/archive/html/bug-gnulib/2024-09/msg00004.html
-.-
Abbreviations get a '\&' added after their final full stop (.) to mark them
as such and not as an end of a sentence.
There is no need to add a '\&' before a full stop (.) if it has a character
before it!
More information about the Pkg-systemd-maintainers
mailing list