It would appear that on Aug 26, Dave Reisner did say:
On Tue, Aug 24, 2010 at 01:35:33PM -0400, Joe(theWordy)Philbrook wrote:
As a mere arch user who happens to think that the concept of well commented configuration files such as Arch's rc.conf are WONDERFUL. Especially when they include examples for beginners and those of us who have difficulty remembering. ;-7
My only concerns about having a man page is that eventually the configuration file (in this case rc.conf) might gradually become less well commented, or it's comments become outdated. And that man pages tend to be long on highly technical explanations that I for one have a hard time understanding and are often short on examples. So rather than having the rc.conf refer to a man page for instruction on how to use it. I'd much prefer that the primary method of "guidance" remain in the rc.local and perhaps include in any man page a url from which one can download a current rc.local.example file.
I don't follow -- how does relocating comments to a man page make them inherently any more technical? If you have specific concerns about the verbiage I've used, I'm happy to address them.
Please don't misunderstand me to mean that I take exception to the your "verbiage". In fact _IF_ I had to depend on a man page rather than a well commented rc.config file someday, I rather hope the man page is very much like yours.
I'm not opposed to the idea of leaving them in the file itself as well, but as brought up earlier, it then exposes the chance for the man page and the comments to be out of sync. I'll propose a middle ground -- syntax exists in both places (as its much less likely to change), but more detailed explanations are provided only in the man page.
Now that might be good. A man page should have fully detailed explanations as well as syntax (and I think at least some examples)... Where as an actual config file should be rich in commented out examples but as far as explanations go, I think concise one liners that rely on the examples to impart a goodly part of the instruction, are the way to go. Especially if it's practical to include in the config file a hint that the man file exists... I also think that the idea of including in the man page a url to an example config file that is as 'up to date', and as 'in sync' with the man page as possible, would be a good hedge against the mutable nature of the config file. My feelings about man pages (and info documents) in general, stem from years of scratching my head while trying to figure out how to do one unfamiliar task or another with only such documentation to go by. I would not really be surprised to find that most of the man pages found on an Arch system might well be better written than the ones that made me feel like they were meant to impress some professor rather than to impart knowledge to those that don't already have a good grasp of the subject. I know the Arch wiki at least does a real good job of imparting knowledge (once you find the right document)... Which makes me wonder if at the end of the man page, in addition to a url for a current version of the commented config file, would it possibly be a good idea to also reference any applicable wiki pages? -- | --- ___ | <0> <-> Joe (theWordy) Philbrook | ^ J(tWdy)P | ~\___/~ <<jtwdyp@ttlc.net>>