In those two pages, we need to include individual entries with xi:include to
merge the list less-variables.xml with the other entries, which is obviously
error prone. All variables are supported in both tools so add them.
This structure of the man page originates from the time when systemd was
installed on top of sysvinit systems, and users had an actual chance to
interact with the systemd binary directly. Nowadays it is almost never called
directly, so let's properly explain this in the overview.
The Options section is moved down below the kernel command line, those options
are only needed in special circumstances. Let's refer the reader to the
description of the kernel command line options, and not duplicate the
descriptions (which makes the text longer than necessary and increases chances
for discrepancies).
Systemd is also prominently used as the user manager, let's mention that in the
Overview.
While at it, use "=" only when an argument is required as we nowadays do.
It was only described in systemd(1), making it hard to discover.
Fixes#13561.
The same for $SYSTEMD_URLIFY.
I think all the tools whose man pages include less-variables.xml support
those variables.
These options are pretty much equivalent to "journal" and
"journal+console" anyway, let's simplify things, and drop them from the
documentation hence.
For compat reasons let's keep them in the code.
(Note that they are not 100% identical to 'journal', but I doubt the
distinction in behaviour is really relevant to keep this in the docs.
And we should probably should drop 'syslog' entirely from our codebase
eventually, but it's problematic as long as we semi-support udev on
non-systemd systems still.)
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
@bl33pbl0p, please fix your editor
(Apparently you never configured the source tree? If you did, then the
git pre-commit hook would have been enabled which doesn't allow
commiting non-whitespace clean stuff...)
Docbook styles required those to be present, even though the templates that we
use did not show those names anywhere. But something changed semi-recently (I
would suspect docbook templates, but there was only a minor version bump in
recent years, and the changelog does not suggest anything related), and builds
now work without those entries. Let's drop this dead weight.
Tested with F26-F29, debian unstable.
$ perl -i -0pe 's/\s*<authorgroup>.*<.authorgroup>//gms' man/*xml
These lines are generally out-of-date, incomplete and unnecessary. With
SPDX and git repository much more accurate and fine grained information
about licensing and authorship is available, hence let's drop the
per-file copyright notice. Of course, removing copyright lines of others
is problematic, hence this commit only removes my own lines and leaves
all others untouched. It might be nicer if sooner or later those could
go away too, making git the only and accurate source of authorship
information.
This part of the copyright blurb stems from the GPL use recommendations:
https://www.gnu.org/licenses/gpl-howto.en.html
The concept appears to originate in times where version control was per
file, instead of per tree, and was a way to glue the files together.
Ultimately, we nowadays don't live in that world anymore, and this
information is entirely useless anyway, as people are very welcome to
copy these files into any projects they like, and they shouldn't have to
change bits that are part of our copyright header for that.
hence, let's just get rid of this old cruft, and shorten our codebase a
bit.
To make debugging easier, this patches allows one to change the log target and
do reload/reexec without modifying configuration permanently, which makes
debugging easier.
Indeed if one changed the log target at runtime (via the bus or via signals),
the change was lost on the next reload/reexecution.
In order to restore back the default value (set via system.conf, environment
variables or any other means ), the empty string in the "LogTarget" property is
now supported as well as sending SIGTRMIN+26 signal.
To make debugging easier, this patches allows one to change the log level and
do reload/reexec without modifying configuration permanently, which makes
debugging easier.
Indeed if one changed the log max level at runtime (via the bus or via
signals), the change was lost on the next daemon reload/reexecution.
In order to restore the original value back (set via system.conf, environment
variables or any other means), the empty string in the "LogLevel" property is
now supported as well as sending SIGRTMIN+23 signal.
Newer terminals (in particular gnome-terminal) understand special escape
sequence for formatting clickable links. Let's support that to make our
tool output more clickable where that's appropriate.
For details see this:
https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda
The one big issue is that 'less' currently doesn't grok this, and
doesn't ignore sequence like regular terminal implementations do if they
don't support it. Hence for now, let's disable URL output if a pager is
used. We should revisit that though as soon as less added support for it
and enough time passed for it to enter various distributions.
Files which are installed as-is (any .service and other unit files, .conf
files, .policy files, etc), are left as is. My assumption is that SPDX
identifiers are not yet that well known, so it's better to retain the
extended header to avoid any doubt.
I also kept any copyright lines. We can probably remove them, but it'd nice to
obtain explicit acks from all involved authors before doing that.
Otherwise people might assume that systemd was installed in the $PATH,
but it is not. Do the same as for systemd-vconsole-setup.service and
friends: let's include the full path in the man page.
The irreversible job mode is required to ensure that shutdown is not
interrupted by the activation of a unit with a conflict.
We already used the correct job mode for `ctrl-alt-del.target`. But not
for `exit.target` (SIGINT of user manager). The SIGRT shutdown signals
also needed fixing.
Also change SIGRTMIN+0 to isolate default.target, instead of starting
it. The previous behaviour was documented. However there was no reason
given for it, nor can we provide one. The problem that isolate is too
aggressive anywhere outside of emergency.target (#2607) is orthogonal.
This feature is "accessible by different means and only really a safety
net"; it is confusing for it to differ from `systemctl default` without
explanation.
`AllowIsolate=yes` is retained on poweroff.target etc. for backwards
compatibility.
`sigpwr.target` is also an obvious candidate for linking to a shutdown
target. Unforunately it is also a possible hook for implementing some
logic like system V init did, reading `/etc/powerstatus`. If we switched
to starting `sigpwr.target` with REPLACE_IRREVERSIBLY, attempts to run
`systemctl shutdown` from it would fail, if they had not thought to set
`DefaultDependencies=no`. We had provided no examples for `sigpwr`, and
the whole idea is cruft to keep legacy people happy. For the moment, I
leave `sigpwr` alone, with no risk of disrupting anyone's
previously-working, half-working, or untested setup.
Fixes#6484. See also #6471
This updates the man page for the changes introduced in 1d84ad9445.
"=" is kep if the option is predominantly used with an argument, and dropped
otherwise.
v2:
- update also description of log_color
- drop '=' in all cases where it is optional
(previous rule of dropping it only in some cases was just too arbitrary.)
As requested in
https://github.com/systemd/systemd/pull/4864#pullrequestreview-12372557.
docbook will substitute triple dots for the ellipsis in man output, so this has
no effect on the troff output, only on HTML, making it infinitesimally nicer.
In some places we show output from programs, which use dots, and those places
should not be changed. In some tables, the alignment would change if dots were
changed to the ellipsis which is only one character. Since docbook replaces the
ellipsis automatically, we should leave those be. This patch changes all other
places.
It's rather hard to parse the confirmation messages (enabled with
systemd.confirm_spawn=true) amongst the status messages and the kernel
ones (if enabled).
This patch gives the possibility to the user to redirect the confirmation
message to a different virtual console, either by giving its name or its path,
so those messages are separated from the other ones and easier to read.
This changes the semantics a bit: before, SYSTEMD_COLORS= would be treated as
"yes", same as SYSTEMD_COLORS=xxx and SYSTEMD_COLORS=1, and only
SYSTEMD_COLORS=0 would be treated as "no". Now, only valid booleans are treated
as "yes". This actually matches how $SYSTEMD_COLORS was announced in NEWS.
