On Sat, 2014-07-05 at 20:01 +0200, Timothy Murphy wrote:
Have you looked at the manual pages? I know of no other project
that
has the breadth and depth of documentation that systemd has.
This is probably a minority view but I don't think a man page should try to tell you everything about a command.
When I first used Unix (version 5) it was explicitly stated that a man page should literally fit on one page.
In particular I don't think it is necessary to list dozens of options, some of which are rarely if ever used, just because they exist. (I recall that there used to be a regular competition for the most useless option one could add to "cat".)
To me, a man page should address the likely needs of 95% of users, and should use any spare space to give examples of usage. A pointer to a reference work would be a useful addition.
I'm an old Unix hand so for me the man page *is* the reference in most cases, though for something as large and complex as systemd I have no issue with there being supplementary material as long as I don't need to access it just to remember a basic command. In fact I get annoyed at many of the desktop tools which don't have a proper man page because they expect you to reach for a browser or one of the lame built-in help tools. However that's another story.
poc