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.
In the context of a table, both would be generally understood to have the same
meaning. "n/a" is a strange beast. It was useful when tables were produced on
the typewriter with "---------" used to separate rows. It is visually more
pleasing to use "-", and there is no risk of it being mistaken for a row
separator.
This option has coredumpctl look at all journals instead of only the
local ones. This allows coredumpctl to show information about remote
coredumps if the coredumps are made available in /var/lib/systemd/coredump
and the corresponding journals are made available in /var/log/journal.
This is already possible using the --directory option but --all makes it
more user friendly since users don't have to enter the journal directory
anymore as long as it's available under /var/log/journal.
$ coredumpctl info |grep Command
Command Line: bash -c kill -SEGV $$ (before)
Command Line: bash -c "kill -SEGV \$\$" (road not taken, C quotes)
Command Line: bash -c $'kill -SEGV $$' (now, POSIX quotes)
Before we wouldn't use any quoting, making it impossible to figure how the
command line was split into arguments. We could use "normal" quotes, but this
has the disadvantage that the commandline *looks* like it could be pasted into
the terminal and executed, but this is not true: various non-printable
characters cannot be expressed in this quoting style. (This is not visible in
this example). Thus, "POSIX quotes" are used, which should allow any command
line to be expressed acurrately and pasted directly into a shell prompt to
reexecute.
I wonder if we should another field in the coredump entry that simply shows the
original cmdline with embedded NULs, in the original /proc/*/cmdline
format. This would allow clients to format the data as they see fit. But I
think we'd want to keep the serialized form anyway, for backwards compatibility.
Fixes#17910: we didn't clearly explain that coredumps may exist without
journal entries, and vice versa.
Also, make the examples more concrete, and use '$' instead of '#' to avoid
suggesting that running as root is required. The text is extended a bit in
various places. In the description of systemd-coredump, the details of executor
separation are split out to a separate subsection, since they are rather
detailed and not necessary to understand for normal use.
For executables which take a verb, we should list the verbs first, and
then options which modify those verbs second. The general layout of
the man page is from general description to specific details, usually
Overview, Commands, Options, Return Value, Examples, References.
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
