On Mon, Aug 23, 2010 at 05:37:29PM -0400, David Campbell wrote:

Excerpts from Dave Reisner's message of 2010-08-23 14:59:11 -0400:

...

*ROUTES (array)*:: A list of routes to be created. For each item in this list, the 'network' service expects to find a variable of the same name to exist providing a string of parameters to be passed to the 'route' command in order to create the route. Routes can prevented from being created by prefixing with a '!' symbol.

For a variable to be found it must exist, so "to exist" is redundant. Fixed on my copy.

The last sentence should read, "Routes can be...", not "Routes can prevented...", or better yet, "Prevent a route from being created by prefixing it with a bang (!).".

Also fixed, and I like your rewording.

I like this manpage, although, I am not so sure it is wise to have a manpage for rc.conf. rc.conf is well commented, and if there is a manpage, the two will have to be kept in sync with each other. Having the code with the documentation also makes understanding the documentation easier. I suggest either adding to the comments in rc.conf if they are not sufficient, or leaving out of the manpage information that can already be found in rc.conf.

My concern is that /etc/rc.conf is mutable, while a man page is not. AIF uses this commenting as guidance, but it (as well as rc.conf itself) could just as easily say "refer to the man page". d

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. +1 No matter man pages become quite useful (and big) rc's files should still be commented because this is very handy when editing them.

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 | ~\___/~ <>