@Dave I readed your man page draft and it's quite useful - to me, a simple end-user. About your concerns with comments in rc.* files being outdated, a short advice can be put at the beginning of each file warning users to take comments in the file as a very general reference, guiding them to the man page for newer help, descriptions and instructions.
