Bug#1082904: kernel-install.8: Some remarks and editorial changes for this man page
Bjarni Ingi Gislason
bjarniig at simnet.is
Sat Sep 28 02:13:46 BST 2024
Package: systemd
Version: 256.6-1
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with
[test-][gn]roff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z < "man page"
[test-groff is a script in the repository for "groff"] (local copy and
"troff" slightly changed by me).
* What was the outcome of this action?
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':526: string 'an-section-heading'
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':531: 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':526: string 'an-section-heading'
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':531: 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':526: string 'an-section-heading'
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':531: 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':526: string 'an-section-heading'
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':531: 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.10.9-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
ii libapparmor1 3.1.7-1+b1
ii libaudit1 1:3.1.2-4+b1
ii libblkid1 2.40.2-8
ii libc6 2.40-2
ii libcap2 1:2.66-5
ii libmount1 2.40.2-8
ii libpam0g 1.5.3-7
ii libseccomp2 2.5.5-1+b1
ii libselinux1 3.7-3
ii libssl3t64 3.3.2-1
ii libsystemd-shared 256.6-1
ii libsystemd0 256.6-1
ii mount 2.40.2-8
Versions of packages systemd recommends:
ii dbus [default-dbus-system-bus] 1.14.10-4+b1
ii libzstd1 1.5.6+dfsg-1
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
ii liblz4-1 1.9.4-3
ii liblzma5 5.6.2-2
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.6-1
-- no debconf information
-------------- next part --------------
Any program (person), that produces man pages, should check its content for
defects by using
groff -mandoc -t -ww -b -z [ -K utf8 | k ] <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 outputs 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...
-.-.
Change a HYPHEN-MINUS (code 0x2D) to a minus(-dash) (\-),
if it
is in front of a name for an option,
is a symbol for standard input,
is a single character used to indicate an option,
or is in the NAME section (man-pages(7)).
N.B. - (0x2D), processed as a UTF-8 file, is changed to a hyphen
(0x2010, groff \[u2010] or \[hy]) in the output.
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)
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
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
The actual line number in the input file is 307.
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':526: string 'an-section-heading'
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':531: 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':526: string 'an-section-heading'
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':531: 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':526: string 'an-section-heading'
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':531: 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':526: string 'an-section-heading'
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':531: 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):
Abbreviations get a '\&' added after their final full stop (.) to mark them as
such and not as an end of sentence.
There is no need to add a '\&' before a full stop (.) if it has a character
before it!
-------------- next part --------------
--- kernel-install.8 2024-09-28 00:25:50.950280029 +0000
+++ kernel-install.8.new 2024-09-28 01:04:27.830361208 +0000
@@ -33,10 +33,8 @@ kernel-install \- Add and remove kernel
.HP \w'\fBkernel\-install\fR\ 'u
\fBkernel\-install\fR [OPTIONS...] list
.SH "DESCRIPTION"
-.PP
\fBkernel\-install\fR
-is used to install and remove kernel and initrd images
-\&\s-2\u[1]\d\s+2
+is used to install and remove kernel and initrd images\&\s-2\u[1]\d\s+2
to and from the boot partition, referred to as
\fI$BOOT\fR
here\&. It will usually be one of
@@ -64,12 +62,11 @@ on success\&. It may also return
\fB77\fR
to cause the whole operation to terminate (executables later in lexical order will be skipped)\&.
.SH "COMMANDS"
-.PP
The following commands are understood:
.PP
\fBadd [[[\fR\fB\fIKERNEL\-VERSION\fR\fR\fB] \fR\fB\fIKERNEL\-IMAGE\fR\fR\fB] [\fR\fB\fIINITRD\-FILE\fR\fR\fB \&.\&.\&.]]\fR
.RS 4
-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
+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
\fBuname \-r\fR
returns\&. If the latter is omitted, specified as an empty string or as "\-" defaults to
/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)\&.
@@ -78,7 +75,7 @@ The executable files from
/usr/lib/kernel/install\&.d/*\&.install
and
/etc/kernel/install\&.d/*\&.install
-(i\&.e\&. the plugins) are called with the following arguments:
+(i.e.\& the plugins) are called with the following arguments:
.sp
.if n \{\
.RS 4
@@ -208,7 +205,7 @@ The executable files from
/usr/lib/kernel/install\&.d/*\&.install
and
/etc/kernel/install\&.d/*\&.install
-(i\&.e\&. the plugins) are called with the following arguments:
+(i.e.\& the plugins) are called with the following arguments:
.sp
.if n \{\
.RS 4
@@ -306,8 +303,7 @@ and
parameters specify the kernel version and the kernel binary\&. The other two parameters (\fIMAP\fR
and
\fIINSTALLATION\-DIR\fR) are currently ignored\&.
-.SH "THE \FI$BOOT\FR PARTITION"
-.PP
+.SH "THE \fI$BOOT\fP PARTITION"
The partition where the kernels and
\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[2]\d\s+2
snippets are located is called
@@ -323,7 +319,6 @@ or
$BOOT/\fIENTRY\-TOKEN\fR/
exists is used\&.
.SH "OPTIONS"
-.PP
The following options are understood:
.PP
\fB\-\-esp\-path=\fR
@@ -372,25 +367,25 @@ as argument\&.
.sp
If set to
\fBmachine\-id\fR
-the entries are named after the machine ID of the running system (e\&.g\&.
+the entries are named after the machine ID of the running system (e.g.\&
"b0e793a9baf14b5fa13ecbe84ff637ac")\&. See
\fBmachine-id\fR(5)
for details about the machine ID concept and file\&.
.sp
If set to
\fBos\-id\fR
-the entries are named after the OS ID of the running system, i\&.e\&. the
+the entries are named after the OS ID of the running system, i.e.\& the
\fIID=\fR
field of
\fBos-release\fR(5)
-(e\&.g\&.
+(e.g.\&
"fedora")\&. Similarly, if set to
\fBos\-image\-id\fR
-the entries are named after the OS image ID of the running system, i\&.e\&. the
+the entries are named after the OS image ID of the running system, i.e.\& the
\fIIMAGE_ID=\fR
field of
os\-release
-(e\&.g\&.
+(e.g.\&
"vendorx\-cashier\-system")\&.
.sp
If set to
@@ -473,16 +468,15 @@ Takes an image policy string as argument
\fBsystemd.image-policy\fR(7)\&. The policy is enforced when operating on the disk image specified via
\fB\-\-image=\fR, see above\&. If not specified defaults to the
"*"
-policy, i\&.e\&. all recognized file systems in the image are used\&.
+policy, i.e.\& all recognized file systems in the image are used\&.
.RE
.PP
\fB\-\-no\-legend\fR
.RS 4
-Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
+Do not print the legend, i.e.\& column headers and the footer with hints\&.
.RE
.SH "ENVIRONMENT VARIABLES"
.SS "Environment variables exported for plugins"
-.PP
If
\fB\-\-verbose\fR
is used,
@@ -522,7 +516,7 @@ is set for the plugins to the desired ma
and used only for a single invocation\&.
.PP
\fI$KERNEL_INSTALL_ENTRY_TOKEN\fR
-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
+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
\fI$KERNEL_INSTALL_MACHINE_ID\fR, but might also be a different type of identifier, for example a fixed string or the
\fIID=\fR,
\fIIMAGE_ID=\fR
@@ -631,7 +625,6 @@ microcode*
will be prepended before
\fIINITRD\-FILE\fRs\&.
.SS "Environment variables understood by kernel\-install"
-.PP
\fI$KERNEL_INSTALL_CONF_ROOT\fR
can be set to override the location of the configuration files read by
\fBkernel\-install\fR\&. When set,
@@ -666,10 +659,8 @@ to override
The last two variables may also be set in
install\&.conf\&. Variables set in the environment take precedence over the values specified in the config file\&.
.SH "EXIT STATUS"
-.PP
If every executable returns 0 or 77, 0 is returned, and a non\-zero failure code otherwise\&.
.SH "FILES"
-.PP
/etc/kernel/install\&.d/*\&.install, /usr/lib/kernel/install\&.d/*\&.install
.RS 4
Drop\-in files which are executed by
@@ -725,7 +716,7 @@ Added in version 240\&.
.PP
/etc/kernel/entry\-token
.RS 4
-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
+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
\fI$KERNEL_INSTALL_ENTRY_TOKEN\fR
above for details\&.
\fI$KERNEL_INSTALL_CONF_ROOT\fR
@@ -823,7 +814,6 @@ environment variable is set, it will ove
\fIonly\fR
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\&.
.SH "SEE ALSO"
-.PP
\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
.SH "NOTES"
.IP " 1." 4
@@ -838,5 +828,5 @@ Boot Loader Specification
.IP " 3." 4
Discoverable Partitions Specification
.RS 4
-\%https://uapi-group.org/specifications/specs/discoverable_partitions_specification
+\%https://uapi-group.org/\:specifications/\:specs/\:discoverable_partitions_specification
.RE
More information about the Pkg-systemd-maintainers
mailing list