* 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
