From owner-cvs-all Sat Nov 25 11:30:36 2000 Delivered-To: cvs-all@freebsd.org Received: from guru.mired.org (okc-65-26-235-186.mmcable.com [65.26.235.186]) by hub.freebsd.org (Postfix) with SMTP id 88BCF37B4CF for ; Sat, 25 Nov 2000 11:30:33 -0800 (PST) Received: (qmail 74446 invoked by uid 100); 25 Nov 2000 19:30:32 -0000 From: Mike Meyer MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Message-ID: <14880.4952.786656.4040@guru.mired.org> Date: Sat, 25 Nov 2000 13:30:32 -0600 (CST) To: mupi@mknet.org Cc: Steve Kargl , Sheldon Hearn , cvs-all@freebsd.org Subject: Re: cvs commit: src/share/man/man5 make.conf.5 src/share/man/man7 build.7 In-Reply-To: <00112511505203.00436@mukappa.home.com> References: <200011251739.eAPHdke20159@troutmask.apl.washington.edu> <00112511505203.00436@mukappa.home.com> X-Mailer: VM 6.75 under 21.1 (patch 10) "Capitol Reef" XEmacs Lucid X-face: "5Mnwy%?j>IIV\)A=):rjWL~NB2aH[}Yq8Z=u~vJ`"(,&SiLvbbz2W`;h9L,Yg`+vb1>RG% *h+%X^n0EZd>TM8_IB;a8F?(Fb"lw'IgCoyM.[Lg#r\ Sender: owner-cvs-all@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.ORG Mike Porter types: > > "man rc.conf" brings up a page that can be read. "man handbook" > > does not work, "handbook handbook" doesn't work, "info handbook" > > does not work. > Having said all that, I think that there is a definite need for > both; on the one hand, man is quick, part of the "standard > distribution" and all that, but on the other hand, the handbook > allows space for much greater detail and explanations, and in > general is easier to use and navigate. This is part of the historical context, though. BSD still follows the AT&T research Unix man page scheme, which System V seems to have dropped. But both CSRG and FreeBSD have added and/or changed the meaning of some of those sections. That information didn't have a place to go in the original man system, it does now. > This makes it easier for people less familiar with BSD specifically > and "Unix-like" or "Unix-based" OSes in general (read: "newbies") to > have an easier time getting stuff set up and running. Not if they don't have the handbook available. While it's installed as part of the release, but the process it documents for updating doesn't update the handbook - and doesn't even mention this. In fact, I couldn't find any information on how to update the handbook, other that that attached to how you go about building it to submit documentation (While I'm at it, the process documented for building the kernel is wrong; see the current build(7) man page for the correct information). Worse yet, there are no tools for searching it, so FreeBSD newbies who *are* used to other Unix-like OS's may never find the thing. This, of course, could be fixed by adding a "handbook" command, that included the ability to do searches on the handbook, and had a man page so it could be found via man. > I know for my part, coming from the Linux world, the BSD-ish way of > doing things seems a little strange at first, and so I have found > myslef referring to both sets of documenation at various times for > various things. Coming from the Linux world doesn't have anything to do with it. Some of the information you need isn't in the man pages; it's in the handbook. You need to check both places to find things - except that there's no easy way to check the handbook. Adding ports just makes things worse, though - some things install man pages, some things install html in ${LOCALBASE/share/doc, some install text there, and some install info pages. > systems of FreeBSD, and most of the time the best person to write the > manual page is the person that wrote that part of > FreeBSD." That should read "best available person to write the manual page". Having the person who wrote the code write the man page is a good way to get a man page that only makes sense after you've grokked the source code. It's far better to have someone who can write English at least as well as the code author writes code to extract the information from the code author and write the man page. That's probably not feasible for a volunteer project, though.