With <para><filename>…</filename></para>, we get a separate "paragraph" for
each line, i.e. entries separated by empty lines. This uses up a lot of space
and was only done because docbook makes it hard to insert a newline. In some
other places, <literallayout> was used, but then we cannot indent the source
text (because the whitespace would end up in the final page). We can get the
desired result with <simplelist>.
With <simplelist> the items are indented in roff output, but not in html
output. In some places this looks better then no indentation, and in others it
would probably be better to have no indent. But this is a minor issue and we
cannot control that.
(I didn't convert all spots. There's a bunch of other man pages which have two
lines, e.g. an executable and service file, and it doesn't matter there so
much.)
<ulinks> contents are used to generate a SEE ALSO section at the
bottom of a man page, so we need to include the title, without additional
words, in the content.
As I noticed a lot of missing information when trying to implement checking
for missing info. I reimplemented the version information script to be more
robust, and here is the result.
Follow up to ec07c3c80b
This tries to add information about when each option was added. It goes
back to version 183.
The version info is included from a separate file to allow generating it,
which would allow more control on the formatting of the final output.
These will be used in UIs to refer to the company or organization which
produces the OS separately from referring to the OS itself.
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
Fixes: #27777
sysext DDI cannot carry an os-release file, but have to carry
an extension-release file. But so far, this was only used to
match the sysext DDI with the base DDI/rootdir. It is also
useful to describe the sysext DDI itself, just like we do in
os-release.
So document that the same fields used in os-release can also
be added to an extension-release, with the 'SYSEXT_' prefix,
and in that case they are understood to define the sysext DDI
itself, rather than for matching purposes.
Fixes#25780.
> Man page: crypttab.5
> Issue 1: Missing fullstop
> Issue 2: I<cipher=>, I<hash=>, I<size=> → B<cipher=>, B<hash=>, B<size=>
>
> "Force LUKS mode\\&. When this mode is used, the following options are "
> "ignored since they are provided by the LUKS header on the device: "
> "I<cipher=>, I<hash=>, I<size=>"
Seems OK to me. The full stop is there and has been for at least a few years. And we use <option> for the markup, which is appropriate here.
> Man page: crypttab.5
> Issue 1: Missing fullstop
> Issue 2: I<cipher=>, I<hash=>, I<keyfile-offset=>, I<keyfile-size=>, I<size=> → B<cipher=>, B<hash=>, B<keyfile-offset=>, B<keyfile-size=>, B<size=>
>
> "Use TrueCrypt encryption mode\\&. When this mode is used, the following "
> "options are ignored since they are provided by the TrueCrypt header on the "
> "device or do not apply: I<cipher=>, I<hash=>, I<keyfile-offset=>, I<keyfile-"
> "size=>, I<size=>"
Same.
> Man page: journalctl.1
> Issue 1: make be → may be
Fixed.
> Issue 2: below\\&. → below:
Fixed.
> Man page: journalctl.1
> Issue: Colon at the end?
>
> "The following commands are understood\\&. If none is specified the default "
> "is to display journal records\\&."
> msgstr ""
> "Die folgenden Befehle werden verstanden\\&. Falls keiner festgelegt ist, ist "
> "die Anzeige von Journal-Datensätzen die Vorgabe\\&."
This is a bit awkward, but I'm not sure how to fix it.
> Man page: kernel-install.8
> Issue: methods a fallback → methods fallback
It was correct, but I added a comma to make the sense clearer.
> Man page: loader.conf.5
> Issue 1: secure boot variables → Secure Boot variables
> Issue 2: one → one for (multiple times)
>
> "Supported secure boot variables are one database for authorized images, one "
> "key exchange key (KEK) and one platform key (PK)\\&. For more information, "
> "refer to the \\m[blue]B<UEFI specification>\\m[]\\&\\s-2\\u[2]\\d\\s+2, "
> "under Secure Boot and Driver Signing\\&. Another resource that describe the "
> "interplay of the different variables is the \\m[blue]B<EDK2 "
> "documentation>\\m[]\\&\\s-2\\u[3]\\d\\s+2\\&."
"one of" would sound strange. "One this and one that" is OK.
> Man page: loader.conf.5
> Issue: systemd-boot → B<systemd-boot>(7)
Fixed.
> Man page: logind.conf.5
> Issue: systemd-logind → B<systemd-logind>(8)
We use <filename>systemd-logind</> on subsequent references… I think that's good enough.
> Man page: nss-myhostname.8
> Issue: B<getent> → B<getent>(1)
Fixed.
> Man page: nss-resolve.8
> Issue: B<systemd-resolved> → B<systemd-resolved>(8)
The first reference does this, subsequent are shorter.
> Man page: os-release.5
> Issue: Portable Services → Portable Services Documentation?
Updated.
> Man page: pam_systemd_home.8
> Issue: auth and account use "reason", while session and password do not?
Reworded.
> Man page: portablectl.1
> Issue: In systemd-portabled.service(8): Portable Services Documentation
Updated.
> Man page: repart.d.5
> Issue: The partition → the partition
Fixed.
> Man page: repart.d.5
> Issue: B<systemd-repart> → B<systemd-repart>(8)
The first reference does this. I also change this one, because it's pretty far down in the text.
> Man page: systemd.1
> Issue: kernel command line twice?
>
> "Takes a boolean argument\\&. If false disables importing credentials from "
> "the kernel command line, qemu_fw_cfg subsystem or the kernel command line\\&."
Apparently this was fixed already.
> Man page: systemd-boot.7
> Issue: enrollement → enrollment
Fixed.
> Man page: systemd-cryptenroll.1
> Issue: multiple cases: any specified → the specified
Reworded.
> Man page: systemd-cryptenroll.1
> Issue: If this this → If this
Fixed tree-wide.
> Man page: systemd-cryptsetup-generator.8
> Issue: and the initrd → and in the initrd
"Is honoured by the initrd" is OK, because we often speak about the initrd as a single unit. But in the same paragraph we also used "in the initrd", which makes the other use look sloppy. I changed it to "in the initrd" everywhere in that file.
> Man page: systemd.directives.7
> Issue: Why are these two quoted (but not others)?
>
> "B<\\*(Aqh\\*(Aq>"
>
> B<\\*(Aqs\\*(Aq>"
>
> "B<\\*(Aqy\\*(Aq>"
This is autogenerated from files… We use slightly different markup in different files, and it's just too hard to make it consistent. We gave up on this.
> Man page: systemd.exec.5
> Issue 1: B<at>(1p) → B<at>(1)
> Issue 2: B<crontab>(1p) → B<crontab>(1)
Fixed.
> Man page: systemd.exec.5
> Issue: B<select()> → B<select>(2)
Fixed.
> Man page: systemd.exec.5
> Issue: qemu → B<qemu>(1)
The man page doesn't seem to be in any of the canonical places on the web.
I added a link to online docs.
> Man page: systemd.exec.5
> Issue: variable → variables
Seems to be fixed already.
> Man page: systemd-integritysetup-generator.8
> Issue: systemd-integritysetup-generator → B<systemd-integritysetup-generator>
I changed <filename> to <command>.
> Man page: systemd-integritysetup-generator.8
> Issue: superfluous comma at the end
Already fixed.
> Man page: systemd-measure.1
> Issue: (see B<--pcr-bank=>) below → (see B<--pcr-bank=> below)
Reworded.
> Man page: systemd-measure.1
> Issue: =PATH> → =>I<PATH>
Fixed.
> Man page: systemd-measure.1.po
> Issue: B<--bank=DIGEST> → B<--bank=>I<DIGEST>
Fixed.
> Man page: systemd.netdev.5
> Issue: os the → on the
Appears to have been fixed already.
> Man page: systemd.netdev.5
> Issue: Onboard → On-board (as in previous string)
Updated.
> Man page: systemd.network.5
> Issue: B<systemd-networkd> -> B<systemd-networkd>(8)
First reference does this, subsequent do not.
> Man page: systemd.network.5
> Issue: B<netlabelctl> → B<netlabelctl>(8)
First reference does this, subsequent do not.
> Man page: systemd.network.5
> Issue: Missing verb (aquired? configured?) in the half sentence starting with "or by a "
I dropped the comma.
> Man page: systemd-nspawn.1
> Issue: All host users outside of that range → All other host users
Reworded.
> # FIXME no effect → no effect\\&.
> #. type: Plain text
> #: archlinux debian-unstable fedora-rawhide mageia-cauldron opensuse-tumbleweed
> msgid ""
> "Whichever ID mapping option is used, the same mapping will be used for users "
> "and groups IDs\\&. If B<rootidmap> is used, the group owning the bind "
> "mounted directory will have no effect"
A period is added. Not sure if there's some other issue.
> Man page: systemd-oomd.service.8
> Issue: B<systemd> → B<systemd>(1)
Done.
> Man page: systemd.path.5
> Issue 1: B<systemd.exec>(1) → B<systemd.exec>(5)
> Issue 2: This section does not (yet?) exist
Fixed.
> Man page: systemd-pcrphase.service.8
> Issue 1: indicate phases into TPM2 PCR 11 ??
> Issue 2: Colon at the end of the paragraph?
Fixed.
> Man page: systemd-pcrphase.service.8
> Issue: final boot phase → final shutdown phase?
Updated.
> Man page: systemd-pcrphase.service.8
> Issue: for the the → for the
Fixed tree-wide.
> Man page: systemd-portabled.service.8
> Issue: In systemd-portabled.service(8): Portable Services Documentation
Updated.
> Man page: systemd-pstore.service.8
> Issue: Here and the following paragraphs: . → \\&. // Upstream: What does this comment mean? // You normally write \\&. for a full dot (full stop etc.); here you write only "." (i.e. a plain dot).
>
> "and we look up \"localhost\", nss-dns will send the following queries to "
> "systemd-resolved listening on 127.0.0.53:53: first \"localhost.foobar.com\", "
> "then \"localhost.barbar.com\", and finally \"localhost\". If (hopefully) the "
> "first two queries fail, systemd-resolved will synthesize an answer for the "
> "third query."
Looks all OK to me.
> Man page: systemd.resource-control.5
> Issue: Missing closing bracket after link to Control Groups version 1
Fixed.
> Man page: systemd-sysext.8
> Issue: In systemd-portabled.service(8): Portable Services Documentation
Updated.
> Man page: systemd.timer.5
> Issue 1: B<systemd.exec>(1) → B<systemd.exec>(5)
> Issue 2: This section does not (yet?) exist
Fixed.
> Man page: systemd.unit.5
> Issue: that is → that are
Fixed.
> Man page: systemd-veritysetup-generator.8
> Issue: systemd-veritysetup-generator → B<systemd-veritysetup-generator>
>
> "systemd-veritysetup-generator implements B<systemd.generator>(7)\\&."
>
> "systemd-veritysetup-generator understands the following kernel command line "
> "parameters:"
Updated.
> Man page: systemd-volatile-root.service.8
> Issue: initrdyes → Initrd
Fixed.
> Man page: sysupdate.d.5
> Issue: : → \\&. (As above in TRANSFER)
Updated.
> Man page: sysupdate.d.5
> Issue: some → certain
Updated.
> Man page: sysupdate.d.5
> Issue 1: i\\&.e\\& → I\\&.e\\&
Fixed.
> Issue 2: the image → the system
"image" seems correct.
> Man page: tmpfiles.d.5
> Issue: systemd-tmpfiles → B<systemd-tmpfiles>(8)
Updated.
In many places we spelled out the phrase behind "initrd" in full, but this
isn't terribly useful. In fact, no "RAM disk" is used, so emphasizing this
is just confusing to the reader. Let's just say "initrd" everywhere, people
understand what this refers to, and that it's in fact an initramfs image.
Also, s/i.e./e.g./ where appropriate.
Also, don't say "in RAM", when in fact it's virtual memory, whose pages
may or may not be loaded in page frames in RAM, and we have no control over
this.
Also, add <filename></filename> and other minor cleanups.
When an extension image has binaries they should match the host
architecture. Currently there is no way to specify this requirement.
Introduce an ARCHITECTURE field in the extension's release file that
may be set to prevent loading on the wrong host architecture.
Since this new field is introduced late, we don't want to make
specifying it mandatory as it would break existing sysext images.
See https://github.com/systemd/systemd/issues/24061
I thought it would be nice to specify the last day of support, because I
thought it'd seem more natural. But in practice this doesn't work well, because
such a truncated timestamp is usually taken to mean midnight that starts the
given date. I.e. 2011-12-13 is a shorthand for 2011-12-13 00:00:00 and not
2011-12-13 23:59:59.999999999999. Let's instead specify that the given date is
the first unsupported day, which is meaningful for humans, and let the computer
treat it as midnight, which gives consistent interpratation.
Fixes#21764.
I think is very simple, but flexible. The date may be set early, for distros
that have a fixed schedule, but it doesn't have to. So for example Debian could
push out an update that sets a few months before the release goes EOL. And
various tools, in particular graphical desktops, can start nagging people to
upgrade a few weeks before the date.
As discussed in the bug, we don't need granularity higher than a day. And this
means that we can use a simple human- and machine-readable format.
I was considering other names, e.g. something with "EOL", but I think that
"SUPPORT_END" is better because it doesn't imply that the machine will somehow
stop working. This is supposed to be an advisory, nothing more.
We didn't actually say that keys should not be repeated. At least the
examples in docs (both python and shell) would do that, and any simple
parser that builds a dictionary would most likely behave the same way.
But let's document this expectation, but also say how to deal with malformed
files.
Python gained support for reading os-release, let's advertise it a bit more.
Our open-coded example is still useful, but let's not suggest it as the
default implementation.
I added quotes around the printed string because it looks a bit better
this way.
This should make things a bit more robust since it ensures system
extension can only applied to the right environments. Right now three
different "scopes" are defined:
1. "system" (for regular OS systems, after the initrd transition)
2. "initrd" (for sysext images that apply to the initrd environment)
3. "portable" (for sysext images that apply to portable images)
If not specified we imply a default of "system portable", i.e. any image
where the field is not specified is implicitly OK for application to OS
images and for portable services – but not for initrds.
This is also not entirely obvious. I think the code I came
up with is pretty elegant ;] The final part of of the code that makes
use of the parsed data is kept very similar to the shell code on purpose,
even though it could be written a bit more idiomatically.
Let's order the fields from the most general to least: os name, os variant, os
version, machine-parseable version details, metadata, special settings. I added
section headers to roughly group the settings. The division is not strict,
because for example CPE_NAME also includes the version, and PRETTY_NAME may
too, but it still makes it easier to find the right name.
Also split out Examples to separate paragraphs:
almost all descriptions had "Example:" at the end, where multiple
examples were listed. Splitting this out to separate paragraphs
makes the whole thing much easier to read.
Add missing markup and punctuation while at it.
About
- If not set, defaults to <literal>NAME=Linux</literal>.
+ If not set, a default of <literal>NAME=Linux</literal> may be used.
and similar changes: in many circumstances, if this is not set, no value should
be used. The fallback mostly make sense when we need to present something to the
user. So let's reword this to not imply that the default is necessary.
This specifes two new optional fields for /etc/os-release:
IMAGE_VERSION= and IMAGE_ID= that are supposed to identify the image of
the current booted system by name and version.
This is inspired by the versioning stuff in
https://github.com/systemd/mkosi/pull/683.
In environments where pre-built images are installed and updated as a
whole the existing os-release version/distro identifier are not
sufficient to describe the system's version, as they describe only the
distro an image is built from, but not the image itself, even if that
image is deployed many times on many systems, and even if that image
contains more resources than just the RPMs/DEBs.
In particular, "mkosi" is a tool for building disk images based on
distro RPMs with additional resources dropped in. The combination of all
of these together with their versions should also carry an identifier
and version, and that's what IMAGE_VERSION= and IMAGE_ID= is supposed to
be.
The motivation is that variants of the same distro that share the same compiled
rpm want to customize various aspects of the system, in particular the
hostname. In some sense the default hostname is part of the identity of the
system, so setting it through os-release makes sense. In particular, instead of
setting a default value in /etc/hostname, the appropriate default can be baked
into the image, leaving /etc/hostname for local overrides only.
Why make this a separate field instead of e.g. using NAME from os-release?
NAME is already used for other purposes, and it seems likely that people want
to set those independently.
In order to allow applications to detect the host OS version or other
metadata, ask container managers to expose the os-release files as
read-only bind mounts.
For systemd-nspawn, we will also expose ID, BUILD_ID, VERSION_ID and
VARIANT_ID as lowercase environment variables prefixed by the
container_host_ string.
Given that ANSI_COLOR= is mostly about branding it probably makes sense
to use RGB rather than paletted colors for them, so that the colors
match the project design as close as possible. Hence, provide a 25bit
RGB example for ANSI_COLOR, and update the overall example to something
newer.
Also see: https://bugzilla.redhat.com/show_bug.cgi?id=1823099
The "include" files had type "book" for some raeason. I don't think this
is meaningful. Let's just use the same everywhere.
$ perl -i -0pe 's^..DOCTYPE (book|refentry) PUBLIC "-//OASIS//DTD DocBook XML V4.[25]//EN"\s+"http^<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"\n "http^gms' man/*.xml
No need to waste space, and uniformity is good.
$ perl -i -0pe 's|\n+<!--\s*SPDX-License-Identifier: LGPL-2.1..\s*-->|\n<!-- SPDX-License-Identifier: LGPL-2.1+ -->|gms' man/*.xml
Strictly speaking, those are not environment variables, but they are compatible
and people think about them like this. Moving them makes them easier to find.
