Items missing from the handbook and/or FAQs.

[Marc Fonvieille]

On Fri, Apr 23, 2004 at 08:10:48PM -0700, Joe Rhett wrote:
> On Fri, Apr 23, 2004 at 10:36:46PM +0200, Marc Fonvieille wrote:
> > > get rid of the ppp0 and sl0 interfaces.  The answer was to copy related
> > > parameters from /etc/defaults/rc.conf to /etc/rc.conf and change them.
> > > 
> > > (The handbook actually does say "modify rc.conf" but it doesn't say what
> > > items should be modified!)
> > >
> > 
> > Wrong, read
> > http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/kernelconfig-config.html
> > about sl and ppp
> 
> Maybe it's just me, but would you look for bathroom cleaning information 
> in a manual about your oven?  Neither would I.  If you need to edit the
> kernel to disable PPP, then this should be noted in the PPP configuration
> documentation.
> 

Hmm be careful with the term you use: "to disable PPP" having an
interface available does not mean the pppd deamon (aka kernel PPP) is
running.  Having the pseudo-device ppp support in your kernel does not
change anything in a day-to-day use.  Well it's true no doc, beside the
kernel config ones, mentions the pseudo-device support, I'll fix it.
But I just gave a shot at:
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/slip.html
the "sl" page and the information is there for the sl pseudo-device, it
seems you did not read that page.

> > > Also a note to create /etc/start_if.{ifname} to put the wireless options in
> > > would also have saved me reading through the rc scripts.  I asusme that's a
> > > general case for all interfaces, but it could bear repeating in the wireless
> > > documentation. (when there is some...)
> > > 
> > 
> > http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/network-wireless.html
> > http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/network-bluetooth.html
>  
> I'm not certain what you are trying to say here, since both of these
> links fail to mention what I stated above.  They give you the basic
> commands, but leave you with the impression that you'll have to type
> these every time you want to configure the interface.  Even just a few
> links to other relevant documentation would greatly improve these
> sections.
>

Please, please and please: when you quote people "do not remove things".
You just removed a revelant part: it was a part of your question in your
original mail.  And of course without this part my answer seems weird.

> > > 3. Choosing filesystem types
> > > 
> > > During setup you can create filesystems other than FreeBSD, but you are
> > > supposed to magickally know their filesystem type numbers.  The setup
> > > documenation and the fdisk tools only tell you the filesystem numbers for
> > > freebsd, linux and dos.  An option to get a list would be nice.
> > > Documentation of the filesystem types would be nice too. (I had to use
> > > fdisk on a linux system to get the filesystem numbers I needed) 
> > 
> > http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/install-pre.html
> > especially 2.2.3.1 Disk Layouts for the i386
> 
> Naturally, I can browse the freebsd website while I'm partitioning the
> disk... makes sense to me.
> 

Well I think, and I'm sure I'm not alone in this case, an installation
documentation must be read/printed before installation.
Another thing, sysinstall comes with an help, and you can read it from
sysinstall.  For example I let you read /stand/help/partition.hlp

> Now how about the real question I raised, which is integrated
> documentation?  An option to see a list of disk types...?
>

By default you are given the FreeBSD type, well FreeBSD installation
system aims the installation of FreeBSD, I mean people hardly need to
create DOS, or other filesystem slices during FreeBSD installation.

> > > Suggestion: put a gdm configuration script there right next to the xdm
> > > configuration. The people who love twm know what to do to make it happy.
> > > Forcing people who aren't in love with twm and startx to hack at and make
> > > their own gdm startup scripts doesn't make much sense.
> > > 
> > > (yes, there is an example gdm startup script, but it won't work be default
> > > and you have to search for it, edit it, move it to the proper directory,
> > > etc....)
> > 
> > Well XDM and KDM are covered in the Handbook, we can't cover everything.
>  
> I'm not talking about documentation, I'm talking about sensible defaults.
> It's not a lack of documentation, it's a lack of useful setup scripts.
> 

I can't comment since I don't use GDM, but as I said in my previous
message, but *once again* you removed that part, you can contact the
FreeBSD GNOME team.

> Straight up: I'm building this system to set up a test environment for a
> client.  When I got done with the installation and there was no usable
> windows environment and no usable mail client, and no usable network
> interface ... I was pretty much ready to tell the client to find a modern
> OS.
> 

Well :(( sorry to say that but it sounds like a troll...

> I mean, hello, Unix systems came better working out the box in the
> mid-80s.  Why are we going backwards?
> 

When I install an application, the application is usable, I'm maybe very
lucky... :)

> > > 1. How to put DHCP on the wireless card?
> > > 
> > > I still haven't figured this out. I run dhclient on the interface by hand
> > > after every reboot and it works fine, but I'm assuming there is some 
> > > standard method of telling the system that wi0 should be a dhcp-managed, right?
> > 
> > http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/network-dhcp.html
>  
> Alright, on this one when I re-read it I found what I was looking for.
> It could be more clear, but it is there.
> 
> > > 2. What is interface faith0 ?
> > > 
> > > It took a ridiculous amount of searching to determine that faith0 was an
> > > ipv4 -> ipv6 interface.  And I can find nothing about how to disable it.
> > > (and if you say compile a new kernel and make world, excuse me while I puke)
> > > 
> > 
> > man faith
>  
> man faith returns information on what it is, with nothing at all about
> how to enable or disable it.
> 

Well, let's stop this talk...
Anyway I'm waiting for your doc PRs, you could even add a Cc to me.

Marc