When wrong element types are used, directives are sometimes placed in the wrong
section. Also, strip part of text starting with "'", which is used in a few
places and which is displayed improperly in the index.
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
For an example where we already use it, see man:sd-login(3):
> A session is defined by the time a user is logged in until they log out.
As far as I can tell, this removes the only remaining occurrences of
referring to users by gendered pronouns in our documentation (though
some still survive in code comments and the NEWS and TODO files):
git grep '\b\(he\|him\|his\|she\|her\|hers\)\b' man/
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
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.
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.
So far we didn't document control, transient, dbus config, or generator paths.
But those paths are visible to users, and they need to understand why systemd
loads units from those paths, and how the precedence hierarchy looks.
The whole thing is a bit messy, since the list of paths is quite long.
I made the tables a bit shorter by combining rows for the alternatives
where $XDG_* is set and the fallback.
In various places, tags are split like <element
param="blah">
this. This is necessary to keep everyting in one logical XML line so that
docbook renders the table properly.
Replaces #8050.
This addition is kept brief on purpose, since in order to write a good
generator users don't really need to grok templating/instantiation.
Fixes: #7257
v2:
- add example files to EXTRA_DIST
v3:
- rework for the new scheme where nothing is written to disk
v4:
- use separate dirs for system and user env generators
