[arch-general] rc.conf man page
I threw together a man page for rc.conf based on info gleaned from the Wiki, rc.conf itself, and my own experiences. I offer it up for for adoption into the initscripts package along with comments, critcisms, and rotten tomatoes. The format is asciidoc, which is the same format used by pacman. If desirable, I'm willing to compile other pages for system config files in a similar manner. d
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. 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 (!).". 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. -- David Campbell
On Mon, Aug 23, 2010 at 1:59 PM, Dave Reisner
I threw together a man page for rc.conf based on info gleaned from the Wiki, rc.conf itself, and my own experiences. I offer it up for for adoption into the initscripts package along with comments, critcisms, and rotten tomatoes. The format is asciidoc, which is the same format used by pacman.
If desirable, I'm willing to compile other pages for system config files in a similar manner.
I like the idea of having manpages for this stuff. netcfg(8) already has a manpage, pacman has manpages, etc. and this is in the psuedo-standard asciidoc we've used for a lot of it. Do any of the developers object to adding some documentation to this Arch-specific stuff and having it be built and installed with the relevant packages? It is also a great way for people to get involved that don't feel as confident coding. -Dan
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
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.
But like I said. I'm only a user, not a developer, so I don't know that my
concerns count for much.
--
| ~^~ ~^~
| <*> <*> Joe (theWordy) Philbrook
| ^ J(tWdy)P
| \___/ <
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.
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
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
| ~\___/~ <
@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.
participants (5)
-
Dan McGee
-
Dave Reisner
-
David Campbell
-
Joe(theWordy)Philbrook
-
Martín Cigorraga