Bob Beck wrote:
* 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
I could see pointing people to the hostname.if(5) man page. I think
most new users will not use the ifconfig command.
Maybe an example could go in there?
