[arch-general] rc.conf man page

[Dave Reisner]

On Tue, Aug 24, 2010 at 01:35:33PM -0400, Joe(theWordy)Philbrook wrote:
> 
> It would appear that on Aug 24, Dave Reisner did say:
> 
> > On Mon, Aug 23, 2010 at 05:37:29PM -0400, David Campbell wrote:
> > > 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".
> > 
> 
> 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.

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.

d