On Tue, Nov 07, 2006 at 11:42:01AM -0700, Bob Beck wrote: > > 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? >
you're right that ifconfig(8) is a bit different... i discussed this very idea of repetition in ifconfig(8) and wireless pages already today. the thing is, it allows us to specify per driver options for these cards. so ath(4) might support one set of options, whilst ral(4) supports a slightly different set (i'm thinking of stuff like supported modes, media types, ...). there is nowhere else sane to document that stuff. ifconfig(8) examples are already too long...adding xrefs for every wireless device to ifconfig(8) is hardly practical (or consistent). looking again through ifconfig(8), i might at some point remove the single section EXAMPLES, and look at integrating them into the subsections of ifconfig(8). so, for example, you'd read the ieee80211 section to get the wireless stuff, then see an example. that could work with ifconfig(8). i dunno - i'd have to try it and see. theo mentioned man -k...people have got to start looking for stuff, and using man -k (apropos(1)). we're really trying to make stuff in man4 coherent, and linked, and findable. just before i replied to this, someone else posted that setting up wireless is non-trivial for a beginner. how can we make it clearer? i plug in my card; ral(4) shows up in dmesg; man ral; /EXAMPLES jmc
