Doesn't the issue with documentation/examples/links in man pages have a lot to do with the target audience? I always thought that the man pages were there for people with a certain amount of technical acumen relative to BSD, while absolute beginners were better of with HOWTO guides (which can ease them into the appropriate use of the man pages.)
If the man pages are intended to satisfy all users regardless of skill level, I think you will find many people will always be left unsatisfied. Dan Farrell > -----Original Message----- > From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of > Bob Beck > Sent: Tuesday, November 07, 2006 1:42 PM > To: [email protected] > Subject: Re: proposed patch for ifconfig(8) man page > > * Jason McIntyre <[EMAIL PROTECTED]> [2006-11-07 11:25]: > > On Tue, Nov 07, 2006 at 06:52:19PM +0100, Igor Sobrado wrote: > > > > > > Can I suggest adding atalk(4), inet6(4), ipsec(4), pf(4), pflog(4), > > > eon(5), hostapd(8), and tcpdump(8) to the "SEE ALSO" section of > > > ifconfig(8)? I think that, as these manual pages are being cited > > > in the ifconfig(8) manual page, they should be added to this section. > > > > > > Just want to check the opinion on this change before submitting a PR. > > > > > > The proposed patch is added to this message. > > > > > > > once upon a time i was inclined to go by the rule that if a man page > > referred to another, it should be listed in the SEE ALSO. i no longer > > think that though, since invariably i see overly large SEE ALSO, most of > > which is ignored anyway. so now my personal opinion is somewhere along > > the lines of "if reading this man page will help the reader understand > > this man page, i should include it in SEE ALSO". > > > > i am now sorely tempted to kill about 2/3 of the references in SEE ALSO, > > rather than actually add to it. it is much more important that stuff > > which uses ifconfig(8) (the various interfaces and so on) all point to > > ifconfig(8), rather than the other way round. > > > > we do not have an eon(5) man page, btw, but there was a fine piece of > > vinyl called "void dweller" which eon released about 15 years ago... > > start the machine! > > > > > I hear you in general jmc, but ifconfig is a bit of an odd duck. > > To give you an example. let us answer the simple question of "how do > I join wireless network "bob"" - the answer from the lists is "use > ifconfig" - ok, so if I read the man page for ifconfig, there is > notably no examples of doing this, however, for example, there are > examples of doing in in wi(4) - and very similar examples in ath(4) > Similarly, the same examples are repeated in ral(4).. See what I mean? > you really do need those "see also" entries as a dummy to be able to > find a reasnoable example in the man pages at the moment. and I am a > firm believer in the man page should have real examples - failing that > we end up with linux faq's. Unfortunately ifconfig is probably the > nastiest example of a man page to have this discussion with. Should > we be re-coalescing those examples back into ifconfig(8)? > > The core problem is simple - a user will be told "use ifconfig" > to do something not "use ath" - so they start at the ifconfig(8) point. > What's the best way to make that as painless as possible? > > -Bob
