cc #39649 and @jcrben

See also: https://discourse.nixos.org/t/can-we-auto-format-the-documentation-docbook-xml/121/2

Well, not indenting top-level paragraphs was intentional in order not to introduce a lot of superfluous indentation.

I've only seen positive-or-neutral (after clarifying with Eelco on IRC) feedback on this, so I think this is a go. I'll document how I did this and send that as a separate PR.

Beyond the top ... few ... here I'm not sure I should go back and ensure they can merge first: https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+label%3A%228.has%3A+documentation%22

Definitely looks an improvement, at least at a superficial look. I'm mainly concerned about conflicts with open PRs and conflicts in future cherry-picks to 18.03.

As for open PRs, they should be solvable after this reformat as well – they can run the formatting tool on the old state and just verify the diff against the newly formatted master.

I suppose 18.03 cherry-picks of docs will also find some way, and I don't expect many of them. In the "worst" case we can just run the reformating on all docs in 18.03 as well, as that doesn't seem as such a breaking change :-)

In the "worst" case we can just run the reformating on all docs in 18.03 as well

I was thinking I would just go ahead and do that :)

I've been making a bit of an effort to backport 18.03-relevant doc improvements, too.

on master, nixpkgs: 77161de
on master, nixos: eca5c99
on release-18.03, nixpkgs: 5eae581
on release-18.03, nixos: d3644fc