[arch-general] rc.conf man page

[Joe(theWordy)Philbrook]

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 at ttlc.net>>