Date: Sat, 25 Nov 2000 13:30:32 -0600 (CST) From: Mike Meyer <mwm@mired.org> To: mupi@mknet.org Cc: Steve Kargl <sgk@troutmask.apl.washington.edu>, Sheldon Hearn <sheldonh@uunet.co.za>, cvs-all@freebsd.org Subject: Re: cvs commit: src/share/man/man5 make.conf.5 src/share/man/man7 build.7 Message-ID: <14880.4952.786656.4040@guru.mired.org> In-Reply-To: <00112511505203.00436@mukappa.home.com> References: <200011251739.eAPHdke20159@troutmask.apl.washington.edu> <00112511505203.00436@mukappa.home.com>
next in thread | previous in thread | raw e-mail | index | archive | help
Mike Porter <mupi@mknet.org> 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.
<mike
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe cvs-all" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?14880.4952.786656.4040>